@hunterzhu/pulse-adapters 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,40 @@
+# @hunterzhu/pulse-adapters
+
+Provider and bridge adapters for Pulse — model providers plus filesystem, shell, and MCP bridges.
+
+## Install
+
+```bash
+npm install @hunterzhu/pulse-adapters
+```
+
+Requires Node.js 22+. This package is ESM-only.
+
+## Usage
+
+`MockAdapter` is a network-free provider that returns scripted responses, which is handy for tests and local runs.
+
+Save as `example.mjs` and run `node example.mjs`.
+
+```js
+import { MockAdapter } from '@hunterzhu/pulse-adapters';
+
+const provider = new MockAdapter();
+provider.enqueue({ text: 'Hello, Pulse', toolCalls: [], finishReason: 'stop' });
+
+const attempt = await provider.executeAttempt();
+console.log(attempt.text); // "Hello, Pulse"
+```
+
+This example runs offline and needs no credentials. For real providers, use
+`createProviderAdapter({ provider, baseURL, defaultModel, apiKey })`; read the key in your
+application, for example `apiKey: process.env.DEEPSEEK_API_KEY`. The CLI's
+`apiKeyEnv` setting is not an adapter option.
+
+The same package also exposes filesystem and shell bridges plus MCP support
+for wiring external tool servers into Pulse.
+
+## Documentation
+
+- [Documentation](https://github.com/zhuhengtan/Pulse#readme)
+- [Source](https://github.com/zhuhengtan/Pulse/tree/main/packages/adapters)

package/dist/tools/filesystem.d.ts

@@ -15,6 +15,8 @@ export declare class FilesystemTool {
     private writable;
     read(path: string, signal?: AbortSignal): Promise<string>;
     readLimited(path: string, maxBytes: number, signal?: AbortSignal): Promise<FilesystemReadResult>;
+    /** Resolve a one-based source line without confusing line numbers with byte offsets. */
+    offsetForLine(path: string, startLine: number, signal?: AbortSignal): Promise<number>;
     readRange(path: string, maxBytes: number, offset?: number, signal?: AbortSignal): Promise<FilesystemReadResult & {
         offset: number;
         nextOffset: number | null;
@@ -26,6 +28,6 @@ export declare class FilesystemTool {
         bytes: number;
     }>;
     hash(path: string, signal?: AbortSignal): Promise<string>;
-    writeIfUnchanged(path: string, content: string, expectedHash: string, signal?: AbortSignal): Promise<FilesystemWriteResult>;
+    writeIfUnchanged(path: string, content: string, expectedHash: string | null, signal?: AbortSignal): Promise<FilesystemWriteResult>;
     private withLock;
 }

package/dist/tools/filesystem.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
-import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 function filesystemError(code, retryable = false, cause) {
@@ -59,6 +59,40 @@ export class FilesystemTool {
         const { content, truncated } = await this.readRange(path, maxBytes, 0, signal);
         return { content, truncated };
     }
+    /** Resolve a one-based source line without confusing line numbers with byte offsets. */
+    async offsetForLine(path, startLine, signal) {
+        if (!Number.isSafeInteger(startLine) || startLine < 1)
+            throw filesystemError('INVALID_START_LINE');
+        if (signal?.aborted)
+            throw filesystemError('ABORTED');
+        if (startLine === 1)
+            return 0;
+        const handle = await open(await this.existing(path), 'r');
+        try {
+            const buffer = Buffer.alloc(64 * 1024);
+            let offset = 0;
+            let line = 1;
+            const scanLimit = 16 * 1024 * 1024;
+            while (offset < scanLimit) {
+                if (signal?.aborted)
+                    throw filesystemError('ABORTED');
+                const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, scanLimit - offset), offset);
+                if (signal?.aborted)
+                    throw filesystemError('ABORTED');
+                if (!bytesRead)
+                    return offset;
+                for (let index = 0; index < bytesRead; index++) {
+                    if (buffer[index] === 10 && ++line === startLine)
+                        return offset + index + 1;
+                }
+                offset += bytesRead;
+            }
+            throw filesystemError('READ_LINE_SCAN_LIMIT');
+        }
+        finally {
+            await handle.close();
+        }
+    }
     async readRange(path, maxBytes, offset = 0, signal) {
         if (signal?.aborted)
             throw filesystemError('ABORTED');
@@ -68,6 +102,8 @@ export class FilesystemTool {
         try {
             const buffer = Buffer.alloc(maxBytes + 1);
             const { bytesRead } = await handle.read(buffer, 0, maxBytes + 1, offset);
+            if (signal?.aborted)
+                throw filesystemError('ABORTED');
             if (bytesRead && (buffer[0] & 0xc0) === 0x80)
                 throw filesystemError('INVALID_UTF8_OFFSET');
             let end = Math.min(bytesRead, maxBytes);
@@ -120,7 +156,7 @@ export class FilesystemTool {
     async writeIfUnchanged(path, content, expectedHash, signal) {
         if (signal?.aborted)
             throw filesystemError('ABORTED');
-        if (!/^[a-f0-9]{64}$/.test(expectedHash))
+        if (expectedHash !== null && !/^[a-f0-9]{64}$/.test(expectedHash))
             throw filesystemError('INVALID_FILE_BASELINE_HASH');
         const target = await this.writable(path);
         return this.withLock(target, async () => {
@@ -131,11 +167,12 @@ export class FilesystemTool {
                 current = await readFile(target);
             }
             catch (cause) {
-                if (cause.code === 'ENOENT')
-                    throw filesystemError('FILE_BASELINE_MISSING');
-                throw filesystemCause(cause);
+                if (cause.code !== 'ENOENT')
+                    throw filesystemCause(cause);
             }
-            const currentHash = createHash('sha256').update(current).digest('hex');
+            if (current === undefined && expectedHash !== null)
+                throw filesystemError('FILE_BASELINE_MISSING');
+            const currentHash = current === undefined ? null : createHash('sha256').update(current).digest('hex');
             if (currentHash !== expectedHash)
                 throw filesystemError('FILE_BASELINE_CONFLICT');
             const bytes = Buffer.byteLength(content, 'utf8');
@@ -144,10 +181,17 @@ export class FilesystemTool {
             try {
                 handle = await open(temporary, 'wx', 0o600);
                 await handle.writeFile(content, 'utf8');
+                if (current !== undefined)
+                    await handle.chmod((await lstat(target)).mode & 0o777);
                 await handle.sync();
                 await handle.close();
                 handle = undefined;
-                await rename(temporary, target);
+                if (signal?.aborted)
+                    throw filesystemError('ABORTED');
+                if (expectedHash === null)
+                    await link(temporary, target);
+                else
+                    await rename(temporary, target);
             }
             finally {
                 if (handle)

package/dist/tools/sandbox-initialization.d.ts

@@ -0,0 +1,2 @@
+import { type SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
+export declare function initializeShellSandbox(policy: SandboxRuntimeConfig, platform?: NodeJS.Platform): Promise<void>;

package/dist/tools/sandbox-initialization.js

@@ -0,0 +1,17 @@
+import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
+export async function initializeShellSandbox(policy, platform = process.platform) {
+    try {
+        await SandboxManager.initialize(policy, undefined, false);
+    }
+    catch (error) {
+        // A cold Windows sandbox account can time out during the WFP readiness
+        // probe. Retry that probe once after cleanup, before any command is run.
+        // A failed isolation check, ACL error, or second timeout still fails closed.
+        if (platform !== 'win32' || !error || typeof error !== 'object'
+            || !('code' in error) || error.code !== 'srt_win_timeout'
+            || !('subcommand' in error) || error.subcommand !== 'wfp')
+            throw error;
+        await SandboxManager.reset();
+        await SandboxManager.initialize(policy, undefined, false);
+    }
+}

package/dist/tools/shell.d.ts

@@ -6,6 +6,11 @@ export interface ShellResult {
     timedOut: boolean;
     aborted: boolean;
 }
+/** Read-only prerequisite probe; never provisions accounts or changes permissions. */
+export declare function checkShellSandbox(): Promise<{
+    errors: string[];
+    warnings: string[];
+}>;
 export declare function quoteWindowsArgument(value: string): string;
 /** Build the command text expected by srt without interpreting model argv as shell syntax. */
 export declare function encodeSandboxCommand(command: string, args: string[], platform?: NodeJS.Platform): string;
@@ -16,4 +21,5 @@ export declare function runShell(command: string, args?: string[], options?: {
     timeoutMs?: number;
     maxOutputBytes?: number;
     env?: NodeJS.ProcessEnv;
+    allowedDomains?: string[];
 }): Promise<ShellResult>;

package/dist/tools/shell.js

@@ -1,10 +1,14 @@
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
-import { dirname, parse, resolve, sep } from 'node:path';
-import { realpath } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
-import { SandboxManager, VENDORED_SRT_WIN_EXE } from '@anthropic-ai/sandbox-runtime';
+import { homedir, tmpdir } from 'node:os';
+import { basename, delimiter, dirname, join, parse, resolve, sep } from 'node:path';
+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 { resolveWindowsPackageManager } from './windows-package-manager.js';
+import { carveWindowsReadDenies } from './windows-read-policy.js';
+import { initializeShellSandbox } from './sandbox-initialization.js';
 function shellError(code, retryable = false, cause) {
     return Object.assign(new Error(code), { code, retryable, ...(cause === undefined ? {} : { cause }) });
 }
@@ -17,6 +21,14 @@ function withSandboxLease(work) {
     sandboxTail = result.then(() => undefined, () => undefined);
     return result;
 }
+/** Read-only prerequisite probe; never provisions accounts or changes permissions. */
+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 }) })
+        : SandboxManager.checkDependenciesAsync());
+}
 function quotePosix(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
@@ -90,7 +102,7 @@ export function encodeSandboxCommand(command, args, platform = process.platform)
     }
     return `exec ${[command, ...args].map(quotePosix).join(' ')}`;
 }
-async function sandboxConfig(cwd) {
+async function sandboxConfig(cwd, allowedDomains = [], toolchainRoots = [], scratch) {
     // 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'
@@ -102,20 +114,25 @@ async function sandboxConfig(cwd) {
     if (cwd === root || cwd === home || home.startsWith(cwd + sep) || parent === root) {
         throw shellError('SANDBOX_WORKSPACE_TOO_BROAD');
     }
-    const denyRead = new Set([home]);
+    // 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.
+    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);
+    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 },
+        network: { allowedDomains, deniedDomains: [], strictAllowlist: true },
         filesystem: {
-            denyRead: [...denyRead],
-            allowRead: [cwd, ...(seccompPath ? [seccompPath] : [])],
-            allowWrite: [cwd],
+            denyRead: process.platform === 'win32' ? await carveWindowsReadDenies([...denyRead], allowRead) : [...denyRead],
+            allowRead,
+            allowWrite: [cwd, ...(scratch ? [scratch] : [])],
             denyWrite: [],
         },
         ...(seccompPath ? { seccomp: { applyPath: seccompPath } } : {}),
@@ -168,125 +185,186 @@ export function runShell(command, args = [], options = {}) {
         catch (cause) {
             throw shellError('INVALID_SHELL_CWD', false, cause);
         }
-        const invocationId = randomUUID();
-        const policy = await sandboxConfig(cwd);
-        let child;
-        const outputChunks = { stdout: [], stderr: [] };
-        const outputBytes = { stdout: 0, stderr: 0 };
-        let truncated = false;
-        let closed = false;
-        let termination;
-        let timer;
-        let killTimer;
-        const signalProcessGroup = (signal) => {
-            if (!child?.pid)
-                return;
-            if (process.platform !== 'win32') {
-                try {
-                    process.kill(-child.pid, signal);
-                    return;
+        // Trust only the installation hosting Pulse, never arbitrary PATH directories.
+        const nodeExecutable = await realpath(process.execPath);
+        const nodeBin = dirname(nodeExecutable);
+        const installation = basename(nodeBin) === 'bin' ? dirname(nodeBin) : nodeBin;
+        const toolchainRoots = installation !== homedir() && installation !== parse(installation).root ? [installation] : [nodeExecutable];
+        // PNPM_HOME is a host installation setting, never supplied by model argv.
+        let pnpmHome;
+        if (process.env.PNPM_HOME) {
+            try {
+                const candidate = await realpath(process.env.PNPM_HOME);
+                if (candidate !== homedir() && candidate !== parse(candidate).root && !homedir().startsWith(candidate + sep)) {
+                    pnpmHome = candidate;
+                    toolchainRoots.push(candidate);
+                    // pnpm/action-setup exposes its executable shims from node_modules/.bin;
+                    // their targets live in the adjacent node_modules tree.
+                    if (basename(candidate) === '.bin')
+                        toolchainRoots.push(dirname(candidate));
                 }
-                catch { /* process group may already be gone */ }
             }
-            if (process.platform === 'win32') {
-                const tree = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, env: shellEnvironment(options.env) });
-                tree.once('error', () => child?.kill(signal));
-                tree.unref();
-                return;
-            }
-            child.kill(signal);
-        };
-        const terminate = (reason) => {
-            if (closed)
-                return;
-            termination ??= reason;
-            signalProcessGroup('SIGTERM');
-            if (!killTimer)
-                killTimer = setTimeout(() => { if (!closed)
-                    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)
-                truncated = true;
-        };
-        const outputText = (target) => {
-            return decodeUtf8WithinByteLimit(Buffer.concat(outputChunks[target]), max);
-        };
+            catch { /* stale installation settings do not grant access */ }
+        }
+        const scratch = await realpath(await mkdtemp(join(tmpdir(), 'pulse-shell-')));
         try {
-            // reset first in case an earlier initialize failed part-way through.
-            await SandboxManager.reset();
-            await SandboxManager.initialize(policy, undefined, false);
-            const commandText = encodeSandboxCommand(command, args);
-            const descriptor = await SandboxManager.wrapWithSandboxArgv(commandText, undefined, undefined, options.signal, cwd, { commandId: invocationId, commandText: 'shell.exec' });
-            if (options.signal?.aborted) {
-                SandboxManager.cleanupAfterCommand();
-                await SandboxManager.reset();
-                return { code: null, stdout: '', stderr: '', truncated: false, timedOut: false, aborted: true };
+            const baseEnv = shellEnvironment(options.env);
+            const pathKey = Object.keys(baseEnv).find((key) => key.toUpperCase() === 'PATH') ?? 'PATH';
+            const executionEnv = { [pathKey]: [...(pnpmHome ? [pnpmHome] : []), nodeBin, join(cwd, 'node_modules', '.bin'), baseEnv[pathKey] ?? ''].join(delimiter),
+                ...(process.platform === 'win32' ? {} : { HOME: scratch, TMPDIR: scratch, TMP: scratch, TEMP: scratch, XDG_CONFIG_HOME: scratch, XDG_CACHE_HOME: scratch, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' }) };
+            let executable = command;
+            let executableArgs = args;
+            if (command === 'node')
+                executable = nodeExecutable;
+            if (process.platform === 'darwin' && command === 'git') {
+                // /usr/bin/git is an xcrun shim that writes outside TMPDIR. Resolve the
+                // installed tool through Apple's fixed locator before entering isolation.
+                const located = await promisify(execFile)('/usr/bin/xcrun', ['--find', 'git'], { timeout: 5000, env: baseEnv });
+                executable = located.stdout.trim();
+                if (!executable.startsWith('/'))
+                    throw shellError('GIT_TOOLCHAIN_NOT_FOUND');
             }
-            child = spawn(descriptor.argv[0], descriptor.argv.slice(1), {
-                cwd,
-                env: shellEnvironment(options.env ?? descriptor.env),
-                shell: false,
-                detached: process.platform !== 'win32',
-                windowsHide: true,
-            });
-        }
-        catch (cause) {
-            try {
-                await SandboxManager.reset();
+            if (process.platform === 'win32') {
+                const resolved = await resolveWindowsPackageManager(command, nodeExecutable, pnpmHome);
+                if (resolved) {
+                    executable = resolved.executable;
+                    executableArgs = [...resolved.prefixArgs, ...args];
+                }
             }
-            catch { /* preserve the setup failure */ }
-            throw shellError('SANDBOX_SETUP_FAILED', false, cause);
-        }
-        // This API has no stdin payload; deliver EOF to readers inside the sandbox.
-        child.stdin?.end();
-        return await new Promise((resolve, reject) => {
-            const cleanup = () => {
-                if (timer)
-                    clearTimeout(timer);
-                if (killTimer)
-                    clearTimeout(killTimer);
-                options.signal?.removeEventListener('abort', abort);
+            const invocationId = randomUUID();
+            const policy = await sandboxConfig(cwd, options.allowedDomains ?? [], toolchainRoots, scratch);
+            let child;
+            const outputChunks = { stdout: [], stderr: [] };
+            const outputBytes = { stdout: 0, stderr: 0 };
+            let truncated = false;
+            let closed = false;
+            let termination;
+            let timer;
+            let killTimer;
+            const signalProcessGroup = (signal) => {
+                if (!child?.pid)
+                    return;
+                if (process.platform !== 'win32') {
+                    try {
+                        process.kill(-child.pid, signal);
+                        return;
+                    }
+                    catch { /* process group may already be gone */ }
+                }
+                if (process.platform === 'win32') {
+                    const tree = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, env: shellEnvironment(options.env) });
+                    tree.once('error', () => child?.kill(signal));
+                    tree.unref();
+                    return;
+                }
+                child.kill(signal);
             };
-            const abort = () => terminate('aborted');
-            timer = options.timeoutMs && options.timeoutMs > 0 ? setTimeout(() => terminate('timeout'), options.timeoutMs) : undefined;
-            if (options.signal)
-                options.signal.addEventListener('abort', abort, { once: true });
-            if (options.signal?.aborted)
-                abort();
-            child.stdout?.on('data', (chunk) => append('stdout', chunk));
-            child.stderr?.on('data', (chunk) => append('stderr', chunk));
-            child.once('error', (cause) => {
-                closed = true;
-                cleanup();
-                const errorCode = cause && typeof cause === 'object' ? cause.code : undefined;
-                const code = typeof errorCode === 'string' ? errorCode : 'SHELL_EXECUTION_ERROR';
-                reject(shellError(code === 'ENOENT' || code === 'EACCES' ? code : 'SHELL_EXECUTION_ERROR', false, cause));
-            });
-            child.once('close', (code) => {
-                closed = true;
-                cleanup();
-                const stdout = outputText('stdout');
-                const stderr = outputText('stderr');
-                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' });
-            });
-        }).finally(async () => {
+            const terminate = (reason) => {
+                if (closed)
+                    return;
+                termination ??= reason;
+                signalProcessGroup('SIGTERM');
+                if (!killTimer)
+                    killTimer = setTimeout(() => { if (!closed)
+                        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)
+                    truncated = true;
+            };
+            const outputText = (target) => {
+                return decodeUtf8WithinByteLimit(Buffer.concat(outputChunks[target]), max);
+            };
+            let setupStage = 'reset';
             try {
-                SandboxManager.cleanupAfterCommand();
+                // reset first in case an earlier initialize failed part-way through.
                 await SandboxManager.reset();
+                setupStage = 'initialize';
+                await initializeShellSandbox(policy);
+                const commandText = encodeSandboxCommand(executable, executableArgs);
+                setupStage = 'wrap';
+                const descriptor = await SandboxManager.wrapWithSandboxArgv(commandText, undefined, undefined, options.signal, cwd, { commandId: invocationId, commandText: 'shell.exec' });
+                if (options.signal?.aborted) {
+                    SandboxManager.cleanupAfterCommand();
+                    await SandboxManager.reset();
+                    return { code: null, stdout: '', stderr: '', truncated: false, timedOut: false, aborted: true };
+                }
+                child = spawn(descriptor.argv[0], descriptor.argv.slice(1), {
+                    cwd,
+                    env: { ...baseEnv, ...shellEnvironment(descriptor.env), ...executionEnv },
+                    shell: false,
+                    detached: process.platform !== 'win32',
+                    windowsHide: true,
+                });
             }
             catch (cause) {
-                // A teardown failure must be visible and fail closed for the next call.
-                throw shellError('SANDBOX_CLEANUP_FAILED', false, cause);
+                try {
+                    await SandboxManager.reset();
+                }
+                catch { /* preserve the setup failure */ }
+                // 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) : '';
+                const reason = /windows-install|not provisioned/i.test(message) ? 'WINDOWS_SANDBOX_NOT_PROVISIONED'
+                    : ['ENOENT', 'EACCES', 'EPERM'].includes(nativeCode) ? nativeCode : 'SANDBOX_INITIALIZATION_ERROR';
+                throw Object.assign(shellError('SANDBOX_SETUP_FAILED', false, cause), {
+                    message: `SANDBOX_SETUP_FAILED (${setupStage}: ${reason})`,
+                    details: { platform: process.platform, stage: setupStage, reason },
+                });
             }
-        });
+            // This API has no stdin payload; deliver EOF to readers inside the sandbox.
+            child.stdin?.end();
+            return await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    if (timer)
+                        clearTimeout(timer);
+                    if (killTimer)
+                        clearTimeout(killTimer);
+                    options.signal?.removeEventListener('abort', abort);
+                };
+                const abort = () => terminate('aborted');
+                timer = options.timeoutMs && options.timeoutMs > 0 ? setTimeout(() => terminate('timeout'), options.timeoutMs) : undefined;
+                if (options.signal)
+                    options.signal.addEventListener('abort', abort, { once: true });
+                if (options.signal?.aborted)
+                    abort();
+                child.stdout?.on('data', (chunk) => append('stdout', chunk));
+                child.stderr?.on('data', (chunk) => append('stderr', chunk));
+                child.once('error', (cause) => {
+                    closed = true;
+                    cleanup();
+                    const errorCode = cause && typeof cause === 'object' ? cause.code : undefined;
+                    const code = typeof errorCode === 'string' ? errorCode : 'SHELL_EXECUTION_ERROR';
+                    reject(shellError(code === 'ENOENT' || code === 'EACCES' ? code : 'SHELL_EXECUTION_ERROR', false, cause));
+                });
+                child.once('close', (code) => {
+                    closed = true;
+                    cleanup();
+                    const stdout = outputText('stdout');
+                    const stderr = outputText('stderr');
+                    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' });
+                });
+            }).finally(async () => {
+                try {
+                    SandboxManager.cleanupAfterCommand();
+                    await SandboxManager.reset();
+                }
+                catch (cause) {
+                    // A teardown failure must be visible and fail closed for the next call.
+                    throw shellError('SANDBOX_CLEANUP_FAILED', false, cause);
+                }
+            });
+        }
+        finally {
+            await rm(scratch, { recursive: true, force: true });
+        }
     });
 }

package/dist/tools/windows-package-manager.d.ts

@@ -0,0 +1,5 @@
+/** Resolve trusted installations without executing .cmd shims or fetching via Corepack first. */
+export declare function resolveWindowsPackageManager(command: string, nodeExecutable: string, pnpmHome?: string): Promise<{
+    executable: string;
+    prefixArgs: string[];
+} | undefined>;

package/dist/tools/windows-package-manager.js

@@ -0,0 +1,31 @@
+import { realpath, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Resolve trusted installations without executing .cmd shims or fetching via Corepack first. */
+export async function resolveWindowsPackageManager(command, nodeExecutable, pnpmHome) {
+    if (!['npm', 'npx', 'pnpm', 'pnpx', 'corepack'].includes(command))
+        return undefined;
+    const nodeBin = dirname(nodeExecutable);
+    const candidates = [];
+    if (command === 'pnpm' || command === 'pnpx') {
+        // pnpm 11+ ships a native executable and an .mjs wrapper; older versions use .cjs.
+        // action-setup installs its package next to PNPM_HOME (.bin).
+        const roots = [...(pnpmHome ? [pnpmHome, join(dirname(pnpmHome), 'pnpm')] : []), join(nodeBin, 'node_modules', 'pnpm')];
+        for (const root of roots) {
+            candidates.push({ path: join(root, 'pnpm.exe'), native: true, dlx: command === 'pnpx' }, { path: join(root, 'bin', `${command}.mjs`) }, { path: join(root, 'bin', 'pnpm.cjs'), dlx: command === 'pnpx' });
+        }
+    }
+    else {
+        candidates.push({ path: join(nodeBin, 'node_modules', command === 'corepack' ? 'corepack/dist/corepack.js' : `npm/bin/${command}-cli.js`) });
+    }
+    candidates.push({ path: join(nodeBin, 'node_modules', 'corepack', 'dist', `${command}.js`) });
+    for (const candidate of candidates) {
+        try {
+            const path = await realpath(candidate.path);
+            if (!(await stat(path)).isFile())
+                continue;
+            return { executable: candidate.native ? path : nodeExecutable, prefixArgs: [...(candidate.native ? [] : [path]), ...(candidate.dlx ? ['dlx'] : [])] };
+        }
+        catch { /* Missing installations fall through to the next trusted candidate. */ }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,2 @@
+/** Keep denied subtrees off the ancestors Git must stat to reach an allowed workspace. */
+export declare function carveWindowsReadDenies(denied: string[], allowed: string[]): Promise<string[]>;

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

@@ -0,0 +1,28 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative, isAbsolute, sep } from 'node:path';
+function within(path, root) {
+    const rel = relative(root, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Keep denied subtrees off the ancestors Git must stat to reach an allowed workspace. */
+export async function carveWindowsReadDenies(denied, allowed) {
+    const result = new Set();
+    const visited = new Set();
+    const visit = async (path) => {
+        if (visited.has(path) || allowed.some(root => within(path, root)))
+            return;
+        visited.add(path);
+        if (!allowed.some(root => within(root, path))) {
+            result.add(path);
+            return;
+        }
+        // Windows inherited DENY ACEs are not POSIX allow-within-deny rules.
+        // Deny siblings along the allowed path, keeping only ancestor metadata
+        // accessible. An enumeration failure aborts setup rather than dropping a deny.
+        for (const entry of await readdir(path))
+            await visit(join(path, entry));
+    };
+    for (const path of denied)
+        await visit(path);
+    return [...result];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunterzhu/pulse-adapters",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/zhuhengtan/Pulse"
@@ -17,8 +17,8 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
-    "@hunterzhu/pulse-runtime": "0.2.0",
-    "@hunterzhu/pulse-tool-sdk": "0.2.0",
+    "@hunterzhu/pulse-runtime": "0.2.1",
+    "@hunterzhu/pulse-tool-sdk": "0.2.1",
     "exceljs": "4.4.0",
     "pdfjs-dist": "4.10.38"
   }