windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/menu/live.js

@@ -0,0 +1,69 @@
+// What the menu shows about the running sandbox (the status line), kept fresh in the background. Drawing and keys only
+// read the last copy: the process list is fetched without blocking (every few seconds, and after an action), and the
+// screen is told when what it shows has changed. While it runs, the host's own "is the sandbox running?" questions are
+// answered from the same copy, so no page waits for a child process.
+import { sandboxStatus } from '../../app/features/sandbox/index.js';
+import { readTasklistAsync, useTasklistCache } from '../../host/sandbox/index.js';
+/** The same rule as the web's live status: the sandbox status query's interval. */
+const DEFAULT_INTERVAL_MS = sandboxStatus.live?.everyMs ?? 2500;
+export class LiveStatus {
+    o;
+    tasklist;
+    text = '';
+    timer;
+    pending;
+    running = false;
+    constructor(o) {
+        this.o = o;
+    }
+    /** The status line as of the last refresh. */
+    line() {
+        return this.text;
+    }
+    /** Reads the process list now and derives the line (one fetch at a time; a caller during one waits for it). */
+    refresh() {
+        this.pending ??= (async () => {
+            try {
+                const list = await (this.o.fetch ?? readTasklistAsync)();
+                // Stopped meanwhile: a command may be running, and nothing here may touch the host's facts any more.
+                if (!this.running)
+                    return;
+                this.tasklist = list;
+                this.derive();
+            }
+            catch {
+                // The line keeps what it showed; the next refresh tries again.
+            }
+            finally {
+                this.pending = undefined;
+            }
+        })();
+        return this.pending;
+    }
+    derive() {
+        const next = this.o.derive();
+        if (next === this.text)
+            return;
+        this.text = next;
+        if (this.running)
+            this.o.onChange();
+    }
+    /** Starts keeping the line fresh and answers the host's process questions from it (until stop). */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        useTasklistCache(() => this.tasklist);
+        this.timer = setInterval(() => void this.refresh(), this.o.intervalMs ?? DEFAULT_INTERVAL_MS);
+        this.timer.unref();
+        await this.refresh();
+    }
+    /** Stops; the host's questions run their own programs again (a command that runs after the menu needs the truth). */
+    stop() {
+        this.running = false;
+        clearInterval(this.timer);
+        this.timer = undefined;
+        useTasklistCache(null);
+        this.tasklist = undefined;
+    }
+}

package/dist/cli/menu/memory.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { MenuView } from './shell.js';
+declare const MenuStateSchema: z.ZodObject<{
+    section: z.ZodString;
+    screens: z.ZodRecord<z.ZodString, z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+        search: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type MenuState = z.output<typeof MenuStateSchema>;
+/** The view as it is stored: the section by name, so a menu with other sections still finds its way. */
+export declare function viewToState(view: MenuView, labels: readonly string[]): MenuState;
+/** A stored state as a view; a section that no longer exists falls back to the first. */
+export declare function stateToView(state: MenuState, labels: readonly string[]): MenuView;
+/** The view the last run left (undefined when there is none or the file is not valid). */
+export declare function readMenuView(labels: readonly string[], dir?: string): MenuView | undefined;
+/** Remembers the view for the next run. Never fails the menu. */
+export declare function saveMenuView(view: MenuView, labels: readonly string[], dir?: string): void;
+export {};

package/dist/cli/menu/memory.js

@@ -0,0 +1,53 @@
+// Where the menu was left, kept in ~/.agent-sandbox/menu-state.json: the open section and, for each section, its
+// category and search. A convenience only: a missing, invalid or unwritable file means the menu opens on Agents.
+import path from 'node:path';
+import { z } from 'zod';
+import { userDir } from '../../core/config/index.js';
+import { JsonFile } from '../../shared/io/index.js';
+const ScreenSchema = z.strictObject({
+    category: z.string().max(100).optional(),
+    search: z.string().max(200).optional(),
+});
+const MenuStateSchema = z.strictObject({
+    section: z.string().max(40),
+    screens: z.record(z.string().max(40), ScreenSchema),
+});
+function stateFile(dir) {
+    return new JsonFile(MenuStateSchema, path.join(dir, 'menu-state.json'));
+}
+/** The view as it is stored: the section by name, so a menu with other sections still finds its way. */
+export function viewToState(view, labels) {
+    const screens = {};
+    for (const [label, screen] of Object.entries(view.screens))
+        if (labels.includes(label) && (screen.category || screen.search))
+            screens[label] = screen;
+    return { section: labels[view.section] ?? labels[0] ?? '', screens };
+}
+/** A stored state as a view; a section that no longer exists falls back to the first. */
+export function stateToView(state, labels) {
+    const section = labels.indexOf(state.section);
+    return {
+        section: section < 0 ? 0 : section,
+        screens: Object.fromEntries(Object.entries(state.screens).filter(([label]) => labels.includes(label))),
+    };
+}
+/** The view the last run left (undefined when there is none or the file is not valid). */
+export function readMenuView(labels, dir = userDir()) {
+    try {
+        const state = stateFile(dir).read();
+        return state ? stateToView(state, labels) : undefined;
+    }
+    catch {
+        // The state is a convenience: an unreadable file counts as none.
+        return undefined;
+    }
+}
+/** Remembers the view for the next run. Never fails the menu. */
+export function saveMenuView(view, labels, dir = userDir()) {
+    try {
+        stateFile(dir).write(viewToState(view, labels));
+    }
+    catch {
+        // Not remembering is fine.
+    }
+}

package/dist/cli/menu/menu.d.ts

@@ -1,11 +1,20 @@
 import type { Context } from '../commands/context.js';
+import { Terminal } from '../tui/index.js';
+/** What a test may replace: the terminal, the process list fetch and how often it is fetched. */
+export interface MenuOptions {
+    readonly terminal?: Terminal;
+    readonly fetchTasklist?: () => Promise<string>;
+    readonly refreshMs?: number;
+}
 export declare class Menu {
     private readonly ctx;
     private readonly runArgv;
     private readonly app;
-    constructor(ctx: Context, runArgv: (argv: string[]) => Promise<number>);
+    private readonly live;
+    constructor(ctx: Context, runArgv: (argv: string[]) => Promise<number>, options?: MenuOptions);
+    /** The status line from the facts now: only ever called by the background refresh, never by a draw or a key. */
     private status;
-    /** The tabs, in order. */
+    /** The sections, in order. */
     private shell;
     /** Runs the menu until you leave it, or until a command that takes over the terminal (attach) has run. */
     start(): Promise<number>;

package/dist/cli/menu/menu.js

@@ -1,6 +1,6 @@
-// The interactive menu (`sandbox` with no arguments): a full-screen app with seven tabs (Start, Sessions, Sandbox,
-// Apps, Settings, Accounts, Maintenance). The tabs are real screens fed by the services; only what needs the terminal
-// (attach, a start, a log) leaves the menu for a moment, one keypress from its screen.
+// The interactive menu (`sandbox` with no arguments): a full-screen app with seven sections down the left (Agents,
+// Sessions, Sandbox, Apps, Settings, Accounts, Maintenance). The sections are real screens fed by the services; only
+// what needs the terminal (attach, a start, a log) leaves the menu for a moment, one keypress from its screen.
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadConfig } from '../../core/config/index.js';
@@ -11,25 +11,38 @@ import { lookAtSandbox } from '../commands/shared-use.js';
 import { commandLine } from '../history.js';
 import { commandSpec } from '../manifest.js';
 import { AgentCommandsService, LogsService } from '../services/index.js';
-import { App, ExitRequested, Frame, Text, Theme } from '../tui/index.js';
+import { App, ExitRequested, Frame, Terminal, Text, Theme } from '../tui/index.js';
 import { AccountsPage } from './pages/accounts-page.js';
+import { AgentsPage } from './pages/agents-page.js';
 import { AppsPage } from './pages/apps-page.js';
 import { MaintenancePage } from './pages/maintenance-page.js';
 import { SandboxPage } from './pages/sandbox-page.js';
 import { SessionsPage } from './pages/sessions-page.js';
 import { SettingsPage } from './pages/settings-page.js';
-import { StartPage } from './pages/start-page.js';
-import { ConfigFile } from './settings/config-file.js';
+import { ConfigFile } from '../../app/features/settings/index.js';
 import { Draft } from './settings/draft.js';
-import { Shell } from './shell.js';
+import { LiveStatus } from './live.js';
+import { readMenuView, saveMenuView } from './memory.js';
+import { SECTION_LABELS, Shell } from './shell.js';
+/** Where the menu was last left: it opens there again (also in a later run, from menu-state.json). */
+let lastView;
 export class Menu {
     ctx;
     runArgv;
-    app = new App();
-    constructor(ctx, runArgv) {
+    app;
+    live;
+    constructor(ctx, runArgv, options = {}) {
         this.ctx = ctx;
         this.runArgv = runArgv;
-        this.app.status = () => this.status();
+        this.app = new App(options.terminal ?? new Terminal());
+        this.live = new LiveStatus({
+            fetch: options.fetchTasklist,
+            derive: () => this.status(),
+            onChange: () => this.app.requestRedraw(),
+            intervalMs: options.refreshMs,
+        });
+        this.app.status = () => this.live.line();
+        this.app.afterAction = () => this.live.refresh();
         try {
             Frame.version =
                 JSON.parse(fs.readFileSync(path.join(ctx.packageRoot, 'package.json'), 'utf8'))
@@ -39,6 +52,7 @@ export class Menu {
             /* no version shown */
         }
     }
+    /** The status line from the facts now: only ever called by the background refresh, never by a draw or a key. */
     status() {
         const folder = Theme.muted(Text.middle(process.cwd(), 70));
         if (!isSandboxRunning())
@@ -55,7 +69,7 @@ export class Menu {
             '   ' +
             folder);
     }
-    /** The tabs, in order. */
+    /** The sections, in order. */
     shell() {
         const files = {
             user: ConfigFile.user(this.ctx.loaded.configPath),
@@ -64,28 +78,33 @@ export class Menu {
         const draft = new Draft();
         const { app, ctx } = this;
         return new Shell(app, [
-            new StartPage(app, ctx),
+            new AgentsPage(app, ctx, files.user, draft),
             new SessionsPage(app, ctx),
             new SandboxPage(app, ctx),
             new AppsPage(app, files, draft, ctx.dataPath),
-            new SettingsPage(app, files, draft),
+            new SettingsPage(app, files, draft, ctx),
             new AccountsPage(app, ctx),
             new MaintenancePage(app, ctx),
         ], draft, (saved) => this.applyAgentCommands(saved));
     }
     /** Runs the menu until you leave it, or until a command that takes over the terminal (attach) has run. */
     async start() {
-        if (!process.stdin.isTTY) {
+        if (!this.app.terminal.interactive) {
             console.log('The menu needs an interactive terminal. Run sandbox --help for the commands.');
             return 1;
         }
         try {
             const shell = this.shell();
-            await shell.openTab(0);
+            await this.live.start();
+            await shell.restore(lastView ?? readMenuView(SECTION_LABELS) ?? { section: 0, screens: {} });
             for (;;) {
                 const exit = await this.app.show(shell);
+                lastView = shell.view();
+                saveMenuView(lastView, SECTION_LABELS);
                 if (exit.kind === 'quit')
                     return 0;
+                // A command (or a log) runs on its own facts, not on the menu's copy.
+                this.live.stop();
                 if (exit.kind === 'view')
                     await this.view(exit.file);
                 else {
@@ -93,6 +112,7 @@ export class Menu {
                     if (code !== undefined)
                         return code;
                 }
+                await this.live.start();
                 await shell.reload();
             }
         }
@@ -103,6 +123,7 @@ export class Menu {
             throw e;
         }
         finally {
+            this.live.stop();
             this.app.close();
         }
     }

package/dist/cli/menu/pages/accounts-page.js

@@ -1,10 +1,14 @@
-// Tab 6: saved logins for every agent. Agents on the left (each with its logins), actions on the right: save the
+// Section 6: saved logins for every agent. Agents on the left (each with its logins), actions on the right: save the
 // sandbox's login or this PC's, use one, make one the default, rename, remove.
 import { errMsg, safeText } from '../../../core/util/index.js';
 import { AccountsService } from '../../services/index.js';
 import { Theme } from '../../tui/index.js';
 import { ListPage } from './list-page.js';
 const NAME = /^[A-Za-z0-9_-]{1,40}$/;
+const SAVE_SANDBOX = '@save-sandbox';
+const SAVE_PC = '@save-pc';
+/** A saved login (not a "save a login" row or a note). */
+const isLogin = (id) => !id.startsWith('@') && !id.startsWith('info:');
 /** The list for the accounts tab. Pure. */
 export function accountsOptions(m) {
     return {
@@ -19,6 +23,26 @@ export function accountsOptions(m) {
         })),
         items: m.agents.flatMap((a) => {
             const rows = m.rows[a.name] ?? [];
+            const save = [
+                {
+                    value: SAVE_SANDBOX,
+                    label: "+ Save the sandbox's login…",
+                    category: a.name,
+                    section: 'Save a login',
+                    description: 'Saves the ' + a.name + ' login you signed in with inside the sandbox, under a name you choose.',
+                },
+                ...(a.canSavePc
+                    ? [
+                        {
+                            value: SAVE_PC,
+                            label: "+ Save this PC's login…",
+                            category: a.name,
+                            section: 'Save a login',
+                            description: 'Saves the ' + a.name + ' login of this PC, under a name you choose.',
+                        },
+                    ]
+                    : []),
+            ];
             if (!a.kept)
                 return [
                     {
@@ -28,25 +52,28 @@ export function accountsOptions(m) {
                         description: 'Sign in again in each new sandbox, or use an API key in the agent’s environment.',
                     },
                 ];
-            return rows.map((r) => ({
-                value: a.name + ':' + r.name,
-                label: r.name,
-                category: a.name,
-                hint: (r.isActive ? Theme.ok('in the sandbox') : '') +
-                    (r.isActive && r.isDefault ? Theme.muted(' · ') : '') +
-                    (r.isDefault ? Theme.accent('default') : ''),
-                description: 'Enter makes the sandbox use this login.',
-                details: [
-                    Theme.muted('Agent  ') + a.name,
-                    Theme.muted('Email  ') + safeText(r.email ?? '-'),
-                    Theme.muted('Saved  ') + r.savedAt.slice(0, 16).replace('T', ' '),
-                ],
-            }));
+            return [
+                ...save,
+                ...rows.map((r) => ({
+                    value: a.name + ':' + r.name,
+                    label: r.name,
+                    category: a.name,
+                    section: 'Saved logins',
+                    hint: (r.isActive ? Theme.ok('in the sandbox') : '') +
+                        (r.isActive && r.isDefault ? Theme.muted(' · ') : '') +
+                        (r.isDefault ? Theme.accent('default') : ''),
+                    description: 'Enter makes the sandbox use this login.',
+                    details: [
+                        Theme.muted('Agent  ') + a.name,
+                        Theme.muted('Email  ') + safeText(r.email ?? '-'),
+                        Theme.muted('Saved  ') + r.savedAt.slice(0, 16).replace('T', ' '),
+                    ],
+                })),
+            ];
         }),
-        empty: "No saved logins. Sign in inside the sandbox, then press s to save that login (p saves this PC's).",
+        empty: 'No agents.',
         actions: accountActions(m.agents),
-        enterLabel: 'use',
-        escapeLabel: 'quit',
+        enterLabel: (_category, id) => (id === SAVE_SANDBOX || id === SAVE_PC ? 'save' : id && isLogin(id) ? 'use' : ''),
     };
 }
 function accountActions(agents) {
@@ -55,11 +82,11 @@ function accountActions(agents) {
         if (!agent?.kept)
             return [];
         return [
-            { key: 's', label: 'save sandbox', importance: 1 },
-            ...(agent.canSavePc ? [{ key: 'p', label: 'save PC', importance: 1 }] : []),
-            { key: 'd', label: 'default', importance: 1 },
-            { key: 'r', label: 'rename', importance: 2 },
-            { key: 'x', label: 'remove', importance: 1 },
+            { key: 's', label: 'save sandbox login', importance: 3 },
+            ...(agent.canSavePc ? [{ key: 'p', label: 'save PC login', importance: 3 }] : []),
+            { key: 'd', label: 'make default', importance: 1, applies: isLogin },
+            { key: 'r', label: 'rename', importance: 2, applies: isLogin },
+            { key: 'x', label: 'remove', importance: 1, applies: isLogin },
         ];
     };
 }
@@ -94,7 +121,7 @@ export class AccountsPage extends ListPage {
     }
     static nameOf(value) {
         const i = value?.indexOf(':') ?? -1;
-        return value && i >= 0 && !value.startsWith('info:') ? value.slice(i + 1) : undefined;
+        return value && i >= 0 && isLogin(value) ? value.slice(i + 1) : undefined;
     }
     async act(result) {
         const agent = this.agentNow();
@@ -102,6 +129,8 @@ export class AccountsPage extends ListPage {
         try {
             if (result.kind === 'action' && (result.key === 's' || result.key === 'p'))
                 return await this.save(agent, result.key === 'p');
+            if (result.kind === 'pick' && (result.value === SAVE_SANDBOX || result.value === SAVE_PC))
+                return await this.save(agent, result.value === SAVE_PC);
             if (result.kind === 'pick' && name)
                 return await this.use(agent, name);
             if (result.kind === 'action' && name) {
@@ -154,6 +183,8 @@ export class AccountsPage extends ListPage {
     async use(agent, name) {
         const account = this.service.activate(name, agent);
         let note = Theme.ok(Theme.glyph.ok + ' The sandbox now uses "' + account.name + '" for ' + agent + '.');
+        if (account.note)
+            note += ' ' + safeText(account.note);
         if (this.service.hasRunningSessions(agent) &&
             (await this.app.ask('Restart the running ' + agent + ' sessions?', ['They restart and continue their conversation where the agent can, now under the new login.'], 'Restart')))
             note += ' ' + safeText(await this.service.restart(agent));

package/dist/cli/menu/pages/agents-page.d.ts

@@ -0,0 +1,68 @@
+import type { Context } from '../../commands/context.js';
+import { type App, type Category, type ListAction, type ListOptions, type ListResult } from '../../tui/index.js';
+import type { ConfigFile } from '../../../app/features/settings/index.js';
+import type { Draft } from '../settings/draft.js';
+import { ListPage, type Outcome } from './list-page.js';
+export type WindowChoice = 'config' | 'hide' | 'show';
+export interface AgentsModel {
+    readonly folder: string;
+    readonly defaultAgent: string;
+    readonly agents: readonly {
+        readonly name: string;
+        readonly ready: boolean;
+    }[];
+    readonly last: string[] | undefined;
+    readonly attach: boolean;
+    readonly window: WindowChoice;
+    /** Agents that can be run on this PC without the sandbox (see hostAgentsToShow). */
+    readonly hostAgents: readonly string[];
+    /** The agents you added yourself: only these can be removed (the built-in ones stay). */
+    readonly removable?: readonly string[];
+}
+/** The agents of `harnesses` that are not built in. Pure. */
+export declare function addedAgents(names: readonly string[]): string[];
+/** The keys of the Start category: make an agent the default, remove one you added. Pure. */
+export declare function agentActions(m: Pick<AgentsModel, 'defaultAgent' | 'removable'>): ListAction<string>[];
+/**
+ * The "not sandboxed" entries: only while agent commands are on (typing the agent then starts the sandbox, so a way to
+ * run the real one is needed), one per agent found installed on this PC.
+ */
+export declare function hostAgentsToShow(enabled: boolean, found: readonly {
+    harness: string;
+}[]): string[];
+/** The command line a start stands for. Pure. */
+export declare function startArgv(m: AgentsModel, agent: string, cwd: string): string[];
+/** The categories of the agents section; "On this PC" only when there is something in it. Pure. */
+export declare function agentCategories(m: Pick<AgentsModel, 'folder' | 'hostAgents'>): Category[];
+/** The list for the agents section. Pure. */
+export declare function agentsOptions(m: AgentsModel, cwd?: string): ListOptions<string>;
+export declare class AgentsPage extends ListPage<string> {
+    private readonly ctx;
+    /** Your own config file and its unsaved changes: where "Add an agent" writes to. */
+    private readonly file;
+    private readonly draft;
+    readonly label = "Agents";
+    private attach;
+    private window;
+    private folder;
+    private model;
+    /** What load() looked up (programs on PATH, the history file): not asked again for every list that is built. */
+    private facts;
+    constructor(app: App, ctx: Context, 
+    /** Your own config file and its unsaved changes: where "Add an agent" writes to. */
+    file: ConfigFile, draft: Draft);
+    /** Every agent: the configured ones, and any added in Settings that is not saved yet. */
+    private harnesses;
+    /** Is this agent already in the sandbox's persistent storage (so starting it needs no install)? */
+    private installed;
+    private current;
+    /** The cursor starts on the default agent. */
+    protected initialFocus(): string;
+    protected load(): Promise<void>;
+    protected options(): ListOptions<string>;
+    protected act(result: ListResult<string>): Promise<Outcome<string>>;
+    /** Make default (d) and Remove (x) on the highlighted agent. */
+    private action;
+    /** "Add an agent…": the new agent shows in the list, with the cursor on it. */
+    private add;
+}