windows-development-sandbox 1.11.6 → 1.12.0

package/dist/selftest/support/web-preview.js

@@ -17,6 +17,8 @@ import { showData } from '../../app/features/data/index.js';
 import { updatesStatus } from '../../app/features/updates/index.js';
 import { containedStatus, showStorage } from '../../app/features/storage/index.js';
 import { listSessions } from '../../app/features/sessions/index.js';
+import { auditListing, listAudit } from '../../app/features/audit/index.js';
+import { AuditLog } from '../../host/audit/index.js';
 import { cancelled } from '../../app/kernel/index.js';
 import { runDefinition } from '../../app/registry.js';
 import { webSession } from '../../cli/services/index.js';
@@ -509,10 +511,101 @@ function sampleLogTail(input) {
         next: 0,
     });
 }
+/** A plausible audit log: two agents' sessions, the sandbox's own setup, a commit each, a guard finding. */
+function sampleAuditLog(dir) {
+    const log = new AuditLog(dir, { days: 7, maxMb: 100 });
+    const at = (minutesAgo) => new Date(Date.now() - minutesAgo * MINUTE).toISOString();
+    const claude = { s: SESSIONS[0].id, ag: 'claude', pj: 'windows-sandbox', sv: 'p' };
+    const codex = { s: 'mva7codex2k91x', ag: 'codex', pj: 'mw2-agent', sv: 'p' };
+    const git = 'C:\\AgentData\\tools\\git\\cmd\\git.exe';
+    const node = 'C:\\nvm\\nodejs\\node.exe';
+    const ws = 'F:\\AgentProjects\\windows-sandbox';
+    const mw = 'F:\\AgentProjects\\mw2-agent';
+    const proc = (m, p, c, who, n) => ({
+        t: at(m),
+        k: 'proc',
+        p,
+        c,
+        pp: node,
+        ...who,
+        ...(n ? { n } : {}),
+    });
+    const file = (m, p, w, who) => ({
+        t: at(m),
+        k: 'file',
+        a: 'change',
+        p,
+        w,
+        ...who,
+    });
+    log.append([
+        { t: at(95), k: 'note', p: 'sandbox started; audit: programs, files, commits, sessions' },
+        proc(94, 'C:\\AgentData\\tools\\uv\\uv.exe', 'uv tool install aider-chat', {}),
+        { t: at(90), k: 'session', a: 'start', p: 'claude', w: SESSIONS[0].cwd, c: claude.s, ...claude, sv: undefined },
+        proc(88, git, 'git status --short', claude),
+        proc(87, node, 'node dist/bin/agent-sandbox.js self-test audit', claude, 2),
+        file(80, 'src/host/audit/collect.ts', ws, claude),
+        file(79, 'src/app/features/audit/audit.def.ts', ws, claude),
+        proc(70, 'C:\\nvm\\nodejs\\npm.cmd', 'npm run build', claude),
+        {
+            t: at(66),
+            k: 'session',
+            a: 'start',
+            p: 'codex',
+            w: 'C:\\Projects\\mw2-agent',
+            c: codex.s,
+            ...codex,
+            sv: undefined,
+        },
+        proc(64, 'C:\\Users\\WDAGUtilityAccount\\.cargo\\bin\\cargo.exe', 'cargo build --release', codex, 3),
+        file(60, 'src/main.rs', mw, { ...codex, sv: 't' }),
+        proc(52, git, 'git commit -m "Audit: link programs to their session"', claude),
+        {
+            t: at(52),
+            k: 'commit',
+            a: 'commit',
+            p: 'Audit: link programs to their session',
+            h: 'a3f9c2e81b7d4c60a1e2f3b4c5d6e7f8a9b0c1d2',
+            au: 'Josh <josh@example.com>',
+            w: ws,
+            ...claude,
+        },
+        proc(40, git, 'git push --set-upstream origin https://***@github.com/example/mw2-agent.git', codex),
+        { t: at(38), k: 'guard', p: 'hook: a pre-push hook added inside the sandbox was neutralised' },
+        proc(30, 'C:\\Users\\WDAGUtilityAccount\\.cargo\\bin\\cargo.exe', 'cargo test', codex, 4),
+        {
+            t: at(28),
+            k: 'commit',
+            a: 'commit',
+            p: 'Fix the map loader',
+            h: '7be0d41c9a2f4e3b8c1d0e9f8a7b6c5d4e3f2a1b',
+            au: 'Josh <josh@example.com>',
+            w: mw,
+            ...codex,
+        },
+        {
+            t: at(20),
+            k: 'session',
+            a: 'end',
+            p: 'codex',
+            w: 'C:\\Projects\\mw2-agent',
+            c: codex.s + ' exit 0',
+            ...codex,
+            sv: undefined,
+        },
+        proc(5, node, 'node dist/bin/agent-sandbox.js self-test app', claude),
+    ]);
+    return log;
+}
 /** The real features where they only touch the temp folder, sample data for the rest. */
 function previewRpc(ctx, state) {
+    const auditDir = path.join(ctx.storageRoot, 'audit', 'preview');
+    const audit = sampleAuditLog(auditDir);
     const sample = async (id, input, io) => {
         switch (id) {
+            case 'audit.list':
+                // The real listing over a sample log in the temp folder.
+                return auditListing(audit, { enabled: true, days: 7, maxMb: 100 }, listAudit.input.parse(input ?? {}), auditDir);
             case 'sandbox.status':
                 return sampleStatus(state.running);
             case 'vpn.status':
@@ -792,6 +885,7 @@ function previewRpc(ctx, state) {
         'logs.tail': 'query',
         'engine.status': 'query',
         'engine.leftovers': 'query',
+        'audit.list': 'query',
     };
     return {
         kind: (id) => kinds[id],

package/dist/selftest/toolchains.test.js

@@ -1,12 +1,13 @@
 // Picking tool versions and release assets: Node/Go/Python/Java version rules, GitHub release pages, PowerShell 7,
-// cargo-binstall, the small CLI tools (gh, zstd, openssl), and when PowerShell 7 is wanted.
+// cargo-binstall, the small CLI tools (gh, zstd, openssl), when PowerShell 7 is wanted, and the apps' agent add-ons.
+import fs from 'node:fs';
 import path from 'node:path';
 import { javaMajorFrom, pickGoRelease, pickNodeVersion, pickPackageVersion, pickSpreadVersions, projectUses, specFromVersionFile, } from '../core/detect/index.js';
 import { parseReleasePage, parseReleaseTags } from '../shared/download/index.js';
 import { decidePwsh, pcHasPwsh, PWSH_MAX_BYTES, readPwshScripts, usesPwsh } from '../core/detect/index.js';
 import { binstallAsset, CLI_TOOLS, decideCli, pwshAsset } from '../guest/toolchains/catalogue.js';
 import { missingExtensions, vscodeExtensions, vscodeSettings } from '../guest/toolchains/tools/vscode-profile.js';
-import { APP_CATEGORIES, APPS, appsNeedMesa, appsToInstall, exeMatcher } from '../shared/apps/index.js';
+import { addonGuideLine, addonMcpServer, APP_CATEGORIES, APPS, appsNeedMesa, appsNeedUv, appsToInstall, CCUSAGE_VERSION, claudeManagedSettings, CONTEXT7_MCP_VERSION, exeMatcher, HEADROOM_VERSION, headroomArgs, headroomEnv, headroomUrl, PLAYWRIGHT_MCP_VERSION, RTK_VERSION, withAddonMcpServers, } from '../shared/apps/index.js';
 import { ConfigSchema, LocalOverridesSchema } from '../core/schema/index.js';
 export const toolchainsSuite = {
     name: 'toolchains',
@@ -236,5 +237,149 @@ export const toolchainsSuite = {
             !custom({ name: 'E', github: 'o/r', asset: 'x', url: 'https://x.org', exe: 'e.exe' }), 'apps: your own program comes from a GitHub release or an https link; plain http, a broken pattern or both are refused');
         t.check(!LocalOverridesSchema.safeParse({ apps: { custom: {} } }).success &&
             LocalOverridesSchema.safeParse({ apps: { install: ['jq'] } }).success, 'apps: a project file may add catalogue apps but never programs of its own');
+        t.section('agent add-ons');
+        const rtk = APPS.find((a) => a.id === 'rtk');
+        const rtkSource = rtk?.source;
+        t.check(rtk?.category === 'agents' &&
+            rtk.cli === true &&
+            rtk.userOnly === true &&
+            rtkSource !== undefined &&
+            'url' in rtkSource &&
+            rtkSource.url.startsWith('https://github.com/rtk-ai/rtk/releases/download/v' + RTK_VERSION + '/') &&
+            rtkSource.url.endsWith('-x86_64-pc-windows-msvc.zip') &&
+            /^[0-9a-f]{64}$/.test(rtkSource.sha256 ?? ''), 'rtk: a pinned https release file of rtk-ai/rtk with its SHA-256, on PATH, in your own settings only');
+        t.check(APPS.every((a) => !('url' in a.source) || a.source.url.startsWith('https://')) &&
+            APPS.every((a) => !('url' in a.source) || a.source.sha256 === undefined || /^[0-9a-f]{64}$/.test(a.source.sha256)), 'apps: every direct link is https, and a pinned checksum is 64 hex characters');
+        const agentApps = APPS.filter((a) => a.category === 'agents').map((a) => a.id);
+        t.check(APP_CATEGORIES.some((c) => c.id === 'agents' && c.label === 'Agent add-ons') &&
+            agentApps.includes('rtk') &&
+            agentApps.includes('claude-mem') &&
+            APPS.find((a) => a.id === 'claude-mem')?.setting === 'claudeProfile.syncClaudeMem', 'apps: the Agent add-ons category holds rtk and claude-mem (claude-mem through its own setting)');
+        t.check(!LocalOverridesSchema.safeParse({ apps: { install: ['rtk'] } }).success &&
+            !LocalOverridesSchema.safeParse({ apps: { install: ['claude-mem'] } }).success &&
+            ConfigSchema.shape.apps.shape.install.safeParse(['rtk']).success, 'rtk: only your own settings turn it on; a project file cannot');
+        const exe = 'C:\\AgentData\\tools\\apps\\rtk\\rtk.exe';
+        const withRtk = claudeManagedSettings([], exe);
+        const both = claudeManagedSettings(['Bash(git push:*)'], exe);
+        const gitOnly = claudeManagedSettings(['Bash(git push:*)'], null);
+        t.equal(withRtk?.hooks?.PreToolUse, [{ matcher: 'Bash', hooks: [{ type: 'command', command: '"C:/AgentData/tools/apps/rtk/rtk.exe" hook claude' }] }], "rtk: its documented Bash PreToolUse hook goes into the sandbox's managed settings");
+        t.check(claudeManagedSettings([], null) === null &&
+            gitOnly?.hooks === undefined &&
+            gitOnly?.permissions?.deny.length === 1 &&
+            both?.permissions?.deny.length === 1 &&
+            both.hooks?.PreToolUse.length === 1 &&
+            withRtk?.permissions === undefined, 'rtk: no hook when it is off; the git deny rules stay beside it; nothing to write when neither');
+        t.section('agent add-ons: Headroom, ccusage, Playwright MCP, Context7 MCP');
+        const pinned = {
+            headroom: ['uv', 'headroom-ai', HEADROOM_VERSION],
+            ccusage: ['npm', 'ccusage', CCUSAGE_VERSION],
+            'playwright-mcp': ['npm', '@playwright/mcp', PLAYWRIGHT_MCP_VERSION],
+            context7: ['npm', '@upstash/context7-mcp', CONTEXT7_MCP_VERSION],
+        };
+        for (const [id, [kind, pkg, version]] of Object.entries(pinned)) {
+            const entry = APPS.find((a) => a.id === id);
+            const source = entry?.source;
+            t.check(entry?.category === 'agents' &&
+                entry.userOnly === true &&
+                source !== undefined &&
+                'locked' in source &&
+                source.locked === kind &&
+                source.package === pkg &&
+                source.version === version &&
+                /^\d+\.\d+\.\d+$/.test(version) &&
+                !LocalOverridesSchema.safeParse({ apps: { install: [id] } }).success &&
+                ConfigSchema.shape.apps.shape.install.safeParse([id]).success, id + ': in Agent add-ons, a pinned ' + kind + ' package (' + pkg + ' ' + version + '), your own settings only');
+            const lockDir = path.join(t.packageRoot, 'sandbox', 'addons', id);
+            if (kind === 'npm') {
+                const manifest = JSON.parse(fs.readFileSync(path.join(lockDir, 'package.json'), 'utf8'));
+                const lock = JSON.parse(fs.readFileSync(path.join(lockDir, 'package-lock.json'), 'utf8'));
+                const deps = Object.entries(lock.packages).filter(([key]) => key !== '');
+                t.check(manifest.dependencies[pkg] === version &&
+                    Object.keys(manifest.dependencies).length === 1 &&
+                    lock.lockfileVersion === 3 &&
+                    lock.packages['node_modules/' + pkg]?.version === version &&
+                    deps.length > 0 &&
+                    deps.every(([, p]) => !p.link &&
+                        (p.resolved ?? '').startsWith('https://registry.npmjs.org/') &&
+                        /^sha512-[A-Za-z0-9+/]+=*$/.test(p.integrity ?? '')), id + ': its lock file pins ' + pkg + ' ' + version + '; every package comes from npm with a sha512 integrity');
+            }
+            else {
+                const lines = fs.readFileSync(path.join(lockDir, 'requirements.txt'), 'utf8').split(/\r?\n/);
+                const requirements = lines.filter((l) => /^[A-Za-z0-9]/.test(l));
+                const blocks = lines
+                    .join('\n')
+                    .split(/\n(?=[A-Za-z0-9])/)
+                    .slice(1);
+                t.check(requirements.includes(pkg + '==' + version + ' \\') &&
+                    requirements.length > 10 &&
+                    requirements.every((l) => /^[A-Za-z0-9._-]+(\[[^\]]+\])?==[^\s]+ \\$/.test(l)) &&
+                    blocks.every((b) => /--hash=sha256:[0-9a-f]{64}/.test(b)) &&
+                    !lines.some((l) => /^\s*(-e|--index-url|--extra-index-url|-f|--find-links|git\+|https?:)/.test(l.trim())), id + ': its requirements.txt pins every package to one version with SHA-256 hashes, from PyPI only');
+            }
+        }
+        t.check(appsNeedUv({ install: ['headroom'], custom: {} }) &&
+            !appsNeedUv({ install: ['ccusage', 'rtk'], custom: {} }) &&
+            !appsNeedUv(undefined), 'headroom: choosing it brings the uv step (it installs with uv)');
+        const services = APPS.filter((a) => a.service).map((a) => a.id);
+        t.check(['headroom', 'playwright-mcp', 'context7'].every((id) => services.includes(id)) &&
+            APPS.find((a) => a.id === 'ccusage')?.cli === true &&
+            !services.includes('ccusage'), 'add-ons: the proxy and MCP servers get no shortcut and no PATH entry; ccusage is a command on PATH');
+        // Headroom: loopback only, Anthropic only, no telemetry, and none of the agents' secrets in its environment.
+        const args = headroomArgs();
+        t.check(args[0] === 'proxy' &&
+            args[args.indexOf('--host') + 1] === '127.0.0.1' &&
+            args[args.indexOf('--port') + 1] === '8787' &&
+            args[args.indexOf('--anthropic-api-url') + 1] === 'https://api.anthropic.com' &&
+            args.includes('--no-telemetry') &&
+            headroomUrl() === 'http://127.0.0.1:8787', 'headroom: the proxy listens on 127.0.0.1 only and forwards only to api.anthropic.com, telemetry off');
+        const proxyEnv = headroomEnv({
+            PATH: 'C:\\Windows',
+            ANTHROPIC_API_KEY: 'sk-ant-x',
+            CLAUDE_CODE_OAUTH_TOKEN: 'oauth',
+            GITHUB_TOKEN: 'ghp',
+            OPENAI_API_KEY: 'sk',
+            DB_PASSWORD: 'pw',
+            HTTPS_PROXY: 'http://127.0.0.1:3128',
+            HEADROOM_OFFLINE: '0',
+        });
+        t.check(proxyEnv.PATH === 'C:\\Windows' &&
+            proxyEnv.HTTPS_PROXY === 'http://127.0.0.1:3128' &&
+            !Object.values(proxyEnv).some((v) => ['sk-ant-x', 'oauth', 'ghp', 'sk', 'pw'].includes(v)) &&
+            proxyEnv.HEADROOM_OFFLINE === '1' &&
+            proxyEnv.HEADROOM_TELEMETRY === 'off' &&
+            proxyEnv.HEADROOM_UPDATE_CHECK === 'off', 'headroom: starts without keys or tokens, offline apart from forwarding (no telemetry, updates or downloads)');
+        const routed = claudeManagedSettings([], null, headroomUrl());
+        t.check(routed?.env?.ANTHROPIC_BASE_URL === 'http://127.0.0.1:8787' &&
+            claudeManagedSettings([], exe)?.env === undefined &&
+            claudeManagedSettings(['Bash(git push:*)'], null)?.env === undefined &&
+            claudeManagedSettings(['Bash(git push:*)'], exe, headroomUrl())?.hooks?.PreToolUse.length === 1, "headroom: Claude Code is pointed at the proxy only while it runs (the sandbox's managed settings env)");
+        // MCP servers: set while on, removed when off, your own servers never touched.
+        const playwright = APPS.find((a) => a.id === 'playwright-mcp')?.mcp;
+        const context7 = APPS.find((a) => a.id === 'context7')?.mcp;
+        const known = APPS.flatMap((a) => (a.mcp ? [a.mcp.name] : []));
+        const pw = playwright ? addonMcpServer('C:\\AgentData\\tools\\apps\\playwright-mcp', playwright) : null;
+        t.equal(pw, {
+            type: 'stdio',
+            command: 'node',
+            args: [
+                'C:\\AgentData\\tools\\apps\\playwright-mcp\\node_modules\\@playwright\\mcp\\cli.js',
+                '--browser',
+                'msedge',
+            ],
+            env: {},
+        }, 'playwright-mcp: a stdio MCP server run by node from its own folder, with Edge');
+        const mine = { playwright: { type: 'stdio', command: 'npx', args: ['@playwright/mcp'] } };
+        const on = withAddonMcpServers(mine, pw ? { 'sbx-playwright': pw } : {}, known);
+        const off = withAddonMcpServers({ ...on, 'sbx-context7': {} }, {}, known);
+        t.check(known.length === 2 &&
+            known.every((n) => n.startsWith('sbx-')) &&
+            context7?.name === 'sbx-context7' &&
+            'sbx-playwright' in on &&
+            'playwright' in on &&
+            Object.keys(off).join() === 'playwright' &&
+            withAddonMcpServers({ 'sbx-other': 1 }, {}, known)['sbx-other'] === 1, 'add-ons: their sbx-... MCP servers are set while on and removed when off; servers of your own stay');
+        t.check(addonGuideLine([], false).length === 0 &&
+            addonGuideLine(['sbx-playwright'], true).length === 2 &&
+            addonGuideLine(['sbx-playwright'], false)[0].includes('sbx-playwright'), 'add-ons: the agent guide names the MCP servers and ccusage only when they are on');
     },
 };

package/dist/selftest/update-service.test.js

@@ -55,10 +55,6 @@ async function service(t) {
         found.available &&
         found.latest?.version === '1.0.1' &&
         layout.activeVersion() === '1.0.0', 'a managed install reports its version, automatic updates off by default; check finds a newer version and changes nothing');
-    sandbox = true;
-    const blocked = await svc.run();
-    t.check(blocked?.kind === 'skipped' && blocked.reason === 'sandbox-running' && layout.activeVersion() === '1.0.0', 'a running sandbox stops the update');
-    sandbox = false;
     const held = new UpdateLock(root, () => clock.at).acquire();
     const whileHeld = held !== null && (await svc.run()) === null;
     held?.();
@@ -239,10 +235,7 @@ async function command(t) {
     publish(t, feed, '1.0.1', 'good');
     lines.length = 0;
     t.check((await runU(machine, { check: true })).includes('Version 1.0.1 is available'), '--check names the newer version and exits 0');
-    const waiting = { kind: 'skipped', reason: 'sandbox-running', current: '1.0.0' };
     t.check(describeResult(null, false).code === 0 &&
-        describeResult(waiting, false).code === 1 &&
-        describeResult(waiting, true).code === 0 &&
         describeResult({ kind: 'installed', version: '1.0.1', previous: '1.0.0' }, false).line.includes('from 1.0.0 to 1.0.1') &&
         describeResult({ kind: 'failed', version: '1.0.1', reason: 'x', blocked: true, rolledBack: true, autoUpdateOff: true }, false).code === 1, 'exit codes: a running sandbox fails by hand but just waits unattended; a failed update exits 1');
 }

package/dist/selftest/update.test.js

@@ -86,13 +86,13 @@ export const updateSuite = {
             skip('no-release'),
             skip('up-to-date'),
             skip('up-to-date'),
-            skip('sandbox-running'),
+            install('1.0.1'),
             skip('too-soon'),
             install('1.0.1'),
             skip('failed-before'),
             skip('failed-before'),
             install('1.0.3'),
-        ], 'only a newer release installs; a running sandbox blocks; an hour after the last check is too soon unless forced; a failed version (and older) is not retried');
+        ], 'only a newer release installs, also while a sandbox runs; an hour after the last check is too soon unless forced; a failed version (and older) is not retried');
         t.check(!isTooSoon({ lastCheck: 'not a date' }, now, 24), 'a damaged last-check time does not block updates');
         t.section('updater: install, failure, rollback');
         const clock = { at: new Date('2026-10-14T12:00:00Z') };
@@ -123,8 +123,8 @@ export const updateSuite = {
         ], [
             { kind: 'skipped', reason: 'too-soon', current: '1.0.1' },
             { kind: 'skipped', reason: 'failed-before', current: '1.0.1' },
-            { kind: 'skipped', reason: 'sandbox-running', current: '1.0.1' },
-        ], 'no second look within 24 hours, no retry of the failed version, never under a running sandbox');
+            { kind: 'skipped', reason: 'failed-before', current: '1.0.1' },
+        ], 'no second look within 24 hours, no retry of the failed version (a running sandbox is not a reason to skip)');
         publish(t, feed, '1.0.3', 'good');
         const third = await updater.run({ sandboxRunning: false });
         t.check(JSON.stringify(third) === JSON.stringify({ kind: 'installed', version: '1.0.3', previous: '1.0.1' }) &&

package/dist/shared/apps/agent-addons.d.ts

@@ -0,0 +1,64 @@
+import type { AddonMcp } from './catalogue.js';
+/** One hook command in Claude Code's settings. */
+interface ClaudeHook {
+    readonly type: 'command';
+    readonly command: string;
+}
+/** Claude Code's managed-settings.json as the sandbox writes it. */
+export interface ManagedSettings {
+    readonly permissions?: {
+        readonly deny: readonly string[];
+    };
+    readonly hooks?: {
+        readonly PreToolUse: readonly {
+            readonly matcher: string;
+            readonly hooks: readonly ClaudeHook[];
+        }[];
+    };
+    readonly env?: Readonly<Record<string, string>>;
+}
+/** The command Claude Code runs for rtk's hook: the program by its full path (quoted, forward slashes for Git Bash). */
+export declare function rtkHookCommand(exe: string): string;
+/**
+ * The managed settings for the git deny rules, rtk's Bash hook when rtk is installed (`rtkExe`) and the Headroom proxy
+ * when it runs (`headroomUrl`). Null when there is nothing to write (the file is removed then).
+ */
+export declare function claudeManagedSettings(deny: readonly string[], rtkExe: string | null, headroomUrl?: string | null): ManagedSettings | null;
+/** The line every agent's sandbox guide gets while rtk is installed (Claude's commands go through it on their own). */
+export declare const RTK_GUIDE_LINE = "- rtk is on PATH and compacts command output: Claude Code's Bash commands go through it on their own; in other agents prefix shell commands with `rtk` (`rtk git status`, `rtk cargo test`, `rtk ls`).";
+/** Headroom listens here, on loopback only (its default port). */
+export declare const HEADROOM_PORT = 8787;
+/** The only upstream Headroom forwards to: Anthropic's API, set on its command line. */
+export declare const HEADROOM_UPSTREAM = "https://api.anthropic.com";
+/** Claude Code's ANTHROPIC_BASE_URL while the proxy runs. */
+export declare function headroomUrl(port?: number): string;
+/** `headroom proxy` on loopback, forwarding only to Anthropic's API, with no telemetry. */
+export declare function headroomArgs(port?: number): string[];
+/**
+ * Headroom's own switches: HEADROOM_OFFLINE refuses every connection Headroom would make on its own (telemetry, update
+ * checks, model downloads, usage polling) and keeps only the forwarding of the agent's requests.
+ */
+export declare const HEADROOM_ENV: Readonly<Record<string, string>>;
+/** The environment Headroom starts with: the sandbox's, minus anything secret, plus its own switches. */
+export declare function headroomEnv(base: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/** The guide line while the proxy runs. */
+export declare function headroomGuideLine(logFile: string): string;
+/** A user-scope MCP server in Claude Code's .claude.json. */
+export interface McpServerConfig {
+    readonly type: 'stdio';
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/** The name prefix of the sandbox's own MCP servers: names with it are the sandbox's to add and remove. */
+export declare const ADDON_MCP_PREFIX = "sbx-";
+/** The MCP server of an installed add-on: `node <folder>\<script> <args>` (Node is on PATH in every sandbox). */
+export declare function addonMcpServer(folder: string, mcp: AddonMcp): McpServerConfig;
+/**
+ * The user-scope MCP servers with the add-ons' servers set: every sbx-... server that `known` lists and that is not in
+ * `servers` is removed (an add-on turned off); servers of your own are never touched.
+ */
+export declare function withAddonMcpServers(current: Readonly<Record<string, unknown>>, servers: Readonly<Record<string, McpServerConfig>>, known: readonly string[]): Record<string, unknown>;
+/** The guide line for the add-ons' MCP servers and tools (none: no line). */
+export declare function addonGuideLine(mcpNames: readonly string[], ccusage: boolean): string[];
+export {};

package/dist/shared/apps/agent-addons.js

@@ -0,0 +1,95 @@
+/** The command Claude Code runs for rtk's hook: the program by its full path (quoted, forward slashes for Git Bash). */
+export function rtkHookCommand(exe) {
+    return '"' + exe.replace(/\\/g, '/') + '" hook claude';
+}
+/**
+ * The managed settings for the git deny rules, rtk's Bash hook when rtk is installed (`rtkExe`) and the Headroom proxy
+ * when it runs (`headroomUrl`). Null when there is nothing to write (the file is removed then).
+ */
+export function claudeManagedSettings(deny, rtkExe, headroomUrl = null) {
+    if (!deny.length && !rtkExe && !headroomUrl)
+        return null;
+    return {
+        ...(deny.length ? { permissions: { deny } } : {}),
+        ...(rtkExe
+            ? { hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: rtkHookCommand(rtkExe) }] }] } }
+            : {}),
+        ...(headroomUrl ? { env: { ANTHROPIC_BASE_URL: headroomUrl } } : {}),
+    };
+}
+/** The line every agent's sandbox guide gets while rtk is installed (Claude's commands go through it on their own). */
+export const RTK_GUIDE_LINE = "- rtk is on PATH and compacts command output: Claude Code's Bash commands go through it on their own; in other agents prefix shell commands with `rtk` (`rtk git status`, `rtk cargo test`, `rtk ls`).";
+/** Headroom listens here, on loopback only (its default port). */
+export const HEADROOM_PORT = 8787;
+/** The only upstream Headroom forwards to: Anthropic's API, set on its command line. */
+export const HEADROOM_UPSTREAM = 'https://api.anthropic.com';
+/** Claude Code's ANTHROPIC_BASE_URL while the proxy runs. */
+export function headroomUrl(port = HEADROOM_PORT) {
+    return 'http://127.0.0.1:' + port;
+}
+/** `headroom proxy` on loopback, forwarding only to Anthropic's API, with no telemetry. */
+export function headroomArgs(port = HEADROOM_PORT) {
+    return [
+        'proxy',
+        '--host',
+        '127.0.0.1',
+        '--port',
+        String(port),
+        '--anthropic-api-url',
+        HEADROOM_UPSTREAM,
+        '--no-telemetry',
+    ];
+}
+/**
+ * Headroom's own switches: HEADROOM_OFFLINE refuses every connection Headroom would make on its own (telemetry, update
+ * checks, model downloads, usage polling) and keeps only the forwarding of the agent's requests.
+ */
+export const HEADROOM_ENV = {
+    HEADROOM_OFFLINE: '1',
+    HEADROOM_TELEMETRY: 'off',
+    HEADROOM_BEACON: 'off',
+    HEADROOM_UPDATE_CHECK: 'off',
+    DO_NOT_TRACK: '1',
+    HF_HUB_OFFLINE: '1',
+    PYTHONIOENCODING: 'utf-8',
+};
+/** Variables the proxy never gets: keys, tokens and passwords of the agents (it only forwards what Claude sends). */
+const SECRET_NAME = /(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)/i;
+/** The environment Headroom starts with: the sandbox's, minus anything secret, plus its own switches. */
+export function headroomEnv(base) {
+    const env = {};
+    for (const [name, value] of Object.entries(base))
+        if (value !== undefined && !SECRET_NAME.test(name) && !/^(ANTHROPIC|OPENAI|CLAUDE)_/i.test(name))
+            env[name] = value;
+    return { ...env, ...HEADROOM_ENV };
+}
+/** The guide line while the proxy runs. */
+export function headroomGuideLine(logFile) {
+    return ("- Headroom compresses Claude Code's requests: Claude Code reaches the API through its proxy on " +
+        headroomUrl() +
+        ' (log: `' +
+        logFile +
+        '`). If Claude Code cannot reach the API, the proxy stopped: it starts again with the next sandbox, or turn Headroom off in Apps.');
+}
+/** The name prefix of the sandbox's own MCP servers: names with it are the sandbox's to add and remove. */
+export const ADDON_MCP_PREFIX = 'sbx-';
+/** The MCP server of an installed add-on: `node <folder>\<script> <args>` (Node is on PATH in every sandbox). */
+export function addonMcpServer(folder, mcp) {
+    const script = folder.replace(/[\\/]+$/, '') + '\\' + mcp.script.replace(/\//g, '\\');
+    return { type: 'stdio', command: 'node', args: [script, ...(mcp.args ?? [])], env: {} };
+}
+/**
+ * The user-scope MCP servers with the add-ons' servers set: every sbx-... server that `known` lists and that is not in
+ * `servers` is removed (an add-on turned off); servers of your own are never touched.
+ */
+export function withAddonMcpServers(current, servers, known) {
+    const kept = Object.fromEntries(Object.entries(current).filter(([name]) => !known.includes(name) || name in servers));
+    return { ...kept, ...servers };
+}
+/** The guide line for the add-ons' MCP servers and tools (none: no line). */
+export function addonGuideLine(mcpNames, ccusage) {
+    return [
+        ...(mcpNames.length ? ['- MCP servers in Claude Code from Apps: ' + mcpNames.join(', ') + '.'] : []),
+        ...(ccusage ? ['- ccusage is on PATH: `ccusage daily` (or `monthly`, `session`) reports token use and cost.'] : []),
+    ];
+}

package/dist/shared/apps/catalogue.d.ts

@@ -1,20 +1,36 @@
-export type AppCategory = 'editors' | 'databases' | 'api' | 'git' | 'utilities' | 'browsers' | 'gamedev' | 'cloud' | 'diagrams' | 'network' | 'reversing' | 'cli';
+export type AppCategory = 'agents' | 'editors' | 'databases' | 'api' | 'git' | 'utilities' | 'browsers' | 'gamedev' | 'cloud' | 'diagrams' | 'network' | 'reversing' | 'cli';
 export declare const APP_CATEGORIES: {
     id: AppCategory;
     label: string;
     description: string;
 }[];
-/** Where a download comes from. Resolvers (sublime, kubectl ...) are code in guest/apps, named here by id. */
+/**
+ * Where a download comes from. Resolvers (sublime, kubectl ...) are code in guest/apps, named here by id. `locked`: a
+ * pinned package installed from the lock file in sandbox\addons\<id> (npm: package.json + package-lock.json, every
+ * tarball checked against its integrity; uv: requirements.txt, every wheel checked against its SHA-256).
+ */
 export type AppSource = {
     github: string;
     asset: string;
 } | {
     url: string;
+    sha256?: string;
 } | {
     resolve: string;
 } | {
     npm: string;
+} | {
+    locked: 'npm' | 'uv';
+    package: string;
+    version: string;
 };
+/** An MCP server an add-on adds to the sandbox's Claude Code: `node <its folder>\<script> <args>`. */
+export interface AddonMcp {
+    /** The server's name in Claude Code (sbx-...: the sandbox removes its own names again when the add-on is off). */
+    readonly name: string;
+    readonly script: string;
+    readonly args?: readonly string[];
+}
 export interface AppEntry {
     id: string;
     name: string;
@@ -39,6 +55,21 @@ export interface AppEntry {
     setting?: string;
     /** Only with full git access (it pushes on its own, past the sandbox's git guard). */
     fullGitOnly?: boolean;
+    /** Which agents it plugs into, and how (agent add-ons). */
+    plugsInto?: string;
+    /** Only in your own settings: a project's .sandbox-config.json cannot turn it on (it changes what the agents run). */
+    userOnly?: boolean;
+    /** Started by the sandbox or the agent (a proxy, an MCP server): not on PATH and no shortcut. */
+    service?: boolean;
+    /** The MCP server it adds to the sandbox's Claude Code while it is on. */
+    mcp?: AddonMcp;
 }
+/** rtk (rtk-ai/rtk), pinned: the Apache-2.0 edition's Windows build. The checksum is the release's checksums.txt. */
+export declare const RTK_VERSION = "1.0.1";
+/** Pinned agent add-ons, installed from the lock files in sandbox\addons\<id> (renewing them: docs/toolchains.md). */
+export declare const HEADROOM_VERSION = "0.41.0";
+export declare const CCUSAGE_VERSION = "20.0.36";
+export declare const PLAYWRIGHT_MCP_VERSION = "0.0.83";
+export declare const CONTEXT7_MCP_VERSION = "4.4.2";
 export declare const APPS: AppEntry[];
 export declare function appById(id: string): AppEntry | undefined;