@hunterzhu/pulse-adapters 0.5.1 → 0.7.0

package/dist/tools/shell.js

@@ -1,3 +1,4 @@
+import { ShellOutput } from './shell-output.js';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
@@ -5,10 +6,12 @@ import { basename, delimiter, dirname, join, parse, resolve, sep } from 'node:pa
 import { mkdtemp, realpath, rm } from 'node:fs/promises';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
-import { SandboxManager, VENDORED_SRT_WIN_EXE, checkWindowsDependenciesAsync, resolveSrtWin } from '@anthropic-ai/sandbox-runtime';
+import { SandboxManager, checkWindowsDependenciesAsync, resolveSrtWin } from '@anthropic-ai/sandbox-runtime';
 import { resolveWindowsPackageManager } from './windows-package-manager.js';
-import { carveWindowsReadDenies } from './windows-read-policy.js';
+import { carveWindowsReadDenies, windowsReadDenyRoots, windowsToolchainWriteDenies } from './windows-read-policy.js';
 import { initializeShellSandbox } from './sandbox-initialization.js';
+import { installationDependencyRoots, workspaceUsesInstallationDependencies } from './installation-dependencies.js';
+import { verifiedWindowsSrt } from './windows-srt-path.js';
 function shellError(code, retryable = false, cause) {
     return Object.assign(new Error(code), { code, retryable, ...(cause === undefined ? {} : { cause }) });
 }
@@ -26,7 +29,7 @@ export async function checkShellSandbox() {
     // doctor runs before initialize(), so the manager has no Windows config yet.
     // Probe the same packaged helper used for execution without provisioning it.
     return withSandboxLease(() => process.platform === 'win32'
-        ? checkWindowsDependenciesAsync({ srtWin: resolveSrtWin({ path: VENDORED_SRT_WIN_EXE }) })
+        ? checkWindowsDependenciesAsync({ srtWin: resolveSrtWin({ path: verifiedWindowsSrt() }) })
         : SandboxManager.checkDependenciesAsync());
 }
 function quotePosix(value) {
@@ -102,7 +105,7 @@ export function encodeSandboxCommand(command, args, platform = process.platform)
     }
     return `exec ${[command, ...args].map(quotePosix).join(' ')}`;
 }
-async function sandboxConfig(cwd, allowedDomains = [], toolchainRoots = [], scratch) {
+async function sandboxConfig(cwd, allowedDomains = [], toolchainRoots = [], scratch, dependencyRoots = []) {
     // Linux invokes this trusted helper *inside* the read-restricted namespace.
     // A user-local npm install otherwise hides it together with the home directory.
     const seccompPath = process.platform === 'linux'
@@ -117,26 +120,31 @@ async function sandboxConfig(cwd, allowedDomains = [], toolchainRoots = [], scra
     // Windows runs as a separate srt-sandbox account, which has no access to
     // private host-profile files without explicit grants. Stamping the entire
     // profile recursively is both redundant and very expensive (registry/cache
-    // trees); only carve the workspace's sibling boundary on that platform.
+    // trees); carve workspace and installation dependency boundaries instead.
     const denyRead = new Set(process.platform === 'win32' ? [] : [home]);
     // Close the common sibling-workspace and temporary-directory escape: deny
     // the workspace's immediate container, then re-open only this invocation's
     // cwd. Root workspaces cannot be carved this way and are rejected upstream.
     if (parent !== parse(cwd).root && parent !== cwd)
         denyRead.add(parent);
+    if (process.platform === 'win32')
+        for (const boundary of windowsReadDenyRoots(cwd, dependencyRoots))
+            denyRead.add(boundary);
     const allowRead = [cwd, ...toolchainRoots, ...(scratch ? [scratch] : []), ...(seccompPath ? [seccompPath] : [])];
     // Reads default to the system toolchain plus this workspace. Writes are
     // limited to the workspace; srt adds only its required stdio/temp paths.
     return {
         network: { allowedDomains, deniedDomains: [], strictAllowlist: true },
         filesystem: {
-            denyRead: process.platform === 'win32' ? await carveWindowsReadDenies([...denyRead], allowRead) : [...denyRead],
+            // Known dependency trees remain outside source denies. Only workspaces
+            // that actually reference them need recursive Windows read grants.
+            denyRead: process.platform === 'win32' ? await carveWindowsReadDenies([...denyRead], [...allowRead, ...dependencyRoots]) : [...denyRead],
             allowRead,
             allowWrite: [cwd, ...(scratch ? [scratch] : [])],
-            denyWrite: [],
+            denyWrite: process.platform === 'win32' ? await windowsToolchainWriteDenies([...toolchainRoots, ...dependencyRoots], [cwd, ...(scratch ? [scratch] : [])]) : [],
         },
         ...(seccompPath ? { seccomp: { applyPath: seccompPath } } : {}),
-        ...(process.platform === 'win32' ? { windows: { srtWin: { path: VENDORED_SRT_WIN_EXE } } } : {}),
+        ...(process.platform === 'win32' ? { windows: { srtWin: { path: verifiedWindowsSrt() } } } : {}),
     };
 }
 function cleanPath(value) {
@@ -167,16 +175,26 @@ function shellLaunchesCommand(command, args) {
         return false;
     return args.some((arg) => /^(?:-lc|-c|-command|\/c)$/i.test(arg));
 }
+/** Deterministic argv validation, shared by pre-approval and actual execution. */
+export function validateShellInvocation(command, args = []) {
+    if (!command || typeof command !== 'string' || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string'))
+        throw shellError('INVALID_SHELL_ARGUMENT');
+    if (/&&|\|\||[|&;<>\n`]|\$\(/.test(command) || shellLaunchesCommand(command, args))
+        throw Object.assign(shellError('SHELL_SYNTAX_UNSUPPORTED'), { message: 'shell.exec does not start a shell. Pass the executable in command and each argument in args. Do not put &&, pipes, redirects, command substitution, or sh -c in command.' });
+    encodeSandboxCommand(command, args);
+}
 export function runShell(command, args = [], options = {}) {
     const max = options.maxOutputBytes ?? 256 * 1024;
     if (!Number.isFinite(max) || max < 0)
         return Promise.reject(shellError('INVALID_SHELL_OUTPUT_LIMIT'));
     if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0))
         return Promise.reject(shellError('INVALID_SHELL_TIMEOUT'));
-    if (!command || typeof command !== 'string' || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string'))
-        return Promise.reject(shellError('INVALID_SHELL_ARGUMENT'));
-    if (/&&|\|\||[|&;<>\n`]|\$\(/.test(command) || shellLaunchesCommand(command, args))
-        return Promise.reject(Object.assign(shellError('SHELL_SYNTAX_UNSUPPORTED'), { message: 'shell.exec does not start a shell. Pass the executable in command and each argument in args. Do not put &&, pipes, redirects, command substitution, or sh -c in command.' }));
+    try {
+        validateShellInvocation(command, args);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
     try {
         encodeSandboxCommand(command, args);
     }
@@ -184,6 +202,9 @@ export function runShell(command, args = [], options = {}) {
         return Promise.reject(error);
     }
     return withSandboxLease(async () => {
+        const started = Date.now();
+        const checkpoint = (phase) => { if (process.env.PULSE_SANDBOX_TIMING === '1')
+            console.info(`[sandbox timing] ${Date.now() - started}ms ${phase}`); };
         if (options.signal?.aborted)
             return { code: null, stdout: '', stderr: '', truncated: false, timedOut: false, aborted: true };
         let cwd;
@@ -198,6 +219,13 @@ export function runShell(command, args = [], options = {}) {
         const nodeBin = dirname(nodeExecutable);
         const installation = basename(nodeBin) === 'bin' ? dirname(nodeBin) : nodeBin;
         const toolchainRoots = installation !== homedir() && installation !== parse(installation).root ? [installation] : [nodeExecutable];
+        const dependencyRoots = await installationDependencyRoots();
+        if (process.platform !== 'win32' || await workspaceUsesInstallationDependencies(cwd, dependencyRoots))
+            toolchainRoots.push(...dependencyRoots);
+        // The Windows broker relaunches itself as the sandbox user before starting
+        // the target command. Permit only its fixed, integrity-checked image folder.
+        if (process.platform === 'win32')
+            toolchainRoots.push(dirname(verifiedWindowsSrt()));
         // PNPM_HOME is a host installation setting, never supplied by model argv.
         let pnpmHome;
         if (process.env.PNPM_HOME) {
@@ -240,9 +268,9 @@ export function runShell(command, args = [], options = {}) {
                 }
             }
             const invocationId = randomUUID();
-            const policy = await sandboxConfig(cwd, options.allowedDomains ?? [], toolchainRoots, scratch);
+            const policy = await sandboxConfig(cwd, options.allowedDomains ?? [], toolchainRoots, scratch, dependencyRoots);
             let child;
-            const outputChunks = { stdout: [], stderr: [] };
+            const archive = new ShellOutput(max, options.outputDirectory, options.maxArchiveBytes, options.outputDirectory !== undefined);
             const outputBytes = { stdout: 0, stderr: 0 };
             let truncated = false;
             let closed = false;
@@ -277,26 +305,27 @@ export function runShell(command, args = [], options = {}) {
                         signalProcessGroup('SIGKILL'); }, 250);
             };
             const append = (target, chunk) => {
-                const remaining = Math.max(0, max - outputBytes[target]);
-                const kept = Math.min(chunk.byteLength, remaining);
-                if (kept > 0)
-                    outputChunks[target].push(chunk.subarray(0, kept));
-                outputBytes[target] += kept;
-                if (kept < chunk.byteLength)
+                archive.append(target, chunk);
+                outputBytes[target] += chunk.byteLength;
+                if (outputBytes[target] > max)
                     truncated = true;
             };
             const outputText = (target) => {
-                return decodeUtf8WithinByteLimit(Buffer.concat(outputChunks[target]), max);
+                return decodeUtf8WithinByteLimit(Buffer.from(archive.text(target)), max);
             };
+            checkpoint('policy ready');
             let setupStage = 'reset';
             try {
                 // reset first in case an earlier initialize failed part-way through.
                 await SandboxManager.reset();
+                checkpoint('reset complete');
                 setupStage = 'initialize';
-                await initializeShellSandbox(policy);
+                await initializeShellSandbox(policy, process.platform, options.signal);
+                checkpoint('initialized');
                 const commandText = encodeSandboxCommand(executable, executableArgs);
                 setupStage = 'wrap';
                 const descriptor = await SandboxManager.wrapWithSandboxArgv(commandText, undefined, undefined, options.signal, cwd, { commandId: invocationId, commandText: 'shell.exec' });
+                checkpoint('wrapped');
                 if (options.signal?.aborted) {
                     SandboxManager.cleanupAfterCommand();
                     await SandboxManager.reset();
@@ -311,10 +340,15 @@ export function runShell(command, args = [], options = {}) {
                 });
             }
             catch (cause) {
+                let resetFailed = false;
                 try {
                     await SandboxManager.reset();
                 }
-                catch { /* preserve the setup failure */ }
+                catch {
+                    resetFailed = true; /* preserve the setup failure */
+                }
+                if (options.signal?.aborted && !resetFailed)
+                    return { code: null, stdout: '', stderr: '', truncated: false, timedOut: false, aborted: true };
                 // Persist only classified diagnostics, never raw subprocess output or credentials.
                 const message = cause instanceof Error ? cause.message : '';
                 const nativeCode = cause && typeof cause === 'object' && 'code' in cause ? String(cause.code) : '';
@@ -348,9 +382,11 @@ export function runShell(command, args = [], options = {}) {
                     cleanup();
                     const errorCode = cause && typeof cause === 'object' ? cause.code : undefined;
                     const code = typeof errorCode === 'string' ? errorCode : 'SHELL_EXECUTION_ERROR';
+                    archive.finish();
                     reject(shellError(code === 'ENOENT' || code === 'EACCES' ? code : 'SHELL_EXECUTION_ERROR', false, cause));
                 });
                 child.once('close', (code) => {
+                    checkpoint('child closed');
                     closed = true;
                     cleanup();
                     const stdout = outputText('stdout');
@@ -358,12 +394,14 @@ export function runShell(command, args = [], options = {}) {
                     const annotated = SandboxManager.annotateStderrWithSandboxFailures(invocationId, stderr);
                     const boundedStderr = decodeUtf8WithinByteLimit(Buffer.from(annotated, 'utf8'), max);
                     const outputWasTruncated = truncated || Buffer.byteLength(annotated, 'utf8') > max;
-                    resolve({ code, stdout, stderr: boundedStderr, truncated: outputWasTruncated, timedOut: termination === 'timeout', aborted: termination === 'aborted' });
+                    resolve({ code, stdout, stderr: boundedStderr, truncated: outputWasTruncated, timedOut: termination === 'timeout', aborted: termination === 'aborted', outputArchive: archive.finish() });
                 });
             }).finally(async () => {
+                checkpoint('cleanup start');
                 try {
                     SandboxManager.cleanupAfterCommand();
                     await SandboxManager.reset();
+                    checkpoint('cleanup complete');
                 }
                 catch (cause) {
                     // A teardown failure must be visible and fail closed for the next call.

package/dist/tools/windows-read-policy.d.ts

@@ -1,2 +1,6 @@
+/** Dependency reads do not authorize adjacent installation source or secrets. */
+export declare function windowsReadDenyRoots(workspace: string, dependencyRoots: string[]): string[];
 /** Keep denied subtrees off the ancestors Git must stat to reach an allowed workspace. */
 export declare function carveWindowsReadDenies(denied: string[], allowed: string[]): Promise<string[]>;
+/** Read grants are additive; inherited Users/Everyone write rights need a deny. */
+export declare function windowsToolchainWriteDenies(readRoots: string[], writeRoots: string[]): Promise<string[]>;

package/dist/tools/windows-read-policy.js

@@ -1,5 +1,9 @@
 import { readdir } from 'node:fs/promises';
-import { join, relative, isAbsolute, sep } from 'node:path';
+import { dirname, join, relative, isAbsolute, sep } from 'node:path';
+/** Dependency reads do not authorize adjacent installation source or secrets. */
+export function windowsReadDenyRoots(workspace, dependencyRoots) {
+    return [...new Set([dirname(workspace), ...dependencyRoots.map(root => dirname(root))])];
+}
 function within(path, root) {
     const rel = relative(root, path);
     return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
@@ -26,3 +30,9 @@ export async function carveWindowsReadDenies(denied, allowed) {
         await visit(path);
     return [...result];
 }
+/** Read grants are additive; inherited Users/Everyone write rights need a deny. */
+export async function windowsToolchainWriteDenies(readRoots, writeRoots) {
+    const unique = readRoots.filter((path, index) => !readRoots.slice(0, index).some(other => relative(path, other) === ''));
+    const roots = unique.filter(path => !unique.some(other => other !== path && within(path, other)));
+    return carveWindowsReadDenies(roots, writeRoots);
+}

package/dist/tools/windows-srt-path.d.ts

@@ -0,0 +1,2 @@
+/** Only the packaged host installation can select the sandbox broker. */
+export declare function verifiedWindowsSrt(directory?: string): string;

package/dist/tools/windows-srt-path.js

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Only the packaged host installation can select the sandbox broker. */
+export function verifiedWindowsSrt(directory = fileURLToPath(new URL('../../dist/native/', import.meta.url))) {
+    const path = join(directory, 'srt-win.exe');
+    try {
+        const manifest = JSON.parse(readFileSync(join(directory, 'srt-win.json'), 'utf8'));
+        const sha256 = createHash('sha256').update(readFileSync(path)).digest('hex');
+        if (manifest.sha256 !== sha256)
+            throw new Error('WINDOWS_SANDBOX_HELPER_HASH_MISMATCH');
+        return path;
+    }
+    catch (cause) {
+        throw Object.assign(new Error('WINDOWS_SANDBOX_HELPER_UNAVAILABLE: run pnpm desktop:build or reinstall the release package'), { code: 'WINDOWS_SANDBOX_HELPER_UNAVAILABLE', cause });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunterzhu/pulse-adapters",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "license": "PolyForm-Noncommercial-1.0.0",
   "repository": {
     "type": "git",
@@ -18,9 +18,10 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
-    "@hunterzhu/pulse-runtime": "0.5.1",
-    "@hunterzhu/pulse-tool-sdk": "0.5.1",
+    "@hunterzhu/pulse-runtime": "0.7.0",
+    "@hunterzhu/pulse-tool-sdk": "0.7.0",
     "exceljs": "4.4.0",
+    "mammoth": "1.11.0",
     "pdfjs-dist": "4.10.38"
   }
 }