windows-development-sandbox 1.12.0 → 1.13.2

package/dist/cli/menu/live.js

@@ -1,14 +1,42 @@
 // 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.
+// read the last copy, 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.
+//
+// The process list (tasklist) is the expensive part: on a busy PC one run costs a large share of a second of CPU. So it
+// is not fetched on a timer: while a sandbox runs, its processes are checked by id (no program started) and the list is
+// fetched again only when one of them has ended; while none runs, the list is fetched less and less often while nothing
+// changes (and again soon after a key press, someone is looking, or when the data folder's run folder changes, a start
+// writes there), and after every action.
 import { sandboxStatus } from '../../app/features/sandbox/index.js';
-import { readTasklistAsync, useTasklistCache } from '../../host/sandbox/index.js';
+import { insideSandbox, readTasklistAsync, sandboxPids, 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;
+/** While no sandbox runs, nobody presses a key and the data folder is quiet, the list is fetched this seldom. */
+const DEFAULT_IDLE_MAX_MS = 30000;
+/** The gap before the next process list after `unchanged` lists in a row found the same: doubling, up to `max`. */
+export function listGap(unchanged, base, max) {
+    return Math.min(max, base * 2 ** Math.max(0, Math.min(unchanged, 16)));
+}
+/** A process with this id exists (EPERM: it does, but belongs to someone else, such as the sandbox's own service). */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
 export class LiveStatus {
     o;
     tasklist;
+    /** The sandbox's processes in the last list (none: no sandbox was running). */
+    pids = [];
+    fetchedAt = 0;
+    /** Lists in a row that found the same answer (the gap to the next one grows with it). */
+    unchanged = 0;
+    /** The signal when the list was last fetched. */
+    signalled = '';
     text = '';
     timer;
     pending;
@@ -16,30 +44,72 @@ export class LiveStatus {
     constructor(o) {
         this.o = o;
     }
+    get interval() {
+        return this.o.intervalMs ?? DEFAULT_INTERVAL_MS;
+    }
     /** 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;
-            }
-        })();
+        // The next gap starts again from the shortest one.
+        this.unchanged = -1;
+        return this.fetch();
+    }
+    fetch() {
+        // Cleared in a callback, so also after a fetch that finished without waiting for anything.
+        this.pending ??= this.load().finally(() => (this.pending = undefined));
         return this.pending;
     }
+    async load() {
+        try {
+            const needed = (this.o.needsList ?? (() => !insideSandbox()))();
+            this.signalled = this.o.signal?.() ?? '';
+            // Not needed: an empty copy, so nothing runs tasklist itself either.
+            const list = needed ? 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;
+            const pids = sandboxPids(list);
+            const same = this.tasklist !== undefined && pids.length > 0 === this.pids.length > 0;
+            this.unchanged = same ? this.unchanged + 1 : 0;
+            this.tasklist = list;
+            this.pids = pids;
+            this.fetchedAt = Date.now();
+            this.derive();
+        }
+        catch {
+            // The line keeps what it showed; the next refresh tries again.
+        }
+    }
+    /** Whether the process list may have changed since it was fetched (checked on every tick, cheaply). */
+    listDue(now) {
+        if (this.tasklist === undefined)
+            return true;
+        if (this.pids.length)
+            return !this.pids.every((pid) => (this.o.alive ?? processAlive)(pid));
+        if (this.o.signal && this.o.signal() !== this.signalled)
+            return true;
+        return now - this.fetchedAt >= listGap(this.unchanged, this.interval, this.o.idleMaxMs ?? DEFAULT_IDLE_MAX_MS);
+    }
+    tick() {
+        if (this.pending)
+            return;
+        if (this.listDue(Date.now()))
+            void this.fetch();
+        else
+            this.derive();
+    }
+    /** A key was pressed: someone is looking, so a list older than one interval is fetched again (after the draw). */
+    touch() {
+        if (!this.running || this.pending || this.pids.length || Date.now() - this.fetchedAt < this.interval)
+            return;
+        setImmediate(() => {
+            if (this.running)
+                void this.refresh();
+        });
+    }
     derive() {
         const next = this.o.derive();
         if (next === this.text)
@@ -54,7 +124,7 @@ export class LiveStatus {
             return;
         this.running = true;
         useTasklistCache(() => this.tasklist);
-        this.timer = setInterval(() => void this.refresh(), this.o.intervalMs ?? DEFAULT_INTERVAL_MS);
+        this.timer = setInterval(() => this.tick(), this.interval);
         this.timer.unref();
         await this.refresh();
     }
@@ -65,5 +135,6 @@ export class LiveStatus {
         this.timer = undefined;
         useTasklistCache(null);
         this.tasklist = undefined;
+        this.pids = [];
     }
 }

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

@@ -1,10 +1,11 @@
 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. */
+/** What a test may replace: the terminal, the process list fetch, how often it is fetched and the process check. */
 export interface MenuOptions {
     readonly terminal?: Terminal;
     readonly fetchTasklist?: () => Promise<string>;
     readonly refreshMs?: number;
+    readonly processAlive?: (pid: number) => boolean;
 }
 export declare class Menu {
     private readonly ctx;

package/dist/cli/menu/menu.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { loadConfig } from '../../core/config/index.js';
 import { errMsg } from '../../core/util/index.js';
 import { SandboxChannel } from '../../host/channel/index.js';
+import { RunDir } from '../../shared/channel/index.js';
 import { isSandboxRunning } from '../../host/sandbox/index.js';
 import { lookAtSandbox } from '../commands/shared-use.js';
 import { commandLine } from '../history.js';
@@ -26,6 +27,15 @@ 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;
+/** When the data folder's run folder last changed (a start writes there): a stat, never a read of what is in it. */
+function runFolderStamp(dataPath) {
+    try {
+        return String(fs.lstatSync(new RunDir(dataPath).root).mtimeMs);
+    }
+    catch {
+        return '';
+    }
+}
 export class Menu {
     ctx;
     runArgv;
@@ -40,9 +50,12 @@ export class Menu {
             derive: () => this.status(),
             onChange: () => this.app.requestRedraw(),
             intervalMs: options.refreshMs,
+            alive: options.processAlive,
+            signal: () => runFolderStamp(ctx.dataPath),
         });
         this.app.status = () => this.live.line();
         this.app.afterAction = () => this.live.refresh();
+        this.app.onKey = () => this.live.touch();
         try {
             Frame.version =
                 JSON.parse(fs.readFileSync(path.join(ctx.packageRoot, 'package.json'), 'utf8'))
@@ -95,7 +108,8 @@ export class Menu {
         }
         try {
             const shell = this.shell();
-            await this.live.start();
+            // The first screen does not wait for the process list: the pages show "Loading…" until it is there.
+            this.app.ready = this.live.start();
             await shell.restore(lastView ?? readMenuView(SECTION_LABELS) ?? { section: 0, screens: {} });
             for (;;) {
                 const exit = await this.app.show(shell);
@@ -112,7 +126,7 @@ export class Menu {
                     if (code !== undefined)
                         return code;
                 }
-                await this.live.start();
+                this.app.ready = this.live.start();
                 await shell.reload();
             }
         }

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

@@ -57,6 +57,11 @@ export declare abstract class ListPage<T> implements Page {
     protected ticked(): T[];
     /** Loads the data again; a slow load does not hold up the keys (the tab keeps what it showed, then updates). */
     open(): Promise<void>;
+    /**
+     * The section came on screen again: it shows what it had at once and loads the data again after that screen is
+     * drawn (the list is rebuilt on the entry and search the user is on). The first time, it is open().
+     */
+    show(): Promise<void>;
     /**
      * Loads the data and waits for it at most QUICK_LOAD_MS. In time, the list is built here (`build`) or by the caller;
      * later, the list is built when the data arrives, on the entry and search the user has moved to meanwhile.

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

@@ -97,6 +97,23 @@ export class ListPage {
     async open() {
         await this.reload(true);
     }
+    /**
+     * The section came on screen again: it shows what it had at once and loads the data again after that screen is
+     * drawn (the list is rebuilt on the entry and search the user is on). The first time, it is open().
+     */
+    async show() {
+        if (!this.loaded)
+            return this.open();
+        const mine = ++this.generation;
+        setImmediate(() => {
+            if (mine !== this.generation)
+                return;
+            void this.loadData().then(() => {
+                if (mine === this.generation)
+                    this.rebuildLate();
+            });
+        });
+    }
     /**
      * Loads the data and waits for it at most QUICK_LOAD_MS. In time, the list is built here (`build`) or by the caller;
      * later, the list is built when the data arrives, on the entry and search the user has moved to meanwhile.
@@ -125,6 +142,8 @@ export class ListPage {
     }
     async loadData() {
         try {
+            // The first screen is drawn before the menu's facts (the process list) are known; loads wait for them.
+            await this.app.ready;
             await this.load();
         }
         catch (e) {

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

@@ -0,0 +1,19 @@
+import { type AnyView, type Caller } from '../../app/kernel/index.js';
+import type { Context } from '../commands/context.js';
+import type { RemoteClient } from '../services/remote-client.js';
+import { type App } from '../tui/index.js';
+/** The views of the owner's program this role may open (remote access itself is the owner's). */
+export declare function remoteViews(role: Caller): AnyView[];
+export declare class RemoteMenu {
+    private readonly app;
+    private readonly client;
+    private readonly owner;
+    private readonly caller;
+    private readonly operations;
+    constructor(app: App, ctx: Context, client: RemoteClient, owner: string, caller: Caller);
+    private title;
+    /** The list of areas, until Esc. */
+    start(): Promise<void>;
+    private page;
+    private showView;
+}

package/dist/cli/menu/remote-menu.js

@@ -0,0 +1,108 @@
+// `sandbox remote`: the menu drawn over another Windows user's program (docs/design/remote-access.md). Every view the
+// web UI has is drawn by the menu's own renderer (menuView) from the shared core's pure definitions; its queries and
+// operations run on the owner's web UI over the RPC socket, which checks the role this user was given and writes each
+// action to the owner's audit log. Nothing here runs on this user's own settings or data.
+import { NAV, navViews, viewById } from '../../app/features/defs.js';
+import { NO_QUESTIONS, allows, viewInputs, } from '../../app/kernel/index.js';
+import { errMsg, safeText } from '../../core/util/index.js';
+import { Theme } from '../tui/index.js';
+import { MenuOperations } from './io-menu.js';
+import { menuView } from './render-view.js';
+/** The views of the owner's program this role may open (remote access itself is the owner's). */
+export function remoteViews(role) {
+    return navViews(NAV)
+        .map((id) => viewById(id))
+        .filter((v) => v !== undefined)
+        .filter((v) => Object.values(v.queries).every((q) => allows(role, q.access ?? 'view')));
+}
+export class RemoteMenu {
+    app;
+    client;
+    owner;
+    caller;
+    operations;
+    constructor(app, ctx, client, owner, caller) {
+        this.app = app;
+        this.client = client;
+        this.owner = owner;
+        this.caller = caller;
+        this.operations = new MenuOperations(app, ctx, (id, input, io) => client.run(id, input, io));
+    }
+    title() {
+        return safeText(this.owner) + "'s sandbox";
+    }
+    /** The list of areas, until Esc. */
+    async start() {
+        const views = remoteViews(this.caller);
+        const role = this.caller.kind === 'owner' ? 'owner' : this.caller.role;
+        let at;
+        for (;;) {
+            const picked = await this.app.list({
+                path: [this.title()],
+                intro: [
+                    'You are using ' + safeText(this.owner) + "'s program with the role " + role + '.',
+                    'What you do runs as ' + safeText(this.owner) + ' and is written to their audit log.',
+                ],
+                items: views.map((v) => ({ value: v.id, label: v.title, description: v.summary })),
+                startAt: at,
+                escapeLabel: 'quit',
+                enterLabel: 'open',
+            });
+            if (picked.kind !== 'pick')
+                return;
+            at = picked.value;
+            const view = views.find((v) => v.id === picked.value);
+            if (view)
+                await this.showView(view);
+        }
+    }
+    async page(view) {
+        const inputs = viewInputs(view, {});
+        const data = {};
+        for (const [name, query] of Object.entries(view.queries))
+            data[name] = await this.client.run(query.id, inputs[name], NO_QUESTIONS);
+        return view.build(data, {});
+    }
+    async showView(view) {
+        let notice;
+        for (;;) {
+            let page;
+            try {
+                page = await this.page(view);
+            }
+            catch (e) {
+                await this.app.message({ path: [this.title(), view.title], lines: [safeText(errMsg(e))], tone: 'error' });
+                return;
+            }
+            const mv = menuView(page);
+            const result = await this.app.list({
+                path: [this.title(), view.title],
+                intro: page.notice ? [safeText(page.notice.text)] : undefined,
+                items: mv.items,
+                actions: mv.actions,
+                enterLabel: mv.enterLabel,
+                notice,
+                empty: page.empty?.text,
+            });
+            if (result.kind === 'back')
+                return;
+            const chosen = mv.resolve(result);
+            notice = undefined;
+            if (!chosen || chosen.kind === 'refresh')
+                continue;
+            const action = chosen.action;
+            if (action.kind === 'link') {
+                notice =
+                    action.target.kind === 'terminal'
+                        ? Theme.muted('Attach to it from your own terminal: sandbox attach ' + safeText(action.target.session))
+                        : Theme.muted('That opens on ' + safeText(this.owner) + "'s side only.");
+                continue;
+            }
+            const done = await this.operations.perform(action, [this.title(), view.title], (text) => {
+                notice = text;
+                this.app.redraw();
+            });
+            notice = done.notice;
+        }
+    }
+}

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

@@ -47,6 +47,8 @@ export interface Page {
     setFocus(list: boolean): void;
     /** The section was opened (or the shell came back from a command): load what it shows again. */
     open(): Promise<void>;
+    /** The section came on screen again: show what it had at once and load it again in the background (default open). */
+    show?(): Promise<void>;
     render(size: Size): FrameParts;
     /** A `quit` from the page means "Esc with nothing left to close": the shell moves to the navigation. */
     handle(key: Key): Promise<Step<ShellExit>> | Step<ShellExit>;

package/dist/cli/menu/shell.js

@@ -76,7 +76,7 @@ export class Shell {
         this.remember();
         this.active = Math.max(0, Math.min(this.pages.length - 1, index));
         this.page.setFocus(this.focus === 'list');
-        await this.page.open();
+        await (this.page.show ?? this.page.open).call(this.page);
         if (this.restored.has(this.active))
             return;
         this.restored.add(this.active);

package/dist/cli/menu/views.js

@@ -18,6 +18,7 @@ import { updatesView } from '../../app/features/updates/index.js';
 import { webView } from '../../app/features/web/index.js';
 import { vpnView } from '../../app/features/vpn/index.js';
 import { githubView } from '../../app/features/github/index.js';
+import { accessView } from '../../app/features/access/index.js';
 export const MENU_VIEWS = [
     { view: agentsView, section: 'Agents' },
     { view: sessionsView, section: 'Sessions' },
@@ -34,6 +35,7 @@ export const MENU_VIEWS = [
     { view: updatesView, section: 'Maintenance' },
     { view: engineView, section: 'Maintenance' },
     { view: webView, section: 'Maintenance' },
+    { view: accessView, section: 'Maintenance' },
     // The Settings page draws the VPN row itself (its login is staged with the settings); the view lists its operations.
     { view: vpnView, section: 'Settings' },
     // The same for the GitHub token row.

package/dist/cli/operations/handler.js

@@ -1,6 +1,7 @@
 // Runs a definition as a command: its input from the command line, its questions on the terminal, and its output as
 // --json, as the definition's one-line text, or as the page of the view that shows it. A declined question prints
-// "Nothing changed." and exits 1, as the commands always have.
+// "Nothing changed." and exits 1, as the commands always have. An operation that opens a session's terminal (a new
+// shell) attaches this terminal to it afterwards.
 import { VIEWS } from '../../app/features/defs.js';
 import { runDefinition } from '../../app/registry.js';
 import { Cancelled } from '../../app/kernel/index.js';
@@ -33,6 +34,16 @@ function printOutput(def, output, input) {
     else
         console.log(JSON.stringify(output, null, 2));
 }
+/** Attaches this terminal to the session an operation opened (in a script: says how to). */
+async function attachOpened(ctx, session) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        nextStep('sandbox attach ' + session);
+        return 0;
+    }
+    // Loaded when needed: attach reaches the launch commands, which reach this handler (no import cycle).
+    const { attach } = await import('../commands/sessions/attach.js');
+    return attach({ ...ctx, options: { ...ctx.options, positionals: [session] } });
+}
 /** The command for a definition. */
 export function definitionHandler(def) {
     return async (ctx) => {
@@ -47,6 +58,9 @@ export function definitionHandler(def) {
                 return code;
             }
             printOutput(def, output, def.input.parse(input));
+            const opened = def.kind === 'operation' ? def.opens?.(output) : undefined;
+            if (opened?.kind === 'terminal')
+                return attachOpened(ctx, opened.session);
             return code;
         }
         catch (e) {

package/dist/cli/services/accounts-service.d.ts

@@ -31,6 +31,13 @@ export declare class AccountsService {
     save(name: string, fromHost: boolean, agent?: string): AccountRef;
     /** Makes the sandbox use a saved login. Running sessions keep the old one until restart(). */
     activate(name: string, agent?: string): AccountRef;
+    /** The agent's default login, if it keeps logins and one is set. */
+    defaultName(agent?: string): string | null;
+    /**
+     * Makes the sandbox use `wanted`, else the agent's default, when it uses another login now (a launch, or a session
+     * started with --account). Returns the login it then uses; null when the agent keeps no login or none is saved.
+     */
+    ensure(agent: string, wanted: string | null): string | null;
     /** Whether a session of this agent is running that would pick up a new login on restart. */
     hasRunningSessions(agent?: string): boolean;
     /** Restarts the agent's running sessions (conversations continue); returns the sandbox's own message. */

package/dist/cli/services/accounts-service.js

@@ -74,6 +74,26 @@ export class AccountsService {
         store.activate(this.ctx.dataPath, name, stateDir);
         return { name, email: null };
     }
+    /** The agent's default login, if it keeps logins and one is set. */
+    defaultName(agent = CLAUDE) {
+        return agent === CLAUDE ? this.claude.defaultName() : this.other(agent).store.defaultName();
+    }
+    /**
+     * Makes the sandbox use `wanted`, else the agent's default, when it uses another login now (a launch, or a session
+     * started with --account). Returns the login it then uses; null when the agent keeps no login or none is saved.
+     */
+    ensure(agent, wanted) {
+        if (!this.agents().some((a) => a.name === agent && a.kept))
+            return null;
+        const name = wanted ?? this.defaultName(agent);
+        if (!name)
+            return this.activeName(agent);
+        if (name !== this.activeName(agent))
+            this.activate(name, agent);
+        else if (agent === CLAUDE)
+            this.claude.syncPlugins(this.ctx.dataPath);
+        return name;
+    }
     /** Whether a session of this agent is running that would pick up a new login on restart. */
     hasRunningSessions(agent = CLAUDE) {
         return (isSandboxRunning() && new SandboxChannel(this.ctx.dataPath).runningSessions().some((s) => s.harness === agent));

package/dist/cli/services/remote-client.d.ts

@@ -0,0 +1,16 @@
+import { type OperationIO } from '../../app/kernel/index.js';
+export declare class RemoteClient {
+    private readonly socket;
+    private readonly pending;
+    private next;
+    private constructor();
+    /** Trades the one-time token for a sign-in cookie, then opens the RPC socket. */
+    static connect(port: number, token: string): Promise<RemoteClient>;
+    private receive;
+    private send;
+    /** Runs a definition on the owner's side (a query or an operation) and returns its output. */
+    run(id: string, input: unknown, io: OperationIO): Promise<unknown>;
+    close(): void;
+}
+/** Connects, or fails with the reason and what to do. */
+export declare function remoteClient(port: number, token: string): Promise<RemoteClient>;