windows-development-sandbox 1.12.0 → 1.13.2

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

@@ -1,13 +1,17 @@
-// The sessions feature's work: the list (as this user may see it under the sharing rules) and restarting the agents.
-import { safeText } from '../../../core/util/index.js';
+// The sessions feature's work: the list (as this user may see it under the sharing rules), restarting the agents,
+// opening a shell in a project of the running sandbox and closing a session.
+import { fail, safeText } from '../../../core/util/index.js';
+import { RunDir } from '../../../shared/channel/index.js';
 import { hostEndpoint } from '../../../host/channel/index.js';
 import { isSandboxRunning } from '../../../host/sandbox/index.js';
 import { requireOnPc, requireRunning } from '../../../cli/commands/context.js';
+import { locateHere } from '../../../cli/commands/projects/here.js';
 import { lookAtSandbox, useSharedSandbox } from '../../../cli/commands/shared-use.js';
 import { SessionsService } from '../../../cli/services/index.js';
+import { runningProjects } from '../../../cli/services/web-service.js';
 import { implement, typedConfirm } from '../../context.js';
 import { cancelled } from '../../kernel/index.js';
-import { listSessions, restartSessions } from './sessions.def.js';
+import { closeSession, listSessions, restartSessions, startShell } from './sessions.def.js';
 /** A listed session as the surfaces see it: no attach address or token, text from the sandbox made safe. */
 function sessionRow(s) {
     const { attach: _attach, ...rest } = s;
@@ -56,3 +60,67 @@ export const restartSessionsRun = implement(restartSessions, async (ctx, input,
     io.progress('Restarting the agents' + (scope.guest ? ' of ' + scope.projectName : ''));
     return { message: safeText(await service.restart(input.harness ?? null, scope.guest)) };
 });
+/** Where a new shell opens: the project named, else the one of the current folder, else the only one, else asked. */
+async function shellPlace(ctx, project, io) {
+    const projects = runningProjects({ ctx, line: null, limited: false, owner: null });
+    if (project !== undefined) {
+        const named = projects.find((p) => p.name.toLowerCase() === project.toLowerCase());
+        if (!named)
+            fail('The running sandbox has no project "' + project + '".', 'sandbox status lists its projects.');
+        return { name: named.name, guest: named.guest };
+    }
+    const here = locateHere(ctx, new RunDir(ctx.dataPath).readSandboxStatus());
+    if (here.guestDir)
+        return { name: here.project?.name, guest: here.guestDir };
+    if (!projects.length)
+        fail('The running sandbox has no projects.');
+    if (projects.length === 1)
+        return projects[0];
+    const chosen = await io.choose({
+        title: 'Which project?',
+        choices: projects.map((p) => ({ value: p.name, label: p.name, description: p.guest })),
+    });
+    const picked = projects.find((p) => p.name === chosen);
+    if (!picked)
+        cancelled();
+    return picked;
+}
+export const startShellRun = implement(startShell, async (asked, input, io) => {
+    requireOnPc('shell');
+    requireRunning();
+    const ctx = await useSharedSandbox(asked, { kind: 'use' }, typedConfirm(io));
+    const place = await shellPlace(ctx, input.project, io);
+    io.progress('Opening ' + (input.shell === 'auto' ? 'a shell' : input.shell) + ' in ' + (place.name ?? place.guest));
+    const session = await new SessionsService(ctx).openShell(input.shell, place.guest);
+    const shell = safeText(session.harness);
+    return {
+        session: safeText(session.id),
+        shell,
+        message: 'Opened ' + shell + ' in ' + safeText(place.name ?? place.guest) + ' (session ' + safeText(session.id) + ').',
+    };
+});
+export const closeSessionRun = implement(closeSession, async (asked, input, io) => {
+    requireOnPc('close');
+    requireRunning();
+    const find = (ctx) => new SessionsService(ctx).running(null).find((s) => s.id === input.session);
+    // Anyone the sandbox is shared with may close a shell; an agent session is its owner's to end.
+    const ctx = await useSharedSandbox(asked, (shared) => find(shared)?.kind === 'shell' ? { kind: 'use' } : { kind: 'owner-only', what: 'close an agent session' }, typedConfirm(io));
+    const session = find(ctx);
+    if (!session)
+        fail('No running session ' + input.session + '.', 'sandbox sessions lists the running ones.');
+    const what = safeText(session.harness) + (session.kind === 'shell' ? ' (shell)' : '');
+    const yes = await io.confirm({
+        title: 'Close ' + what + ' session ' + input.session + '?',
+        lines: [
+            'It ends, with every program it started.' +
+                (session.kind === 'shell' ? '' : ' The agent can pick its conversation up again in a new session.'),
+        ],
+        yes: 'Close',
+        danger: true,
+        implied: true,
+    });
+    if (!yes)
+        cancelled();
+    io.progress('Closing session ' + input.session);
+    return { message: safeText(await new SessionsService(ctx).close(input.session)) };
+});

package/dist/app/features/settings/settings-file.d.ts

@@ -22,6 +22,8 @@ export declare class ConfigFile {
     readonly target: SettingsTarget;
     readonly file: string;
     readonly schema: SchemaNode;
+    /** The file as read in this synchronous run (see read). */
+    private snapshot;
     constructor(target: SettingsTarget, file: string);
     static user(configPath: string | null): ConfigFile;
     static project(dir: string): ConfigFile;
@@ -30,6 +32,11 @@ export declare class ConfigFile {
     text(): string;
     /** The value written in this file (undefined = not set here). */
     valueInFile(key: string[]): unknown;
+    /**
+     * The file's text and what it parses to, read once per synchronous run: the settings list asks for every setting's
+     * value (hundreds of reads), and the next run (after a key, a save or a change outside) reads the file again.
+     */
+    private read;
     /** Your own settings with the built-in defaults filled in (what a sandbox uses without a project file). */
     userConfig(): Config;
     /** What is in effect: for your file the merged config, for a project file only what the file sets. */

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

@@ -34,6 +34,8 @@ export class ConfigFile {
     target;
     file;
     schema;
+    /** The file as read in this synchronous run (see read). */
+    snapshot;
     constructor(target, file) {
         this.target = target;
         this.file = file;
@@ -52,11 +54,25 @@ export class ConfigFile {
         return fs.existsSync(this.file);
     }
     text() {
-        return this.exists ? fs.readFileSync(this.file, 'utf8') : '';
+        return this.read().text;
     }
     /** The value written in this file (undefined = not set here). */
     valueInFile(key) {
-        return fileValue(this.text(), key);
+        const value = _.get(this.read().parsed, key);
+        // A copy: the parsed file is shared by every read in this run.
+        return value !== null && typeof value === 'object' ? structuredClone(value) : value;
+    }
+    /**
+     * The file's text and what it parses to, read once per synchronous run: the settings list asks for every setting's
+     * value (hundreds of reads), and the next run (after a key, a save or a change outside) reads the file again.
+     */
+    read() {
+        if (!this.snapshot) {
+            const text = this.exists ? fs.readFileSync(this.file, 'utf8') : '';
+            this.snapshot = { text, parsed: parse(text) ?? {} };
+            queueMicrotask(() => (this.snapshot = undefined));
+        }
+        return this.snapshot;
     }
     /** Your own settings with the built-in defaults filled in (what a sandbox uses without a project file). */
     userConfig() {
@@ -100,6 +116,7 @@ export class ConfigFile {
             return 'unchanged';
         fs.mkdirSync(path.dirname(this.file), { recursive: true });
         fs.writeFileSync(this.file, text, 'utf8');
+        this.snapshot = undefined;
         return 'saved';
     }
 }

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

@@ -46,9 +46,17 @@ export function masked(key, value) {
         return undefined;
     return _.get(redactSecrets(_.set({}, key, structuredClone(value))), key);
 }
+/** The keys a project file's schema can set, worked out once per schema (a list asks for it on every row). */
+const projectKeysOf = new WeakMap();
 /** The keys a project file can set. */
 function projectKeys(files) {
-    return new Set(files.project.schema.leaves().map((l) => l.key.join('.')));
+    const schema = files.project.schema;
+    let keys = projectKeysOf.get(schema);
+    if (!keys) {
+        keys = new Set(schema.leaves().map((l) => l.key.join('.')));
+        projectKeysOf.set(schema, keys);
+    }
+    return keys;
 }
 /** One setting's row in a scope (`config` and `inProject` can be passed when making many rows). */
 export function settingRow(s, files, scope, source = SAVED, config = files.user.userConfig(), inProject = projectKeys(files)) {

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

@@ -94,6 +94,14 @@ export declare const getSetting: import("../../kernel/define.js").QueryDef<z.Zod
     key: z.ZodString;
     value: z.ZodUnknown;
 }, z.core.$strip>, "settings.get">;
+/**
+ * The settings someone with control (not the owner) may change: how attaching and reopening sessions behave, in your
+ * own settings file. Everything else (folders, agents, secrets, network, storage, sharing, the audit log, remote
+ * access) changes what the sandbox can reach or who can come in, so it is the owner's (docs/design/remote-access.md).
+ */
+export declare const CONTROL_SETTINGS: readonly string[];
+/** settings.set / settings.reset: control for CONTROL_SETTINGS in the user file, owner for everything else. */
+export declare function controlSettingAccess(input: unknown): 'control' | 'owner';
 export declare const setSetting: import("../../kernel/define.js").OperationDef<z.ZodObject<{
     scope: z.ZodDefault<z.ZodEnum<{
         project: "project";

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

@@ -65,8 +65,24 @@ export const getSetting = defineQuery({
     surfaces: { except: { menu: 'Settings shows every value', web: 'the Settings page shows every value' } },
     cli: { name: 'config', action: 'get', positional: ['key'] },
 });
+/**
+ * The settings someone with control (not the owner) may change: how attaching and reopening sessions behave, in your
+ * own settings file. Everything else (folders, agents, secrets, network, storage, sharing, the audit log, remote
+ * access) changes what the sandbox can reach or who can come in, so it is the owner's (docs/design/remote-access.md).
+ */
+export const CONTROL_SETTINGS = ['attach.', 'resume.'];
+/** settings.set / settings.reset: control for CONTROL_SETTINGS in the user file, owner for everything else. */
+export function controlSettingAccess(input) {
+    const o = (input ?? {});
+    const key = typeof o.key === 'string' ? o.key : '';
+    const userFile = o.scope === undefined || o.scope === 'user';
+    return userFile && CONTROL_SETTINGS.some((prefix) => key.startsWith(prefix) && key.length > prefix.length)
+        ? 'control'
+        : 'owner';
+}
 export const setSetting = defineOperation({
     id: 'settings.set',
+    access: controlSettingAccess,
     title: 'Change a setting',
     summary: 'change one setting (text is read like the command line: true/on, numbers, JSON)',
     input: z.object({
@@ -80,6 +96,7 @@ export const setSetting = defineOperation({
 });
 export const resetSetting = defineOperation({
     id: 'settings.reset',
+    access: controlSettingAccess,
     title: 'Reset a setting',
     summary: 'put one setting back to its default (in a project file: remove it)',
     input: z.object({ scope: ScopeSchema.default('user'), key: KeySchema }),

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

@@ -4,12 +4,18 @@ export declare const WebStatusSchema: z.ZodObject<{
     running: z.ZodBoolean;
     port: z.ZodNullable<z.ZodNumber>;
     address: z.ZodNullable<z.ZodString>;
+    lanAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanFingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanProblem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type WebStatus = z.output<typeof WebStatusSchema>;
 export declare const webStatus: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
     running: z.ZodBoolean;
     port: z.ZodNullable<z.ZodNumber>;
     address: z.ZodNullable<z.ZodString>;
+    lanAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanFingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lanProblem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>, "web.status">;
 export declare const startWeb: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
     port: z.ZodNumber;
@@ -29,5 +35,8 @@ export declare const webView: import("../../kernel/define.js").ViewDef<{
         running: z.ZodBoolean;
         port: z.ZodNullable<z.ZodNumber>;
         address: z.ZodNullable<z.ZodString>;
+        lanAddress: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lanFingerprint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lanProblem: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>, "web.status">;
 }, Record<string, never>, "web">;

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

@@ -8,6 +8,13 @@ export const WebStatusSchema = z.object({
     running: z.boolean().describe('The web UI server answers'),
     port: z.number().nullable().describe('Its port on 127.0.0.1, when it runs'),
     address: z.string().nullable().describe('Its address (without the login token), when it runs'),
+    lanAddress: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Its address on your network for paired devices (LAN mode), when it listens there'),
+    lanFingerprint: z.string().nullable().optional().describe("The LAN certificate's SHA-256 fingerprint"),
+    lanProblem: z.string().nullable().optional().describe('Why LAN mode is on but not listening'),
 });
 const MessageSchema = z.object({ message: z.string().describe('What happened') });
 export const webStatus = defineQuery({
@@ -18,7 +25,11 @@ export const webStatus = defineQuery({
     output: WebStatusSchema,
     surfaces: NOT_ON_WEB,
     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 web UI is running at http://127.0.0.1:' +
+            o.port +
+            '/ (sandbox web open 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).',
     cli: { name: 'web', action: 'status', json: true },
 });
@@ -73,6 +84,20 @@ export function webPage(o) {
                         tone: o.running ? 'ok' : 'muted',
                     },
                     ...(o.address ? [{ id: 'address', label: 'Address', value: o.address + '  (this PC only)' }] : []),
+                    ...(o.lanAddress
+                        ? [
+                            {
+                                id: 'lan',
+                                label: 'On your network',
+                                value: o.lanAddress,
+                                description: 'Type this into the phone, then enter the code from Remote access > Allow a new device.',
+                                details: o.lanFingerprint ? ['Certificate ' + o.lanFingerprint] : undefined,
+                            },
+                        ]
+                        : []),
+                    ...(o.lanProblem
+                        ? [{ id: 'lan-problem', label: 'LAN mode', value: o.lanProblem, tone: 'warn' }]
+                        : []),
                 ],
                 actions: o.running ? [open, stop] : [start, open],
                 notes: [{ text: 'Loopback only, behind a token. Open signs you in.', tone: 'muted' }],

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

@@ -10,6 +10,9 @@ export declare const webStatusRun: import("../../kernel/define.js").Implementati
     running: import("zod").ZodBoolean;
     port: import("zod").ZodNullable<import("zod").ZodNumber>;
     address: import("zod").ZodNullable<import("zod").ZodString>;
+    lanAddress: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+    lanFingerprint: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+    lanProblem: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
 }, import("zod/v4/core").$strip>, "web.status">, import("../../../cli/commands/context.js").Context>;
 export declare const startWebRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
     port: import("zod").ZodNumber;

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

@@ -60,7 +60,15 @@ export const webStatusRun = implement(webStatus, async (ctx) => {
     requireOnPc('web');
     const { running, state } = await controlOf(ctx).status();
     const port = running && state ? state.port : null;
-    return { running, port, address: port ? 'http://127.0.0.1:' + port + '/' : null };
+    const lan = running ? (state?.lan ?? null) : null;
+    return {
+        running,
+        port,
+        address: port ? 'http://127.0.0.1:' + port + '/' : null,
+        lanAddress: lan?.url ?? null,
+        lanFingerprint: lan?.fingerprint ?? null,
+        lanProblem: lan?.problem ?? null,
+    };
 });
 export const startWebRun = implement(startWeb, async (ctx, _input, io) => {
     requireOnPc('web');
@@ -73,8 +81,8 @@ export const openWebRun = implement(openWeb, async (ctx, _input, io) => {
     const started = await startServer(ctx, io, control);
     if (started.wasRunning)
         io.log(started.message);
-    const { state } = await control.status();
-    if (!state)
+    const { running, state } = await control.status();
+    if (!running || !state)
         return fail('The web UI stopped right away.', 'Run sandbox web start again.');
     openBrowser(control.url(state));
     return { message: 'Opened in your browser.' };

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

@@ -0,0 +1,33 @@
+/** What a definition needs. Default (fails closed): a query needs view, an operation owner. */
+export type Access = 'view' | 'control' | 'owner';
+/** A role the owner can give: view only, or full control (everything but the owner's own things). */
+export type RemoteRole = 'view' | 'control';
+/** Who runs a definition: the owner, or someone the owner let in. */
+export type Caller = {
+    readonly kind: 'owner';
+} | {
+    readonly kind: 'windows';
+    readonly user: string;
+    readonly role: RemoteRole;
+} | {
+    readonly kind: 'device';
+    readonly id: string;
+    readonly name: string;
+    readonly role: RemoteRole;
+};
+export declare const OWNER: Caller;
+/** A definition's need, as written: fixed, or from its input (settings.set on a web.* key needs owner). */
+export type AccessRule = Access | ((input: unknown) => Access);
+/** The most a caller may do. */
+export declare function callerAccess(caller: Caller): Access;
+/** The caller may run something that needs `need`. */
+export declare function allows(caller: Caller, need: Access): boolean;
+/** What a definition needs for this input. A rule that throws on a strange input needs owner. */
+export declare function accessNeeded(def: {
+    readonly kind: 'operation' | 'query';
+    readonly access?: AccessRule;
+}, input: unknown): Access;
+/** Who the caller is, in a few words (the audit log, the page's header). */
+export declare function callerLabel(caller: Caller): string;
+/** The refusal text for a caller that may not. */
+export declare function refusalText(caller: Caller, need: Access): string;

package/dist/app/kernel/access.js

@@ -0,0 +1,44 @@
+// Who may run what (docs/design/remote-access.md): every definition needs view, control or owner; the caller of a run
+// has a role. The owner (at the PC, or through the token link) may do everything; another Windows user of this PC or a
+// paired device has the role the owner gave them, never owner. Pure (the web bundle shows what the role allows).
+export const OWNER = { kind: 'owner' };
+const RANK = { view: 0, control: 1, owner: 2 };
+/** The most a caller may do. */
+export function callerAccess(caller) {
+    return caller.kind === 'owner' ? 'owner' : caller.role;
+}
+/** The caller may run something that needs `need`. */
+export function allows(caller, need) {
+    return RANK[callerAccess(caller)] >= RANK[need];
+}
+/** What a definition needs for this input. A rule that throws on a strange input needs owner. */
+export function accessNeeded(def, input) {
+    const rule = def.access;
+    if (rule === undefined)
+        return def.kind === 'query' ? 'view' : 'owner';
+    if (typeof rule === 'string')
+        return rule;
+    try {
+        return rule(input);
+    }
+    catch {
+        return 'owner';
+    }
+}
+/** Who the caller is, in a few words (the audit log, the page's header). */
+export function callerLabel(caller) {
+    switch (caller.kind) {
+        case 'owner':
+            return 'you';
+        case 'windows':
+            return 'Windows user ' + caller.user;
+        case 'device':
+            return 'device ' + caller.name;
+    }
+}
+/** The refusal text for a caller that may not. */
+export function refusalText(caller, need) {
+    if (need === 'owner')
+        return 'Only the owner of this PC can do that, at the PC.';
+    return callerAccess(caller) === 'view' ? 'Your access is view only.' : 'You may not do that.';
+}

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

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
+import type { AccessRule } from './access.js';
 import type { OperationIO } from './io.js';
-import type { Page } from './view.js';
+import type { Page, Target } from './view.js';
 export type SurfaceName = 'cli' | 'menu' | 'web';
 export declare const SURFACE_NAMES: readonly SurfaceName[];
 /** Where a definition is offered: everywhere, or everywhere but these surfaces (each with the reason). */
@@ -63,6 +64,11 @@ interface Definition<Id extends string, I extends z.ZodType, O extends z.ZodType
     readonly output: O;
     /** Default: every surface. */
     readonly surfaces?: Surfaces;
+    /**
+     * What a caller other than the owner needs (docs/design/remote-access.md). Default (fails closed): view for a query,
+     * owner for an operation; an operation says 'control' to be open to someone the owner gave control.
+     */
+    readonly access?: AccessRule;
     readonly cli?: CliHint;
     /** The output in one text: what an operation did, or a value a query read (CLI output, menu notice, web note). */
     text?(output: z.output<O>): string;
@@ -77,6 +83,13 @@ export interface OperationDef<I extends z.ZodType = z.ZodType, O extends z.ZodTy
     readonly kind: 'operation';
     /** Shown as dangerous (red); it asks for its own confirmation through io.confirm. */
     readonly danger?: boolean;
+    /** Its result must stay on screen until dismissed (a one-time code to type elsewhere): the web keeps it open. */
+    readonly keepResult?: boolean;
+    /**
+     * Where every surface goes once it succeeded: a new session's terminal is attached on the command line and in the
+     * menu, and opened in the web UI.
+     */
+    opens?(output: z.output<O>): Target | undefined;
 }
 export interface QueryDef<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType, Id extends string = string> extends Definition<Id, I, O> {
     readonly kind: 'query';

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

@@ -1,3 +1,4 @@
+export * from './access.js';
 export * from './define.js';
 export * from './errors.js';
 export * from './fields.js';

package/dist/app/kernel/index.js

@@ -1,5 +1,6 @@
 // The kernel of the shared core: pure (zod and nothing of Node, the terminal or the DOM), so the CLI, the menu, the
 // web server and the browser all import the same definitions, view model, form fields, questions and RPC messages.
+export * from './access.js';
 export * from './define.js';
 export * from './errors.js';
 export * from './fields.js';

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { Access, Caller } from './access.js';
 import { type OperationIO } from './io.js';
 /** One call or subscription on the socket (chosen by the browser, unique while it runs). */
 export declare const RpcIdSchema: z.ZodString;
@@ -168,6 +169,8 @@ export interface RpcHost {
     kind(id: string): 'operation' | 'query' | undefined;
     /** How often a query is read again while subscribed (undefined: once). */
     liveMs(id: string): number | undefined;
-    /** Runs an allowed definition (input and output checked). */
-    run(id: string, input: unknown, io: OperationIO): Promise<unknown>;
+    /** What a caller other than the owner needs to run it with this input (undefined: not here). */
+    need(id: string, input: unknown): Access | undefined;
+    /** Runs an allowed definition (input and output checked); refused when `caller` (default: the owner) may not. */
+    run(id: string, input: unknown, io: OperationIO, caller?: Caller): Promise<unknown>;
 }

package/dist/app/registry.d.ts

@@ -6,5 +6,8 @@ export declare function implementationOf(id: string): Implementation<AnyDefiniti
 export declare function runDefinition(id: string, ctx: AppContext, input: unknown, io: OperationIO): Promise<unknown>;
 /** Reads a query in-process (the menu): typed output, and no questions. */
 export declare function readQuery<D extends QueryDef>(def: D, ctx: AppContext, input?: unknown): Promise<OutputOf<D>>;
-/** What the web server may run: the registered definitions whose surfaces include the web. */
+/**
+ * What the web server may run: the registered definitions whose surfaces include the web, each refused to a caller
+ * whose role does not reach what it needs (docs/design/remote-access.md).
+ */
 export declare function createRpcHost(ctx: AppContext): RpcHost;

package/dist/app/registry.js

@@ -1,4 +1,5 @@
-import { invoke, NO_QUESTIONS, onSurface, } from './kernel/index.js';
+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 { defaultAccountRun, listAccountsRun, removeAccountRun, renameAccountRun, saveAccountRun, useAccountRun, } from './features/accounts/index.js';
 import { listAppsRun, requestAppRun, setCustomAppsRun, toggleAppRun } from './features/apps/index.js';
@@ -10,13 +11,14 @@ import { checkHealthRun, enableSandboxRun, lastHealthRun, repairHealthRun } from
 import { hideWindowRun, sandboxStatusRun, showWindowRun, stopSandboxRun } from './features/sandbox/index.js';
 import { listLogsRun, tailLogRun } from './features/logs/index.js';
 import { listAuditRun } from './features/audit/index.js';
-import { listSessionsRun, restartSessionsRun } from './features/sessions/index.js';
+import { closeSessionRun, listSessionsRun, restartSessionsRun, startShellRun } from './features/sessions/index.js';
 import { exportConfigRun, getSettingRun, importConfigRun, listSettingsRun, resetSettingRun, setSettingRun, } from './features/settings/index.js';
 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 { 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';
 export const IMPLEMENTATIONS = [
     sandboxStatusRun,
     showWindowRun,
@@ -24,6 +26,8 @@ export const IMPLEMENTATIONS = [
     stopSandboxRun,
     listSessionsRun,
     restartSessionsRun,
+    startShellRun,
+    closeSessionRun,
     startAgentRun,
     addAgentRun,
     makeDefaultAgentRun,
@@ -88,6 +92,12 @@ export const IMPLEMENTATIONS = [
     githubLoginRun,
     githubLogoutRun,
     webStatusRun,
+    accessStatusRun,
+    allowDeviceRun,
+    revokeAccessRun,
+    revokeAllAccessRun,
+    lanOnRun,
+    lanOffRun,
 ];
 export function implementationOf(id) {
     return IMPLEMENTATIONS.find((i) => i.def.id === id);
@@ -103,7 +113,10 @@ export function runDefinition(id, ctx, input, io) {
 export async function readQuery(def, ctx, input = {}) {
     return (await runDefinition(def.id, ctx, input, NO_QUESTIONS));
 }
-/** What the web server may run: the registered definitions whose surfaces include the web. */
+/**
+ * What the web server may run: the registered definitions whose surfaces include the web, each refused to a caller
+ * whose role does not reach what it needs (docs/design/remote-access.md).
+ */
 export function createRpcHost(ctx) {
     const allowed = (id) => {
         const impl = implementationOf(id);
@@ -115,10 +128,17 @@ export function createRpcHost(ctx) {
             const def = allowed(id)?.def;
             return def?.kind === 'query' ? def.live?.everyMs : undefined;
         },
-        run: (id, input, io) => {
+        need: (id, input) => {
+            const impl = allowed(id);
+            return impl ? accessNeeded(impl.def, input) : undefined;
+        },
+        run: async (id, input, io, caller = OWNER) => {
             const impl = allowed(id);
             if (!impl)
                 throw new Error('Not allowed on the web: ' + id);
+            const need = accessNeeded(impl.def, input);
+            if (!allows(caller, need))
+                fail(refusalText(caller, need));
             return invoke(impl, ctx, input, io);
         },
     };

package/dist/bin/agent-sandbox.js

@@ -1,3 +1,9 @@
 #!/usr/bin/env node
-import { run } from '../cli/index.js';
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+import {
+  run
+} from "./chunk-K4SU3MHJ.js";
+import "./chunk-VENWSGX2.js";
+
+// src/bin/agent-sandbox.ts
 run(process.argv.slice(2));

package/dist/bin/chunk-IL7BXJF2.js

@@ -0,0 +1,7 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+import {
+  attach
+} from "./chunk-VENWSGX2.js";
+export {
+  attach
+};