windows-development-sandbox 1.18.4 → 1.23.0

package/dist/app/features/agent-commands/agent-commands.def.js

@@ -0,0 +1,91 @@
+// Agent commands: typing claude, codex ... on this PC starts them in a hidden sandbox and attaches the terminal.
+// Pure: schemas, labels and the page section; agent-commands.run.ts does the work (files and PATH on this PC).
+import { z } from 'zod';
+import { action, defineOperation, defineQuery } from '../../kernel/index.js';
+export const AgentCommandsStatusSchema = z.object({
+    enabled: z.boolean().describe('Typing claude, codex ... starts them in a sandbox (setting agentCommands.enabled)'),
+    dir: z.string().describe('The folder with the forwarding commands (first on your PATH while this is on)'),
+    found: z
+        .array(z.object({
+        command: z.string().describe('What you type (claude)'),
+        harness: z.string().describe('The agent it starts in the sandbox'),
+        real: z.string().describe('The real program on this PC'),
+    }))
+        .describe('The agents found on this PC'),
+});
+export const agentCommandsStatus = defineQuery({
+    id: 'agentCommands.status',
+    title: 'Agent commands',
+    summary: 'whether claude, codex ... on this PC start in a sandbox, and which agents were found',
+    input: z.object({}),
+    output: AgentCommandsStatusSchema,
+    text: (o) => agentCommandsText(o),
+    cli: { name: 'agent-commands', action: 'status', json: true },
+});
+const ChangedSchema = z.object({
+    on: z.boolean().describe('Agent commands are on now'),
+    commands: z.array(z.string()).describe('The commands that start an agent in a sandbox'),
+    message: z.string().describe('What happened'),
+});
+export const agentCommandsOn = defineOperation({
+    id: 'agentCommands.on',
+    title: 'Turn agent commands on',
+    summary: 'make claude, codex ... on this PC start in a hidden sandbox and attach',
+    input: z.object({}).strict(),
+    output: ChangedSchema,
+    text: (o) => o.message,
+    cli: { name: 'agent-commands', action: 'on' },
+});
+export const agentCommandsOff = defineOperation({
+    id: 'agentCommands.off',
+    title: 'Turn agent commands off',
+    summary: 'make claude, codex ... on this PC run on the PC again',
+    input: z.object({}).strict(),
+    output: ChangedSchema,
+    text: (o) => o.message,
+    cli: { name: 'agent-commands', action: 'off' },
+});
+/** The words printed by `sandbox agent-commands status`. Pure. */
+export function agentCommandsText(s) {
+    const lines = ['Agent commands: ' + (s.enabled ? 'on' : 'off') + '  (' + s.dir + ')'];
+    if (s.found.length)
+        for (const a of s.found)
+            lines.push('  ' + a.command + '  sandboxed ' + a.harness + (s.enabled ? '' : ' when on') + '  real: ' + a.real);
+    else
+        lines.push('No agents found on this PC (claude, codex, gemini ... on your PATH).');
+    return lines.join('\n');
+}
+/** What turning them on does, in words (also the message after it). */
+export const AGENT_COMMANDS_EXPLAINED = 'Typing claude, codex ... in a folder on this PC starts that agent in a hidden sandbox and attaches your terminal. Open a new terminal after turning it on or off. To run the real program once, set SANDBOX_AGENT_DIRECT=1.';
+/** The "Agent commands" section of the agents page: the switch, then one row per agent found. Pure. */
+export function agentCommandsSection(s) {
+    const toggle = s.enabled
+        ? action(agentCommandsOff, {}, { label: 'Turn off', verb: 'turn off', key: 'o' })
+        : action(agentCommandsOn, {}, { label: 'Turn on', verb: 'turn on', key: 'o' });
+    const rows = [
+        {
+            id: 'agentCommands',
+            label: 'Agent commands',
+            hint: s.enabled ? 'on' : 'off',
+            tone: s.enabled ? 'ok' : 'muted',
+            description: AGENT_COMMANDS_EXPLAINED,
+            primary: toggle,
+            keys: 'o turns it ' + (s.enabled ? 'off' : 'on') + '.',
+            actions: [toggle],
+        },
+        ...s.found.map((a) => ({
+            id: 'agentCommand:' + a.command,
+            label: a.command,
+            hint: s.enabled ? 'starts in a sandbox' : 'runs on this PC',
+            tone: s.enabled ? 'ok' : 'muted',
+            description: s.enabled
+                ? 'Typing ' + a.command + ' starts ' + a.harness + ' in a sandbox. The real program: ' + a.real
+                : 'Typing ' +
+                    a.command +
+                    ' runs the real program (' +
+                    a.real +
+                    '). Turn agent commands on to use a sandbox instead.',
+        })),
+    ];
+    return { id: 'agentCommands', title: 'Agent commands', items: rows };
+}

package/dist/app/features/agent-commands/agent-commands.run.d.ts

@@ -0,0 +1,28 @@
+import { AgentCommandsService } from '../../../cli/services/agent-commands-service.js';
+import { type AgentCommandsStatus } from './agent-commands.def.js';
+export declare function readAgentCommands(service: AgentCommandsService): Promise<AgentCommandsStatus>;
+export declare const agentCommandsStatusRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    enabled: import("zod").ZodBoolean;
+    dir: import("zod").ZodString;
+    found: import("zod").ZodArray<import("zod").ZodObject<{
+        command: import("zod").ZodString;
+        harness: import("zod").ZodString;
+        real: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, "agentCommands.status">, import("../../../cli/commands/context.js").Context>;
+/** Switches agent commands, with the words that say what changed. */
+export declare function switchAgentCommands(service: AgentCommandsService, on: boolean): {
+    on: boolean;
+    commands: string[];
+    message: string;
+};
+export declare const agentCommandsOnRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    on: import("zod").ZodBoolean;
+    commands: import("zod").ZodArray<import("zod").ZodString>;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "agentCommands.on">, import("../../../cli/commands/context.js").Context>;
+export declare const agentCommandsOffRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    on: import("zod").ZodBoolean;
+    commands: import("zod").ZodArray<import("zod").ZodString>;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "agentCommands.off">, import("../../../cli/commands/context.js").Context>;

package/dist/app/features/agent-commands/agent-commands.run.js

@@ -0,0 +1,35 @@
+// Agent commands' work: the status, and turning them on or off (your settings file, then the files and PATH on this
+// PC). The same function runs after a change of agentCommands.* in Settings (settings.run.ts), so every surface agrees.
+import { requireOnPc } from '../../../cli/commands/context.js';
+import { AgentCommandsService } from '../../../cli/services/agent-commands-service.js';
+import { implement } from '../../context.js';
+import { agentCommandsOff, agentCommandsOn, agentCommandsStatus, AGENT_COMMANDS_EXPLAINED, } from './agent-commands.def.js';
+export async function readAgentCommands(service) {
+    const s = await service.statusAsync();
+    return {
+        enabled: s.enabled,
+        dir: s.dir,
+        found: s.found.map((a) => ({ command: a.command, harness: a.harness, real: a.real })),
+    };
+}
+export const agentCommandsStatusRun = implement(agentCommandsStatus, (ctx) => readAgentCommands(new AgentCommandsService(ctx)));
+/** Switches agent commands, with the words that say what changed. */
+export function switchAgentCommands(service, on) {
+    const result = service.setEnabled(on);
+    const commands = result?.on ? result.commands.map((a) => a.command) : [];
+    const message = on
+        ? 'Agent commands are on for: ' +
+            (commands.join(', ') || 'no installed agents found yet') +
+            '. ' +
+            AGENT_COMMANDS_EXPLAINED
+        : 'Agent commands are off: claude, codex ... run on this PC again. Open a new terminal.';
+    return { on, commands, message };
+}
+export const agentCommandsOnRun = implement(agentCommandsOn, (ctx) => {
+    requireOnPc('agent-commands on');
+    return switchAgentCommands(new AgentCommandsService(ctx), true);
+});
+export const agentCommandsOffRun = implement(agentCommandsOff, (ctx) => {
+    requireOnPc('agent-commands off');
+    return switchAgentCommands(new AgentCommandsService(ctx), false);
+});

package/dist/app/features/agent-commands/index.d.ts

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

package/dist/app/features/agent-commands/index.js

@@ -0,0 +1,3 @@
+// The agent commands feature: claude, codex ... on this PC start in a sandbox.
+export * from './agent-commands.def.js';
+export * from './agent-commands.run.js';

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

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type AgentCommandsStatus } from '../agent-commands/agent-commands.def.js';
 import { type Page } from '../../kernel/index.js';
 export declare const AgentRowSchema: z.ZodObject<{
     name: z.ZodString;
@@ -16,6 +17,7 @@ export declare const AgentsListSchema: z.ZodObject<{
         isDefault: z.ZodBoolean;
         removable: z.ZodBoolean;
     }, z.core.$strip>>;
+    subagents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, 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<{
@@ -27,6 +29,7 @@ export declare const listAgents: import("../../kernel/define.js").QueryDef<z.Zod
         isDefault: z.ZodBoolean;
         removable: z.ZodBoolean;
     }, z.core.$strip>>;
+    subagents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>, "agents.list">;
 export declare const startAgent: import("../../kernel/define.js").OperationDef<z.ZodObject<{
     agent: z.ZodString;
@@ -50,7 +53,7 @@ export declare const removeAgent: import("../../kernel/define.js").OperationDef<
     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 function agentsPage(o: AgentsList, commands: AgentCommandsStatus): 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;
@@ -61,5 +64,15 @@ export declare const agentsView: import("../../kernel/define.js").ViewDef<{
             isDefault: z.ZodBoolean;
             removable: z.ZodBoolean;
         }, z.core.$strip>>;
+        subagents: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>, "agents.list">;
+    agentCommands: import("../../kernel/define.js").QueryDef<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+        enabled: z.ZodBoolean;
+        dir: z.ZodString;
+        found: z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            harness: z.ZodString;
+            real: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, "agentCommands.status">;
 }, Record<string, never>, "agents">;

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

@@ -1,7 +1,9 @@
 // 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';
+import { agentsEnvSet, subagentsText, SUBAGENTS_VAR } from './env.def.js';
+import { agentCommandsOff, agentCommandsOn, agentCommandsSection, agentCommandsStatus, } from '../agent-commands/agent-commands.def.js';
+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({
@@ -14,6 +16,12 @@ 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'),
+    subagents: z
+        .number()
+        .int()
+        .nullable()
+        .optional()
+        .describe('Claude: how many subagents run at once (null = its default); missing when Claude is not an agent here'),
 });
 export const listAgents = defineQuery({
     id: 'agents.list',
@@ -86,7 +94,11 @@ function agentDescription(a, where) {
 }
 /** 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;
+    const keys = [
+        ...(a.name === 'claude' ? ['e opens its environment.'] : []),
+        ...(a.removable && !a.isDefault ? ['x removes it.'] : []),
+    ];
+    return keys.length ? keys.join(' ') : undefined;
 }
 function agentItem(a, where) {
     return {
@@ -103,19 +115,61 @@ function agentItem(a, where) {
             ...(a.isDefault
                 ? []
                 : [action(makeDefaultAgent, { name: a.name }, { key: 'd', verb: 'make default', importance: 1 })]),
+            ...(a.name === 'claude'
+                ? [
+                    link({ kind: 'view', view: 'agentEnv', params: { agent: 'claude' } }, 'Environment…', {
+                        key: 'e',
+                        verb: 'environment',
+                        importance: 1,
+                        description: 'Models, limits, how many subagents run at once, and other variables of Claude.',
+                    }),
+                ]
+                : []),
             ...(a.removable && !a.isDefault
                 ? [action(removeAgent, { name: a.name }, { key: 'x', verb: 'remove', importance: 1 })]
                 : []),
         ],
     };
 }
+/** Claude's "Subagents at once": its value, changed in place (the rest of its variables: Environment…). */
+function subagentsSection(n) {
+    return {
+        id: 'claude',
+        title: 'Claude',
+        items: [
+            {
+                id: 'subagents',
+                label: 'Subagents at once',
+                hint: subagentsText(n),
+                description: 'How many subagents Claude may run at the same time. Empty goes back to its default.',
+                primary: action(agentsEnvSet, { agent: 'claude', name: SUBAGENTS_VAR }, {
+                    label: 'Change',
+                    verb: 'edit',
+                    inline: true,
+                    fields: [
+                        {
+                            name: 'value',
+                            key: ['value'],
+                            kind: 'text',
+                            label: 'Subagents at once',
+                            help: 'A whole number from 1 to 1000. Empty goes back to the default.',
+                            optional: true,
+                        },
+                    ],
+                    initial: { value: n === null ? '' : String(n) },
+                }),
+            },
+        ],
+    };
+}
 /** The agents page: the default agent first, then the others, then "Add an agent…" (ids `agent:<name>` and `add`). */
-export function agentsPage(o) {
+export function agentsPage(o, commands) {
     const where = folderName(o.folder);
     const sorted = [...o.agents].sort((a, b) => Number(b.isDefault) - Number(a.isDefault));
     return {
         title: 'Agents',
         sections: [
+            ...(o.subagents !== undefined ? [subagentsSection(o.subagents)] : []),
             {
                 id: 'start',
                 title: 'Start in ' + where,
@@ -130,6 +184,7 @@ export function agentsPage(o) {
                     },
                 ],
             },
+            agentCommandsSection(commands),
         ],
     };
 }
@@ -137,7 +192,7 @@ 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),
+    queries: { agents: listAgents, agentCommands: agentCommandsStatus },
+    operations: [startAgent, addAgent, makeDefaultAgent, removeAgent, agentsEnvSet, agentCommandsOn, agentCommandsOff],
+    build: ({ agents, agentCommands }) => agentsPage(agents, agentCommands),
 });

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

@@ -7,6 +7,7 @@ export declare const listAgentsRun: import("../../kernel/define.js").Implementat
         isDefault: import("zod").ZodBoolean;
         removable: import("zod").ZodBoolean;
     }, import("zod/v4/core").$strip>>;
+    subagents: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodNumber>>;
 }, 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;

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

@@ -14,6 +14,7 @@ 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 { SUBAGENTS_VAR } from './env.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;
@@ -42,7 +43,13 @@ export const listAgentsRun = implement(listAgents, async (ctx) => {
         isDefault: name === config.defaultHarness,
         removable: removable.includes(name),
     }));
-    return { folder: hereDir(ctx), defaultAgent: config.defaultHarness, agents };
+    const limit = Number(config.harnesses.claude?.environment?.[SUBAGENTS_VAR]);
+    return {
+        folder: hereDir(ctx),
+        defaultAgent: config.defaultHarness,
+        agents,
+        ...(config.harnesses.claude ? { subagents: Number.isInteger(limit) && limit > 0 ? limit : null } : {}),
+    };
 });
 export const startAgentRun = implement(startAgent, async (ctx, input, io) => {
     if (insideSandbox() || !isSandboxRunning())

package/dist/app/features/agents/claude-env.def.d.ts

@@ -0,0 +1,36 @@
+export declare const ENV_GROUPS: readonly ["Subagents", "Models", "Limits", "Behaviour", "Privacy", "Network", "Providers"];
+export type EnvGroup = (typeof ENV_GROUPS)[number];
+export interface EnvVarSpec {
+    readonly name: string;
+    readonly group: EnvGroup;
+    readonly label: string;
+    readonly kind: 'flag' | 'number' | 'text' | 'enum';
+    readonly choices?: readonly string[];
+    readonly min?: number;
+    readonly max?: number;
+    /** Its value is a login or a token: never shown, never sent to a screen. */
+    readonly secret?: boolean;
+    readonly description: string;
+    /** What Claude does when it is not set (shown beside the value). */
+    readonly defaultText?: string;
+}
+/** The variable that sets how many subagents run at once (Claude's code default is 20). */
+export declare const MAX_SUBAGENTS_VAR = "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS";
+export declare const MAX_SUBAGENTS_DEFAULT = 20;
+export declare const CLAUDE_ENV: readonly EnvVarSpec[];
+/** The catalogue entry of a variable name. */
+export declare function envSpec(name: string): EnvVarSpec | undefined;
+/** A variable name anyone may set (the same shape the settings accept). */
+export declare const ENV_NAME: RegExp;
+/**
+ * What a typed value becomes for this variable: the text to save, null when it removes the variable, or a problem the
+ * person can act on. A flag is "1" or removed; a number is whole and in range; ANTHROPIC_API_KEY must pass the key
+ * check it is given. Pure.
+ */
+export declare function envValue(spec: EnvVarSpec | undefined, raw: string | null, 
+/** What is wrong with an Anthropic API key (the host passes anthropicKeyProblem), or null. */
+keyProblem?: (key: string) => string | null): {
+    readonly save: string | null;
+} | {
+    readonly problem: string;
+};