windows-development-sandbox 1.1.0 → 1.4.0

package/sandbox/ptyhost.cs

@@ -16,6 +16,9 @@
 //                  18 ERROR   utf8 message
 //                  19 RESTARTING
 //                  20 STATUS  [viewers:2][remoteViewers:2]  viewers heard from recently (remote = not loopback, i.e. the PC)
+//                  21 CONSOLE utf8 "conpty.dll" or "windows", sent after HELLO. With conpty.dll the output is passed
+//                             through (real scrollback, no repaint on resize): a viewer that joins later is sent the
+//                             output since the last screen clear instead, and must not clear its screen on a resize.
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
@@ -75,6 +78,7 @@ sealed class SessionHost
             using (var console = PseudoConsole.Start(command, hub.Cols, hub.Rows, hub.Broadcast))
             {
                 hub.Attach(console);
+                log.Write("pseudo console: " + Native.ConsoleKind);
                 int exitCode = console.WaitForExit();
                 if (!restartRequested)
                 {
@@ -92,6 +96,7 @@ sealed class SessionHost
     public void Restart()
     {
         restartRequested = true;
+        hub.ResetReplay();
         hub.Notify(Frame.Restarting);
         hub.KillProgram();
     }
@@ -225,6 +230,9 @@ sealed class ClientHub
     readonly byte[] token;
     readonly byte[] tail = new byte[8192];
     int tailLength;
+    readonly object replayGate = new object();
+    readonly MemoryStream replay = new MemoryStream();
+    const int MaxReplay = 4 << 20;
     PseudoConsole console;
     Client sizeOwner;
     short cols, rows;
@@ -251,8 +259,18 @@ sealed class ClientHub
         client.ControlOnly = (hello[4] & 3) != 0;
         client.Query = (hello[4] & 2) != 0;
         if (client.Query) return true;
-        lock (gate) clients.Add(client);
-        if (!client.ControlOnly) TakeOwnership(client);
+        if (!client.ControlOnly)
+        {
+            Send(client, Frame.Console, Encoding.UTF8.GetBytes(Native.ConsoleKind.StartsWith("conpty") ? "conpty.dll" : "windows"));
+            // Taken and queued under the replay lock, so no output falls between the replay and the live stream.
+            lock (replayGate)
+            {
+                if (Native.ConsoleKind.StartsWith("conpty") && replay.Length > 0) Send(client, Frame.Output, replay.ToArray());
+                lock (gate) clients.Add(client);
+            }
+            TakeOwnership(client);
+        }
+        else lock (gate) clients.Add(client);
         return true;
     }
 
@@ -287,7 +305,41 @@ sealed class ClientHub
     public void Broadcast(byte[] output)
     {
         Remember(output);
-        foreach (Client c in Snapshot()) if (!c.ControlOnly) Send(c, Frame.Output, output);
+        lock (replayGate)
+        {
+            Record(output);
+            foreach (Client c in Snapshot()) if (!c.ControlOnly) Send(c, Frame.Output, output);
+        }
+    }
+
+    /**
+     * The output a viewer joining now needs to see the screen (conpty.dll does not repaint for it): everything since the
+     * last "clear screen", capped. Cut at a line start when capped, so the replay never begins inside an escape sequence.
+     */
+    void Record(byte[] output)
+    {
+        if (!Native.ConsoleKind.StartsWith("conpty")) return;
+        int clear = LastClear(output);
+        if (clear >= 0) { replay.SetLength(0); replay.Write(output, clear, output.Length - clear); }
+        else replay.Write(output, 0, output.Length);
+        if (replay.Length <= MaxReplay) return;
+        byte[] all = replay.ToArray();
+        int from = all.Length - MaxReplay / 2;
+        while (from < all.Length && all[from] != (byte)'\n') from++;
+        replay.SetLength(0);
+        if (from + 1 < all.Length) replay.Write(all, from + 1, all.Length - from - 1);
+    }
+
+    /** Where the last ESC[2J (clear screen) or ESC c (reset) starts in `data`, or -1. */
+    static int LastClear(byte[] data)
+    {
+        for (int i = data.Length - 2; i >= 0; i--)
+        {
+            if (data[i] != 0x1b) continue;
+            if (data[i + 1] == (byte)'c') return i;
+            if (i + 3 < data.Length && data[i + 1] == (byte)'[' && data[i + 2] == (byte)'2' && data[i + 3] == (byte)'J') return i;
+        }
+        return -1;
     }
 
     /** The program's last output as plain text (escape sequences removed), for the log when it exits. */
@@ -311,6 +363,9 @@ sealed class ClientHub
         }
     }
 
+    /** A restarted program starts on a clean screen (viewers clear theirs on RESTARTING). */
+    public void ResetReplay() { lock (replayGate) replay.SetLength(0); }
+
     public void Notify(byte type)
     {
         foreach (Client c in Snapshot()) if (!c.ControlOnly) Send(c, type, new byte[0]);
@@ -503,7 +558,7 @@ sealed class PseudoConsole : IDisposable
 static class Frame
 {
     public const byte Hello = 1, Input = 2, Resize = 3, Restart = 4, Ping = 5;
-    public const byte Output = 16, Exit = 17, Error = 18, Restarting = 19, Status = 20;
+    public const byte Output = 16, Exit = 17, Error = 18, Restarting = 19, Status = 20, Console = 21;
     const int MaxPayload = 1 << 20;
 
     public static bool Read(Stream stream, out byte type, out byte[] payload)
@@ -598,9 +653,52 @@ static class Native
         }
     }
 
-    [DllImport("kernel32.dll")] public static extern int CreatePseudoConsole(Coord size, SafeFileHandle hInput, SafeFileHandle hOutput, uint dwFlags, out IntPtr phPC);
-    [DllImport("kernel32.dll")] public static extern int ResizePseudoConsole(IntPtr hPC, Coord size);
-    [DllImport("kernel32.dll")] public static extern void ClosePseudoConsole(IntPtr hPC);
+    // The pseudo console: the newer conpty.dll (+ OpenConsole.exe next to it) when PTYHOST_CONPTY names one, else the one
+    // built into Windows. Windows 10/11 before 24H2 ship a ConPTY that re-renders the screen instead of passing the
+    // program's output through, which garbles wide characters after a resize and loses mouse input and scrollback.
+    [UnmanagedFunctionPointer(CallingConvention.Winapi)] delegate int CreateFn(Coord size, SafeFileHandle hInput, SafeFileHandle hOutput, uint dwFlags, out IntPtr phPC);
+    [UnmanagedFunctionPointer(CallingConvention.Winapi)] delegate int ResizeFn(IntPtr hPC, Coord size);
+    [UnmanagedFunctionPointer(CallingConvention.Winapi)] delegate void CloseFn(IntPtr hPC);
+    static CreateFn create;
+    static ResizeFn resize;
+    static CloseFn close;
+    /** "conpty.dll" or "windows": which pseudo console is in use (logged, and told to viewers). */
+    public static string ConsoleKind = "windows";
+
+    static Native()
+    {
+        string dll = Environment.GetEnvironmentVariable("PTYHOST_CONPTY");
+        if (string.IsNullOrEmpty(dll) || !File.Exists(dll) || !File.Exists(Path.Combine(Path.GetDirectoryName(dll), "OpenConsole.exe"))) return;
+        IntPtr module = LoadLibraryW(dll);
+        if (module == IntPtr.Zero) return;
+        IntPtr c = GetProcAddress(module, "ConptyCreatePseudoConsole"), r = GetProcAddress(module, "ConptyResizePseudoConsole"), x = GetProcAddress(module, "ConptyClosePseudoConsole");
+        if (c == IntPtr.Zero || r == IntPtr.Zero || x == IntPtr.Zero) return;
+        create = (CreateFn)Marshal.GetDelegateForFunctionPointer(c, typeof(CreateFn));
+        resize = (ResizeFn)Marshal.GetDelegateForFunctionPointer(r, typeof(ResizeFn));
+        close = (CloseFn)Marshal.GetDelegateForFunctionPointer(x, typeof(CloseFn));
+        ConsoleKind = "conpty.dll";
+    }
+
+    /** conpty.dll first; if it cannot start one (OpenConsole.exe blocked or broken), the built-in one for good. */
+    public static int CreatePseudoConsole(Coord size, SafeFileHandle hInput, SafeFileHandle hOutput, uint dwFlags, out IntPtr phPC)
+    {
+        if (create != null)
+        {
+            int hr = create(size, hInput, hOutput, dwFlags, out phPC);
+            if (hr == 0) return 0;
+            create = null; resize = null; close = null;
+            ConsoleKind = "windows (conpty.dll failed: 0x" + hr.ToString("X8") + ")";
+        }
+        return KernelCreatePseudoConsole(size, hInput, hOutput, dwFlags, out phPC);
+    }
+    public static int ResizePseudoConsole(IntPtr hPC, Coord size) { return resize != null ? resize(hPC, size) : KernelResizePseudoConsole(hPC, size); }
+    public static void ClosePseudoConsole(IntPtr hPC) { if (close != null) close(hPC); else KernelClosePseudoConsole(hPC); }
+
+    [DllImport("kernel32.dll", EntryPoint = "CreatePseudoConsole")] static extern int KernelCreatePseudoConsole(Coord size, SafeFileHandle hInput, SafeFileHandle hOutput, uint dwFlags, out IntPtr phPC);
+    [DllImport("kernel32.dll", EntryPoint = "ResizePseudoConsole")] static extern int KernelResizePseudoConsole(IntPtr hPC, Coord size);
+    [DllImport("kernel32.dll", EntryPoint = "ClosePseudoConsole")] static extern void KernelClosePseudoConsole(IntPtr hPC);
+    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)] static extern IntPtr LoadLibraryW(string path);
+    [DllImport("kernel32.dll", CharSet = CharSet.Ansi, BestFitMapping = false)] static extern IntPtr GetProcAddress(IntPtr module, string name);
     [DllImport("kernel32.dll", SetLastError = true)] public static extern bool CreatePipe(out SafeFileHandle hReadPipe, out SafeFileHandle hWritePipe, IntPtr lpPipeAttributes, int nSize);
     [DllImport("kernel32.dll", SetLastError = true)] static extern bool InitializeProcThreadAttributeList(IntPtr lpAttributeList, int dwAttributeCount, int dwFlags, ref IntPtr lpSize);
     [DllImport("kernel32.dll", SetLastError = true)] static extern bool UpdateProcThreadAttribute(IntPtr lpAttributeList, uint dwFlags, IntPtr attribute, IntPtr lpValue, IntPtr cbSize, IntPtr lpPreviousValue, IntPtr lpReturnSize);

package/schemas/config.schema.json

@@ -32,6 +32,62 @@
       "type": "boolean",
       "description": "Map the workspace read-only."
     },
+    "workspaceFilter": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Keep what your .gitignore lists (.env files, node_modules, build output ...) out of the sandbox. The sandbox works on a copy of the project without those files, kept in step with it both ways within about a second; what it creates that is ignored (its own node_modules, builds) stays in the sandbox. Git works as usual. Off = the project folder itself is mapped."
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "description": "Also keep these out, as .gitignore patterns, e.g. secrets/, *.pem, data/private/."
+        },
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 500
+          },
+          "description": "Let these in although .gitignore lists them, e.g. .env.example, data/fixtures/."
+        }
+      },
+      "additionalProperties": false
+    },
+    "audit": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Keep an audit log on this PC of what happened in your sandboxes: programs started (with their command lines), files changed in the project, sessions, and what the repo guard caught. The sandbox cannot change it. Read it with sandbox audit."
+        },
+        "days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "description": "Days the audit log is kept."
+        },
+        "maxMb": {
+          "type": "integer",
+          "minimum": 5,
+          "maximum": 5000,
+          "description": "Most space the audit log may take, in MB (older days go first). Days before today are compressed."
+        },
+        "processes": {
+          "type": "boolean",
+          "description": "Record every program started in the sandbox with its command line (Windows process auditing; repeated runs are counted, not listed)."
+        },
+        "files": {
+          "type": "boolean",
+          "description": "Record the files changed in the project while the sandbox runs."
+        }
+      },
+      "additionalProperties": false
+    },
     "mappings": {
       "type": "array",
       "items": {
@@ -102,6 +158,12 @@
           ],
           "description": "Most of this PC's CPU the sandbox may use, in percent (5-100), e.g. 50 keeps half free for you; \"none\" = no cap (Windows Sandbox would take every processor). Covers everything this tool starts in the sandbox (agents, installs, builds, its terminal)."
         },
+        "pageFileMb": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 262144,
+          "description": "Size of the sandbox's paging file in MB, created at full size when it starts so it never grows while builds run (8 GB of its disk always stays free). Windows Sandbox starts with about 1 GB: parallel builds then fail with \"The paging file is too small\", and Windows grows the file under load. 0 = leave Windows' own."
+        },
         "reserveHostMb": {
           "type": "integer",
           "minimum": 0,
@@ -139,6 +201,10 @@
         "headless": {
           "type": "boolean",
           "description": "Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends."
+        },
+        "keepAwake": {
+          "type": "boolean",
+          "description": "Keep this PC from sleeping while a sandbox runs, so agents left working overnight keep going (the screen may still turn off; closing a laptop lid still sleeps it)."
         }
       },
       "additionalProperties": false
@@ -159,6 +225,15 @@
           "type": "string",
           "pattern": "^[A-Za-z0-9_-]+$",
           "description": "Name of the persistent data set (C:\\AgentData) shared by all workspaces."
+        },
+        "markSandboxFiles": {
+          "type": "boolean",
+          "description": "Programs and scripts (.exe, .ps1, .bat, .cmd, .msi, .lnk ...) that appear or change in your project while a sandbox runs get Windows' \"downloaded from the internet\" mark, so SmartScreen and PowerShell ask before they run on this PC."
+        },
+        "warnDataGb": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space."
         }
       },
       "additionalProperties": false
@@ -169,6 +244,59 @@
         "blockPrivateRanges": {
           "type": "boolean",
           "description": "Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox."
+        },
+        "allowOnly": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 253,
+            "pattern": "^(@developer|(\\*\\.)?([a-zA-Z0-9-]+\\.)*[a-zA-Z0-9-]+)$"
+          },
+          "description": "Only these hosts can be reached once the sandbox is set up (tools still download first). *.example.com covers its subdomains; @developer adds package registries, GitHub, toolchain downloads and the AI providers. Programs go through a proxy in the sandbox (HTTP_PROXY); anything else is blocked by its firewall. Empty = no limit."
+        },
+        "blockHosts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 253,
+            "pattern": "^([a-zA-Z0-9-]+\\.)*[a-zA-Z0-9-]+$"
+          },
+          "description": "Never reachable from the sandbox, e.g. production servers or telemetry (each exact name; the sandbox's hosts file sends them nowhere)."
+        },
+        "forwardPorts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "pc": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535,
+                "description": "The port on this PC (localhost only)."
+              },
+              "sandbox": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535,
+                "description": "The port inside the sandbox (a server there may listen on localhost only)."
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "Reach servers in the sandbox from this PC: http://localhost:<pc> here goes to <sandbox> inside, while it runs. Nothing else on your network can use them."
+        },
+        "dns": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\d{1,3}(\\.\\d{1,3}){3}$"
+          },
+          "description": "DNS servers for the sandbox instead of your network's, e.g. 1.1.1.1 and 9.9.9.9."
+        },
+        "proxy": {
+          "type": "string",
+          "pattern": "^(https?:\\/\\/[^\\s]+)?$",
+          "description": "An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none."
         }
       },
       "additionalProperties": false
@@ -216,6 +344,16 @@
             }
           },
           "additionalProperties": false
+        },
+        "conpty": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Agent sessions use Microsoft's newer pseudo console (conpty.dll, downloaded once) instead of the one built into Windows: no garbled screen after resizing, real scrollback for the mouse wheel. Off = the one built into Windows."
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -725,6 +863,22 @@
             "enabled": {
               "type": "boolean",
               "description": "Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist."
+            },
+            "setup": {
+              "type": "boolean",
+              "description": "Point VS Code at the sandbox's own tools (JDK, Python, Go, compilers, .NET, Git, PowerShell 7 and Git Bash terminals) and install the language extensions for the toolchains in use."
+            },
+            "recommended": {
+              "type": "boolean",
+              "description": "Also install the extensions a project recommends in its .vscode/extensions.json."
+            },
+            "extensions": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[\\w-]+\\.[\\w-]+$"
+              },
+              "description": "More extensions to install in every sandbox, e.g. eamodio.gitlens, ms-azuretools.vscode-docker."
             }
           },
           "additionalProperties": false
@@ -999,6 +1153,141 @@
       },
       "additionalProperties": false
     },
+    "apps": {
+      "type": "object",
+      "properties": {
+        "install": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "notepadpp",
+              "sublime",
+              "neovim",
+              "dbeaver",
+              "pgadmin",
+              "heidisql",
+              "sqlitebrowser",
+              "compass",
+              "redisinsight",
+              "dbgate",
+              "beekeeper",
+              "dynamodb-admin",
+              "bruno",
+              "insomnia",
+              "sourcegit",
+              "githubdesktop",
+              "lazygit",
+              "7zip",
+              "winmerge",
+              "everything",
+              "sysinternals",
+              "imhex",
+              "chrome",
+              "firefox",
+              "godot",
+              "blender",
+              "love",
+              "defold",
+              "pixelorama",
+              "tiled",
+              "kubectl",
+              "helm",
+              "k9s",
+              "terraform",
+              "azure-cli",
+              "gcloud",
+              "aws-cli",
+              "drawio",
+              "pandoc",
+              "mitmproxy",
+              "xh",
+              "grpcurl",
+              "k6",
+              "jq",
+              "yq",
+              "ripgrep",
+              "fd",
+              "bat",
+              "fzf",
+              "delta",
+              "just",
+              "hyperfine",
+              "watchexec",
+              "protoc",
+              "ninja",
+              "ffmpeg",
+              "sqlite",
+              "shellcheck",
+              "gitleaks"
+            ]
+          },
+          "description": "Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept."
+        },
+        "custom": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,40}$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 80,
+                "description": "The name on the desktop shortcut, e.g. \"My Tool\"."
+              },
+              "github": {
+                "description": "GitHub repository (owner/repo): the file comes from its latest release.",
+                "type": "string",
+                "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+              },
+              "asset": {
+                "description": "With github: a pattern (regular expression) matching the release file, e.g. windows.*x64\\.zip$",
+                "type": "string",
+                "maxLength": 200
+              },
+              "url": {
+                "description": "Or a direct https:// download link (zip, 7z, exe or msi).",
+                "type": "string",
+                "format": "starts_with",
+                "pattern": "^https:\\/\\/.*"
+              },
+              "sha256": {
+                "description": "SHA-256 of the download (GitHub releases usually publish one; then this is not needed).",
+                "type": "string",
+                "pattern": "^[0-9a-fA-F]{64}$"
+              },
+              "unpack": {
+                "description": "archive (zip, 7z, tar: the default), file (a single .exe), nsis (an installer 7-Zip can open) or msi.",
+                "type": "string",
+                "enum": [
+                  "archive",
+                  "file",
+                  "nsis",
+                  "msi"
+                ]
+              },
+              "exe": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 200,
+                "description": "The program to start (found anywhere in the download), e.g. mytool.exe."
+              },
+              "cli": {
+                "description": "A command-line tool: its folder goes on PATH instead of getting a desktop shortcut.",
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          },
+          "description": "Programs of your own: a GitHub release or a download link, and the program to start. Installed like the catalogue apps."
+        }
+      },
+      "additionalProperties": false
+    },
     "claudeProfile": {
       "type": "object",
       "properties": {
@@ -1032,11 +1321,23 @@
         },
         "syncHistory": {
           "type": "boolean",
-          "description": "Bring all conversation history in, and sync new history back (path-translated)."
+          "description": "Bring conversation history in, and sync new history back (path-translated)."
+        },
+        "historyScope": {
+          "type": "string",
+          "enum": [
+            "project",
+            "all"
+          ],
+          "description": "Which history comes in: \"project\" = only the projects in this sandbox (other projects' conversations, file backups and prompts stay on this PC), \"all\" = everything. Only this sandbox's projects ever sync back."
         },
         "syncClaudeMem": {
           "type": "boolean",
-          "description": "Bring claude-mem data in, and its database back when the sandbox closes."
+          "description": "Bring claude-mem data into the sandbox (its settings and backups stay on this PC)."
+        },
+        "syncClaudeMemBack": {
+          "type": "boolean",
+          "description": "Also copy claude-mem's database back to this PC when the sandbox closes. Off by default: what is in it is loaded into every Claude session on this PC, so a compromised agent could plant instructions there."
         }
       },
       "additionalProperties": false