windows-development-sandbox 1.11.7 → 1.13.0

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

@@ -0,0 +1,129 @@
+// Remote access's work (docs/design/remote-access.md): the access list in <storage>\web\access.json (shared with the
+// running web server, which reads it again when it changes and closes the pages of whoever was signed out), the
+// remote settings, the firewall rule and the network check of LAN mode. The one-time code is returned once and only
+// its hash is kept.
+import { requireOnPc } from '../../../cli/commands/context.js';
+import { fail } from '../../../core/util/index.js';
+import { AccessStore, addRuleRequest, applyFirewall, chooseLanAddress, lanUrl, networkProblem, networkProfile, removeRuleRequest, showCode, } from '../../../host/remote/index.js';
+import { SecretStore } from '../../../host/secrets/index.js';
+import { protectPrivateFolder } from '../../../host/sharing/index.js';
+import { selfTestRunning } from '../../../host/test-guard.js';
+import { WebStore } from '../../../host/web/index.js';
+import { implement } from '../../context.js';
+import { ConfigFile } from '../settings/index.js';
+import { accessStatus, allowDevice, lanOff, lanOn, revokeAccess, revokeAllAccess } from './access.def.js';
+/** The access list of this user (the folder is the web state's private one). */
+export function accessStoreOf(ctx) {
+    return AccessStore.at(ctx.storageRoot, SecretStore.standard(), {
+        // The self-test never changes folder permissions; its storage is a temp folder.
+        protect: selfTestRunning() ? undefined : (dir) => protectPrivateFolder(dir),
+    });
+}
+function lanStateOf(ctx) {
+    const lan = new WebStore(ctx.storageRoot).read()?.lan;
+    return { url: lan?.url ?? null, fingerprint: lan?.fingerprint ?? null, problem: lan?.problem ?? null };
+}
+function setLan(ctx, enabled) {
+    const outcome = ConfigFile.user(ctx.loaded.configPath).set(['web', 'remote', 'lan', 'enabled'], enabled);
+    if (typeof outcome === 'object')
+        fail('Could not change web.remote.lan.enabled: ' + outcome.problems.join('; '));
+}
+export const accessStatusRun = implement(accessStatus, (ctx) => {
+    requireOnPc('web');
+    const remote = ctx.loaded.config.web.remote;
+    const data = accessStoreOf(ctx).read();
+    const now = Date.now();
+    const alive = (iso) => Date.parse(iso) > now;
+    const lan = lanStateOf(ctx);
+    return {
+        lan: {
+            enabled: remote.lan.enabled,
+            running: remote.lan.enabled && lan.url !== null,
+            address: remote.lan.enabled ? lan.url : null,
+            fingerprint: remote.lan.enabled ? lan.fingerprint : null,
+            problem: remote.lan.enabled ? lan.problem : null,
+            network: data.network,
+        },
+        windowsSignIn: remote.windowsSignIn,
+        users: remote.users.map((u) => ({ name: u.name, role: u.role })),
+        rememberDays: remote.rememberDays,
+        devices: data.devices
+            .filter((d) => alive(d.expiresAt))
+            .map((d) => ({
+            id: d.id,
+            name: d.name,
+            role: d.role,
+            address: d.address,
+            createdAt: d.createdAt,
+            expiresAt: d.expiresAt,
+            lastSeen: d.lastSeen ?? null,
+        })),
+        windows: data.windows
+            .filter((w) => alive(w.expiresAt))
+            .map((w) => ({ id: w.id, user: w.user, createdAt: w.createdAt, expiresAt: w.expiresAt })),
+        pending: data.code && alive(data.code.expiresAt) ? { role: data.code.role, expiresAt: data.code.expiresAt } : null,
+        codeVoided: data.codeVoided,
+    };
+});
+export const allowDeviceRun = implement(allowDevice, (ctx, input) => {
+    requireOnPc('web');
+    if (!ctx.loaded.config.web.remote.lan.enabled)
+        fail('LAN mode is off, so no device on your network can reach the web UI.', 'Turn it on first: sandbox web lan-on');
+    const { code, expiresAt } = accessStoreOf(ctx).newDeviceCode(input.role);
+    const lan = lanStateOf(ctx);
+    return { code: showCode(code), expiresAt, role: input.role, address: lan.url, fingerprint: lan.fingerprint };
+});
+export const revokeAccessRun = implement(revokeAccess, (ctx, input) => {
+    requireOnPc('web');
+    if (!accessStoreOf(ctx).revoke(input.id))
+        fail('There is no device or sign-in ' + input.id + '.', 'See sandbox web devices.');
+    return { message: 'Signed out. Its open pages close within half a minute.' };
+});
+export const revokeAllAccessRun = implement(revokeAllAccess, async (ctx, _input, io) => {
+    requireOnPc('web');
+    const ok = await io.confirm({
+        title: 'Sign out every device and Windows user now?',
+        danger: true,
+        yes: 'Sign out all',
+    });
+    if (!ok)
+        return { message: 'Nothing changed.' };
+    accessStoreOf(ctx).revokeAll('everything');
+    return { message: 'Everyone is signed out, and a code not used yet is void.' };
+});
+export const lanOnRun = implement(lanOn, async (ctx, _input, io) => {
+    requireOnPc('web');
+    const lan = ctx.loaded.config.web.remote.lan;
+    const bound = chooseLanAddress(lan.address);
+    io.progress('Checking the network');
+    const profile = await networkProfile(bound.address);
+    const problem = networkProblem(profile, null);
+    if (problem)
+        fail(problem, 'LAN mode only runs on a network you marked Private (Windows Settings > Network > your network).');
+    io.progress('Adding the firewall rule (Windows asks for permission)');
+    await applyFirewall(addRuleRequest(lan.port, bound.address));
+    accessStoreOf(ctx).setNetwork(profile.name);
+    setLan(ctx, true);
+    const address = lanUrl(bound.address, lan.port);
+    return {
+        address,
+        message: 'LAN mode is on for the network "' +
+            profile.name +
+            '": devices open ' +
+            address +
+            ' (the running web UI starts listening within half a minute). Next: Allow a new device.',
+    };
+});
+export const lanOffRun = implement(lanOff, async (ctx, _input, io) => {
+    requireOnPc('web');
+    const ok = await io.confirm({ title: 'Turn off LAN mode and sign out every device?', danger: true, yes: 'Turn off' });
+    if (!ok)
+        return { message: 'Nothing changed.' };
+    setLan(ctx, false);
+    const store = accessStoreOf(ctx);
+    store.revokeAll('devices');
+    store.setNetwork(null);
+    io.progress('Removing the firewall rule (Windows asks for permission)');
+    await applyFirewall(removeRuleRequest());
+    return { message: 'LAN mode is off: the firewall rule is gone and every device is signed out.' };
+});

package/dist/app/features/access/index.d.ts

@@ -0,0 +1,2 @@
+export * from './access.def.js';
+export * from './access.run.js';

package/dist/app/features/access/index.js

@@ -0,0 +1,3 @@
+// Remote access: devices on your network and other Windows users of this PC (docs/design/remote-access.md).
+export * from './access.def.js';
+export * from './access.run.js';

package/dist/app/features/agents/agent-entry.js

@@ -2,6 +2,8 @@
 // adding and removing one change. Node side (it checks names with the config schema); the agents run writes them.
 import { DEFAULTS } from '../../../core/config/index.js';
 import { HarnessSchema, NameSchema, describeIssues } from '../../../core/schema/index.js';
+/** Names an agent cannot have. */
+const RESERVED = ['shell', 'pwsh', 'powershell', 'cmd', 'close'];
 /** Nothing wrong with the name (true), or what is wrong. Pure. */
 export function agentNameProblem(name, taken) {
     const typed = name.trim();
@@ -12,6 +14,9 @@ export function agentNameProblem(name, taken) {
         return 'Use letters, numbers, - and _ only.';
     if (taken.some((t) => t.toLowerCase() === typed.toLowerCase()))
         return typed + ' is an agent already.';
+    // Shell sessions are listed by these names, and sandbox shell / close are commands.
+    if (RESERVED.includes(typed.toLowerCase()))
+        return typed + ' is taken by the sandbox; choose another name.';
     return true;
 }
 /** The command a package usually provides: "@scope/my-agent@latest" gives "my-agent". Pure. */

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

@@ -25,6 +25,7 @@ export const listAgents = defineQuery({
 });
 export const startAgent = defineOperation({
     id: 'agents.start',
+    access: 'control',
     title: 'Start an agent',
     summary: 'start an agent in a project of the running sandbox',
     input: z.object({

package/dist/app/features/apps/apps-rows.d.ts

@@ -21,7 +21,10 @@ export interface AppsSource {
 }
 /** The files as they are on disk. */
 export declare const SAVED: AppsSource;
-/** The catalogue entries a file can change (a project cannot change an app that has a setting of its own). */
+/**
+ * The catalogue entries a file can change (a project cannot change an app that has a setting of its own, nor an agent
+ * add-on that is yours only).
+ */
 export declare function entriesOf(file: ConfigFile): AppEntry[];
 /** Is the entry on in this source? */
 export declare function appIsOn(entry: AppEntry, file: ConfigFile, source: AppsSource): boolean;

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

@@ -17,9 +17,12 @@ export const SAVED = {
     setting: (file, key) => _.get(file.userConfig(), key),
     custom: (file) => (file.isProject ? {} : file.userConfig().apps.custom),
 };
-/** The catalogue entries a file can change (a project cannot change an app that has a setting of its own). */
+/**
+ * The catalogue entries a file can change (a project cannot change an app that has a setting of its own, nor an agent
+ * add-on that is yours only).
+ */
 export function entriesOf(file) {
-    return APPS.filter((a) => !(file.isProject && a.setting));
+    return APPS.filter((a) => !(file.isProject && (a.setting || a.userOnly)));
 }
 /** Downloaded already (into this data folder), so the next sandbox starts it without a download. */
 function installed(entry, dataPath) {
@@ -57,6 +60,8 @@ export function appRows(file, dataPath, source = SAVED) {
         cli: Boolean(entry.cli),
         mesa: entry.needs?.includes('mesa') ?? false,
         fullGitOnly: Boolean(entry.fullGitOnly),
+        ...(entry.plugsInto ? { plugsInto: entry.plugsInto } : {}),
+        ...(entry.service ? { service: true } : {}),
         ...settingParts(entry, file, source),
         installed: installed(entry, dataPath),
         on: appIsOn(entry, file, source),

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

@@ -32,6 +32,8 @@ export declare const AppRowSchema: z.ZodObject<{
     cli: z.ZodBoolean;
     mesa: z.ZodBoolean;
     fullGitOnly: z.ZodBoolean;
+    plugsInto: z.ZodOptional<z.ZodString>;
+    service: z.ZodOptional<z.ZodBoolean>;
     setting: z.ZodOptional<z.ZodString>;
     settingField: z.ZodOptional<z.ZodType<Field, unknown, z.core.$ZodTypeInternals<Field, unknown>>>;
     settingValue: z.ZodOptional<z.ZodUnknown>;
@@ -63,6 +65,8 @@ export declare const AppsListSchema: z.ZodObject<{
         cli: z.ZodBoolean;
         mesa: z.ZodBoolean;
         fullGitOnly: z.ZodBoolean;
+        plugsInto: z.ZodOptional<z.ZodString>;
+        service: z.ZodOptional<z.ZodBoolean>;
         setting: z.ZodOptional<z.ZodString>;
         settingField: z.ZodOptional<z.ZodType<Field, unknown, z.core.$ZodTypeInternals<Field, unknown>>>;
         settingValue: z.ZodOptional<z.ZodUnknown>;
@@ -100,6 +104,8 @@ export declare const listApps: import("../../kernel/define.js").QueryDef<z.ZodOb
         cli: z.ZodBoolean;
         mesa: z.ZodBoolean;
         fullGitOnly: z.ZodBoolean;
+        plugsInto: z.ZodOptional<z.ZodString>;
+        service: z.ZodOptional<z.ZodBoolean>;
         setting: z.ZodOptional<z.ZodString>;
         settingField: z.ZodOptional<z.ZodType<Field, unknown, z.core.$ZodTypeInternals<Field, unknown>>>;
         settingValue: z.ZodOptional<z.ZodUnknown>;
@@ -137,6 +143,17 @@ export declare const setCustomApps: import("../../kernel/define.js").OperationDe
 export declare const requestApp: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>, "apps.request">;
+/** One line under an app: a short label ('' for a warning on its own) and its text. */
+export interface AppDetail {
+    readonly label: string;
+    readonly text: string;
+    readonly warn?: boolean;
+}
+/**
+ * The lines under an app: its download, how it starts, what it plugs into, what it needs. A setting-backed entry with
+ * nothing to download (claude-mem) has no size, so no download lines. The menu draws the same lines with colours.
+ */
+export declare function appDetails(row: AppRow): AppDetail[];
 /** The apps page of one scope: a category per group (with a switch per app), your own programs and their actions. */
 export declare function appsPage(o: AppsList): Page;
 export declare const appsView: import("../../kernel/define.js").ViewDef<{
@@ -161,6 +178,8 @@ export declare const appsView: import("../../kernel/define.js").ViewDef<{
             cli: z.ZodBoolean;
             mesa: z.ZodBoolean;
             fullGitOnly: z.ZodBoolean;
+            plugsInto: z.ZodOptional<z.ZodString>;
+            service: z.ZodOptional<z.ZodBoolean>;
             setting: z.ZodOptional<z.ZodString>;
             settingField: z.ZodOptional<z.ZodType<Field, unknown, z.core.$ZodTypeInternals<Field, unknown>>>;
             settingValue: z.ZodOptional<z.ZodUnknown>;

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

@@ -10,6 +10,12 @@ export const AppsScopeSchema = z
     .describe("Your own settings (all projects) or this folder's .sandbox-config.json (this project)");
 /** The groups the page shows; the menu and the web list the apps by these, so the navigation stays short. */
 export const APP_GROUPS = [
+    {
+        id: 'agents',
+        label: 'Agent add-ons',
+        description: 'Plug-ins for the agents: rtk and Headroom save tokens, claude-mem gives Claude a memory, ccusage reports token use, Playwright, Context7 and REA add MCP servers. Only your own settings turn them on (except REA).',
+        members: ['agents'],
+    },
     {
         id: 'editors',
         label: 'Editors & docs',
@@ -79,6 +85,8 @@ export const AppRowSchema = z.object({
     cli: z.boolean().describe('A command-line tool (on PATH), not a desktop app'),
     mesa: z.boolean().describe('Needs OpenGL on the CPU (Mesa)'),
     fullGitOnly: z.boolean().describe('Only with full git access'),
+    plugsInto: z.string().optional().describe('Which agents an add-on plugs into, and how'),
+    service: z.boolean().optional().describe('Started by the sandbox or the agent (a proxy, an MCP server)'),
     setting: z.string().optional().describe('The setting it stands for (VS Code, Windows Terminal)'),
     /** That setting's own Field and value (on, off or auto), so it is changed with its own control. */
     settingField: FieldSchema.optional(),
@@ -137,6 +145,7 @@ export const setCustomApps = defineOperation({
 });
 export const requestApp = defineOperation({
     id: 'apps.request',
+    access: 'control',
     title: 'Request an app…',
     summary: 'open a prefilled GitHub request for an app that is not in the list',
     input: z.object({}),
@@ -144,23 +153,52 @@ export const requestApp = defineOperation({
     text: (o) => 'Opened the request form in your browser: ' + o.url,
     surfaces: { except: { cli: 'a request is filed on GitHub; the address is in docs' } },
 });
-/** The lines under an app: its download, how it starts, what it needs. Plain text, like the CLI's. */
-function details(row) {
+/**
+ * The lines under an app: its download, how it starts, what it plugs into, what it needs. A setting-backed entry with
+ * nothing to download (claude-mem) has no size, so no download lines. The menu draws the same lines with colours.
+ */
+export function appDetails(row) {
+    const downloads = row.size !== '';
     return [
-        'Download  ~' +
-            row.size +
-            ' once, kept in C:\\AgentData\\tools\\' +
-            (row.setting ? '' : 'apps\\') +
-            row.id +
-            (row.installed ? ' (downloaded already)' : ''),
-        'Starts    ' + (row.cli ? 'from a terminal (on PATH)' : 'from the desktop or Start > Sandbox apps'),
-        ...(row.mesa ? ['Graphics  OpenGL on the CPU (Mesa) is added for it'] : []),
+        ...(downloads
+            ? [
+                {
+                    label: 'Download',
+                    text: '~' +
+                        row.size +
+                        ' once, kept in C:\\AgentData\\tools\\' +
+                        (row.setting ? '' : 'apps\\') +
+                        row.id +
+                        (row.installed ? ' (downloaded already)' : ''),
+                },
+                {
+                    label: 'Starts',
+                    text: row.service
+                        ? 'by the sandbox or the agent (no shortcut, not on PATH)'
+                        : row.cli
+                            ? 'from a terminal (on PATH)'
+                            : 'from the desktop or Start > Sandbox apps',
+                },
+            ]
+            : []),
+        ...(row.plugsInto ? [{ label: 'Plugs in', text: row.plugsInto }] : []),
+        ...(row.mesa ? [{ label: 'Graphics', text: 'OpenGL on the CPU (Mesa) is added for it' }] : []),
         ...(row.fullGitOnly
-            ? ['Needs full git access (Settings > Projects & setup > Git): it pushes with its own git.']
+            ? [
+                {
+                    label: '',
+                    text: 'Needs full git access (Settings > Projects & setup > Git): it pushes with its own git.',
+                    warn: true,
+                },
+            ]
             : []),
-        ...(row.setting ? ['Setting   ' + row.setting] : []),
+        ...(row.setting ? [{ label: 'Setting', text: row.setting }] : []),
     ];
 }
+/** The lines as plain text, like the CLI's. */
+function details(row) {
+    return appDetails(row).map((d) => (d.label ? d.label.padEnd(10) : '') + d.text);
+}
 /** The switch that turns an app on or off: one boolean field, changed in place. */
 function switchField(row) {
     return { name: 'on', key: ['apps', 'install'], kind: 'boolean', label: row.name, optional: false };

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

@@ -19,6 +19,8 @@ export declare const listAppsRun: import("../../kernel/define.js").Implementatio
         cli: import("zod").ZodBoolean;
         mesa: import("zod").ZodBoolean;
         fullGitOnly: import("zod").ZodBoolean;
+        plugsInto: import("zod").ZodOptional<import("zod").ZodString>;
+        service: import("zod").ZodOptional<import("zod").ZodBoolean>;
         setting: import("zod").ZodOptional<import("zod").ZodString>;
         settingField: import("zod").ZodOptional<import("zod").ZodType<import("../../kernel/fields.js").Field, unknown, import("zod/v4/core").$ZodTypeInternals<import("../../kernel/fields.js").Field, unknown>>>;
         settingValue: import("zod").ZodOptional<import("zod").ZodUnknown>;

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

@@ -26,7 +26,7 @@ export const listAppsRun = implement(listApps, (ctx, input) => {
 export const toggleAppRun = implement(toggleApp, (ctx, input) => {
     const file = settingsFiles(ctx)[input.scope];
     const entry = APPS.find((a) => a.id === input.id);
-    if (!entry || (file.isProject && entry.setting))
+    if (!entry || (file.isProject && (entry.setting || entry.userOnly)))
         fail('"' + input.id + '" is not an app this scope can change.', 'Pick one of the apps the Apps page lists.');
     const name = entry.name;
     // A setting-backed app (VS Code, Windows Terminal) is its setting; a catalogue app is one id in apps.install.