windows-development-sandbox 1.5.0 → 1.7.0

package/dist/core/schema/config.js

@@ -11,6 +11,8 @@ import { ToolchainsSchema } from './toolchains.js';
 import { AppsSchema } from './apps.js';
 import { ProjectsSchema } from './projects.js';
 import { ResumeSchema } from './resume.js';
+import { WebSchema } from './web.js';
+import { VpnSchema } from './vpn.js';
 export const ConfigSchema = z
     .strictObject({
     $schema: SchemaRefSchema.optional(),
@@ -23,7 +25,10 @@ export const ConfigSchema = z
     sandbox: SandboxSchema,
     sharing: SharingSchema,
     storage: z.strictObject({
-        root: z.string().min(1).describe('Where everything is kept on this PC (tools, databases, logins, launches).'),
+        root: z
+            .string()
+            .min(1)
+            .describe('Where everything is kept on this PC (tools, databases, logins, launches). The default is a private folder for you under %ProgramData%\\AgentSandbox\\users, which works for installs for one user and for everyone. sandbox storage move <folder> moves it.'),
         persistAgentState: z.boolean().describe('Keep agent logins and history between sandboxes.'),
         dataName: NameSchema.describe('Name of the persistent data set (C:\\AgentData) shared by all workspaces.'),
         markSandboxFiles: z
@@ -35,11 +40,13 @@ export const ConfigSchema = z
             .describe('Say at launch when the persisted data (tools, databases, logins) is bigger than this many GB; 0 = never. sandbox data shows what takes the space.'),
     }),
     network: NetworkSchema,
+    vpn: VpnSchema,
     provisioning: ProvisioningSchema,
     downloads: DownloadsSchema,
     toolchains: ToolchainsSchema,
     databases: DatabasesSchema.describe('Databases running inside the sandbox. Data persists in C:\\AgentData\\databases; each one starts at boot.'),
     attach: AttachSchema,
+    web: WebSchema,
     agentCommands: AgentCommandsSchema,
     secrets: SecretsSchema,
     personalization: toggle('Copy your desktop look (theme, accent, taskbar, wallpaper, ...) into the sandbox.'),
@@ -74,6 +81,8 @@ export const LocalOverridesSchema = z
     sandbox: SandboxSchema.omit({ cpuLimit: true, pageFileMb: true }).partial(),
     // A project may block more (the LAN, hosts); it never opens hosts, ports, DNS or a proxy.
     network: NetworkSchema.pick({ blockPrivateRanges: true, blockHosts: true }).partial(),
+    // A project may turn the kill switch on, never off, and never choose a VPN, a server, a file or a login.
+    vpn: VpnSchema.pick({ killSwitch: true }).partial(),
     provisioning: ProvisioningSchema.pick({ copyFromHost: true, fallbackToInstall: true, refresh: true })
         .extend({ git: GitSchema.partial(), terminal: toggle('Windows Terminal as the sandbox window.').partial() })
         .partial(),

package/dist/core/schema/harness.d.ts

@@ -21,6 +21,7 @@ export declare const HarnessSchema: z.ZodObject<{
         loginFiles: z.ZodArray<z.ZodString>;
         hostDir: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    localState: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     resumeArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     resumeOneArguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;

package/dist/core/schema/harness.js

@@ -1,6 +1,6 @@
 // An agent (claude, codex, ...) the sandbox can run.
 import { z } from 'zod';
-import { StringsSchema } from './common.js';
+import { secret, StringsSchema } from './common.js';
 /** A folder below the agent's state folder: plain names only, no drive, no "..". */
 const SubfolderSchema = z
     .string()
@@ -41,8 +41,14 @@ export const HarnessSchema = z
         .describe('Python package installed with `uv tool install` inside the sandbox (e.g. aider-chat).'),
     uvBin: z.string().optional().describe('Command the uv package provides.'),
     arguments: StringsSchema.describe('Arguments always passed to the agent.'),
-    environment: z.record(z.string(), z.string()).describe('Environment variables for the agent.'),
+    environment: z
+        .record(z.string(), secret(z.string()))
+        .describe('Environment variables for the agent (API keys go here). Their values are shown as *** and are handed to the sandbox in a one-shot file, never kept in the launch folder. The agent can read its own environment.'),
     home: HarnessHomeSchema.optional().describe('Where its login lives inside the sandbox; leave out when the agent cannot be pointed at a folder (then its login is not kept between sandboxes).'),
+    localState: z
+        .record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), SubfolderSchema)
+        .optional()
+        .describe("Environment variable -> folder below the agent's own state folder (state\\<agent>) for SQLite databases. SQLite cannot run in a mapped folder, so the agent runs from a copy on the sandbox's disk (the variable points to it) that is copied from and back to that folder."),
     resumeArguments: StringsSchema.optional().describe('Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.'),
     resumeOneArguments: StringsSchema.optional().describe('Arguments that reopen one conversation, with {id} where its id goes (claude: --resume {id}). Used instead of resumeArguments when the conversation of a session is known.'),
 })

package/dist/core/schema/index.d.ts

@@ -1,6 +1,8 @@
-export { GitAccessSchema } from './common.js';
+export { GitAccessSchema, NameSchema, secret } from './common.js';
+export { REDACTED, redactSecrets, scrubSecrets, secretPaths, secretValues } from './redact.js';
 export { ConfigSchema, LocalOverridesSchema } from './config.js';
 export { HarnessSchema } from './harness.js';
 export { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';
+export { VpnSchema, VPN_PROVIDERS, type VpnProvider } from './vpn.js';

package/dist/core/schema/index.js

@@ -1,8 +1,10 @@
 // Every setting, defined once with zod, split by area in schema/. This file is the one place the rest of the code (and
 // scripts/schemas.mjs, which generates the JSON Schema files) imports them from.
-export { GitAccessSchema } from './common.js';
+export { GitAccessSchema, NameSchema, secret } from './common.js';
+export { REDACTED, redactSecrets, scrubSecrets, secretPaths, secretValues } from './redact.js';
 export { ConfigSchema, LocalOverridesSchema } from './config.js';
 export { HarnessSchema } from './harness.js';
 export { describeIssues, jsonSchemas } from './json-schema.js';
 export { MappingSchema } from './sandbox.js';
 export { ToolchainsSchema } from './toolchains.js';
+export { VpnSchema, VPN_PROVIDERS } from './vpn.js';

package/dist/core/schema/profile.d.ts

@@ -22,6 +22,7 @@ export declare const ClaudeProfileSchema: z.ZodObject<{
     globalStateFile: z.ZodString;
     copyCredentials: z.ZodBoolean;
     overwrite: z.ZodBoolean;
+    sharePluginsAcrossAccounts: z.ZodBoolean;
     syncHistory: z.ZodBoolean;
     historyScope: z.ZodEnum<{
         project: "project";

package/dist/core/schema/profile.js

@@ -38,6 +38,9 @@ export const ClaudeProfileSchema = z.strictObject({
     globalStateFile: z.string().describe('Your .claude.json, or "auto". Empty string = do not copy.'),
     copyCredentials: z.boolean().describe('Copy your Claude LOGIN into the sandbox. Prefer sandbox account instead.'),
     overwrite: z.boolean().describe('Refresh these settings from this PC on every launch.'),
+    sharePluginsAcrossAccounts: z
+        .boolean()
+        .describe('When you switch Claude accounts, copy your Claude plugins (and which ones are enabled) into a data set that has none yet. Off by default: plugins are code that runs in your sessions.'),
     syncHistory: z.boolean().describe('Bring conversation history in, and sync new history back (path-translated).'),
     historyScope: z
         .enum(['project', 'all'])

package/dist/core/schema/redact.d.ts

@@ -0,0 +1,13 @@
+/** What is printed instead of a secret. */
+export declare const REDACTED = "***";
+/** A path through a config; "*" stands for any key of a map or any item of a list. */
+type SecretPath = readonly string[];
+/** Every setting marked secret, found from the schema itself (so a new secret setting needs no list). */
+export declare function secretPaths(): readonly SecretPath[];
+/** A copy of `config` with every secret value replaced by ***. */
+export declare function redactSecrets<T>(config: T): T;
+/** The secret values in `config` (for scrubbing text that was built from it). */
+export declare function secretValues(config: unknown): string[];
+/** `text` with every secret value of `config` replaced by *** (a last safety net for output built from a config). */
+export declare function scrubSecrets(text: string, config: unknown): string;
+export {};

package/dist/core/schema/redact.js

@@ -0,0 +1,75 @@
+// Secrets in settings: which values are marked `secret` in the schemas, and printing a config without them.
+import { z } from 'zod';
+import { ConfigSchema } from './config.js';
+/** What is printed instead of a secret. */
+export const REDACTED = '***';
+let cached = null;
+const walk = (node, at, out) => {
+    if (typeof node !== 'object' || node === null)
+        return;
+    const n = node;
+    if (n.secret === true)
+        out.push(at);
+    for (const [k, v] of Object.entries(n.properties ?? {}))
+        walk(v, [...at, k], out);
+    if (typeof n.additionalProperties === 'object')
+        walk(n.additionalProperties, [...at, '*'], out);
+    if (n.items)
+        walk(n.items, [...at, '*'], out);
+    for (const key of ['anyOf', 'oneOf', 'allOf'])
+        if (Array.isArray(n[key]))
+            for (const v of n[key])
+                walk(v, at, out);
+};
+/** Every setting marked secret, found from the schema itself (so a new secret setting needs no list). */
+export function secretPaths() {
+    if (!cached) {
+        const out = [];
+        walk(z.toJSONSchema(ConfigSchema, { io: 'input', unrepresentable: 'any' }), [], out);
+        cached = out;
+    }
+    return cached;
+}
+const blank = (value, path) => {
+    if (path.length === 0)
+        return typeof value === 'string' && value !== '' ? REDACTED : value;
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const [head, ...rest] = path;
+    if (Array.isArray(value))
+        return value.map((v) => (head === '*' ? blank(v, rest) : v));
+    const o = value;
+    return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, head === '*' || head === k ? blank(v, rest) : v]));
+};
+/** A copy of `config` with every secret value replaced by ***. */
+export function redactSecrets(config) {
+    return secretPaths().reduce((value, path) => blank(value, path), config);
+}
+const collect = (value, path, out) => {
+    if (path.length === 0) {
+        if (typeof value === 'string' && value !== '')
+            out.push(value);
+        return;
+    }
+    if (typeof value !== 'object' || value === null)
+        return;
+    const [head, ...rest] = path;
+    const o = value;
+    for (const [k, v] of Object.entries(o))
+        if (head === '*' || head === k)
+            collect(v, rest, out);
+};
+/** The secret values in `config` (for scrubbing text that was built from it). */
+export function secretValues(config) {
+    const out = [];
+    for (const path of secretPaths())
+        collect(config, path, out);
+    return [...new Set(out)];
+}
+/** `text` with every secret value of `config` replaced by *** (a last safety net for output built from a config). */
+export function scrubSecrets(text, config) {
+    return secretValues(config)
+        .filter((v) => v.length >= 4)
+        .sort((a, b) => b.length - a.length)
+        .reduce((t, v) => t.split(v).join(REDACTED).split(JSON.stringify(v).slice(1, -1)).join(REDACTED), text);
+}

package/dist/core/schema/sandbox.js

@@ -85,6 +85,7 @@ export const NetworkSchema = z.strictObject({
     proxy: z
         .string()
         .regex(/^(https?:\/\/[^\s]+)?$/, 'http://host:port')
+        .refine((v) => !/^https?:\/\/[^/?#]*@/i.test(v), 'no user name or password in the address (it would be stored in plain text and visible to the agent): use a proxy that needs no login')
         .describe('An HTTP proxy the sandbox uses to reach the internet (HTTP_PROXY / HTTPS_PROXY for everything in it), e.g. http://proxy.corp:8080. Empty = none.'),
 });
 export const AuditSchema = z.strictObject({

package/dist/core/schema/vpn.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const VPN_PROVIDERS: readonly ["nordvpn", "openvpn-file"];
+export declare const VpnSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    provider: z.ZodEnum<{
+        nordvpn: "nordvpn";
+        "openvpn-file": "openvpn-file";
+    }>;
+    protocol: z.ZodEnum<{
+        udp: "udp";
+        tcp: "tcp";
+    }>;
+    country: z.ZodString;
+    configFile: z.ZodString;
+    killSwitch: z.ZodBoolean;
+}, z.core.$strict>;
+export type VpnProvider = (typeof VPN_PROVIDERS)[number];

package/dist/core/schema/vpn.js

@@ -0,0 +1,22 @@
+// The VPN setting (inside the sandbox only; the login is not a setting: it is kept encrypted by `sandbox vpn login`).
+import { z } from 'zod';
+export const VPN_PROVIDERS = ['nordvpn', 'openvpn-file'];
+export const VpnSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe("Send the sandbox's traffic through a VPN. Only the sandbox: your PC's own connection is untouched. Needs a saved login first (sandbox vpn login). The agent in the sandbox can read that login and can turn the tunnel off (it is the administrator there)."),
+    provider: z
+        .enum(VPN_PROVIDERS)
+        .describe('nordvpn: a recommended NordVPN server is picked at every launch. openvpn-file: your own .ovpn file (configFile).'),
+    protocol: z.enum(['udp', 'tcp']).describe('udp is faster; tcp gets through networks that block udp.'),
+    country: z
+        .string()
+        .regex(/^([A-Za-z][A-Za-z .'-]{0,39})?$/, 'a country name or code like uk or Germany')
+        .describe('nordvpn: the country of the server, e.g. uk, us or Germany. Empty = the best server anywhere.'),
+    configFile: z
+        .string()
+        .describe("openvpn-file: the .ovpn file on this PC (its certificates inside it). Files that run programs (script-security, up, down, plugin ...) are refused. A project's file can never set this."),
+    killSwitch: z
+        .boolean()
+        .describe('Block all traffic that does not go through the tunnel: when the tunnel cannot start, the sandbox stays offline instead of using your normal connection. A project can only turn this on, never off.'),
+});

package/dist/core/schema/web.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export declare const WEB_DEFAULT_PORT = 47800;
+export declare const WebSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    port: z.ZodNumber;
+}, z.core.$strict>;

package/dist/core/schema/web.js

@@ -0,0 +1,14 @@
+// The web UI settings (sandbox web): not part of LocalOverrides, a repo never turns a way into your agents on.
+import { z } from 'zod';
+export const WEB_DEFAULT_PORT = 47800;
+export const WebSchema = z.strictObject({
+    enabled: z
+        .boolean()
+        .describe('(Beta) Allow the web UI: your sandbox sessions in a browser on this PC. Off by default, and nothing starts it by itself yet: sandbox web start works either way and runs it until sandbox web stop (or a restart of the PC).'),
+    port: z
+        .number()
+        .int()
+        .min(1024)
+        .max(65535)
+        .describe('Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken.'),
+});

package/dist/core/types.d.ts

@@ -102,6 +102,16 @@ export interface DatabasePlan {
     port: number;
     adminPort?: number;
 }
+/** The VPN decided at launch (host/vpn/prepare.ts): its checked profile, and the login for the one-shot file. */
+export interface PreparedVpn {
+    session: GuestVpn;
+    /** The profile text, already checked. */
+    profile: string;
+    credentials: {
+        username: string;
+        password: string;
+    };
+}
 /** databases / pcLanguages: use these instead of scanning (tests). */
 export interface GenerateOptions {
     packageRoot: string;
@@ -124,6 +134,8 @@ export interface GenerateOptions {
         projects: BootWant[];
         keepOff: string[];
     };
+    /** The VPN for this launch (vpn.enabled); its profile goes in the launch folder, its login in the one-shot file. */
+    vpn?: PreparedVpn;
 }
 export interface Generated {
     wsbPath: string;
@@ -162,6 +174,16 @@ export interface ProfileResult {
     credentials: boolean;
     secretsRemoved: string[];
 }
+/** The VPN of one launch: what the guest needs besides the login (which comes in the one-shot secrets file). */
+export interface GuestVpn {
+    provider: Config['vpn']['provider'];
+    protocol: Config['vpn']['protocol'];
+    killSwitch: boolean;
+    /** The server's name, for messages. */
+    server: string;
+    /** The checked profile, relative to the launch folder. */
+    profile: string;
+}
 /** Written by the host to C:\AgentLaunch\session.json (read-only for the guest): everything the guest needs to know. */
 export interface GuestSession {
     launchId: string;
@@ -196,6 +218,8 @@ export interface GuestSession {
     attach: Config['attach'];
     hooks: Config['hooks'];
     downloads: Config['downloads'];
+    /** Set when the VPN is on for this launch (older launch folders lack it). */
+    vpn?: GuestVpn;
     /** nodeVersion: this PC's Node (e.g. 22.11.0), found under nvm\v<version> when nvm is mapped, else under node. */
     /** volta / pyenv: this PC uses them (their "auto" settings turn them on in the sandbox too). */
     hostTools: {
@@ -237,4 +261,6 @@ export interface GuestSession {
     agentHomes?: Record<string, string>;
     /** Per agent: folders of the user profile (.qwen ...) linked into the persistent state at boot. */
     agentProfileDirs?: Record<string, string[]>;
+    /** Every configured agent (without its environment): a terminal command each; older launch folders lack it. */
+    agents?: Record<string, Harness>;
 }

package/dist/guest/agents/agent-files.d.ts

@@ -0,0 +1,49 @@
+import type { Harness } from '../../core/types.js';
+/** Where an agent lives in persistent storage: its folder, and the program (an .exe, or an npm .cmd) in it. */
+export interface AgentPaths {
+    readonly dir: string;
+    readonly exe: string | null;
+    readonly cmd: string | null;
+}
+export declare function agentPaths(toolsDir: string, name: string, harness: Harness): AgentPaths;
+/** The word a user types for this agent (`claude`, `codex` ...). */
+export declare function agentCommand(name: string, harness: Harness): string;
+/** What a terminal needs to run the agent by name: the command, and the program it runs once installed. */
+export interface AgentShim {
+    readonly name: string;
+    readonly command: string;
+    readonly target: string;
+}
+/** One shim per configured agent that can be installed here (a name that is not a plain command word is skipped). */
+export declare function agentShims(toolsDir: string, agents: Readonly<Record<string, Harness>>): AgentShim[];
+/**
+ * The text of `<command>.cmd`: runs the installed agent, or installs it first (`install` = node + installer script).
+ * The agent's own arguments pass through %* untouched.
+ */
+export declare function shimText(shim: AgentShim, install: {
+    node: string;
+    script: string;
+}): string;
+/** The `sbx-agent` command: `sbx-agent install <agent>` / `sbx-agent list`. */
+export declare function sbxAgentText(install: {
+    node: string;
+    script: string;
+}): string;
+/** A SQLite folder an agent runs from the sandbox's disk: the variable that points to `local`, and its saved copy. */
+export interface LocalState {
+    readonly agent: string;
+    readonly env: string;
+    /** The saved copy in persistent storage (state\<agent>\<folder>). */
+    readonly store: string;
+    /** The working copy on the sandbox's own disk. */
+    readonly local: string;
+    /** Image names of the programs that hold the databases open while they run. */
+    readonly processes: readonly string[];
+    /** Where the agent kept the databases before this existed (its state folder itself). */
+    readonly legacy: string;
+}
+export declare function localStateEntries(agents: Readonly<Record<string, Harness>>, stateDir: string, localRoot: string): LocalState[];
+/** A SQLite database file or one of its -wal / -shm siblings. */
+export declare const isDatabaseFile: (name: string) => boolean;
+/** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */
+export declare const isCopyableDatabaseFile: (name: string) => boolean;

package/dist/guest/agents/agent-files.js

@@ -0,0 +1,63 @@
+// Pure parts of the agents' files: where an agent is installed, the command that starts it in a terminal tab, and the
+// SQLite folders it runs from the sandbox's own disk. No side effects: the self-test imports this file.
+import path from 'node:path';
+export function agentPaths(toolsDir, name, harness) {
+    const dir = path.join(toolsDir, 'agents', name);
+    const exe = harness.hostExecutable ?? (harness.uvBin ? harness.uvBin + '.exe' : null);
+    return {
+        dir,
+        exe: exe ? path.join(dir, exe) : null,
+        cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null,
+    };
+}
+/** The word a user types for this agent (`claude`, `codex` ...). */
+export function agentCommand(name, harness) {
+    return harness.npmBin ?? harness.uvBin ?? (harness.hostExecutable ?? name).replace(/\.exe$/i, '');
+}
+/** One shim per configured agent that can be installed here (a name that is not a plain command word is skipped). */
+export function agentShims(toolsDir, agents) {
+    return Object.entries(agents).flatMap(([name, harness]) => {
+        const p = agentPaths(toolsDir, name, harness);
+        const target = p.exe ?? p.cmd;
+        const command = agentCommand(name, harness);
+        return target && /^[A-Za-z0-9_-]+$/.test(command) && /^[A-Za-z0-9_-]+$/.test(name)
+            ? [{ name, command, target }]
+            : [];
+    });
+}
+/**
+ * The text of `<command>.cmd`: runs the installed agent, or installs it first (`install` = node + installer script).
+ * The agent's own arguments pass through %* untouched.
+ */
+export function shimText(shim, install) {
+    return [
+        '@echo off',
+        'setlocal',
+        'set "SBX_REAL=' + shim.target + '"',
+        'if exist "%SBX_REAL%" goto run',
+        'echo ' + shim.command + ' is not installed in this sandbox yet. Installing it now (one time)...',
+        '"' + install.node + '" "' + install.script + '" install ' + shim.name,
+        'if errorlevel 1 exit /b 1',
+        ':run',
+        'endlocal & "%SBX_REAL%" %*',
+        '',
+    ].join('\r\n');
+}
+/** The `sbx-agent` command: `sbx-agent install <agent>` / `sbx-agent list`. */
+export function sbxAgentText(install) {
+    return '@"' + install.node + '" "' + install.script + '" %*\r\n';
+}
+export function localStateEntries(agents, stateDir, localRoot) {
+    return Object.entries(agents).flatMap(([agent, harness]) => Object.entries(harness.localState ?? {}).map(([env, folder]) => ({
+        agent,
+        env,
+        store: path.join(stateDir, agent, folder),
+        local: path.join(localRoot, agent, folder),
+        processes: [agentCommand(agent, harness) + '.exe'],
+        legacy: path.join(stateDir, agent),
+    })));
+}
+/** A SQLite database file or one of its -wal / -shm siblings. */
+export const isDatabaseFile = (name) => /\.(sqlite3?|db)(-wal|-shm)?$/i.test(name);
+/** Files that make a consistent copy: the databases and their -wal (the -shm is rebuilt by SQLite). */
+export const isCopyableDatabaseFile = (name) => isDatabaseFile(name) && !/-shm$/i.test(name);

package/dist/guest/agents/agent-installer.js

@@ -11,16 +11,9 @@ import { exists, mkdirp } from '../runtime/fs.js';
 import { log, warn } from '../runtime/log.js';
 import { session } from '../runtime/session.js';
 import { addMachineEnvironment } from '../setup/environment.js';
+import { agentPaths as paths } from './agent-files.js';
 import { linkHarnessProfile } from './profile-links.js';
-function agentPaths(name, harness) {
-    const dir = path.join(toolsDir, 'agents', name);
-    const exe = harness.hostExecutable ?? (harness.uvBin ? harness.uvBin + '.exe' : null);
-    return {
-        dir,
-        exe: exe ? path.join(dir, exe) : null,
-        cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null,
-    };
-}
+const agentPaths = (name, harness) => paths(toolsDir, name, harness);
 /** npm install with the runner's own npm into tools\agents\<name> (no global state outside persistent storage). */
 async function installViaNpm(name, harness, dir, env) {
     if (!harness.npmPackage)

package/dist/guest/agents/local-state.d.ts

@@ -0,0 +1,12 @@
+import { type LocalState } from './agent-files.js';
+/** Every SQLite folder of every configured agent (none in launch folders that predate the agents list). */
+export declare function agentLocalStates(): LocalState[];
+/** Variable -> working folder, for the agent environment (and the machine environment of new terminal tabs). */
+export declare function localStateVars(): Record<string, string>;
+/** Boot: the saved databases of every configured agent are copied to the sandbox's disk, where the agent runs them. */
+export declare function restoreLocalState(): void;
+/**
+ * Copies the working databases back to persistent storage (staging folder + swap). While the agent runs they are
+ * snapshotted with SQLite's online backup instead (see snapshotWhileRunning); nothing is done when nothing changed.
+ */
+export declare function saveLocalState(): void;