windows-development-sandbox 1.5.0 → 1.9.0

package/dist/selftest/menu-perf.test.js

@@ -0,0 +1,248 @@
+// The menu stays quick: no key or draw waits for a child process (tasklist is faked and counted), a slow tab load shows
+// "Loading…" instead of holding up the keys, a held key is drawn once, and the terminal writes only the rows that
+// changed (the screen after the diffs is the same as a full draw, also after a resize).
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { DEFAULTS } from '../core/config/index.js';
+import { sleep } from '../core/util/index.js';
+import { Menu } from '../cli/menu/menu.js';
+import { LiveStatus } from '../cli/menu/live.js';
+import { ListPage } from '../cli/menu/pages/list-page.js';
+import { App, Text, Terminal } from '../cli/tui/index.js';
+import { supportsSyncUpdate } from '../cli/tui/terminal.js';
+import { isSandboxRunning, useTasklistCache, useTasklistRunners } from '../host/sandbox/index.js';
+const TASKLIST = [
+    '"System Idle Process","0","Services","0","8 K"',
+    '"WindowsSandboxClient.exe","4242","Console","1","9,000 K"',
+].join('\r\n');
+const KEYS = { down: '\x1b[B', up: '\x1b[A', left: '\x1b[D', right: '\x1b[C', tab: '\t', ctrlC: '\x03' };
+/** A terminal the test can type into and read: the keys go in as bytes, everything written is kept. */
+class FakeTty {
+    stdin = Object.assign(new PassThrough(), { isTTY: true, setRawMode: () => undefined });
+    stdout = Object.assign(new EventEmitter(), {
+        columns: 100,
+        rows: 30,
+        write: (chunk) => {
+            this.writes.push(String(chunk));
+            return true;
+        },
+    });
+    writes = [];
+    terminal() {
+        return new Terminal(this.stdin, this.stdout);
+    }
+    type(bytes) {
+        this.stdin.write(bytes);
+    }
+}
+/** What the screen shows after a stream of writes: rows set by "ESC[r;1H", wiped by "ESC[H ESC[2J". */
+function replay(writes, height) {
+    const rows = Array.from({ length: height }, () => '');
+    for (const write of writes) {
+        const body = write.replace(/\x1b\[\?2026[hl]/g, '');
+        if (body.startsWith('\x1b[?1049h'))
+            continue;
+        for (const part of body.split(/(?=\x1b\[(?:\d+;1H|H))/)) {
+            const clear = /^\x1b\[H\x1b\[2J/.exec(part);
+            if (clear)
+                rows.fill('');
+            const at = /^\x1b\[(\d+);1H([\s\S]*?)\x1b\[0m/.exec(part.slice(clear ? clear[0].length : 0));
+            if (at)
+                rows[Number(at[1]) - 1] = at[2];
+        }
+    }
+    return rows;
+}
+function context(t) {
+    const root = t.dir('menu-perf');
+    return {
+        packageRoot: t.packageRoot,
+        entry: 'sandbox.js',
+        options: {},
+        loaded: {
+            config: structuredClone(DEFAULTS),
+            configPath: null,
+            base: root,
+            layers: { machine: null, user: null },
+        },
+        storageRoot: root,
+        dataPath: t.dir('menu-perf', 'data'),
+    };
+}
+export const menuPerfSuite = {
+    name: 'menu-perf',
+    title: 'menu speed: no child process on a key or a draw, diff rendering, slow loads',
+    run: async (t) => {
+        t.section('the terminal writes only what changed');
+        {
+            const tty = new FakeTty();
+            const term = tty.terminal();
+            const height = term.height;
+            const frame = (mark) => Array.from({ length: height }, (_, i) => 'row ' + i + (i === 7 ? mark : ''));
+            term.start();
+            tty.writes.length = 0;
+            term.render(frame('a'));
+            const first = tty.writes.join('');
+            term.render(frame('a'));
+            const unchanged = tty.writes.length;
+            term.render(frame('b'));
+            const diff = tty.writes.slice(1).join('');
+            t.check(unchanged === 1 && diff.includes('row 7b') && !diff.includes('row 6') && diff.length < first.length / 5, 'an identical frame writes nothing and a change writes only its rows, in one write', diff);
+            t.equal(replay(tty.writes, height).map((r) => r.trimEnd()), frame('b').map((r) => Text.fit(r, term.width - 1).trimEnd()), 'the screen after the diffs equals a full draw');
+            tty.stdout.rows = height + 5;
+            tty.stdout.emit('resize');
+            tty.writes.length = 0;
+            const bigger = Array.from({ length: height + 5 }, (_, i) => 'big ' + i);
+            term.render(bigger);
+            t.check(tty.writes.length === 1 && tty.writes[0].includes('\x1b[2J'), 'a resize repaints everything in one write');
+            t.equal(replay(tty.writes, height + 5).map((r) => r.trimEnd()), bigger.map((r) => Text.fit(r, term.width - 1).trimEnd()), 'the screen after a resize equals a full draw');
+            term.stop();
+            t.check(supportsSyncUpdate({ WT_SESSION: 'x' }) &&
+                !supportsSyncUpdate({}) &&
+                !supportsSyncUpdate({ WT_SESSION: 'x', AGENT_SANDBOX_SYNC_UPDATE: '0' }) &&
+                supportsSyncUpdate({ AGENT_SANDBOX_SYNC_UPDATE: '1' }), 'synchronized updates are used where the terminal is known to take them, and can be forced on or off');
+        }
+        t.section('a held key is drawn once');
+        {
+            const tty = new FakeTty();
+            const app = new App(tty.terminal());
+            let renders = 0;
+            let handled = 0;
+            const screen = {
+                render: (_size) => {
+                    renders++;
+                    return { path: [], body: ['x'], keys: [] };
+                },
+                handle: (key) => {
+                    handled++;
+                    return key.text === 'q' ? { done: 'bye' } : undefined;
+                },
+            };
+            // Thirty keys arrive together (a held arrow, a paste).
+            tty.type(KEYS.down.repeat(30) + 'q');
+            const result = await app.show(screen);
+            app.close();
+            t.check(result === 'bye' && handled === 31 && renders < 10, 'keys that are already waiting are handled first and drawn once, not once each', 'handled ' + handled + ', drawn ' + renders);
+        }
+        t.section('a slow load does not hold up the keys');
+        {
+            const tty = new FakeTty();
+            const app = new App(tty.terminal());
+            class Slow extends ListPage {
+                label = 'Slow';
+                rows = [];
+                async load() {
+                    await sleep(500);
+                    this.rows = ['alpha', 'beta'];
+                }
+                options() {
+                    return { path: [], items: this.rows.map((r) => ({ value: r, label: r })) };
+                }
+                act() {
+                    return Promise.resolve({});
+                }
+            }
+            const page = new Slow(app);
+            const started = Date.now();
+            await page.open();
+            const waited = Date.now() - started;
+            const text = () => Text.strip(page.render({ width: 80, height: 14 }).body.join('\n'));
+            t.check(waited < 400 && page.loading && text().includes('Loading'), 'the tab opens at once and says Loading… while the data comes', 'waited ' + waited + ' ms');
+            const arrived = await t.waitFor(() => (text().includes('beta') ? true : null), 5000, 20);
+            t.check(arrived === true && !page.loading, 'the list is built when the data arrives');
+        }
+        t.section('no child process on a key or a draw');
+        const saved = { hostOnly: process.env.AGENT_SANDBOX_HOST_ONLY };
+        process.env.AGENT_SANDBOX_HOST_ONLY = '1';
+        const calls = { sync: 0, async: 0 };
+        useTasklistRunners({
+            sync: () => {
+                calls.sync++;
+                return TASKLIST;
+            },
+            async: async () => {
+                calls.async++;
+                // A busy PC: every look at the process list takes a second and a half.
+                await sleep(1500);
+                return TASKLIST;
+            },
+        });
+        try {
+            const tty = new FakeTty();
+            const menu = new Menu(context(t), () => Promise.resolve(0), {
+                terminal: tty.terminal(),
+                fetchTasklist: async () => {
+                    calls.async++;
+                    await sleep(1500);
+                    return TASKLIST;
+                },
+                refreshMs: 100,
+            });
+            const done = menu.start();
+            const shown = await t.waitFor(() => tty.writes.length > 0, 20000, 20);
+            t.check(shown === true, 'the menu draws its first screen');
+            const slowest = { ms: 0, key: '' };
+            const press = async (name, bytes) => {
+                const before = tty.writes.length;
+                const at = Date.now();
+                tty.type(bytes);
+                // Not every key changes the screen: give the ones that do a chance, and measure those.
+                await t.waitFor(() => tty.writes.length > before, 400, 5);
+                const took = Date.now() - at;
+                if (tty.writes.length > before && took > slowest.ms) {
+                    slowest.ms = took;
+                    slowest.key = name;
+                }
+                await sleep(15);
+            };
+            const syncBefore = calls.sync;
+            for (const section of ['2', '3', '4', '5', '6', '7', '1'])
+                await press('section ' + section, section);
+            for (const k of ['down', 'down', 'up', 'left', 'down', 'down', 'right', 'down', 'down', 'tab'])
+                await press(k, KEYS[k]);
+            for (const section of ['5', '4', '2', '1'])
+                await press('section ' + section, section);
+            t.check(calls.sync === syncBefore, 'no key or draw ran tasklist (' + (calls.sync - syncBefore) + ' calls in 21 keys and every draw)', String(calls.sync - syncBefore));
+            t.check(calls.async >= 2, 'the process list is refreshed in the background (' + calls.async + ' times)');
+            t.check(slowest.ms < 1000, 'with a 1.5 second tasklist, no key took a second to show its result (slowest: ' +
+                slowest.key +
+                ' ' +
+                slowest.ms +
+                ' ms)');
+            tty.type(KEYS.ctrlC);
+            const code = await Promise.race([done, sleep(5000).then(() => -1)]);
+            t.check(code === 130, 'Ctrl+C leaves the menu');
+            const after = calls.sync;
+            isSandboxRunning();
+            t.check(calls.sync === after + 1, 'after the menu, "is the sandbox running?" runs tasklist again');
+        }
+        finally {
+            useTasklistRunners();
+            useTasklistCache(null);
+            if (saved.hostOnly === undefined)
+                delete process.env.AGENT_SANDBOX_HOST_ONLY;
+            else
+                process.env.AGENT_SANDBOX_HOST_ONLY = saved.hostOnly;
+        }
+        t.section('the status line');
+        {
+            let facts = 'a';
+            let changes = 0;
+            const live = new LiveStatus({
+                fetch: () => Promise.resolve(facts),
+                derive: () => 'status ' + facts,
+                onChange: () => changes++,
+                intervalMs: 20,
+            });
+            await live.start();
+            t.equal([live.line(), changes], ['status a', 1], 'the first look sets the line');
+            facts = 'b';
+            const changed = await t.waitFor(() => live.line() === 'status b', 3000, 10);
+            t.check(changed === true && changes === 2, 'a change is picked up in the background and announced');
+            live.stop();
+            facts = 'c';
+            await sleep(80);
+            t.check(live.line() === 'status b' && changes === 2, 'a stopped status looks at nothing');
+        }
+    },
+};

package/dist/selftest/menu-screens.d.ts

@@ -1,2 +1,9 @@
+import { type ListOptions, type NavState } from '../cli/tui/index.js';
+export declare const SIZES: {
+    width: number;
+    height: number;
+}[];
+/** The navigation the shell would show: every section, the open one with the categories of `options`. */
+export declare function navFor(active: number, options: ListOptions<string>, focused: boolean, unsaved?: number, dimmed?: boolean): NavState;
 /** All screens, at both sizes, as one text. `dir` is a scratch folder for the made-up config files. */
 export declare function renderScreens(dir: string): string;

package/dist/selftest/menu-screens.js

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Draft } from '../cli/menu/settings/draft.js';
-import { ConfigFile } from '../cli/menu/settings/config-file.js';
+import { ConfigFile } from '../app/features/settings/index.js';
 import { AppsModel } from '../cli/menu/apps.js';
 import { accountsOptions } from '../cli/menu/pages/accounts-page.js';
 import { appsOptions } from '../cli/menu/pages/apps-page.js';
@@ -11,14 +11,28 @@ import { maintenanceOptions } from '../cli/menu/pages/maintenance-page.js';
 import { sandboxOptions } from '../cli/menu/pages/sandbox-page.js';
 import { sessionsOptions } from '../cli/menu/pages/sessions-page.js';
 import { settingsOf, settingsOptions } from '../cli/menu/pages/settings-page.js';
-import { startOptions } from '../cli/menu/pages/start-page.js';
-import { TAB_LABELS } from '../cli/menu/shell.js';
+import { CATEGORIES } from '../app/features/settings/index.js';
+import { agentsOptions } from '../cli/menu/pages/agents-page.js';
+import { SECTION_LABELS } from '../cli/menu/shell.js';
 import { Frame, ListScreen, OverlayScreen, Text } from '../cli/tui/index.js';
-const SIZES = [
+export const SIZES = [
+    { width: 200, height: 60 },
     { width: 100, height: 30 },
     { width: 80, height: 24 },
+    { width: 60, height: 20 },
 ];
 const NOW = Date.now();
+const API_FOLDER = 'C:\\Projects\\api';
+/** The Data folder row of General (in the menu it comes from data-folder.ts). */
+const DATA_FOLDER_ROW = [
+    {
+        value: '@data-folder',
+        category: 'general',
+        label: 'Data folder',
+        hint: 'C:\\ProgramData\\AgentSandbox\\users\\me',
+        description: 'Where the sandbox keeps its data. Enter changes it.',
+    },
+];
 const ACCOUNTS = {
     agents: [
         { name: 'claude', kept: true, canSavePc: true },
@@ -43,6 +57,7 @@ const SESSIONS = [
         projectName: 'api',
         here: true,
         viewers: { remote: 1, viewers: 1 },
+        canOpen: true,
     },
     {
         id: '1791927991436-cc22dd',
@@ -53,17 +68,33 @@ const SESSIONS = [
         projectName: 'web',
         here: false,
         viewers: { remote: 0, viewers: 0 },
+        canOpen: true,
     },
 ];
-/** Frame for one screen: the tabs, a status line, the list, the keys. */
-function draw(active, options, size, status = '', unsaved = 0) {
-    const body = { width: size.width, height: Frame.bodyHeight(size.height, true) };
-    const parts = new ListScreen(options).render(body);
+/** The navigation the shell would show: every section, the open one with the categories of `options`. */
+export function navFor(active, options, focused, unsaved = 0, dimmed = false) {
+    const list = new ListScreen({ ...options, categoryNav: 'external' });
+    return {
+        sections: SECTION_LABELS.map((label, i) => ({
+            label,
+            marked: unsaved > 0 && (label === 'Settings' || label === 'Apps'),
+            categories: i === active ? list.categories.map((c) => ({ label: c.label, current: c.id === list.currentCategory })) : [],
+        })),
+        active,
+        focused,
+        dimmed,
+    };
+}
+/** Frame for one screen: the navigation, a status line, the list, the keys. */
+function draw(active, options, size, status = '', unsaved = 0, focusNav = false) {
+    const nav = navFor(active, options, focusNav, unsaved);
+    const body = { width: Frame.bodyWidth(size.width, nav), height: Frame.bodyHeight(size.height) };
+    const parts = new ListScreen({ ...options, categoryNav: 'external', escapeLabel: 'sections' }).render(body);
     return Frame.render({
         ...parts,
         keys: unsaved ? [['ctrl+s', 'save (' + unsaved + ')', 0], ...parts.keys] : parts.keys,
         status: (unsaved ? 'unsaved: ' + unsaved + '   ' : '') + (parts.status ?? status),
-        tabs: { tabs: TAB_LABELS.map((label) => ({ label })), active },
+        nav,
     }, size.width, size.height).map((l) => Text.strip(l).replace(/\s+$/, ''));
 }
 function block(title, lines, size) {
@@ -124,6 +155,12 @@ export function renderScreens(dir) {
             { name: 'postgres', running: true, port: 5432, title: 'PostgreSQL 18' },
             { name: 'redis', running: false, port: 6379, title: 'Redis' },
         ],
+        defaultAgent: 'claude',
+    };
+    const stopped = {
+        ...sandbox,
+        report: { ...sandbox.report, sandbox: { ...sandbox.report.sandbox, running: false, phase: 'stopped' } },
+        databases: null,
     };
     const maintenance = {
         data: {
@@ -150,11 +187,17 @@ export function renderScreens(dir) {
             { name: 'Toolchain cache', status: 'needs-you', detail: 'close the sandbox first' },
         ],
         settings: { pending: ['2026-10-unpin-config-defaults: stop pinning old defaults in your config.json'] },
+        dataFolder: {
+            label: 'Data folder',
+            hint: 'C:\\ProgramData\\AgentSandbox\\users\\me',
+            description: 'Where the sandbox keeps its tools, databases and agent state. Enter changes it.',
+        },
         updates: {
             managed: true,
             version: '1.4.3',
             scope: 'user',
             autoUpdate: true,
+            autoOffText: null,
             state: {
                 previous: '1.4.2',
                 failed: { version: '1.4.4', at: '2026-10-13T03:00:00Z', reason: 'it did not start' },
@@ -187,8 +230,8 @@ export function renderScreens(dir) {
     apps.stageTicks(appsDraft, ['git-gui']);
     const out = [];
     for (const size of SIZES) {
-        out.push(block('1 Start', draw(0, startOptions({
-            folder: 'C:\\Projects\\api',
+        const agentsModel = {
+            folder: API_FOLDER,
             defaultAgent: 'claude',
             agents: [
                 { name: 'claude', ready: true },
@@ -199,13 +242,21 @@ export function renderScreens(dir) {
             attach: true,
             window: 'config',
             hostAgents: ['codex'],
-        }, 'C:\\Projects\\api'), size, status), size), block('2 Sessions', draw(1, sessionsOptions({ sandboxRunning: true, sessions: SESSIONS }), size, status), size), block('2 Sessions (no sandbox)', draw(1, sessionsOptions({ sandboxRunning: false, sessions: [] }), size), size));
+            removable: ['gemini'],
+        };
+        out.push(block('1 Agents · Start', draw(0, { ...agentsOptions(agentsModel, API_FOLDER), startCategory: 'start' }, size, status), size), block('1 Agents · Options (navigation focused)', draw(0, { ...agentsOptions(agentsModel, API_FOLDER), startCategory: 'options' }, size, status, 0, true), size), block('1 Agents · On this PC', draw(0, { ...agentsOptions(agentsModel, API_FOLDER), startCategory: 'host' }, size, status), size), block('2 Sessions', draw(1, sessionsOptions({ sandboxRunning: true, sessions: SESSIONS, defaultAgent: 'claude' }), size, status), size), block('2 Sessions (no sandbox)', draw(1, sessionsOptions({ sandboxRunning: false, sessions: [], defaultAgent: 'claude' }), size), size));
+        for (const category of ['status', 'databases'])
+            out.push(block('3 Sandbox (stopped) · ' + category, draw(2, { ...sandboxOptions(stopped), startCategory: category }, size), size));
         for (const category of ['status', 'projects', 'databases'])
             out.push(block('3 Sandbox · ' + category, draw(2, { ...sandboxOptions(sandbox), startCategory: category }, size, status), size));
-        out.push(block('4 Apps (1 unsaved)', draw(3, appsOptions(apps, user, appsDraft, 'user'), size, status, appsDraft.count()), size), block('5 Settings (2 unsaved)', draw(4, settingsOptions(files, 'user', draft), size, status, draft.count()), size));
+        out.push(block('4 Apps (1 unsaved)', draw(3, appsOptions(apps, user, appsDraft, 'user'), size, status, appsDraft.count()), size));
+        for (const category of CATEGORIES)
+            out.push(block('5 Settings · ' + category.label + ' (2 unsaved)', draw(4, { ...settingsOptions(files, 'user', draft, DATA_FOLDER_ROW), startCategory: category.id }, size, status, draft.count()), size));
         // The leave dialog over the settings screen.
-        const background = new ListScreen(settingsOptions(files, 'user', draft));
-        const bodySize = { width: size.width, height: Frame.bodyHeight(size.height, true) };
+        const settingsList = settingsOptions(files, 'user', draft, DATA_FOLDER_ROW);
+        const nav = navFor(4, settingsList, false, draft.count(), true);
+        const background = new ListScreen({ ...settingsList, categoryNav: 'external' });
+        const bodySize = { width: Frame.bodyWidth(size.width, nav), height: Frame.bodyHeight(size.height) };
         const dialog = new OverlayScreen(background, {
             title: 'Unsaved changes',
             lines: ['You have 2 unsaved changes in Settings and Apps.'],
@@ -216,8 +267,8 @@ export function renderScreens(dir) {
             ],
             escape: 'cancel',
         });
-        out.push(block('5 Settings: Save / Discard / Cancel', Frame.render({ ...dialog.render(bodySize), tabs: { tabs: TAB_LABELS.map((label) => ({ label })), active: 4 } }, size.width, size.height).map((l) => Text.strip(l).replace(/\s+$/, '')), size), block('6 Accounts', draw(5, accountsOptions(ACCOUNTS), size, status), size), block('6 Accounts · codex', draw(5, { ...accountsOptions(ACCOUNTS), startCategory: 'codex' }, size, status), size), block('6 Accounts · opencode (login not kept)', draw(5, { ...accountsOptions(ACCOUNTS), startCategory: 'opencode' }, size, status), size));
-        for (const category of ['data', 'logs', 'doctor', 'repair', 'settings', 'updates', 'setup', 'more'])
+        out.push(block('5 Settings: Save / Discard / Cancel', Frame.render({ ...dialog.render(bodySize), nav }, size.width, size.height).map((l) => Text.strip(l).replace(/\s+$/, '')), size), block('6 Accounts', draw(5, accountsOptions(ACCOUNTS), size, status), size), block('6 Accounts · codex', draw(5, { ...accountsOptions(ACCOUNTS), startCategory: 'codex' }, size, status), size), block('6 Accounts · opencode (login not kept)', draw(5, { ...accountsOptions(ACCOUNTS), startCategory: 'opencode' }, size, status), size));
+        for (const category of ['updates', 'data', 'health', 'logs', 'more'])
             out.push(block('7 Maintenance · ' + category, draw(6, { ...maintenanceOptions(maintenance), startCategory: category }, size, status), size));
     }
     return out.join('\n');