windows-development-sandbox 1.23.2 → 1.25.0

package/dist/guest/runtime/log-line.js

@@ -0,0 +1,18 @@
+// The lines of the guest's log files: plain text (no colours), one timestamped line per line of the message. Pure.
+/** Colour and cursor sequences (CSI ... letter), bounded so a hostile line costs linear time. */
+const ESCAPES = /\x1b\[[0-9;?]{0,32}[A-Za-z]/g;
+/** Text without its terminal colour and cursor sequences. */
+export function plainText(text) {
+    return text.replace(ESCAPES, '');
+}
+/**
+ * The file lines for one message: each line of it with an ISO timestamp (UTC, zero-padded:
+ * `2026-11-04T12:07:27.930Z`) and the task that logged it, if any; blank lines are dropped.
+ */
+export function fileLines(message, at = new Date(), task) {
+    const stamp = at.toISOString() + ' ' + (task ? '[' + task + '] ' : '');
+    return plainText(message)
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== '')
+        .map((line) => stamp + line.trimEnd());
+}

package/dist/guest/runtime/log.d.ts

@@ -1,15 +1,28 @@
-/** Who is logging: the task title (a prefix while several tasks run) and whether the console stays silent. */
+/** Who is logging: the boot task (its stage and title) and whether the console stays silent. */
 export interface LogContext {
-    readonly prefix?: () => string;
+    readonly stage?: number;
+    readonly task?: string;
     /** File only: nothing may print once the first session owns the console. */
     readonly quiet?: boolean;
 }
+/** Takes the console's lines while the boot draws its progress (boot/boot-console.ts). */
+export interface ConsoleSink {
+    /** An info line; `stage` is the stage of the task that logged it. */
+    line(message: string, stage: number | undefined): void;
+    warning(message: string): void;
+    /** A line the user should read once the boot is ready (shown with the summary). */
+    notice(message: string): void;
+}
 /** Runs `work` so that everything it logs (also after awaits) carries `ctx`. */
 export declare function withLogContext<T>(ctx: LogContext, work: () => T): T;
 /** Runs `work` logging to the file only. */
 export declare function runQuiet<T>(work: () => T): T;
-/** One line of the file: an ISO timestamp first (the console shows no times). */
-export declare function fileLine(message: string, at?: Date): string;
+/** Sends the console's lines to `next` (null: straight to the console again). */
+export declare function routeConsole(next: ConsoleSink | null): void;
 export declare function log(message: string): void;
 export declare function warn(message: string): void;
+/** A line for the user once the boot is ready (printed at once outside the boot). */
+export declare function notice(message: string): void;
+/** A line for the log file only. */
+export declare function record(message: string): void;
 export declare const logPath: string;

package/dist/guest/runtime/log.js

@@ -1,10 +1,14 @@
+// The guest's log: every line goes to the log file (timestamped, plain) and, unless it is quiet, to the console, or
+// to the boot's progress view while that owns the console.
 import fs from 'node:fs';
 import path from 'node:path';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { logsDir } from './paths.js';
+import { fileLines } from './log-line.js';
 fs.mkdirSync(logsDir, { recursive: true });
 const logFile = path.join(logsDir, (process.env.AGENT_LOG_PREFIX ?? 'guest') + '-' + new Date().toISOString().replace(/[:.]/g, '-') + '.log');
 const context = new AsyncLocalStorage();
+let sink = null;
 /** Runs `work` so that everything it logs (also after awaits) carries `ctx`. */
 export function withLogContext(ctx, work) {
     return context.run(ctx, work);
@@ -13,34 +17,53 @@ export function withLogContext(ctx, work) {
 export function runQuiet(work) {
     return context.run({ ...context.getStore(), quiet: true }, work);
 }
-/** One line of the file: an ISO timestamp first (the console shows no times). */
-export function fileLine(message, at = new Date()) {
-    return at.toISOString() + ' ' + message;
+/** Sends the console's lines to `next` (null: straight to the console again). */
+export function routeConsole(next) {
+    sink = next;
 }
-const append = (line) => {
+const append = (message, ctx) => {
     try {
-        fs.appendFileSync(logFile, fileLine(line) + '\n');
+        const lines = fileLines(message, new Date(), ctx?.task);
+        if (lines.length)
+            fs.appendFileSync(logFile, lines.join('\n') + '\n');
     }
     catch {
         /* logging must never break the run */
     }
 };
-const tagged = (message, ctx) => {
-    const prefix = ctx?.prefix?.();
-    return prefix ? prefix + ' | ' + message : message;
-};
 export function log(message) {
     const ctx = context.getStore();
-    const line = tagged(message, ctx);
-    if (!ctx?.quiet)
-        console.log(line);
-    append(line);
+    append(message, ctx);
+    if (ctx?.quiet)
+        return;
+    if (sink)
+        sink.line(message, ctx?.stage);
+    else
+        console.log(message);
 }
 export function warn(message) {
     const ctx = context.getStore();
-    const line = tagged(message, ctx);
-    if (!ctx?.quiet)
-        console.warn('\x1b[33mWARNING: ' + line + '\x1b[0m');
-    append('WARNING: ' + line);
+    append('WARNING: ' + message, ctx);
+    if (ctx?.quiet)
+        return;
+    if (sink)
+        sink.warning(message);
+    else
+        console.warn('\x1b[33mWARNING: ' + message + '\x1b[0m');
+}
+/** A line for the user once the boot is ready (printed at once outside the boot). */
+export function notice(message) {
+    const ctx = context.getStore();
+    append(message, ctx);
+    if (ctx?.quiet)
+        return;
+    if (sink)
+        sink.notice(message);
+    else
+        console.log(message);
+}
+/** A line for the log file only. */
+export function record(message) {
+    append(message, context.getStore());
 }
 export const logPath = logFile;

package/dist/guest/runtime/process.d.ts

@@ -1,4 +1,13 @@
 import { type SpawnOptions, type SpawnSyncOptions } from 'node:child_process';
+/** Takes the output of the programs started while the boot draws its progress (boot/boot-console.ts). */
+export interface OutputSink {
+    /** Whether programs started now hand their output over instead of writing to the console. */
+    capturing(): boolean;
+    /** One line of a program's output (to the log). */
+    line(text: string): void;
+}
+/** Hands the output of programs started from now on to `sink` while it is capturing (null: the console again). */
+export declare function routeOutput(sink: OutputSink | null): void;
 /** Runs a program, streaming output, and throws with a readable message when it fails. */
 export declare function exec(file: string, args: string[], options?: SpawnSyncOptions): void;
 /** exec without blocking: other toolchains keep downloading while this one runs an installer. */

package/dist/guest/runtime/process.js

@@ -8,9 +8,48 @@ import { robocopyErrors, robocopyFailed, robocopyMeaning } from '../../shared/io
 import { SYSTEM } from '../../shared/system.js';
 import { scriptArgs } from '../../shared/scripts.js';
 import { isWin } from './paths.js';
+// Set by the boot only: this module stays free of the log (pure helpers such as tool-env import it).
+let outputSink = null;
+/** Hands the output of programs started from now on to `sink` while it is capturing (null: the console again). */
+export function routeOutput(sink) {
+    outputSink = sink;
+}
+const captureOutput = () => outputSink?.capturing() ?? false;
+/** A program's captured output, line by line (its blank lines dropped). */
+function logOutput(text) {
+    for (const line of text.split(/\r?\n/))
+        if (line.trim())
+            outputSink?.line(line.trimEnd());
+}
+/** What a program may print while the boot holds its output for the log (a larger output stops it). */
+const CAPTURE_BYTES = 64 * 1024 * 1024;
+/** A captured line longer than this is cut (an installer's progress bar without line ends). */
+const LINE_CHARS = 2000;
+/** Feeds a stream to the log line by line as it arrives. */
+function logLines(stream) {
+    if (!stream)
+        return;
+    let partial = '';
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        const lines = (partial + chunk).split(/\r?\n/);
+        partial = lines.pop().slice(0, LINE_CHARS);
+        logOutput(lines.map((l) => l.slice(0, LINE_CHARS)).join('\n'));
+    });
+    stream.on('end', () => logOutput(partial));
+}
 /** Runs a program, streaming output, and throws with a readable message when it fails. */
 export function exec(file, args, options = {}) {
-    const result = spawnSync(file, args, { stdio: 'inherit', windowsHide: true, ...options });
+    // While the boot draws its progress, the program's output goes to the log (it would break the drawing).
+    const capture = captureOutput();
+    const result = spawnSync(file, args, {
+        stdio: capture ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+        windowsHide: true,
+        ...(capture ? { maxBuffer: CAPTURE_BYTES } : {}),
+        ...options,
+    });
+    if (capture)
+        logOutput(String(result.stdout ?? '') + '\n' + String(result.stderr ?? ''));
     if (result.error)
         throw result.error;
     if (result.status !== 0)
@@ -18,36 +57,59 @@ export function exec(file, args, options = {}) {
 }
 /** exec without blocking: other toolchains keep downloading while this one runs an installer. */
 export async function execAsync(file, args, options = {}) {
-    const code = await spawnAsync(file, args, { stdio: 'inherit', ...options });
+    const code = captureOutput()
+        ? await new Promise((resolve, reject) => {
+            const child = spawn(file, args, { stdio: ['inherit', 'pipe', 'pipe'], windowsHide: true, ...options });
+            logLines(child.stdout);
+            logLines(child.stderr);
+            child.once('error', reject);
+            child.once('close', (c) => resolve(c ?? -1));
+        })
+        : await spawnAsync(file, args, { stdio: 'inherit', ...options });
     if (code !== 0)
         throw new Error(path.basename(file) + ' ' + args.slice(0, 3).join(' ') + ' failed with exit code ' + code);
 }
+/** A script's error output: to the log while the boot holds the console, else to the console's error stream. */
+function scriptErrors(errors) {
+    if (!errors)
+        return;
+    if (captureOutput())
+        logOutput(errors);
+    else
+        process.stderr.write(errors + '\n');
+}
 export function execOutput(file, args, options = {}) {
     const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, ...options });
     return result.status === 0 ? String(result.stdout ?? '').trim() : '';
 }
 /** Runs sandbox\scripts\<name> (a .ps1 in the launch folder) with `args`; throws when it fails. */
 export function runScript(name, args = []) {
+    const capture = captureOutput();
     const result = spawnSync(SYSTEM.powershell(), scriptArgs(name, args), {
-        stdio: ['inherit', 'inherit', 'pipe'],
+        stdio: ['inherit', capture ? 'pipe' : 'inherit', 'pipe'],
         encoding: 'utf8',
         windowsHide: true,
+        ...(capture ? { maxBuffer: CAPTURE_BYTES } : {}),
     });
+    if (capture)
+        logOutput(String(result.stdout ?? ''));
     if (result.error)
         throw result.error;
     const errors = String(result.stderr ?? '').trim();
-    if (errors)
-        process.stderr.write(errors + '\n');
+    scriptErrors(errors);
     if (result.status !== 0)
         throw new Error(name + ' failed with exit code ' + result.status + (errors ? ': ' + errors.slice(0, 400) : ''));
 }
 /** runScript without blocking the event loop (other boot tasks keep going while the script runs). */
 export function runScriptAsync(name, args = []) {
     return new Promise((resolve, reject) => {
+        const capture = captureOutput();
         const child = spawn(SYSTEM.powershell(), scriptArgs(name, args), {
-            stdio: ['inherit', 'inherit', 'pipe'],
+            stdio: ['inherit', capture ? 'pipe' : 'inherit', 'pipe'],
             windowsHide: true,
         });
+        if (capture)
+            logLines(child.stdout);
         let errors = '';
         child.stderr?.setEncoding('utf8');
         child.stderr?.on('data', (chunk) => {
@@ -57,8 +119,7 @@ export function runScriptAsync(name, args = []) {
         child.once('error', reject);
         child.once('close', (code) => {
             errors = errors.trim();
-            if (errors)
-                process.stderr.write(errors + '\n');
+            scriptErrors(errors);
             if (code !== 0)
                 reject(new Error(name + ' failed with exit code ' + code + (errors ? ': ' + errors.slice(0, 400) : '')));
             else

package/dist/guest/setup/environment.js

@@ -1,7 +1,7 @@
 // The environment every agent session, hook and terminal tab in the sandbox gets.
 import path from 'node:path';
 import { claudeDir, session, stateDir, workspace } from '../runtime/session.js';
-import { dataDir, dryRun, isWin, testMode, toolsDir } from '../runtime/paths.js';
+import { dataDir, dryRun, isWin, localDir, testMode, toolsDir } from '../runtime/paths.js';
 import { exists, mkdirp } from '../runtime/fs.js';
 import { execOutput, runScriptWithJson, runScriptWithJsonAsync } from '../runtime/process.js';
 import { SYSTEM } from '../../shared/system.js';
@@ -9,7 +9,7 @@ import { warn } from '../runtime/log.js';
 import { errMsg } from '../../core/util/errors.js';
 import { localStateVars } from '../agents/local-state.js';
 import { agentPaths } from '../agents/agent-files.js';
-import { appendMissing, expandVars, isPinnedNodeDir, msvcBeforeGitUsr, parseRegPath, pathKey, planPath, } from './path-plan.js';
+import { appendMissing, expandVars, isPinnedNodeDir, parseRegPath, pathKey, planPath, sessionPath, } from './path-plan.js';
 /** Older launch folders have no agentHomes: these two were always set. */
 const LEGACY_HOMES = { CODEX_HOME: 'codex', GEMINI_CLI_HOME: 'gemini' };
 /** Every agent's home variable (CODEX_HOME ...) with the folder it points to in the persistent state. */
@@ -57,8 +57,13 @@ export function agentEnv(tools, target = { workspace, project: session.project,
     // The runner's own Node (bootstrap.ps1 puts it first on PATH) is not exposed: `node` is whatever nvm selected.
     const runners = [path.join(toolsDir, 'node'), path.dirname(process.execPath)].map((d) => d.toLowerCase());
     const base = (target.base.PATH ?? '').split(path.delimiter).filter((d) => d && !runners.includes(d.toLowerCase()));
-    // MSVC's link.exe before Git's coreutils link.exe, wherever each came from.
-    env.PATH = msvcBeforeGitUsr([...new Set([...tools.prepend, ...base, ...tools.append])]).join(path.delimiter);
+    // The sandbox's commands (agent shims, sbx-db) first; MSVC's link.exe before Git's coreutils link.exe.
+    env.PATH = sessionPath({
+        commands: path.join(localDir, 'bin'),
+        prepend: tools.prepend,
+        base,
+        append: tools.append,
+    }).join(path.delimiter);
     return env;
 }
 /** Makes the agent environment machine-wide, so new terminal tabs and anything the agent starts see the same tools. */

package/dist/guest/setup/hooks.d.ts

@@ -4,6 +4,8 @@ export interface HookTarget {
     cwd: string;
 }
 export declare function projectHooks(name: string, cwd: string): HookTarget;
+/** Whether `stage` has hooks to run (they write to the terminal themselves). */
+export declare function hasHooks(stage: string, target?: HookTarget): boolean;
 export declare function runHooks(stage: string, env: NodeJS.ProcessEnv, target?: HookTarget): void;
 /** The same without blocking: the session daemon keeps answering other requests while a project's hooks run. */
 export declare function runHooksAsync(stage: string, env: NodeJS.ProcessEnv, target: HookTarget): Promise<void>;

package/dist/guest/setup/hooks.js

@@ -45,6 +45,10 @@ const failed = (stage, name, status) => {
         throw new Error(message);
     warn(message);
 };
+/** Whether `stage` has hooks to run (they write to the terminal themselves). */
+export function hasHooks(stage, target = BOOT) {
+    return hooksOf(stage, target).length > 0;
+}
 export function runHooks(stage, env, target = BOOT) {
     for (const { name, command } of hooksOf(stage, target)) {
         log('Hook [' + stage + ']: ' + name);

package/dist/guest/setup/path-plan.d.ts

@@ -13,6 +13,18 @@ export interface PathPlanInput {
 }
 /** Ordered, de-duplicated (case, trailing slash) PATH folders; missing and dropped folders are left out. */
 export declare function planPath(input: PathPlanInput): string[];
+/**
+ * The PATH folders of the agent environment (sessions, the machine PATH, terminal tabs): the sandbox's own commands
+ * folder first, because its `claude` / `codex` shims carry the sandbox's flags and must beat a copy installed with
+ * `npm i -g` in nvm's node folder; then the toolchains' folders, the process's own and the appended ones. No
+ * duplicates (matched like pathKey); MSVC's tools before Git's usr\bin.
+ */
+export declare function sessionPath(o: {
+    readonly commands: string;
+    readonly prepend: readonly string[];
+    readonly base: readonly string[];
+    readonly append: readonly string[];
+}): string[];
 /** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
 export declare function appendMissing(base: string, extra: string, skip?: (folder: string) => boolean): string;
 /**

package/dist/guest/setup/path-plan.js

@@ -32,6 +32,24 @@ export function planPath(input) {
     }
     return msvcBeforeGitUsr(result);
 }
+/**
+ * The PATH folders of the agent environment (sessions, the machine PATH, terminal tabs): the sandbox's own commands
+ * folder first, because its `claude` / `codex` shims carry the sandbox's flags and must beat a copy installed with
+ * `npm i -g` in nvm's node folder; then the toolchains' folders, the process's own and the appended ones. No
+ * duplicates (matched like pathKey); MSVC's tools before Git's usr\bin.
+ */
+export function sessionPath(o) {
+    const seen = new Set();
+    const result = [];
+    for (const folder of [o.commands, ...o.prepend, ...o.base, ...o.append]) {
+        const key = pathKey(folder);
+        if (!folder.trim() || seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(folder);
+    }
+    return msvcBeforeGitUsr(result);
+}
 /** `base` with the folders of `extra` it lacks added at the end (a process keeps its own order and entries). */
 export function appendMissing(base, extra, skip = () => false) {
     const seen = new Set(splitPath(base).map(pathKey));

package/dist/guest/toolchains/native/unreal.js

@@ -1,7 +1,8 @@
 // Unreal Engine development (toolchains.unreal): the DirectX End-User Runtime the engine lists (a real installer: it
 // runs every boot), then the engines (engines/unreal-engines.ts: the launcher's install folder on the data disk, PC
-// engines from pcInstalls, the derived data cache). Visual Studio Community with the C++ game workload is its own step
-// (visual-studio.ts), which the plan runs first. The engine itself comes from the Epic Games Launcher or its source.
+// engines from pcInstalls, the derived data cache). Visual Studio (Community with the C++ game workload, or the Build
+// Tools) is its own step (visual-studio.ts), which the plan runs first. The engine itself comes from the Epic Games
+// Launcher or its source.
 import os from 'node:os';
 import path from 'node:path';
 import { runInstaller } from '../../runtime/pools.js';
@@ -12,7 +13,6 @@ import { log } from '../../runtime/log.js';
 import { setupUnrealEngines } from '../engines/unreal-engines.js';
 import { SIGNERS, signedInstaller } from '../installers.js';
 import { tool } from '../tool-env.js';
-import { setupAutosdk } from './autosdk.js';
 import { installedVs } from './visual-studio.js';
 export { UNREAL_COMPONENTS } from './vs-request.js';
 const DIRECTX_URL = 'https://download.microsoft.com/download/8/4/A/84A35BF1-DAFE-4AE8-82AF-AD2AE20B6B14/directx_Jun2010_redist.exe';
@@ -50,11 +50,9 @@ export async function setupUnreal(env, config, ctx) {
         return;
     }
     await installDirectX();
-    if (config.visualStudio === 'autosdk')
-        await setupAutosdk(env);
     await setupUnrealEngines(env, config, ctx);
     const vs = installedVs();
     env.summary.push('unreal: ' +
-        (vs ? 'Visual Studio ' + vs.version + ' (C++ game workload, Windows 11 SDK, Unreal support); ' : '') +
+        (vs ? 'Visual Studio ' + vs.version + ' at ' + vs.path + '; ' : '') +
         'DirectX End-User Runtime; get the engine from the Epic Games Launcher (Start menu)');
 }

package/dist/guest/toolchains/native/visual-studio.d.ts

@@ -1,18 +1,18 @@
 import { type ToolEnv } from '../tool-env.js';
 import { type VsRequest } from './vs-request.js';
-export { BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, unrealUsesAutosdk, visualStudioWanted, type VsRequest, } from './vs-request.js';
-/** The newest Visual Studio (or Build Tools) with the C++ compiler: its folder and version, or null. */
-export declare function installedVs(): {
-    path: string;
-    version: string;
-} | null;
-/** Downloads the bootstrapper now, so the install later starts without waiting for it. */
+export { BUILD_TOOLS_COMPONENTS, UNREAL_BUILD_TOOLS_COMPONENTS, UNREAL_COMPONENTS, visualStudioWanted, type VsRequest, } from './vs-request.js';
+export interface InstalledVs {
+    readonly path: string;
+    readonly version: string;
+    readonly instanceId: string;
+}
+/** The newest Visual Studio (or Build Tools) with the C++ compiler, installed or put back: where it is, or null. */
+export declare function installedVs(): InstalledVs | null;
+/** Whether a later boot only puts Visual Studio back (quick enough to wait for) instead of installing it. */
+export declare function visualStudioSaved(req: VsRequest): boolean;
+/** Downloads the bootstrapper now, so the install later starts without waiting (not needed with a saved copy). */
 export declare function prefetchVisualStudio(req: VsRequest): Promise<void>;
-/** Visual Studio as asked for: installed at boot when it is not there yet; its folder and version. */
-export declare function ensureVisualStudio(env: ToolEnv, req: VsRequest, o: {
-    keepInstallFiles: boolean;
+/** Visual Studio as asked for: put back from the data disk, or installed (and saved) the first time. */
+export declare function ensureVisualStudio(env: ToolEnv, req: VsRequest, o?: {
     lowPriority?: boolean;
-}): Promise<{
-    path: string;
-    version: string;
-}>;
+}): Promise<InstalledVs>;