windows-development-sandbox 1.1.0 → 1.4.0

package/dist/guest/toolchains/python.js

@@ -35,6 +35,27 @@ const shimPair = (folder, version, dir) => {
     shim(folder, 'python' + version, python);
     shim(folder, 'pip' + version, python + ' -m pip');
 };
+/**
+ * `py` like the Python launcher Windows installs: `py -3 x.py`, `py -3.12 ...`, `py -2 ...`, `py x.py`. The launcher
+ * itself is not portable, so py.cmd runs a small script that picks the interpreter (cmd's %* ignores shift).
+ */
+const pyLauncher = (folder, py3, py2) => {
+    const script = path.join(mkdirp(folder), 'py-launcher.py');
+    fs.writeFileSync(script, [
+        'import subprocess, sys',
+        'PY3, PY2 = ' + JSON.stringify(path.join(py3, 'python.exe')) + ', ' + JSON.stringify(py2 ? path.join(py2, 'python.exe') : null),
+        'args = sys.argv[1:]',
+        'exe = PY3',
+        "if args and args[0].startswith('-2'):",
+        '    if not PY2: sys.exit("py: Python 2 is not installed (toolchains.python.python2)")',
+        '    exe, args = PY2, args[1:]',
+        "elif args and (args[0] == '-3' or args[0].startswith('-3.') or args[0].startswith('-3-')):",
+        '    args = args[1:]',
+        'sys.exit(subprocess.call([exe] + args))',
+        '',
+    ].join('\n'));
+    shim(folder, 'py', '"' + path.join(py3, 'python.exe') + '" "' + script + '"');
+};
 export const setupPython = async (env, config, versions) => {
     if (dryRun) {
         log('(dry run) would provision Python ' + versions.python.spec + (config.python2 ? ' and Python 2.7' : ''));
@@ -45,10 +66,13 @@ export const setupPython = async (env, config, versions) => {
     shimPair(shims, '3', py3);
     env.prepend.push(py3, path.join(py3, 'Scripts'), shims);
     env.vars.PYTHONIOENCODING = 'utf-8';
-    env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + ')');
-    if (!config.python2)
+    env.summary.push('python: ' + path.basename(py3).replace('python-', '') + ' (from ' + versions.python.source + '; py works too)');
+    if (!config.python2) {
+        pyLauncher(shims, py3, null);
         return;
+    }
     const py2 = await installPython('python2', '2.7');
     shimPair(shims, '2', py2);
+    pyLauncher(shims, py3, py2);
     env.summary.push('python2: ' + path.basename(py2).replace('python2-', ''));
 };

package/dist/guest/toolchains/vscode-profile.d.ts

@@ -0,0 +1,30 @@
+/** Where the sandbox's tools are (absent = not installed). */
+export interface ToolPaths {
+    javaHome?: string;
+    python?: string;
+    goRoot?: string;
+    go?: string;
+    gcc?: string;
+    cl?: string;
+    cmake?: string;
+    dotnet?: string;
+    node?: string;
+    pwsh?: string;
+    git?: string;
+    bash?: string;
+    php?: string;
+    ruby?: string;
+    deno?: string;
+}
+/** User settings for the sandbox's VS Code. Only keys with a value are set; the caller removes the ones it set before. */
+export declare const vscodeSettings: (p: ToolPaths) => Record<string, unknown>;
+export declare const EXTENSION_ID: RegExp;
+/** The extensions to have: always EditorConfig, then per toolchain and database in use, the project's, and yours. */
+export declare const vscodeExtensions: (o: {
+    toolchains: string[];
+    databases: string[];
+    recommended: string[];
+    extra: string[];
+}) => string[];
+/** Extensions not installed yet, from the names of the folders in VS Code's extensions folder (publisher.name-1.2.3). */
+export declare const missingExtensions: (wanted: string[], folders: string[]) => string[];

package/dist/guest/toolchains/vscode-profile.js

@@ -0,0 +1,69 @@
+// What VS Code is told about the sandbox: the settings that point it at the sandbox's own tools, and the extensions
+// for the languages in use. Pure (tested); vscode.ts finds the paths and writes them.
+/** The JDK's major version from its folder name (jdk-21.0.5+11 -> 21). */
+const javaMajor = (home) => /(?:jdk|jre)?-?(\d{1,2})(?:[.+_-]|$)/i.exec(home.split(/[\\/]/).pop() ?? '')?.[1];
+/** User settings for the sandbox's VS Code. Only keys with a value are set; the caller removes the ones it set before. */
+export const vscodeSettings = (p) => {
+    const profiles = {};
+    if (p.pwsh)
+        profiles['PowerShell 7'] = { path: p.pwsh, args: ['-NoLogo'] };
+    if (p.bash)
+        profiles['Git Bash'] = { path: p.bash, args: ['--login', '-i'] };
+    const settings = {
+        'telemetry.telemetryLevel': 'off',
+        'update.mode': 'none',
+        'workbench.startupEditor': 'none',
+        'git.path': p.git,
+        'terminal.integrated.profiles.windows': Object.keys(profiles).length ? profiles : undefined,
+        'terminal.integrated.defaultProfile.windows': p.pwsh ? 'PowerShell 7' : undefined,
+        'python.defaultInterpreterPath': p.python,
+        'java.jdt.ls.java.home': p.javaHome,
+        'java.configuration.runtimes': p.javaHome ? [{ name: 'JavaSE-' + (javaMajor(p.javaHome) ?? '21'), path: p.javaHome, default: true }] : undefined,
+        'maven.terminal.useJavaHome': p.javaHome ? true : undefined,
+        'go.goroot': p.goRoot,
+        'go.alternateTools': p.go ? { go: p.go } : undefined,
+        'C_Cpp.default.compilerPath': p.cl ?? p.gcc,
+        'cmake.cmakePath': p.cmake,
+        'dotnet.dotnetPath': p.dotnet ? p.dotnet.replace(/[\\/]dotnet\.exe$/i, '') : undefined,
+        'dotnetAcquisitionExtension.existingDotnetPath': p.dotnet ? [{ extensionId: 'ms-dotnettools.csharp', path: p.dotnet }] : undefined,
+        'php.validate.executablePath': p.php,
+        'php.debug.executablePath': p.php,
+        'rubyLsp.rubyVersionManager': p.ruby ? { identifier: 'none' } : undefined,
+        'deno.path': p.deno,
+        'powershell.powerShellAdditionalExePaths': p.pwsh ? { 'PowerShell 7 (sandbox)': p.pwsh } : undefined,
+        'npm.packageManager': 'auto',
+    };
+    return Object.fromEntries(Object.entries(settings).filter(([, v]) => v !== undefined));
+};
+/** Extensions per toolchain (Marketplace ids). */
+const BY_TOOLCHAIN = {
+    node: ['dbaeumer.vscode-eslint', 'esbenp.prettier-vscode'],
+    python: ['ms-python.python', 'ms-python.debugpy'],
+    java: ['redhat.java', 'vscjava.vscode-java-debug', 'vscjava.vscode-java-test', 'vscjava.vscode-maven', 'vscjava.vscode-gradle'],
+    go: ['golang.go'],
+    rust: ['rust-lang.rust-analyzer', 'vadimcn.vscode-lldb'],
+    cpp: ['ms-vscode.cpptools', 'ms-vscode.cmake-tools'],
+    msvc: ['ms-vscode.cpptools', 'ms-vscode.cmake-tools'],
+    dotnet: ['ms-dotnettools.csharp'],
+    ruby: ['shopify.ruby-lsp'],
+    php: ['bmewburn.vscode-intelephense-client', 'xdebug.php-debug'],
+    deno: ['denoland.vscode-deno'],
+    pwsh: ['ms-vscode.powershell'],
+};
+const BY_DATABASE = {
+    postgres: ['mtxr.sqltools', 'mtxr.sqltools-driver-pg'],
+    mysql: ['mtxr.sqltools', 'mtxr.sqltools-driver-mysql'],
+    mongodb: ['mongodb.mongodb-vscode'],
+    redis: ['redis.redis-for-vscode'],
+};
+export const EXTENSION_ID = /^[\w-]+\.[\w-]+$/;
+/** The extensions to have: always EditorConfig, then per toolchain and database in use, the project's, and yours. */
+export const vscodeExtensions = (o) => {
+    const all = ['editorconfig.editorconfig', ...o.toolchains.flatMap((t) => BY_TOOLCHAIN[t] ?? []), ...o.databases.flatMap((d) => BY_DATABASE[d] ?? []), ...o.recommended, ...o.extra];
+    return [...new Set(all.map((e) => e.toLowerCase()))].filter((e) => EXTENSION_ID.test(e));
+};
+/** Extensions not installed yet, from the names of the folders in VS Code's extensions folder (publisher.name-1.2.3). */
+export const missingExtensions = (wanted, folders) => {
+    const have = folders.map((f) => f.toLowerCase());
+    return wanted.filter((id) => !have.some((f) => f.startsWith(id + '-')));
+};

package/dist/guest/toolchains/vscode.d.ts

@@ -1,2 +1,19 @@
+import type { Toolchains } from '../../core/types.js';
 import { type ToolEnv } from './common.js';
+/**
+ * After every toolchain is installed: points VS Code at the sandbox's own JDK, Python, Go, compilers, .NET, Git and
+ * terminals (user settings; only the keys this tool manages are changed, your own stay), and installs the extensions
+ * for the languages in use in the background (they persist, so only new ones are downloaded).
+ */
+export declare const configureVscode: (tools: {
+    vars: Record<string, string>;
+    prepend: string[];
+    append: string[];
+    summary: string[];
+}, o: {
+    toolchains: string[];
+    databases: string[];
+    config: Toolchains["vscode"];
+    workspace: string;
+}) => void;
 export declare const setupVscode: (env: ToolEnv, refresh: boolean) => Promise<void>;

package/dist/guest/toolchains/vscode.js

@@ -3,9 +3,13 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser';
 import { fetchJson, installArchive } from '../../shared/download.js';
-import { dryRun, exists, isWin, log, mkdirp, powershell } from '../env.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, exists, isWin, log, logsDir, mkdirp, powershell } from '../env.js';
 import { arch, tool } from './common.js';
+import { EXTENSION_ID, missingExtensions, vscodeExtensions, vscodeSettings } from './vscode-profile.js';
 /** Newer builds keep their files under a commit-hash folder, so the installed version is recorded here. */
 const VERSION_MARKER = '.agent-sandbox-version';
 const desktopShortcut = (exe) => {
@@ -15,6 +19,88 @@ const desktopShortcut = (exe) => {
     const q = (s) => "'" + s.replace(/'/g, "''") + "'";
     powershell('$s = (New-Object -ComObject WScript.Shell).CreateShortcut(' + q(link) + '); $s.TargetPath = ' + q(exe) + '; $s.Arguments = ' + q('"' + (process.env.AGENT_WORKSPACE ?? '') + '"') + '; $s.Save()');
 };
+/** The first of `names` in one of `dirs`. */
+const findIn = (dirs, ...names) => {
+    for (const dir of dirs)
+        for (const name of names) {
+            const file = path.join(dir, name);
+            if (exists(file))
+                return file;
+        }
+    return undefined;
+};
+/** The project's .vscode/extensions.json recommendations (bounded; anything odd is ignored). */
+const recommendedBy = (workspace) => {
+    const file = path.join(workspace, '.vscode', 'extensions.json');
+    try {
+        if (!exists(file) || fs.statSync(file).size > 64 * 1024)
+            return [];
+        const data = parseJsonc(fs.readFileSync(file, 'utf8'));
+        return Array.isArray(data?.recommendations) ? data.recommendations.filter((r) => typeof r === 'string' && EXTENSION_ID.test(r)).slice(0, 50) : [];
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * After every toolchain is installed: points VS Code at the sandbox's own JDK, Python, Go, compilers, .NET, Git and
+ * terminals (user settings; only the keys this tool manages are changed, your own stay), and installs the extensions
+ * for the languages in use in the background (they persist, so only new ones are downloaded).
+ */
+export const configureVscode = (tools, o) => {
+    const root = tool('vscode');
+    const code = path.join(root, 'bin', 'code.cmd');
+    if (dryRun) {
+        log('(dry run) would set up VS Code for: ' + o.toolchains.join(', '));
+        return;
+    }
+    if (!exists(path.join(root, 'Code.exe')))
+        return;
+    const dirs = [...tools.prepend, ...tools.append];
+    const git = findIn([tool('git', 'cmd'), ...dirs], 'git.exe');
+    const settings = vscodeSettings({
+        javaHome: tools.vars.JAVA_HOME, goRoot: tools.vars.GOROOT, go: findIn(dirs, 'go.exe'), python: findIn(dirs, 'python.exe'), gcc: findIn(dirs, 'gcc.exe'), cl: findIn(dirs, 'cl.exe'),
+        cmake: findIn(dirs, 'cmake.exe'), dotnet: findIn(dirs, 'dotnet.exe'), node: findIn(dirs, 'node.exe'), pwsh: findIn(dirs, 'pwsh.exe'), git,
+        bash: git ? findIn([path.join(path.dirname(path.dirname(git)), 'bin')], 'bash.exe') : undefined, php: findIn(dirs, 'php.exe'), ruby: findIn(dirs, 'ruby.exe'), deno: findIn(dirs, 'deno.exe'),
+    });
+    writeManagedSettings(path.join(root, 'data', 'user-data', 'User', 'settings.json'), path.join(root, 'data', '.agent-sandbox-managed.json'), settings);
+    const wanted = vscodeExtensions({ toolchains: o.toolchains, databases: o.databases, recommended: o.config.recommended ? recommendedBy(o.workspace) : [], extra: o.config.extensions });
+    let folders = [];
+    try {
+        folders = fs.readdirSync(path.join(root, 'data', 'extensions'));
+    }
+    catch { /* none yet */ }
+    const missing = missingExtensions(wanted, folders);
+    tools.summary.push('vscode: set up for ' + (o.toolchains.join(', ') || 'Node') + (missing.length ? '; installing ' + missing.length + ' extension(s) in the background' : '; extensions ready'));
+    if (!missing.length)
+        return;
+    // In the background: the Marketplace can take a minute, and nothing else waits for it.
+    const logFile = fs.openSync(path.join(logsDir, 'vscode-extensions.log'), 'a');
+    spawn(SYSTEM.cmd(), ['/d', '/c', code, ...missing.flatMap((id) => ['--install-extension', id])], { detached: true, stdio: ['ignore', logFile, logFile], windowsHide: true }).unref();
+    fs.closeSync(logFile);
+};
+/**
+ * Sets `values` in a settings file, keeping everything else (comments too), and removes keys this tool set last time
+ * but no longer has a value for (a toolchain turned off). The keys it manages are remembered in `managedFile`.
+ */
+const writeManagedSettings = (file, managedFile, values) => {
+    let text = exists(file) ? fs.readFileSync(file, 'utf8') : '{}';
+    let before = [];
+    try {
+        before = JSON.parse(fs.readFileSync(managedFile, 'utf8'));
+    }
+    catch { /* first time */ }
+    const format = { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } };
+    for (const key of before.filter((k) => !(k in values))) {
+        if (parseJsonc(text)?.[key] !== undefined)
+            text = applyEdits(text, modify(text, [key], undefined, format));
+    }
+    for (const [key, value] of Object.entries(values))
+        text = applyEdits(text, modify(text, [key], value, format));
+    mkdirp(path.dirname(file));
+    fs.writeFileSync(file, text);
+    fs.writeFileSync(managedFile, JSON.stringify(Object.keys(values)));
+};
 export const setupVscode = async (env, refresh) => {
     const root = tool('vscode');
     const exe = path.join(root, 'Code.exe');

package/dist/host/attach.js

@@ -14,7 +14,8 @@ const ipToInt = (ip) => ip.split('.').reduce((n, part) => n * 256 + Number(part)
 export const isSandboxAddress = (ip, interfaces = os.networkInterfaces()) => {
     if (!net.isIPv4(ip))
         return false;
-    return Object.entries(interfaces).some(([name, list]) => /^vEthernet/i.test(name) && (list ?? []).some((i) => {
+    // WSL's adapter is a Hyper-V adapter too, but no sandbox lives there: keystrokes must never go to a WSL VM.
+    return Object.entries(interfaces).some(([name, list]) => /^vEthernet/i.test(name) && !/WSL/i.test(name) && (list ?? []).some((i) => {
         if (i.family !== 'IPv4' || i.internal)
             return false;
         const mask = ipToInt(i.netmask);

package/dist/host/audit/collect.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+declare const AuditSettings: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    days: z.ZodNumber;
+    maxMb: z.ZodNumber;
+    processes: z.ZodBoolean;
+    files: z.ZodBoolean;
+    projects: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type AuditSettings = z.output<typeof AuditSettings>;
+/** Host-only: the audit settings of the running sandbox (written at launch, read by the watcher). */
+export declare const saveAuditSettings: (storageRoot: string, dataPath: string, settings: AuditSettings) => void;
+export declare const readAuditSettings: (storageRoot: string, dataPath: string) => AuditSettings | null;
+export declare class AuditCollector {
+    private readonly dataPath;
+    private readonly settings;
+    private readonly log;
+    private pending;
+    private sessions;
+    private watchers;
+    constructor(dataPath: string, storageRoot: string, settings: AuditSettings);
+    private add;
+    /** Starts watching the projects' files (when audit.files). */
+    start(): void;
+    /** Programs the sandbox reported: taken in (checked) and deleted. */
+    private takeGuestReports;
+    private trackSessions;
+    guard(detail: string): void;
+    /** Writes what came in since the last call (repeats folded); call every few seconds. */
+    flush(): void;
+    stop(): void;
+    maintain(): void;
+}
+export {};

package/dist/host/audit/collect.js

@@ -0,0 +1,126 @@
+// What goes into the audit log, from the background watcher while the sandbox runs:
+//  - programs started in the sandbox: the .jsonl files it leaves in run\audit\ (untrusted: links refused, each file
+//    and line size-capped, every line checked and forced to kind "proc"), taken in and deleted;
+//  - files changed in the projects: watched from this PC (the sandbox cannot hide or fake these);
+//  - sessions starting and ending, and what the repo guard caught.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { assertNoLinks } from '../../core/util.js';
+import { listSessions, readValid, runPaths, writeJsonAtomic } from '../../shared/rundir.js';
+import { AuditEvent, AuditLog, fold } from './log.js';
+const MAX_FILES_PER_PASS = 200;
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+/** Paths in a project not worth a line each (git's own bookkeeping, dependency folders). */
+const QUIET = /(^|[\\/])(\.git[\\/](objects|logs|refs|index\.lock|FETCH_HEAD|ORIG_HEAD)|node_modules[\\/]|target[\\/]|\.venv[\\/]|__pycache__[\\/])/i;
+const AuditSettings = z.object({
+    enabled: z.boolean(), days: z.number().int().min(1).max(365), maxMb: z.number().int().min(5).max(5000), processes: z.boolean(), files: z.boolean(),
+    projects: z.array(z.string().max(1024)).max(64),
+});
+const settingsFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-audit.json');
+/** Host-only: the audit settings of the running sandbox (written at launch, read by the watcher). */
+export const saveAuditSettings = (storageRoot, dataPath, settings) => writeJsonAtomic(settingsFile(storageRoot, dataPath), settings);
+export const readAuditSettings = (storageRoot, dataPath) => readValid(AuditSettings, settingsFile(storageRoot, dataPath));
+export class AuditCollector {
+    dataPath;
+    settings;
+    log;
+    pending = [];
+    sessions = new Map();
+    watchers = [];
+    constructor(dataPath, storageRoot, settings) {
+        this.dataPath = dataPath;
+        this.settings = settings;
+        this.log = new AuditLog(AuditLog.dirFor(storageRoot, dataPath), settings);
+    }
+    add(e) { this.pending.push({ t: new Date().toISOString(), ...e }); }
+    /** Starts watching the projects' files (when audit.files). */
+    start() {
+        this.add({ k: 'note', p: 'sandbox started; audit: ' + [this.settings.processes && 'programs', this.settings.files && 'files', 'sessions'].filter(Boolean).join(', ') });
+        if (!this.settings.files)
+            return;
+        for (const project of this.settings.projects) {
+            try {
+                this.watchers.push(fs.watch(project, { recursive: true }, (event, file) => {
+                    const rel = file ? String(file) : '';
+                    if (!rel || QUIET.test(rel))
+                        return;
+                    this.add({ k: 'file', a: event === 'rename' ? 'rename' : 'change', p: rel.replace(/\\/g, '/').slice(0, 1024), w: project });
+                }));
+            }
+            catch { /* a project that is gone */ }
+        }
+    }
+    /** Programs the sandbox reported: taken in (checked) and deleted. */
+    takeGuestReports() {
+        if (!this.settings.processes)
+            return;
+        const dir = runPaths(this.dataPath).audit;
+        assertNoLinks(this.dataPath, dir);
+        let names = [];
+        try {
+            names = fs.readdirSync(dir).filter((n) => /^[\w-]+\.jsonl$/.test(n)).sort().slice(0, MAX_FILES_PER_PASS);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const file = path.join(dir, name);
+            try {
+                const stat = fs.lstatSync(file);
+                if (stat.isFile() && stat.size <= MAX_FILE_BYTES) {
+                    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+                        if (!line.trim() || line.length > 8192)
+                            continue;
+                        let raw;
+                        try {
+                            raw = JSON.parse(line);
+                        }
+                        catch {
+                            continue;
+                        }
+                        const e = AuditEvent.safeParse(raw);
+                        if (e.success)
+                            this.pending.push({ ...e.data, k: 'proc', w: undefined, a: undefined });
+                    }
+                }
+            }
+            finally {
+                fs.rmSync(file, { force: true });
+            }
+        }
+    }
+    trackSessions() {
+        const now = new Map(listSessions(this.dataPath).map((s) => [s.id, s.phase]));
+        for (const s of listSessions(this.dataPath)) {
+            const before = this.sessions.get(s.id);
+            if (!before && s.phase === 'running')
+                this.add({ k: 'session', a: 'start', p: s.harness, w: s.cwd, c: s.id });
+            if (before === 'running' && (s.phase === 'exited' || s.phase === 'failed'))
+                this.add({ k: 'session', a: 'end', p: s.harness, w: s.cwd, c: s.id + (s.exitCode !== undefined ? ' exit ' + s.exitCode : '') });
+        }
+        this.sessions = now;
+    }
+    guard(detail) { this.add({ k: 'guard', p: detail.slice(0, 1024) }); }
+    /** Writes what came in since the last call (repeats folded); call every few seconds. */
+    flush() {
+        try {
+            this.takeGuestReports();
+        }
+        catch { /* next pass */ }
+        try {
+            this.trackSessions();
+        }
+        catch { /* next pass */ }
+        const events = this.pending.sort((a, b) => a.t.localeCompare(b.t));
+        this.pending = [];
+        this.log.append(fold(events));
+    }
+    stop() {
+        this.watchers.forEach((w) => w.close());
+        this.add({ k: 'note', p: 'sandbox closed' });
+        this.flush();
+        this.log.maintain();
+    }
+    maintain() { this.log.maintain(); }
+}

package/dist/host/audit/log.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+/** One event. k: proc (a program started), file (changed in a project), session, guard (repo guard), note. */
+export declare const AuditEvent: z.ZodObject<{
+    t: z.ZodString;
+    k: z.ZodEnum<{
+        file: "file";
+        session: "session";
+        proc: "proc";
+        guard: "guard";
+        note: "note";
+    }>;
+    p: z.ZodOptional<z.ZodString>;
+    c: z.ZodOptional<z.ZodString>;
+    pp: z.ZodOptional<z.ZodString>;
+    a: z.ZodOptional<z.ZodString>;
+    w: z.ZodOptional<z.ZodString>;
+    n: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AuditEvent = z.output<typeof AuditEvent>;
+export declare class AuditLog {
+    readonly dir: string;
+    private readonly limits;
+    constructor(dir: string, limits: {
+        days: number;
+        maxMb: number;
+    });
+    /** <storage>\audit\<data set name>. */
+    static dirFor(storageRoot: string, dataPath: string): string;
+    private dayFile;
+    append(events: AuditEvent[]): void;
+    /** Compresses finished days, then deletes days past the limits. Cheap when there is nothing to do. */
+    maintain(today?: string): void;
+    /** Events of the last `days` days (newest last), optionally of some kinds and containing a text. */
+    read(o?: {
+        days?: number;
+        kinds?: AuditEvent['k'][];
+        grep?: string;
+    }): AuditEvent[];
+    /** Total size on disk. */
+    bytes(): number;
+}
+/**
+ * Folds repeats: the same event (kind, program/path, command line, action, project) within one minute becomes one line
+ * with n = how many times; after `cap` distinct lines a minute, the rest of that minute is one "note" line.
+ */
+export declare const fold: (events: AuditEvent[], cap?: number) => AuditEvent[];

package/dist/host/audit/log.js

@@ -0,0 +1,143 @@
+// The audit log (audit.enabled): one file per day of JSON lines in host-only storage (<storage>\audit\<data set>),
+// which the sandbox cannot reach. Days before today are gzipped; days past audit.days and, past audit.maxMb, the
+// oldest days are deleted. Lines are short (field names are one or two letters) and capped in length.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { z } from 'zod';
+/** One event. k: proc (a program started), file (changed in a project), session, guard (repo guard), note. */
+export const AuditEvent = z.object({
+    /** ISO time. */
+    t: z.string().max(40),
+    k: z.enum(['proc', 'file', 'session', 'guard', 'note']),
+    /** proc: program; file: path in the project; session: agent; guard/note: what happened. */
+    p: z.string().max(1024).optional(),
+    /** proc: its command line (capped). */
+    c: z.string().max(2048).optional(),
+    /** proc: the program that started it. */
+    pp: z.string().max(1024).optional(),
+    /** file: change | rename; session: start | end. */
+    a: z.string().max(32).optional(),
+    /** project folder (file, session). */
+    w: z.string().max(1024).optional(),
+    /** how many times it happened in this line's minute (repeats are counted, not repeated). */
+    n: z.number().int().min(1).max(1e9).optional(),
+});
+const DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.jsonl(\.gz)?$/;
+export class AuditLog {
+    dir;
+    limits;
+    constructor(dir, limits) {
+        this.dir = dir;
+        this.limits = limits;
+    }
+    /** <storage>\audit\<data set name>. */
+    static dirFor(storageRoot, dataPath) { return path.join(storageRoot, 'audit', path.basename(dataPath)); }
+    dayFile(day, gz = false) { return path.join(this.dir, day + '.jsonl' + (gz ? '.gz' : '')); }
+    append(events) {
+        if (!events.length)
+            return;
+        fs.mkdirSync(this.dir, { recursive: true });
+        const byDay = new Map();
+        for (const e of events) {
+            const day = e.t.slice(0, 10);
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(day))
+                continue;
+            byDay.set(day, [...(byDay.get(day) ?? []), JSON.stringify(e)]);
+        }
+        for (const [day, lines] of byDay)
+            fs.appendFileSync(this.dayFile(day), lines.join('\n') + '\n');
+    }
+    /** Compresses finished days, then deletes days past the limits. Cheap when there is nothing to do. */
+    maintain(today = new Date().toISOString().slice(0, 10)) {
+        if (!fs.existsSync(this.dir))
+            return;
+        for (const name of fs.readdirSync(this.dir)) {
+            const m = DAY_FILE.exec(name);
+            if (!m || m[2] || m[1] >= today)
+                continue;
+            const file = path.join(this.dir, name);
+            fs.writeFileSync(file + '.gz', zlib.gzipSync(fs.readFileSync(file)));
+            fs.rmSync(file);
+        }
+        const oldest = new Date(Date.parse(today) - (this.limits.days - 1) * 86400000).toISOString().slice(0, 10);
+        const files = fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n)).sort();
+        for (const name of files.filter((n) => DAY_FILE.exec(n)[1] < oldest))
+            fs.rmSync(path.join(this.dir, name), { force: true });
+        let left = fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n)).sort();
+        const size = () => left.reduce((sum, n) => sum + fs.statSync(path.join(this.dir, n)).size, 0);
+        while (left.length > 1 && size() > this.limits.maxMb * 1024 * 1024) {
+            fs.rmSync(path.join(this.dir, left[0]), { force: true });
+            left = left.slice(1);
+        }
+    }
+    /** Events of the last `days` days (newest last), optionally of some kinds and containing a text. */
+    read(o = {}) {
+        if (!fs.existsSync(this.dir))
+            return [];
+        const since = new Date(Date.now() - ((o.days ?? 1) - 1) * 86400000).toISOString().slice(0, 10);
+        const needle = o.grep?.toLowerCase();
+        const events = [];
+        for (const name of fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n) && DAY_FILE.exec(n)[1] >= since).sort()) {
+            const raw = fs.readFileSync(path.join(this.dir, name));
+            const text = name.endsWith('.gz') ? zlib.gunzipSync(raw).toString('utf8') : raw.toString('utf8');
+            for (const line of text.split('\n')) {
+                if (!line.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const e = AuditEvent.safeParse(parsed);
+                if (!e.success)
+                    continue;
+                if (o.kinds?.length && !o.kinds.includes(e.data.k))
+                    continue;
+                if (needle && !line.toLowerCase().includes(needle))
+                    continue;
+                events.push(e.data);
+            }
+        }
+        return events;
+    }
+    /** Total size on disk. */
+    bytes() {
+        if (!fs.existsSync(this.dir))
+            return 0;
+        return fs.readdirSync(this.dir).filter((n) => DAY_FILE.test(n)).reduce((sum, n) => sum + fs.statSync(path.join(this.dir, n)).size, 0);
+    }
+}
+/**
+ * Folds repeats: the same event (kind, program/path, command line, action, project) within one minute becomes one line
+ * with n = how many times; after `cap` distinct lines a minute, the rest of that minute is one "note" line.
+ */
+export const fold = (events, cap = 300) => {
+    const out = [];
+    const index = new Map();
+    const perMinute = new Map();
+    const dropped = new Map();
+    for (const e of events) {
+        const minute = e.t.slice(0, 16);
+        const key = [minute, e.k, e.p, e.c, e.a, e.w].join('\0');
+        const seen = index.get(key);
+        if (seen) {
+            seen.n = (seen.n ?? 1) + (e.n ?? 1);
+            continue;
+        }
+        const count = (perMinute.get(minute) ?? 0) + 1;
+        perMinute.set(minute, count);
+        if (count > cap) {
+            dropped.set(minute, (dropped.get(minute) ?? 0) + (e.n ?? 1));
+            continue;
+        }
+        const copy = { ...e };
+        index.set(key, copy);
+        out.push(copy);
+    }
+    for (const [minute, n] of dropped)
+        out.push({ t: minute + ':59.999Z', k: 'note', p: n + ' more events in this minute were not listed (audit cap)' });
+    return out;
+};

package/dist/host/generate.d.ts

@@ -2,6 +2,12 @@ import type { GenerateOptions, Generated } from '../core/types.js';
 import { decideToolchains } from '../core/detect-toolchains.js';
 /** Which toolchains the project needs ("auto" settings follow the project's files and what this PC has). */
 export declare const decideProjectToolchains: (o: Pick<GenerateOptions, "run" | "pcLanguages">) => ReturnType<typeof decideToolchains>;
+/**
+ * env.cmd, which logon.cmd calls before it opens Windows Terminal: Terminal expands "%AGENT_WORKSPACE%" (the starting
+ * folder of new tabs) from its own environment, and the runtime only sets the variable machine-wide after Terminal
+ * started. `%` is doubled for cmd; a Windows path holds no quotes.
+ */
+export declare const logonEnv: (workspace: string) => string;
 export declare const generateSandbox: (o: GenerateOptions) => Generated & {
     personalization: string;
 };