windows-development-sandbox 1.11.7 → 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/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;

package/dist/shared/apps/catalogue.js

@@ -1,8 +1,14 @@
 // The apps catalogue: desktop programs and command-line tools the sandbox can install on request (apps.install), each a
 // portable download kept in C:\AgentData\tools\apps\<id> (installers would be lost when the sandbox closes). Pure data,
 // shared by the menu on the PC (to list them) and the sandbox (to install them, guest/apps). VS Code and Windows
-// Terminal have settings of their own (toolchains.vscode, provisioning.terminal) and are listed here too.
+// Terminal have settings of their own (toolchains.vscode, provisioning.terminal) and are listed here too, like
+// claude-mem (claudeProfile.syncClaudeMem) among the agent add-ons.
 export const APP_CATEGORIES = [
+    {
+        id: 'agents',
+        label: 'Agent add-ons',
+        description: 'Things that plug into the agents: token savers, memory, MCP servers.',
+    },
     {
         id: 'editors',
         label: 'Editors & IDEs',
@@ -49,7 +55,102 @@ export const APP_CATEGORIES = [
     },
 ];
 const gh = (github, asset) => ({ github, asset });
+/** rtk (rtk-ai/rtk), pinned: the Apache-2.0 edition's Windows build. The checksum is the release's checksums.txt. */
+export const RTK_VERSION = '1.0.1';
+const RTK_URL = 'https://github.com/rtk-ai/rtk/releases/download/v' + RTK_VERSION + '/rtk-oss-x86_64-pc-windows-msvc.zip';
+const RTK_SHA256 = '0e53e2eca471e15fbd3636e64e6bc0b182cbc278ed0339c80450a2dd03f4cd6b';
+/** Pinned agent add-ons, installed from the lock files in sandbox\addons\<id> (renewing them: docs/toolchains.md). */
+export const HEADROOM_VERSION = '0.41.0';
+export const CCUSAGE_VERSION = '20.0.36';
+export const PLAYWRIGHT_MCP_VERSION = '0.0.83';
+export const CONTEXT7_MCP_VERSION = '4.4.2';
 export const APPS = [
+    // ---- agent add-ons
+    {
+        id: 'rtk',
+        name: 'rtk (Rust Token Killer)',
+        category: 'agents',
+        about: "Compacts the output of shell commands (git, tests, builds, ls ...) before the agent reads it, so it uses fewer tokens. Claude Code's Bash commands go through it on their own.",
+        size: '6 MB',
+        source: { url: RTK_URL, sha256: RTK_SHA256 },
+        exe: 'rtk.exe',
+        cli: true,
+        plugsInto: "Claude Code through a hook in the sandbox's managed settings; other agents are told to use it",
+        userOnly: true,
+    },
+    {
+        id: 'headroom',
+        name: 'Headroom',
+        category: 'agents',
+        about: "Compresses what Claude Code sends to the model (tool output, logs, files) so it uses fewer tokens: a local proxy on 127.0.0.1:8787 that sits in Claude Code's API path, offline apart from forwarding to api.anthropic.com.",
+        size: '150 MB',
+        source: { locked: 'uv', package: 'headroom-ai', version: HEADROOM_VERSION },
+        exe: 'headroom.exe',
+        service: true,
+        plugsInto: 'Claude Code: the sandbox starts the proxy and points Claude Code at it (managed settings)',
+        userOnly: true,
+    },
+    {
+        id: 'ccusage',
+        name: 'ccusage',
+        category: 'agents',
+        about: "Reports the agents' token use and cost by day, month or session from their logs in the sandbox (`ccusage daily`; add --offline to skip fetching prices).",
+        size: '5 MB',
+        source: { locked: 'npm', package: 'ccusage', version: CCUSAGE_VERSION },
+        exe: 'ccusage.cmd',
+        cli: true,
+        plugsInto: "Reads Claude Code's session logs in the sandbox; changes nothing",
+        userOnly: true,
+    },
+    {
+        id: 'playwright-mcp',
+        name: 'Playwright MCP',
+        category: 'agents',
+        about: 'Lets Claude Code drive a browser (Microsoft Edge, already in the sandbox) to open pages, click, fill forms and take screenshots: the MCP server of microsoft/playwright-mcp.',
+        size: '20 MB',
+        source: { locked: 'npm', package: '@playwright/mcp', version: PLAYWRIGHT_MCP_VERSION },
+        exe: 'playwright-mcp.cmd',
+        service: true,
+        mcp: { name: 'sbx-playwright', script: 'node_modules/@playwright/mcp/cli.js', args: ['--browser', 'msedge'] },
+        plugsInto: "Claude Code as the MCP server sbx-playwright (the sandbox's Claude settings)",
+        userOnly: true,
+    },
+    {
+        id: 'context7',
+        name: 'Context7 MCP',
+        category: 'agents',
+        about: "Up-to-date documentation and code examples for libraries, looked up by Claude Code while it works (upstash/context7). The library names and questions go to Upstash's context7.com.",
+        size: '55 MB',
+        source: { locked: 'npm', package: '@upstash/context7-mcp', version: CONTEXT7_MCP_VERSION },
+        exe: 'context7-mcp.cmd',
+        service: true,
+        mcp: { name: 'sbx-context7', script: 'node_modules/@upstash/context7-mcp/dist/index.js' },
+        plugsInto: "Claude Code as the MCP server sbx-context7 (the sandbox's Claude settings)",
+        userOnly: true,
+    },
+    {
+        id: 'claude-mem',
+        name: 'claude-mem',
+        category: 'agents',
+        about: 'Persistent memory for Claude Code (a plugin you install on this PC): its database is brought into the sandbox.',
+        size: '',
+        source: { resolve: 'setting' },
+        exe: '',
+        setting: 'claudeProfile.syncClaudeMem',
+        plugsInto: 'Claude Code, with your Claude settings copied from this PC',
+        userOnly: true,
+    },
+    {
+        id: 'rea',
+        name: 'REA (Reverse Engineer Anything)',
+        category: 'agents',
+        about: 'Agent-driven reverse engineering (MCP server and CLI, by morluto). Run `rea setup` once to add it to Claude Code and Codex. Native binaries need Ghidra; needs Node 22.19+.',
+        size: '8 MB',
+        source: { npm: 'rea-agents' },
+        exe: 'rea.cmd',
+        cli: true,
+        plugsInto: 'Claude Code and Codex as an MCP server, after `rea setup`',
+    },
     // ---- editors
     {
         id: 'vscode',
@@ -511,16 +612,6 @@ export const APPS = [
         cli: true,
     },
     // ---- reverse engineering
-    {
-        id: 'rea',
-        name: 'REA (Reverse Engineer Anything)',
-        category: 'reversing',
-        about: 'Agent-driven reverse engineering (MCP server and CLI, by morluto). Run `rea setup` once to add it to Claude Code and Codex. Native binaries need Ghidra; needs Node 22.19+.',
-        size: '8 MB',
-        source: { npm: 'rea-agents' },
-        exe: 'rea.cmd',
-        cli: true,
-    },
     {
         id: 'ghidra',
         name: 'Ghidra',

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

@@ -1,2 +1,3 @@
-export { type AppCategory, APP_CATEGORIES, type AppSource, type AppEntry, APPS, appById } from './catalogue.js';
-export { exeMatcher, appsToInstall, appsNeedMesa } from './selection.js';
+export { type AddonMcp, type AppCategory, APP_CATEGORIES, type AppSource, type AppEntry, APPS, appById, CCUSAGE_VERSION, CONTEXT7_MCP_VERSION, HEADROOM_VERSION, PLAYWRIGHT_MCP_VERSION, RTK_VERSION, } from './catalogue.js';
+export { exeMatcher, appsToInstall, appsNeedMesa, appsNeedUv } from './selection.js';
+export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, claudeManagedSettings, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, type ManagedSettings, type McpServerConfig, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';