windows-development-sandbox 1.9.0 → 1.11.3

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

@@ -0,0 +1,125 @@
+// The accounts feature's work: the saved logins of each agent, and saving, using, defaulting, renaming and removing
+// them (through AccountsService). Talks only through io; prints nothing. Emails and the sandbox's own words go through
+// safeText. Logins are never read here: the store keeps them sealed, and outputs hold names, emails and dates only.
+import { fail, safeText } from '../../../core/util/index.js';
+import { AccountsService } from '../../../cli/services/index.js';
+import { implement } from '../../context.js';
+import { cancelled } from '../../kernel/index.js';
+import { defaultAccount, listAccounts, NAME_RULE, removeAccount, renameAccount, saveAccount, useAccount, } from './accounts.def.js';
+const NAME = /^[A-Za-z0-9_-]{1,40}$/;
+const validName = (v) => NAME.test(v.trim()) || NAME_RULE;
+/** "work" (me@example.com) as the notices and the command line have always said it. */
+function label(a) {
+    return safeText('"' + a.name + '"' + (a.email ? ' (' + a.email + ')' : ''));
+}
+/** The saved logins of a kept agent; none when its folder cannot be read (the other agents still list). */
+function savedLogins(service, agent) {
+    try {
+        return service.list(agent).map((r) => ({
+            name: r.name,
+            email: r.email === null ? null : safeText(r.email),
+            isDefault: r.isDefault,
+            isActive: r.isActive,
+            savedAt: r.savedAt,
+        }));
+    }
+    catch {
+        // The menu has always shown such an agent with no logins; the command line says so too.
+        return [];
+    }
+}
+/**
+ * The account an operation is about: the name given, else asked. Saving asks for a new name; the others pick one of
+ * the saved logins (none saved: the fix is to save one).
+ */
+async function accountName(io, service, verb, agent, given) {
+    if (given !== undefined)
+        return verb === 'save' ? given.trim() : given;
+    if (verb === 'save') {
+        const typed = await io.text({ title: 'Name for this login:', validate: validName });
+        if (typed === undefined)
+            cancelled();
+        return typed.trim();
+    }
+    const rows = service.list(agent);
+    if (!rows.length)
+        fail('No saved accounts.', 'Sign in inside the sandbox, then run: sandbox account save <name>');
+    const picked = await io.choose({
+        title: 'Which account?',
+        choices: rows.map((a) => ({ value: a.name, label: label(a) })),
+    });
+    if (picked === undefined)
+        cancelled();
+    return picked;
+}
+export const listAccountsRun = implement(listAccounts, async (ctx, input) => {
+    const service = new AccountsService(ctx);
+    const agents = service.agents().map((a) => ({
+        name: a.name,
+        kept: a.kept,
+        canSavePc: a.canSavePc,
+        accounts: a.kept ? savedLogins(service, a.name) : [],
+    }));
+    // An agent that keeps no login, or no such agent: the command line says why (the store's own message).
+    if (!agents.some((a) => a.name === input.agent && a.kept))
+        service.list(input.agent);
+    return { agent: input.agent, agents };
+});
+export const saveAccountRun = implement(saveAccount, async (ctx, input, io) => {
+    const service = new AccountsService(ctx);
+    const name = await accountName(io, service, 'save', input.agent, input.name);
+    const saved = service.save(name, input.fromHost, input.agent);
+    return { name: saved.name, message: 'Saved account ' + label(saved) + '.' };
+});
+export const useAccountRun = implement(useAccount, async (ctx, input, io) => {
+    const service = new AccountsService(ctx);
+    const name = await accountName(io, service, 'use', input.agent, input.name);
+    // The switch is done before the question: a "no" to the restart keeps the new login and only skips the restart.
+    const used = service.activate(name, input.agent);
+    const lines = ['Sandbox now uses ' + label(used) + '.'];
+    if (used.note)
+        lines.push(safeText(used.note));
+    if (service.hasRunningSessions(input.agent) && !input.noRestart) {
+        const restart = await io.confirm({
+            title: 'Restart the running ' + input.agent + ' sessions?',
+            lines: ['They restart and continue their conversation where the agent can, now under the new login.'],
+            yes: 'Restart',
+            implied: true,
+        });
+        if (restart)
+            lines.push(safeText(await service.restart(input.agent)) +
+                ' with --continue; the conversation carries on under the new account.');
+    }
+    return { lines };
+});
+export const defaultAccountRun = implement(defaultAccount, async (ctx, input, io) => {
+    const service = new AccountsService(ctx);
+    const name = await accountName(io, service, 'default', input.agent, input.name);
+    service.setDefault(name, input.agent);
+    return { message: 'Default account: ' + name };
+});
+export const renameAccountRun = implement(renameAccount, async (ctx, input, io) => {
+    const service = new AccountsService(ctx);
+    const name = await accountName(io, service, 'rename', input.agent, input.name);
+    const typed = input.to ?? (await io.text({ title: 'New name for "' + name + '":', initial: name, validate: validName }));
+    const to = typed?.trim();
+    if (to === undefined || to === name)
+        cancelled();
+    service.rename(name, to, input.agent);
+    return { message: 'Renamed account ' + name + ' to ' + to + '.' };
+});
+export const removeAccountRun = implement(removeAccount, async (ctx, input, io) => {
+    const service = new AccountsService(ctx);
+    const name = await accountName(io, service, 'remove', input.agent, input.name);
+    const yes = await io.confirm({
+        title: 'Remove the saved account "' + name + '"?',
+        lines: ['Its login cannot be recovered; you would sign in again.'],
+        yes: 'Remove',
+        danger: true,
+        noTerminal: { message: 'Cannot ask here (no terminal).', fix: 'Add --yes to remove it without asking.' },
+    });
+    if (!yes)
+        cancelled('Nothing removed.');
+    service.remove(name, input.agent);
+    return { message: 'Removed account ' + name + '.' };
+});

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

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

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

@@ -0,0 +1,3 @@
+// The accounts feature: the saved logins of each agent, and saving, using, defaulting, renaming and removing them.
+export * from './accounts.def.js';
+export * from './accounts.run.js';

package/dist/app/features/agents/agent-entry.d.ts

@@ -0,0 +1,17 @@
+import type { Harness } from '../../../core/types.js';
+/** How a new agent gets into the sandbox. */
+export type AgentSource = 'npm' | 'uv' | 'host';
+/** Nothing wrong with the name (true), or what is wrong. Pure. */
+export declare function agentNameProblem(name: string, taken: readonly string[]): true | string;
+/** The command a package usually provides: "@scope/my-agent@latest" gives "my-agent". Pure. */
+export declare function commandFromPackage(pkg: string): string;
+/** The config entry for a new agent. Pure. */
+export declare function newAgent(source: AgentSource, what: string, command: string, hostDir?: string): Harness;
+/** The entry of an agent, checked the way the config file checks it. Returns the entry or what is wrong. */
+export declare function checkedAgent(harness: Harness): Harness | string;
+/** What `harnesses` should say with `name` added. Pure. */
+export declare function withAgent(current: unknown, name: string, harness: Harness): Record<string, unknown>;
+/** What `harnesses` should say with `name` taken out. Pure. */
+export declare function withoutAgent(current: unknown, name: string): Record<string, unknown>;
+/** The agents of `names` that are not built in (only these can be removed). Pure. */
+export declare function addedAgents(names: readonly string[]): string[];

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

@@ -0,0 +1,50 @@
+// Agents as entries of `harnesses` in your settings: their names, the entry a new agent gets, and the lists that
+// 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';
+/** Nothing wrong with the name (true), or what is wrong. Pure. */
+export function agentNameProblem(name, taken) {
+    const typed = name.trim();
+    if (!typed)
+        return 'Type a name.';
+    const parsed = NameSchema.safeParse(typed);
+    if (!parsed.success)
+        return 'Use letters, numbers, - and _ only.';
+    if (taken.some((t) => t.toLowerCase() === typed.toLowerCase()))
+        return typed + ' is an agent already.';
+    return true;
+}
+/** The command a package usually provides: "@scope/my-agent@latest" gives "my-agent". Pure. */
+export function commandFromPackage(pkg) {
+    const version = pkg.lastIndexOf('@');
+    const bare = version > 0 ? pkg.slice(0, version) : pkg;
+    return (bare.split(/[\\/]/).pop() ?? '').replace(/[^A-Za-z0-9._-]/g, '');
+}
+/** The config entry for a new agent. Pure. */
+export function newAgent(source, what, command, hostDir = 'auto') {
+    const common = { arguments: [], environment: {} };
+    if (source === 'npm')
+        return { ...common, npmPackage: what, npmBin: command };
+    if (source === 'uv')
+        return { ...common, uvPackage: what, uvBin: command };
+    return { ...common, hostExecutable: what, hostDir };
+}
+/** The entry of an agent, checked the way the config file checks it. Returns the entry or what is wrong. */
+export function checkedAgent(harness) {
+    const checked = HarnessSchema.safeParse(harness);
+    return checked.success ? harness : describeIssues(checked.error).join('; ');
+}
+/** What `harnesses` should say with `name` added. Pure. */
+export function withAgent(current, name, harness) {
+    return { ...(current && typeof current === 'object' ? current : {}), [name]: harness };
+}
+/** What `harnesses` should say with `name` taken out. Pure. */
+export function withoutAgent(current, name) {
+    const rest = { ...(current && typeof current === 'object' ? current : {}) };
+    delete rest[name];
+    return rest;
+}
+/** The agents of `names` that are not built in (only these can be removed). Pure. */
+export function addedAgents(names) {
+    return names.filter((n) => !(n in DEFAULTS.harnesses));
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { type Page } from '../../kernel/index.js';
+export declare const AgentRowSchema: z.ZodObject<{
+    name: z.ZodString;
+    ready: z.ZodBoolean;
+    isDefault: z.ZodBoolean;
+    removable: z.ZodBoolean;
+}, z.core.$strip>;
+export type AgentRow = z.output<typeof AgentRowSchema>;
+export declare const AgentsListSchema: z.ZodObject<{
+    folder: z.ZodString;
+    defaultAgent: z.ZodString;
+    agents: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ready: z.ZodBoolean;
+        isDefault: z.ZodBoolean;
+        removable: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentsList = z.output<typeof AgentsListSchema>;
+export declare const listAgents: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    folder: z.ZodString;
+    defaultAgent: z.ZodString;
+    agents: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ready: z.ZodBoolean;
+        isDefault: z.ZodBoolean;
+        removable: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>, "agents.list">;
+export declare const startAgent: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    agent: z.ZodString;
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    session: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, "agents.start">;
+export declare const addAgent: import("../../kernel/define.js").OperationDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>, "agents.add">;
+export declare const makeDefaultAgent: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>, "agents.makeDefault">;
+export declare const removeAgent: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>, "agents.remove">;
+/** The agents page: the default agent first, then the others, then "Add an agent…" (ids `agent:<name>` and `add`). */
+export declare function agentsPage(o: AgentsList): Page;
+export declare const agentsView: import("../../kernel/define.js").ViewDef<{
+    agents: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+        folder: z.ZodString;
+        defaultAgent: z.ZodString;
+        agents: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            ready: z.ZodBoolean;
+            isDefault: z.ZodBoolean;
+            removable: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, "agents.list">;
+}, Record<string, never>, "agents">;

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

@@ -0,0 +1,142 @@
+// The agents you can start: the list, starting one in a project of the running sandbox, adding one, making one the
+// default and removing one you added. Pure: schemas, labels and the view; agents.run.ts does the work.
+import { z } from 'zod';
+import { action, defineOperation, defineQuery, defineView, link } from '../../kernel/index.js';
+/** Agent and project names as the web UI has always accepted them. */
+const NameText = z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/);
+export const AgentRowSchema = z.object({
+    name: z.string().describe('The agent'),
+    ready: z.boolean().describe('Installed in the sandbox already (starts without an install)'),
+    isDefault: z.boolean().describe('The agent that starts by default'),
+    removable: z.boolean().describe('You added it (built-in agents cannot be removed)'),
+});
+export const AgentsListSchema = z.object({
+    folder: z.string().describe('The folder a start works on (the current folder)'),
+    defaultAgent: z.string().describe('The default agent'),
+    agents: z.array(AgentRowSchema).describe('Every agent in your settings, built in or added'),
+});
+export const listAgents = defineQuery({
+    id: 'agents.list',
+    title: 'Agents',
+    summary: 'the agents you can start, and which one is the default',
+    input: z.object({}),
+    output: AgentsListSchema,
+    surfaces: { except: { cli: 'sandbox config list shows the agents (harnesses) and the default (defaultHarness)' } },
+});
+export const startAgent = defineOperation({
+    id: 'agents.start',
+    title: 'Start an agent',
+    summary: 'start an agent in a project of the running sandbox',
+    input: z.object({
+        agent: NameText.describe('The agent to start'),
+        project: NameText.optional().describe('The project of the running sandbox (asked when there are several)'),
+    }),
+    output: z.object({
+        session: z.string().describe('The new session'),
+        message: z.string().describe('What happened'),
+    }),
+    text: (o) => o.message,
+    surfaces: {
+        except: {
+            cli: 'sandbox <agent> and sandbox launch start agents on the command line (they boot the sandbox and can attach the terminal)',
+            menu: 'the menu starts agents with launch, which can boot the sandbox and attach this terminal',
+        },
+    },
+});
+export const addAgent = defineOperation({
+    id: 'agents.add',
+    title: 'Add an agent…',
+    summary: 'add an agent by its npm or Python package, or a program on this PC',
+    input: z.object({}),
+    output: z.object({ name: z.string().describe('The new agent'), message: z.string().describe('What happened') }),
+    text: (o) => o.message,
+    surfaces: { except: { cli: 'sandbox config set harnesses adds agents on the command line' } },
+});
+export const makeDefaultAgent = defineOperation({
+    id: 'agents.makeDefault',
+    title: 'Make default',
+    summary: 'make an agent the one that starts by default',
+    input: z.object({ name: z.string().describe('The agent') }),
+    output: z.object({ message: z.string().describe('What happened') }),
+    text: (o) => o.message,
+    surfaces: { except: { cli: 'sandbox config set defaultHarness <name> does this on the command line' } },
+});
+export const removeAgent = defineOperation({
+    id: 'agents.remove',
+    title: 'Remove',
+    summary: 'take an agent you added out of your settings',
+    input: z.object({ name: z.string().describe('The agent') }),
+    output: z.object({ message: z.string().describe('What happened') }),
+    danger: true,
+    text: (o) => o.message,
+    surfaces: { except: { cli: 'sandbox config set harnesses removes agents on the command line' } },
+});
+function folderName(folder) {
+    return folder.split(/[\\/]/).pop() ?? folder;
+}
+/** The description of an agent row: what a start does, and whether you can remove it. Pure. */
+function agentDescription(a, where) {
+    const removing = a.removable
+        ? a.isDefault
+            ? ' You added it. Make another agent the default to remove it.'
+            : ' You added it.'
+        : '';
+    return 'Starts ' + a.name + ' in ' + where + '.' + (a.isDefault ? ' It is the default agent.' : '') + removing;
+}
+/** The menu's words for the remove key, on an agent you added that is not the default. */
+function agentKeys(a) {
+    return a.removable && !a.isDefault ? 'x removes it.' : undefined;
+}
+function agentItem(a, where) {
+    return {
+        id: 'agent:' + a.name,
+        label: a.name,
+        hint: a.ready ? 'ready' : 'installs on first start',
+        tone: a.ready ? 'ok' : 'muted',
+        icon: a.name,
+        badges: a.isDefault ? [{ text: 'default', tone: 'accent' }] : [],
+        description: agentDescription(a, where),
+        keys: agentKeys(a),
+        primary: link({ kind: 'start-agent', agent: a.name }, 'Start ' + a.name, { verb: 'start' }),
+        actions: [
+            ...(a.isDefault
+                ? []
+                : [action(makeDefaultAgent, { name: a.name }, { key: 'd', verb: 'make default', importance: 1 })]),
+            ...(a.removable && !a.isDefault
+                ? [action(removeAgent, { name: a.name }, { key: 'x', verb: 'remove', importance: 1 })]
+                : []),
+        ],
+    };
+}
+/** The agents page: the default agent first, then the others, then "Add an agent…" (ids `agent:<name>` and `add`). */
+export function agentsPage(o) {
+    const where = folderName(o.folder);
+    const sorted = [...o.agents].sort((a, b) => Number(b.isDefault) - Number(a.isDefault));
+    return {
+        title: 'Agents',
+        sections: [
+            {
+                id: 'start',
+                title: 'Start in ' + where,
+                cards: true,
+                items: [
+                    ...sorted.map((a) => agentItem(a, where)),
+                    {
+                        id: 'add',
+                        label: 'Add an agent…',
+                        description: 'Add another agent by its npm or Python package, or a program on this PC. It is saved in your settings and appears in this list.',
+                        primary: action(addAgent, {}, { verb: 'add' }),
+                    },
+                ],
+            },
+        ],
+    };
+}
+export const agentsView = defineView({
+    id: 'agents',
+    title: 'Agents',
+    summary: 'The agents you can start: start one, add one, choose the default.',
+    queries: { agents: listAgents },
+    operations: [startAgent, addAgent, makeDefaultAgent, removeAgent],
+    build: ({ agents }) => agentsPage(agents),
+});

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

@@ -0,0 +1,31 @@
+export declare const listAgentsRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    folder: import("zod").ZodString;
+    defaultAgent: import("zod").ZodString;
+    agents: import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        ready: import("zod").ZodBoolean;
+        isDefault: import("zod").ZodBoolean;
+        removable: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, "agents.list">, import("../../../cli/commands/context.js").Context>;
+export declare const startAgentRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    agent: import("zod").ZodString;
+    project: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    session: import("zod").ZodString;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "agents.start">, import("../../../cli/commands/context.js").Context>;
+export declare const addAgentRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    name: import("zod").ZodString;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "agents.add">, import("../../../cli/commands/context.js").Context>;
+export declare const makeDefaultAgentRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    name: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "agents.makeDefault">, import("../../../cli/commands/context.js").Context>;
+export declare const removeAgentRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    name: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "agents.remove">, import("../../../cli/commands/context.js").Context>;

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

@@ -0,0 +1,189 @@
+// The agents feature's work: the list, starting an agent in a project of the running sandbox (the sharing rules as the
+// web UI always applied them), and the agents in your settings (added, made default, removed). Talks only through io.
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS } from '../../../core/config/index.js';
+import { fail, safeText } from '../../../core/util/index.js';
+import { SandboxChannel } from '../../../host/channel/index.js';
+import { insideSandbox, isSandboxRunning } from '../../../host/sandbox/index.js';
+import { ownerRule } from '../../../host/sharing/index.js';
+import { hereDir } from '../../../cli/commands/projects/here.js';
+import { lookAtSandbox } from '../../../cli/commands/shared-use.js';
+import { runningProjects } from '../../../cli/services/web-service.js';
+import { implement } from '../../context.js';
+import { cancelled } from '../../kernel/index.js';
+import { ConfigFile } from '../settings/settings-file.js';
+import { addAgent, listAgents, makeDefaultAgent, removeAgent, startAgent, } from './agents.def.js';
+import { addedAgents, agentNameProblem, checkedAgent, commandFromPackage, newAgent, withAgent, withoutAgent, } from './agent-entry.js';
+/** The longest a start waits for the agent to run (the first start installs it). */
+const SESSION_START_MS = 15 * 60 * 1000;
+/** Writes one setting; a value the config file would refuse is said with what is wrong. */
+function save(file, key, value) {
+    const result = file.set(key, value);
+    if (typeof result === 'object')
+        fail('It could not be saved: ' + result.problems.join('; '));
+}
+/** Is this agent already in the sandbox's persistent storage (so starting it needs no install)? */
+function installed(dataPath, name, harness) {
+    const dir = path.join(dataPath, 'tools', 'agents', name);
+    return [
+        harness.hostExecutable,
+        harness.npmBin && harness.npmBin + '.cmd',
+        harness.uvBin && harness.uvBin + '.exe',
+    ].some((f) => f && fs.existsSync(path.join(dir, f)));
+}
+export const listAgentsRun = implement(listAgents, async (ctx) => {
+    const file = ConfigFile.user(ctx.loaded.configPath);
+    const config = file.userConfig();
+    const removable = addedAgents(Object.keys(config.harnesses));
+    const agents = Object.entries(config.harnesses).map(([name, harness]) => ({
+        name,
+        ready: installed(ctx.dataPath, name, harness),
+        isDefault: name === config.defaultHarness,
+        removable: removable.includes(name),
+    }));
+    return { folder: hereDir(ctx), defaultAgent: config.defaultHarness, agents };
+});
+export const startAgentRun = implement(startAgent, async (ctx, input, io) => {
+    if (insideSandbox() || !isSandboxRunning())
+        fail('No Windows Sandbox is running.', 'Start one with sandbox claude, then try again.');
+    const view = lookAtSandbox(ctx);
+    if (view.owner && view.owner.kind !== 'none' && view.owner.kind !== 'mine') {
+        const rule = ownerRule(view.owner, { kind: 'use' });
+        if (rule.kind === 'refuse')
+            fail(rule.reason, rule.fix);
+    }
+    const projects = runningProjects(view);
+    const chosen = input.project ??
+        (projects.length === 1
+            ? projects[0].name
+            : await io.choose({
+                title: 'Which project?',
+                choices: projects.map((p) => ({ value: p.name, label: p.name, description: p.guest })),
+            }));
+    if (chosen === undefined)
+        cancelled();
+    const project = projects.find((p) => p.name === chosen);
+    if (!project)
+        fail('The running sandbox has no project "' + chosen + '".');
+    const harness = view.ctx.loaded.config.harnesses[input.agent];
+    if (!harness)
+        fail('There is no agent called "' + input.agent + '".');
+    io.progress('Starting ' + input.agent + ' (the first time sets things up and can take a while)');
+    const channel = new SandboxChannel(view.ctx.dataPath);
+    const id = channel.requestSession(input.agent, [], project.guest, { harnessSpec: harness });
+    const session = await channel.waitForSession(id, SESSION_START_MS, () => undefined);
+    return {
+        session: safeText(session.id),
+        message: 'Started ' + input.agent + ' in ' + project.name + '.',
+    };
+});
+export const addAgentRun = implement(addAgent, async (ctx, _input, io) => {
+    const file = ConfigFile.user(ctx.loaded.configPath);
+    const taken = Object.keys(file.userConfig().harnesses);
+    const source = await io.choose({
+        title: 'How does the agent get into the sandbox?',
+        choices: [
+            {
+                value: 'npm',
+                label: 'An npm package',
+                description: 'Installed inside the sandbox with npm once and kept (e.g. @openai/codex).',
+            },
+            {
+                value: 'uv',
+                label: 'A Python package',
+                description: 'Installed inside the sandbox with uv once and kept (e.g. aider-chat).',
+            },
+            {
+                value: 'host',
+                label: 'A program on this PC',
+                description: 'An .exe copied from this PC into the sandbox (looked up on PATH and in ~/.local/bin).',
+            },
+        ],
+    });
+    if (source === undefined)
+        cancelled();
+    const kind = source;
+    const name = await io.text({
+        title: 'Name of the agent',
+        lines: ['What you type after "sandbox", e.g. sandbox <name>. Letters, numbers, - and _.'],
+        validate: (v) => agentNameProblem(v, taken),
+    });
+    if (name === undefined)
+        cancelled();
+    const agent = name.trim();
+    if (kind === 'host') {
+        const exe = await io.path({
+            title: 'Choose the program (.exe)',
+            lines: ['The agent program on this PC. It is copied into the sandbox. A bare file name is looked up on PATH.'],
+            pathKind: 'file',
+            validate: (v) => (v.trim() ? true : 'Choose a file.'),
+        });
+        if (exe === undefined)
+            cancelled();
+        const slash = Math.max(exe.lastIndexOf('\\'), exe.lastIndexOf('/'));
+        const dir = slash > 0 ? exe.slice(0, slash) : 'auto';
+        return saveAgent(file, agent, newAgent('host', exe.slice(slash + 1), '', dir));
+    }
+    const what = await io.text({
+        title: kind === 'npm' ? 'npm package' : 'Python package',
+        lines: [
+            kind === 'npm'
+                ? 'The package to install, optionally with a version: @scope/name or name@latest.'
+                : 'The package for `uv tool install`.',
+        ],
+        validate: (v) => (v.trim() ? true : 'Type it.'),
+    });
+    if (what === undefined)
+        cancelled();
+    const command = await io.text({
+        title: 'Command',
+        lines: ['The command the package provides; it is what runs inside the sandbox.'],
+        initial: commandFromPackage(what.trim()),
+        validate: (v) => (/^[A-Za-z0-9._-]+$/.test(v.trim()) ? true : 'Letters, numbers, . - and _ only.'),
+    });
+    if (command === undefined)
+        cancelled();
+    return saveAgent(file, agent, newAgent(kind, what.trim(), command.trim()));
+});
+/** Checks the entry and writes it into your settings. */
+function saveAgent(file, name, harness) {
+    const checked = checkedAgent(harness);
+    if (typeof checked === 'string')
+        fail('That agent is not valid: ' + checked);
+    save(file, ['harnesses'], withAgent(file.valueInFile(['harnesses']), name, harness));
+    return { name, message: 'Added ' + name + '.' };
+}
+/** The agent must be one of your settings' agents (built in or added). */
+function knownAgent(file, name) {
+    if (!(name in file.userConfig().harnesses))
+        fail('There is no agent called "' + name + '".');
+}
+export const makeDefaultAgentRun = implement(makeDefaultAgent, async (ctx, input) => {
+    const file = ConfigFile.user(ctx.loaded.configPath);
+    knownAgent(file, input.name);
+    save(file, ['defaultHarness'], input.name);
+    return { message: input.name + ' is the default agent.' };
+});
+export const removeAgentRun = implement(removeAgent, async (ctx, input, io) => {
+    const name = input.name;
+    if (name in DEFAULTS.harnesses)
+        fail(name + ' is built in, so it cannot be removed.');
+    const file = ConfigFile.user(ctx.loaded.configPath);
+    knownAgent(file, name);
+    if (file.userConfig().defaultHarness === name)
+        fail(name + ' is the default agent.', 'Make another agent the default first.');
+    const yes = await io.confirm({
+        title: 'Remove ' + name + '?',
+        lines: ['It is taken out of your settings. Its files in the sandbox stay until you clean them up.'],
+        yes: 'Remove',
+        danger: true,
+        implied: true,
+    });
+    if (!yes)
+        cancelled();
+    const rest = withoutAgent(file.valueInFile(['harnesses']), name);
+    // Nothing of your own left: the setting goes (the built-in agents need no line).
+    save(file, ['harnesses'], Object.keys(rest).length ? rest : undefined);
+    return { message: 'Removed ' + name + '.' };
+});

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

@@ -0,0 +1,3 @@
+export * from './agents.def.js';
+export * from './agents.run.js';
+export * from './agent-entry.js';

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

@@ -0,0 +1,4 @@
+// The agents feature: the list, starting an agent in a project of the running sandbox, and the agents in your settings.
+export * from './agents.def.js';
+export * from './agents.run.js';
+export * from './agent-entry.js';