windows-development-sandbox 1.18.4 → 1.23.0

package/dist/app/features/settings/settings-rows.js

@@ -6,6 +6,7 @@ import { NEVER_LOOSER } from '../../../core/local-config/index.js';
 import { redactSecrets } from '../../../core/schema/index.js';
 import { fail } from '../../../core/util/index.js';
 import { closest } from '../../../cli/validate.js';
+import { isToolchainReady } from '../../../shared/readiness.js';
 import { fieldOf } from '../../kernel/index.js';
 import { categoryOf, labelOf, nameOf } from './categories.def.js';
 /** Every editable setting of a file, each in its category (settings covered by another section are left out). */
@@ -24,7 +25,10 @@ export function settingsOf(file) {
                     section: several && category.id !== 'general' ? nameOf(top) : undefined,
                 },
             ];
-        return node.leaves([top]).map(({ key, node: leaf }) => {
+        return node
+            .leaves([top])
+            .filter(({ key }) => top !== 'toolchains' || isToolchainReady(key[1]))
+            .map(({ key, node: leaf }) => {
             const heading = [
                 several ? nameOf(top) : undefined,
                 key.length > 2 ? key.slice(1, -1).map(nameOf).join(' › ') : undefined,
@@ -98,5 +102,5 @@ export function findSetting(file, key) {
         '"' +
         (file.isProject ? ' a project can set' : '') +
         '.' +
-        (hint ? ' Did you mean ' + hint + '?' : ''), 'Settings are named like sandbox.memoryMb. See them all with: sandbox config show');
+        (hint ? ' Did you mean ' + hint + '?' : ''), 'Settings are named like sandbox.memoryMb. Search the Settings page by name to find one.');
 }

package/dist/app/features/settings/settings.def.js

@@ -203,7 +203,7 @@ function dataFolderItem(folder) {
         label: 'Data folder',
         hint: folder,
         cells: { setting: 'storage.root', value: folder },
-        description: 'Where your tools, logins, history and logs are kept between sandboxes. Move it with sandbox storage move <folder>.',
+        description: 'Where your tools, logins, history and logs are kept between sandboxes. Maintenance > Storage moves it.',
         primary: action(changeDataFolder, {}, { label: 'Data folder', verb: 'change' }),
     };
 }

package/dist/app/features/settings/settings.run.d.ts

@@ -1,5 +1,7 @@
+import type { Config } from '../../../core/types.js';
 import { type AppContext } from '../../context.js';
 import { type SettingsFiles } from './settings-rows.js';
+import { type Scope } from './settings.def.js';
 /** The file `sandbox config export` writes when none is named. */
 export declare const DEFAULT_EXPORT = "sandbox-settings.json";
 /** Your own settings file (the one --config names) and the project file of the current folder. */
@@ -48,6 +50,12 @@ export declare const getSettingRun: import("../../kernel/define.js").Implementat
 /** The file of a scope, and the setting a key names in it. */
 /** incoming with every *** that stands where saved has a text replaced by that saved text. Pure. */
 export declare function keepShownSecrets(saved: unknown, incoming: unknown): unknown;
+/** What brings this PC in line with a changed agentCommands setting (the real service, or a fake in a test). */
+export interface AgentCommandsReconciler {
+    reconcile(config: Config): unknown;
+}
+/** After your own settings change: a key under agentCommands also changes this PC (files, PATH), on every surface. */
+export declare function applyAgentCommandsChange(ctx: AppContext, scope: Scope, key: string, service?: AgentCommandsReconciler): void;
 export declare const setSettingRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
     scope: import("zod").ZodDefault<import("zod").ZodEnum<{
         project: "project";

package/dist/app/features/settings/settings.run.js

@@ -7,6 +7,7 @@ import { loadConfig } from '../../../core/config/index.js';
 import { REDACTED, redactSecrets } from '../../../core/schema/index.js';
 import { fail, safeText, writeJson } from '../../../core/util/index.js';
 import { hereDir } from '../../../cli/commands/projects/here.js';
+import { AgentCommandsService } from '../../../cli/services/agent-commands-service.js';
 import { implement } from '../../context.js';
 import { allowedText, cancelled, valueFromText } from '../../kernel/index.js';
 import { CATEGORIES } from './categories.def.js';
@@ -66,6 +67,12 @@ function target(ctx, scope, name) {
     const file = settingsFiles(ctx)[scope];
     return { ...findSetting(file, name), file };
 }
+/** After your own settings change: a key under agentCommands also changes this PC (files, PATH), on every surface. */
+export function applyAgentCommandsChange(ctx, scope, key, service = new AgentCommandsService(ctx)) {
+    if (scope !== 'user' || !/^agentCommands(\.|$)/.test(key))
+        return;
+    service.reconcile(freshConfig(ctx));
+}
 export const setSettingRun = implement(setSetting, (ctx, input) => {
     const { key, node, file } = target(ctx, input.scope, input.key);
     if (node.isSection)
@@ -81,6 +88,7 @@ export const setSettingRun = implement(setSetting, (ctx, input) => {
     const outcome = file.set(key, value);
     if (typeof outcome === 'object')
         fail('Could not change ' + input.key + ': ' + outcome.problems.join('; '), 'Nothing was written.');
+    applyAgentCommandsChange(ctx, input.scope, input.key);
     return {
         key: input.key,
         changed: outcome === 'saved',
@@ -96,6 +104,7 @@ export const resetSettingRun = implement(resetSetting, (ctx, input) => {
     const outcome = file.set(key, undefined);
     if (typeof outcome === 'object')
         fail('Could not reset ' + input.key + ': ' + outcome.problems.join('; '), 'Nothing was written.');
+    applyAgentCommandsChange(ctx, input.scope, input.key);
     return {
         key: input.key,
         changed: outcome === 'saved',
@@ -112,12 +121,12 @@ function freshConfig(ctx) {
 function readImport(config, file) {
     const source = path.resolve(file);
     if (!fs.existsSync(source))
-        fail('There is no file ' + source + '.', 'Give the path of a file made by sandbox config export.');
+        fail('There is no file ' + source + '.', 'Give the path of a file made by Export settings.');
     if (fs.statSync(source).size > MAX_BYTES)
         fail(source + ' is too big to be a settings file.');
     const plan = planImport(fs.readFileSync(source, 'utf8'), config);
     if (plan.problems.length)
-        fail(source + ' is not valid settings:\n  ' + plan.problems.map(safeText).join('\n  '), 'Nothing was changed. Fix the file, or export a new one with: sandbox config export');
+        fail(source + ' is not valid settings:\n  ' + plan.problems.map(safeText).join('\n  '), 'Nothing was changed. Fix the file, or export a new one with Export settings.');
     return plan;
 }
 /** Writes the planned changes to your settings file (comments stay); returns how many settings changed. */
@@ -151,7 +160,7 @@ export const importConfigRun = implement(importConfig, async (ctx, input, io) =>
     const file = input.settingsFile ??
         (await io.path({
             title: 'Which settings file',
-            lines: ['A file made by Export settings (or sandbox config export).'],
+            lines: ['A file made by Export settings (or one exported on the command line).'],
             pathKind: 'file',
         }));
     if (file === undefined)

package/dist/app/features/storage/storage.run.js

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { userConfigPath, userDir } from '../../../core/config/index.js';
 import { humanBytes } from '../../../core/disk.js';
-import { expandPath, fail } from '../../../core/util/index.js';
+import { expandPath, fail, failWith } from '../../../core/util/index.js';
 import { requireOnPc } from '../../../cli/commands/context.js';
 import { StorageService } from '../../../cli/services/index.js';
 import { isSandboxRunning, realContainedDeps } from '../../../host/sandbox/index.js';
@@ -26,7 +26,11 @@ function requireAvailable() {
 }
 function requireNoSandbox() {
     if (isSandboxRunning())
-        fail('A sandbox is running.', 'Close it (sandbox stop) first: the folders in the image are in use.');
+        failWith('A sandbox is running.', 'Stop it first: the folders in the image are in use.', {
+            op: 'sandbox.stop',
+            label: 'Stop the sandbox',
+            cli: 'sandbox stop',
+        });
 }
 function storageFor(ctx) {
     const { config } = ctx.loaded;
@@ -122,7 +126,7 @@ async function useData(io, service, from, to, ask) {
             cancelled('Nothing was changed.');
     }
     service.use(to);
-    return 'Your data is now looked for in ' + to + '. Move it later with: sandbox storage move <folder>';
+    return 'Your data is now looked for in ' + to + '. Move it later from Maintenance > Storage.';
 }
 export const showStorageRun = implement(showStorage, async (ctx, input, io) => {
     requireOnPc('storage');
@@ -153,7 +157,12 @@ export const moveStorageRun = implement(moveStorage, async (ctx, input, io) => {
         ? expandPath(input.folder, process.cwd())
         : await chooseFolder(io, service, 'move', 'Nothing was moved.');
     if (!fs.existsSync(from))
-        fail('There is nothing to move: ' + from + ' does not exist.', 'Use sandbox storage use ' + to + ' to switch.');
+        failWith('There is nothing to move: ' + from + ' does not exist.', 'Switch to ' + to + ' without moving instead.', {
+            op: 'storage.use',
+            input: { folder: to },
+            label: 'Use ' + to,
+            cli: 'sandbox storage use ' + to,
+        });
     return moveData(io, service, from, to, input.keepOld, true);
 });
 export const useStorageRun = implement(useStorage, async (ctx, input, io) => {
@@ -271,7 +280,7 @@ export const containedOnRun = implement(containedOn, async (ctx, _input, io) =>
         noTerminal: { message: NO_TERMINAL, fix: 'Add --yes to turn it on without asking.' },
     });
     if (!turnOn)
-        fail('Nothing was changed.', 'Run sandbox storage contained on when you want it.');
+        fail('Nothing was changed.', 'Turn contained storage on when you want it.');
     io.progress('Making and mounting the image (Windows asks for permission)');
     const mount = await storage.acquire({ id: 'cli', pid: process.pid }, { create: true });
     try {
@@ -293,7 +302,7 @@ export const containedOnRun = implement(containedOn, async (ctx, _input, io) =>
                     io.log(note, 'warn');
             }
             else
-                io.log('They stay where they are and are not used: tools are downloaded again into the image. Delete them later with sandbox data clean.');
+                io.log('They stay where they are and are not used: tools are downloaded again into the image. Delete them later in Maintenance > Data.');
         }
         writeContainedSetting(configFile, 'vhdx');
     }
@@ -301,9 +310,9 @@ export const containedOnRun = implement(containedOn, async (ctx, _input, io) =>
         io.progress('Dismounting the image (Windows asks for permission)');
         const done = await storage.release('cli');
         if (!done.dismounted)
-            io.log('The image stays mounted (' + (done.note ?? '') + '). sandbox repair dismounts it.', 'warn');
+            io.log('The image stays mounted (' + (done.note ?? '') + '). Repairing from Health dismounts it.', 'warn');
     }
-    return { message: 'Contained storage is on. sandbox launch mounts the image first.' };
+    return { message: 'Contained storage is on. The next sandbox mounts the image first.' };
 });
 export const containedOffRun = implement(containedOff, async (ctx, _input, io) => {
     requireOnPc('storage');
@@ -345,7 +354,7 @@ export const containedOffRun = implement(containedOff, async (ctx, _input, io) =
         io.progress('Dismounting the image (Windows asks for permission)');
         const done = await storage.release('cli');
         if (!done.dismounted)
-            io.log('The image stays mounted (' + (done.note ?? '') + '). sandbox repair dismounts it.', 'warn');
+            io.log('The image stays mounted (' + (done.note ?? '') + '). Repairing from Health dismounts it.', 'warn');
         else if (!moved)
             io.log('The image was dismounted; contained storage is still on.');
     }

package/dist/app/features/updates/update-lines.js

@@ -24,9 +24,9 @@ export function describeResult(result, _unattended) {
                 result.reason.replace(/\.?\s*$/, '.') +
                 (result.rolledBack
                     ? ' The change was undone: you are on the version you had.'
-                    : ' Going back to your previous version did not fully work: run sandbox update --rollback or the installer.') +
+                    : ' Going back to your previous version did not fully work: use Go back to the previous version, or run the installer.') +
                 (result.autoUpdateOff
-                    ? ' Automatic updates are off; turn them back on in Maintenance > Updates or with sandbox update --auto on.'
+                    ? ' Automatic updates are off; turn them back on in Maintenance > Updates.'
                     : result.blocked
                         ? ' It is not tried again; the next release is.'
                         : ' It is tried again later.'),

package/dist/app/features/updates/updates.def.js

@@ -100,7 +100,7 @@ export function updatesPage(s, latest) {
         title: 'This program',
         notes: [
             {
-                text: 'After an update this page still runs the version it started with; sandbox web open (or the next sandbox start) starts the new one.',
+                text: 'After an update this page still runs the version it started with. Stop and start the web UI (Maintenance > Web UI) to use the new one.',
                 tone: 'muted',
                 only: 'web',
             },

package/dist/app/features/updates/updates.run.js

@@ -3,7 +3,7 @@
 // runs, rollback on failure) stays in host/update.
 import { userDir } from '../../../core/config/index.js';
 import { errMsg, fail } from '../../../core/util/index.js';
-import { MigrateService, NPM_UPDATE_COMMAND, UpdateService } from '../../../cli/services/index.js';
+import { AgentCommandsService, MigrateService, NPM_UPDATE_COMMAND, UpdateService, } from '../../../cli/services/index.js';
 import { implement } from '../../context.js';
 import { cancelled } from '../../kernel/index.js';
 import { describeResult, whereOf } from './update-lines.js';
@@ -39,7 +39,7 @@ export async function updateWith(service, input, io) {
         const found = await service.check();
         if (found.available && found.latest)
             return {
-                line: 'Version ' + found.latest.version + ' is available (you have ' + found.current + '). Run: sandbox update',
+                line: 'Version ' + found.latest.version + ' is available (you have ' + found.current + ').',
                 latest: found.latest.version,
             };
         if (found.blocked)
@@ -73,7 +73,17 @@ export const runUpdateRun = implement(runUpdate, async (ctx, input, io) => {
     // A folder of the user's choosing is installed from only on the command line (the web and the menu send no feed).
     if (input.feed !== undefined && input.feed !== ctx.options.feed)
         fail('--feed works only on the command line.');
-    return updateWith(UpdateService.forPackage(ctx.packageRoot, input.feed, { userDir: userDir() }), input, io);
+    const result = await updateWith(UpdateService.forPackage(ctx.packageRoot, input.feed, { userDir: userDir() }), input, io);
+    // The agent commands (claude, codex ...) point at the program: bring them in line with what is installed now.
+    if (ctx.loaded.config.agentCommands.enabled && !input.check && !input.rollback && !input.auto) {
+        try {
+            new AgentCommandsService(ctx).reconcile(ctx.loaded.config);
+        }
+        catch {
+            // The update itself worked; the agent commands are put right at the next launch.
+        }
+    }
+    return result;
 });
 /** sandbox migrate's work, given the service (tests pass their own). */
 export async function migrateWith(service, input, io) {

package/dist/app/features/vpn/vpn.def.d.ts

@@ -31,6 +31,17 @@ export declare const VpnStatusSchema: z.ZodObject<{
         }>;
         text: z.ZodString;
     }, z.core.$strip>>;
+    lastFailure: z.ZodNullable<z.ZodObject<{
+        code: z.ZodEnum<{
+            auth: "auth";
+            unreachable: "unreachable";
+            driver: "driver";
+            timeout: "timeout";
+            other: "other";
+        }>;
+        text: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type VpnStatus = z.output<typeof VpnStatusSchema>;
 export declare const vpnStatus: import("../../kernel/define.js").QueryDef<z.ZodObject<{
@@ -62,6 +73,17 @@ export declare const vpnStatus: import("../../kernel/define.js").QueryDef<z.ZodO
         }>;
         text: z.ZodString;
     }, z.core.$strip>>;
+    lastFailure: z.ZodNullable<z.ZodObject<{
+        code: z.ZodEnum<{
+            auth: "auth";
+            unreachable: "unreachable";
+            driver: "driver";
+            timeout: "timeout";
+            other: "other";
+        }>;
+        text: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>, "vpn.status">;
 export declare const vpnLogin: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strict>, z.ZodObject<{
     message: z.ZodString;
@@ -108,5 +130,16 @@ export declare const vpnView: import("../../kernel/define.js").ViewDef<{
             }>;
             text: z.ZodString;
         }, z.core.$strip>>;
+        lastFailure: z.ZodNullable<z.ZodObject<{
+            code: z.ZodEnum<{
+                auth: "auth";
+                unreachable: "unreachable";
+                driver: "driver";
+                timeout: "timeout";
+                other: "other";
+            }>;
+            text: z.ZodString;
+            at: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>, "vpn.status">;
 }, Record<string, never>, "vpn">;

package/dist/app/features/vpn/vpn.def.js

@@ -37,6 +37,14 @@ export const VpnStatusSchema = z.object({
     })
         .nullable()
         .describe("The running sandbox's tunnel, when one runs with the VPN on"),
+    lastFailure: z
+        .object({
+        code: z.enum(['auth', 'unreachable', 'driver', 'timeout', 'other']).describe('Why the last attempt failed'),
+        text: z.string().describe('The reason in plain words'),
+        at: z.string().describe('When (ISO date and time)'),
+    })
+        .nullable()
+        .describe("The last sandbox's VPN attempt, when it failed (kept after the sandbox closed)"),
 });
 export const vpnStatus = defineQuery({
     id: 'vpn.status',
@@ -125,6 +133,16 @@ export function vpnPage(s) {
         wireguard
             ? { id: 'login', label: 'Login', value: 'not needed (the keys are in your config)', tone: 'muted' }
             : { id: 'login', label: 'Login', value: LOGIN_TEXT[s.login] + savedDate, tone: LOGIN_TONE[s.login] },
+        ...(s.lastFailure
+            ? [
+                {
+                    id: 'lastAttempt',
+                    label: 'Last attempt',
+                    value: s.lastFailure.text + ' (' + s.lastFailure.at.slice(0, 16).replace('T', ' ') + ')',
+                    tone: 'danger',
+                },
+            ]
+            : []),
         ...(s.running
             ? [
                 {
@@ -137,14 +155,14 @@ export function vpnPage(s) {
             : []),
     ];
     const notes = [
-        ...(!wireguard && s.login === 'none'
-            ? [{ text: 'Next: sandbox vpn login', tone: 'muted', only: 'cli' }]
-            : []),
         ...(s.login === 'unreadable'
+            ? [{ text: 'Only the Windows user that saved it can read it. Save it again.', tone: 'muted' }]
+            : []),
+        ...(s.lastFailure?.code === 'auth' && s.provider === 'nordvpn'
             ? [
                 {
-                    text: 'Only the Windows user that saved it can read it. Save it again: sandbox vpn login',
-                    tone: 'muted',
+                    text: 'NordVPN refused the login. It needs the service credentials (Nord Account > NordVPN > Manual setup), not your e-mail and password.',
+                    tone: 'warn',
                 },
             ]
             : []),
@@ -152,12 +170,18 @@ export function vpnPage(s) {
     ];
     // Turning it on or off is the vpn.enabled setting (it applies from the next start).
     const toggle = action(setSetting, { scope: 'user', key: 'vpn.enabled', value: !s.enabled }, { label: s.enabled ? 'Turn the VPN off' : 'Turn the VPN on', verb: s.enabled ? 'turn off' : 'turn on', key: 'o' });
+    const refused = s.lastFailure?.code === 'auth';
     const actions = [
         toggle,
+        ...(s.lastFailure?.code === 'unreachable' && s.protocol === 'udp'
+            ? [
+                action(setSetting, { scope: 'user', key: 'vpn.protocol', value: 'tcp' }, { label: 'Try TCP instead of UDP', verb: 'use tcp', key: 't' }),
+            ]
+            : []),
         ...(wireguard
             ? []
             : [
-                action(vpnLogin, {}, { key: 'v', verb: 'save login' }),
+                action(vpnLogin, {}, { key: 'v', verb: 'save login', ...(refused ? { label: 'Save the login again…' } : {}) }),
                 ...(s.login !== 'none' ? [action(vpnLogout, {}, { key: 'x', verb: 'delete login' })] : []),
             ]),
     ];

package/dist/app/features/vpn/vpn.run.d.ts

@@ -27,6 +27,17 @@ export declare const vpnStatusRun: import("../../kernel/define.js").Implementati
         }>;
         text: import("zod").ZodString;
     }, import("zod/v4/core").$strip>>;
+    lastFailure: import("zod").ZodNullable<import("zod").ZodObject<{
+        code: import("zod").ZodEnum<{
+            auth: "auth";
+            unreachable: "unreachable";
+            driver: "driver";
+            timeout: "timeout";
+            other: "other";
+        }>;
+        text: import("zod").ZodString;
+        at: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
 }, import("zod/v4/core").$strip>, "vpn.status">, import("../../../cli/commands/context.js").Context>;
 export declare const vpnLoginRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
     message: import("zod").ZodString;

package/dist/app/features/vpn/vpn.run.js

@@ -32,8 +32,11 @@ export const vpnLoginRun = implement(vpnLogin, async (ctx, _input, io) => {
     if (password === undefined)
         cancelled();
     service.save({ username, password });
+    const warning = service.warning({ username, password });
+    if (warning)
+        io.log(warning, 'warn');
     VPN_WARNINGS.forEach((w) => io.log(w, 'muted'));
-    return { message: 'Saved. Turn the VPN on with: sandbox config set vpn.enabled true' };
+    return { message: 'Saved. Use "Turn the VPN on" on the VPN page to use it from the next start.' };
 });
 export const vpnLogoutRun = implement(vpnLogout, async (ctx, _input, io) => {
     requireOnPc('vpn logout');

package/dist/app/features/web/web.def.js

@@ -27,10 +27,10 @@ export const webStatus = defineQuery({
     text: (o) => o.running && o.port
         ? 'The web UI is running at http://127.0.0.1:' +
             o.port +
-            '/ (sandbox web open signs you in).' +
+            '/ (the Open action signs you in).' +
             (o.lanAddress ? '\nOn your network: ' + o.lanAddress + ' (certificate ' + o.lanFingerprint + ')' : '') +
             (o.lanProblem ? '\nLAN mode is on but not listening: ' + o.lanProblem : '')
-        : 'The web UI is not running (sandbox web start).',
+        : 'The web UI is not running.',
     cli: { name: 'web', action: 'status', json: true },
 });
 export const startWeb = defineOperation({

package/dist/app/features/web/web.run.js

@@ -3,7 +3,7 @@
 // it. The server itself (`sandbox _web`) stays in cli/commands/web.ts.
 import path from 'node:path';
 import { packageVersion } from '../../../core/package-info.js';
-import { fail, sleep } from '../../../core/util/index.js';
+import { fail, failWith, sleep } from '../../../core/util/index.js';
 import { requireOnPc } from '../../../cli/commands/context.js';
 import { spawnDetached } from '../../../host/sandbox/index.js';
 import { openBrowser, WebControl, WebStore } from '../../../host/web/index.js';
@@ -50,10 +50,14 @@ async function startServer(ctx, io, control) {
         const now = await control.status();
         if (now.running && now.state) {
             io.log('The web UI is running at http://127.0.0.1:' + now.state.port + '/ (this PC only).');
-            return { port: now.state.port, message: 'Open it already signed in with: sandbox web open', wasRunning: false };
+            return {
+                port: now.state.port,
+                message: 'Open it already signed in from Maintenance > Web UI.',
+                wasRunning: false,
+            };
         }
     }
-    return fail('The web UI did not start.', 'Run sandbox _web to see why (the port ' + config.web.port + ' may be taken: change web.port).');
+    return fail('The web UI did not start.', 'The port ' + config.web.port + ' may be taken: change web.port in Settings. The Logs page may say more.');
 }
 /** Whether the web UI runs, and its address without the token. Never returns the state (it holds the token). */
 export const webStatusRun = implement(webStatus, async (ctx) => {
@@ -83,7 +87,11 @@ export const openWebRun = implement(openWeb, async (ctx, _input, io) => {
         io.log(started.message);
     const { running, state } = await control.status();
     if (!running || !state)
-        return fail('The web UI stopped right away.', 'Run sandbox web start again.');
+        return failWith('The web UI stopped right away.', 'Start it again.', {
+            op: 'web.start',
+            label: 'Start the web UI',
+            cli: 'sandbox web start',
+        });
     openBrowser(control.url(state));
     return { message: 'Opened in your browser.' };
 });

package/dist/app/kernel/errors.d.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { type ErrorAction } from '../../core/util/errors.js';
+export type { ErrorAction };
 export declare const ErrorKindSchema: z.ZodEnum<{
     user: "user";
     cancelled: "cancelled";
@@ -16,6 +18,11 @@ export declare const WireErrorSchema: z.ZodObject<{
     }>;
     message: z.ZodString;
     fix: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodObject<{
+        op: z.ZodString;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        label: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type WireError = z.output<typeof WireErrorSchema>;
 /** The user said no to a question the operation needed: nothing changed. */

package/dist/app/kernel/errors.js

@@ -9,6 +9,14 @@ export const WireErrorSchema = z.strictObject({
     kind: ErrorKindSchema,
     message: z.string().max(2000),
     fix: z.string().max(2000).optional(),
+    /** A button that fixes it (the command line is not sent: only the CLI prints it). */
+    action: z
+        .strictObject({
+        op: z.string().max(100),
+        input: z.record(z.string(), z.unknown()).optional(),
+        label: z.string().max(200),
+    })
+        .optional(),
 });
 /** The user said no to a question the operation needed: nothing changed. */
 export class Cancelled extends Error {
@@ -27,8 +35,15 @@ export const BUG_MESSAGE = 'Something went wrong.';
 export function toWireError(e) {
     if (e instanceof Cancelled)
         return { kind: 'cancelled', message: e.message };
-    if (e instanceof UserError)
-        return { kind: 'user', message: e.message, ...(e.fix ? { fix: e.fix } : {}) };
+    if (e instanceof UserError) {
+        const a = e.action;
+        return {
+            kind: 'user',
+            message: e.message,
+            ...(e.fix ? { fix: e.fix } : {}),
+            ...(a ? { action: { op: a.op, ...(a.input ? { input: { ...a.input } } : {}), label: a.label } } : {}),
+        };
+    }
     if (e instanceof z.ZodError)
         return { kind: 'invalid', message: issuesText(e) };
     return { kind: 'bug', message: BUG_MESSAGE };
@@ -37,7 +52,7 @@ export function toWireError(e) {
 export function fromWireError(w) {
     if (w.kind === 'cancelled')
         return new Cancelled(w.message);
-    return new UserError(w.message, w.fix);
+    return new UserError(w.message, w.fix, w.action ? { op: w.action.op, input: w.action.input, label: w.action.label, cli: '' } : undefined);
 }
 /** "key: problem; other: problem" for a value that did not fit its schema. */
 export function issuesText(e) {

package/dist/app/kernel/rpc.d.ts

@@ -57,8 +57,8 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     text: z.ZodString;
     tone: z.ZodOptional<z.ZodEnum<{
         ok: "ok";
-        muted: "muted";
         warn: "warn";
+        muted: "muted";
         danger: "danger";
         accent: "accent";
     }>>;
@@ -154,6 +154,11 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }>;
         message: z.ZodString;
         fix: z.ZodOptional<z.ZodString>;
+        action: z.ZodOptional<z.ZodObject<{
+            op: z.ZodString;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     t: z.ZodLiteral<"data">;

package/dist/app/kernel/view.d.ts

@@ -20,11 +20,21 @@ export type Target =
     readonly kind: 'start-agent';
     readonly agent: string;
 }
-/** A command line of an area that is not a feature yet: the menu runs it, the web does not offer it. */
+/** A command line of an area that is not a feature yet: the menu runs it. No Page uses it. */
  | {
     readonly kind: 'command';
     readonly argv: readonly string[];
 }
+/** One setting: Settings opens at its row (the web: /v/settings?focus=<key>; the menu: Settings, searched for it). */
+ | {
+    readonly kind: 'setting';
+    readonly key: string;
+}
+/** A page on the internet (only https://github.com/ so far): the menu opens it in the browser, the web in a tab. */
+ | {
+    readonly kind: 'url';
+    readonly href: string;
+}
 /** Another view. */
  | {
     readonly kind: 'view';

package/dist/app/registry.js

@@ -1,6 +1,6 @@
 import { fail } from '../core/util/errors.js';
 import { accessNeeded, allows, invoke, OWNER, refusalText, NO_QUESTIONS, onSurface, } from './kernel/index.js';
-import { addAgentRun, listAgentsRun, makeDefaultAgentRun, removeAgentRun, startAgentRun, } from './features/agents/index.js';
+import { addAgentRun, agentEnvRun, agentsEnvSetRun, listAgentsRun, makeDefaultAgentRun, removeAgentRun, startAgentRun, } from './features/agents/index.js';
 import { defaultAccountRun, listAccountsRun, removeAccountRun, renameAccountRun, saveAccountRun, useAccountRun, listServicesRun, serviceImportRun, serviceLoginRun, serviceLogoutRun, } from './features/accounts/index.js';
 import { listAppsRun, requestAppRun, setCustomAppsRun, toggleAppRun } from './features/apps/index.js';
 import { browseFolderRun } from './features/files/index.js';
@@ -16,6 +16,7 @@ import { exportConfigRun, getSettingRun, importConfigRun, listSettingsRun, reset
 import { migrateSettingsRun, runUpdateRun, updatesStatusRun } from './features/updates/index.js';
 import { checkEngineRun, cleanEngineRun, engineLeftoversRun, engineStatusRun } from './features/engine/index.js';
 import { openWebRun, startWebRun, stopWebRun, webStatusRun } from './features/web/index.js';
+import { agentCommandsOffRun, agentCommandsOnRun, agentCommandsStatusRun } from './features/agent-commands/index.js';
 import { vpnLoginRun, vpnLogoutRun, vpnStatusRun } from './features/vpn/index.js';
 import { githubLoginRun, githubLogoutRun, githubStatusRun } from './features/github/index.js';
 import { accessStatusRun, allowDeviceRun, lanOffRun, lanOnRun, revokeAccessRun, revokeAllAccessRun, } from './features/access/index.js';
@@ -34,6 +35,8 @@ export const IMPLEMENTATIONS = [
     makeDefaultAgentRun,
     removeAgentRun,
     listAgentsRun,
+    agentEnvRun,
+    agentsEnvSetRun,
     listSettingsRun,
     getSettingRun,
     setSettingRun,
@@ -89,6 +92,9 @@ export const IMPLEMENTATIONS = [
     vpnStatusRun,
     vpnLoginRun,
     vpnLogoutRun,
+    agentCommandsStatusRun,
+    agentCommandsOnRun,
+    agentCommandsOffRun,
     githubStatusRun,
     githubLoginRun,
     githubLogoutRun,

package/dist/bin/agent-sandbox.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-N4GXYTLV.js";
-import "./chunk-FRPLQLSY.js";
+} from "./chunk-JETGP2C3.js";
+import "./chunk-ZTTOF5V3.js";
 
 // src/bin/agent-sandbox.ts
 run(process.argv.slice(2));