@purista/harness 1.2.5 → 1.5.0

package/dist/local/local-sandbox.js

@@ -0,0 +1,368 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile, rm, readdir, stat, lstat, realpath } from 'node:fs/promises';
+import { resolve, dirname, posix, join } from 'node:path';
+import { SandboxError, SandboxNoExecutorError, OperationTimeoutError } from '../errors/index.js';
+import { abortError } from '../runtime/abort.js';
+import { sha256Hex } from './ref-hash.js';
+const DEFAULT_EXEC_TIMEOUT_MS = 120_000;
+/** Maximum captured stdout/stderr bytes per exec call (spec 22 §5). */
+const MAX_EXEC_CAPTURE_BYTES = 10 * 1024 * 1024;
+const EXEC_OUTPUT_TRUNCATION_MARKER = '\n[truncated: local sandbox capture limit reached]';
+/** Shell metacharacters rejected outside quotes when an allow-list is active (spec 22 §5). */
+const SHELL_METACHARACTERS = new Set([';', '|', '&', '<', '>', '`', '$', '(', ')', '\n', '\r']);
+/** Path-segment-safe id for sandbox session roots (no separators, no dot segments). */
+const SANDBOX_ID_SEGMENT_PATTERN = /^[A-Za-z0-9_.:-]{1,200}$/;
+function assertSafeIdSegment(value, field) {
+    if (!SANDBOX_ID_SEGMENT_PATTERN.test(value) || value === '.' || value === '..' || value.includes('/') || value.includes('\\')) {
+        throw new SandboxError(`Sandbox ${field} contains unsupported path characters.`, { reason: 'invalid_path' });
+    }
+}
+/**
+ * Tokenizes a command line without invoking a shell. Supports single/double
+ * quotes for grouping; performs no expansion, substitution, or redirection.
+ * When `rejectMetacharacters` is set (active allow-list), unquoted shell
+ * metacharacters are rejected so the allow-list cannot be bypassed.
+ */
+function tokenizeCommand(command, opts) {
+    const tokens = [];
+    let current = '';
+    let quote;
+    let hasToken = false;
+    for (const char of command) {
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            hasToken = true;
+            continue;
+        }
+        if (opts.rejectMetacharacters && SHELL_METACHARACTERS.has(char)) {
+            throw new SandboxError('Command contains shell metacharacters that are not allowed by local sandbox policy.', { reason: 'exec_failed' });
+        }
+        if (char === ' ' || char === '\t') {
+            if (hasToken) {
+                tokens.push(current);
+                current = '';
+                hasToken = false;
+            }
+            continue;
+        }
+        current += char;
+        hasToken = true;
+    }
+    if (quote)
+        throw new SandboxError('Command has an unterminated quote.', { reason: 'exec_failed' });
+    if (hasToken)
+        tokens.push(current);
+    return tokens;
+}
+function appendCapped(target, chunk) {
+    if (target.truncated)
+        return;
+    const chunkBytes = Buffer.byteLength(chunk);
+    if (target.bytes + chunkBytes <= MAX_EXEC_CAPTURE_BYTES) {
+        target.text += chunk;
+        target.bytes += chunkBytes;
+        return;
+    }
+    const remaining = MAX_EXEC_CAPTURE_BYTES - target.bytes;
+    target.text += chunk.slice(0, Math.max(0, remaining)) + EXEC_OUTPUT_TRUNCATION_MARKER;
+    target.bytes = MAX_EXEC_CAPTURE_BYTES;
+    target.truncated = true;
+}
+class LocalDirectorySandboxSession {
+    executor;
+    root;
+    execPolicy;
+    telemetry;
+    fallbackExecTimeoutMs;
+    constructor(root, execPolicy, telemetry, fallbackExecTimeoutMs) {
+        this.root = resolve(root);
+        this.execPolicy = execPolicy;
+        this.telemetry = telemetry;
+        this.fallbackExecTimeoutMs = fallbackExecTimeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
+        this.executor = execPolicy === false ? 'unavailable' : 'available';
+    }
+    async read(path) {
+        return this.sandboxSpan('read', {}, async () => readFile(await this.toPhysical(path)));
+    }
+    async readText(path) {
+        return this.sandboxSpan('read_text', {}, async () => readFile(await this.toPhysical(path), 'utf8'));
+    }
+    async write(path, data) {
+        return this.sandboxSpan('write', {
+            'harness.sandbox.write_bytes': typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength
+        }, async () => {
+            const physical = await this.toPhysical(path, { forWrite: true });
+            await mkdir(dirname(physical), { recursive: true });
+            await writeFile(physical, data);
+        });
+    }
+    async remove(path, opts = {}) {
+        return this.sandboxSpan('remove', {
+            'harness.sandbox.recursive': opts.recursive ?? false
+        }, async () => { await rm(await this.toPhysical(path), { recursive: opts.recursive ?? false, force: true }); });
+    }
+    async list(path, opts = {}) {
+        return this.sandboxSpan('list', {
+            'harness.sandbox.recursive': opts.recursive ?? false,
+            'harness.sandbox.has_glob': Boolean(opts.glob)
+        }, async () => {
+            const root = await this.toPhysical(path);
+            const entries = [];
+            await this.collect(root, path, opts.recursive ?? false, entries);
+            if (!opts.glob)
+                return entries;
+            const globPattern = globToRegExp(opts.glob);
+            return entries.filter((entry) => globPattern.test(entry.path));
+        });
+    }
+    async stat(path) {
+        return this.sandboxSpan('stat', {}, async () => {
+            const info = await stat(await this.toPhysical(path));
+            return { kind: info.isDirectory() ? 'directory' : 'file', size: info.isDirectory() ? 0 : info.size, modifiedAt: info.mtime.toISOString() };
+        });
+    }
+    async exists(path) {
+        return this.sandboxSpan('exists', {}, async () => {
+            try {
+                await this.toPhysical(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    async mount(files, atPath) {
+        return this.sandboxSpan('mount', {
+            'harness.sandbox.file_count': files.size
+        }, async () => {
+            for (const [name, data] of files) {
+                const target = posix.join(atPath, name);
+                await this.write(target, data);
+            }
+        });
+    }
+    async exec(command, opts = {}) {
+        return this.sandboxSpan('exec', {
+            'harness.sandbox.has_cwd': Boolean(opts.cwd),
+            'harness.sandbox.has_stdin': Boolean(opts.stdin)
+        }, async () => {
+            if (this.execPolicy === false) {
+                throw new SandboxNoExecutorError('Sandbox session has no executor.', { session_id: 'local' });
+            }
+            const policy = this.execPolicy;
+            // No shell is involved: the command is tokenized and spawned as argv, so
+            // metacharacters carry no semantics. With an allow-list they are rejected
+            // outright to keep the policy boundary obvious (spec 22 §5).
+            const argv = tokenizeCommand(command, { rejectMetacharacters: policy.allowCommands !== undefined });
+            const commandName = argv[0];
+            if (!commandName) {
+                throw new SandboxError('Sandbox command is empty.', { reason: 'exec_failed' });
+            }
+            if (policy.allowCommands && !policy.allowCommands.includes(commandName)) {
+                throw new SandboxError('Command is not allowed by local sandbox policy.', { reason: 'exec_failed' });
+            }
+            const cwd = await this.toPhysical(opts.cwd ?? '/workspace');
+            const timeoutMs = opts.timeoutMs ?? policy.timeoutMs ?? this.fallbackExecTimeoutMs;
+            const signal = opts.signal;
+            if (signal?.aborted)
+                throw abortError(signal, 'sandbox', 'Sandbox exec was cancelled.');
+            const started = Date.now();
+            return new Promise((resolveExec, rejectExec) => {
+                const child = spawn(commandName, argv.slice(1), {
+                    cwd,
+                    env: { PATH: process.env['PATH'] ?? '', HOME: this.root, ...policy.env, ...opts.env },
+                    stdio: ['pipe', 'pipe', 'pipe']
+                });
+                const stdout = { text: '', bytes: 0, truncated: false };
+                const stderr = { text: '', bytes: 0, truncated: false };
+                let settled = false;
+                const onAbort = () => {
+                    child.kill('SIGTERM');
+                    finish(() => rejectExec(abortError(signal, 'sandbox', 'Sandbox exec was cancelled.')));
+                };
+                const timer = setTimeout(() => {
+                    child.kill('SIGKILL');
+                    finish(() => rejectExec(new OperationTimeoutError('Sandbox exec timed out.', { scope: 'sandbox_run', timeout_ms: timeoutMs })));
+                }, timeoutMs);
+                const finish = (settle) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    signal?.removeEventListener('abort', onAbort);
+                    settle();
+                };
+                signal?.addEventListener('abort', onAbort, { once: true });
+                child.stdout.on('data', (chunk) => { appendCapped(stdout, String(chunk)); });
+                child.stderr.on('data', (chunk) => { appendCapped(stderr, String(chunk)); });
+                child.on('error', (error) => {
+                    finish(() => rejectExec(new SandboxError('Local sandbox exec failed.', { reason: 'exec_failed', stdout: stdout.text, stderr: stderr.text }, error)));
+                });
+                child.on('close', (exitCode, exitSignal) => {
+                    finish(() => {
+                        if (exitCode === null) {
+                            rejectExec(new SandboxError(`Local sandbox exec was terminated by signal ${exitSignal ?? 'unknown'}.`, { reason: 'exec_failed', stdout: stdout.text, stderr: stderr.text }));
+                            return;
+                        }
+                        resolveExec({ stdout: stdout.text, stderr: stderr.text, exitCode, durationSeconds: (Date.now() - started) / 1000 });
+                    });
+                });
+                if (opts.stdin)
+                    child.stdin.end(opts.stdin);
+                else
+                    child.stdin.end();
+            });
+        });
+    }
+    async close() { }
+    async collect(root, virtualRoot, recursive, out) {
+        for (const entry of await readdir(root, { withFileTypes: true })) {
+            const physical = join(root, entry.name);
+            const virtual = posix.join(virtualRoot, entry.name);
+            const info = await stat(physical);
+            out.push({ name: entry.name, path: virtual, kind: entry.isDirectory() ? 'directory' : 'file', ...(entry.isFile() ? { size: info.size } : {}) });
+            if (recursive && entry.isDirectory())
+                await this.collect(physical, virtual, recursive, out);
+        }
+    }
+    async toPhysical(input, opts = {}) {
+        if (!input.startsWith('/'))
+            throw new SandboxError('Invalid path.', { reason: 'invalid_path' });
+        const normalized = posix.normalize(input);
+        if (!normalized.startsWith('/'))
+            throw new SandboxError('Invalid path.', { reason: 'invalid_path' });
+        const target = resolve(this.root, `.${normalized}`);
+        const guardPath = opts.forWrite ? dirname(target) : target;
+        const existing = await realpath(guardPath).catch(() => opts.forWrite ? realpathExistingParent(guardPath) : undefined);
+        if (!existing)
+            throw new SandboxError('Path not found.', { reason: 'fs_failed' });
+        const rootReal = await realpath(this.root);
+        if (existing !== rootReal && !existing.startsWith(`${rootReal}/`)) {
+            throw new SandboxError('Path escapes local sandbox root.', { reason: 'invalid_path' });
+        }
+        if (opts.forWrite) {
+            // The final component must not be a symlink (including dangling ones):
+            // writing through it would follow the link target outside the jail.
+            const targetInfo = await lstat(target).catch(() => undefined);
+            if (targetInfo?.isSymbolicLink()) {
+                throw new SandboxError('Path escapes local sandbox root.', { reason: 'invalid_path' });
+            }
+        }
+        return target;
+    }
+    async sandboxSpan(operation, attrs, fn) {
+        const spanAttrs = {
+            'harness.sandbox.adapter': 'local_directory_sandbox',
+            'harness.sandbox.operation': operation,
+            'harness.sandbox.exec_enabled': this.execPolicy !== false,
+            ...attrs
+        };
+        const started = Date.now();
+        const run = async () => {
+            try {
+                const result = await fn();
+                this.telemetry?.recordCounter('harness.local_sandbox.operations', 1, spanAttrs);
+                return result;
+            }
+            finally {
+                this.telemetry?.recordHistogram('harness.local_sandbox.operation.duration', (Date.now() - started) / 1000, spanAttrs);
+            }
+        };
+        return this.telemetry ? this.telemetry.span(`harness.local_sandbox.${operation}`, spanAttrs, run) : run();
+    }
+}
+class FilesOnlyLocalSandboxSession extends LocalDirectorySandboxSession {
+    constructor(root, telemetry) {
+        super(root, false, telemetry, undefined);
+    }
+}
+class ExecLocalSandboxSession extends LocalDirectorySandboxSession {
+    constructor(root, execPolicy, telemetry, fallbackExecTimeoutMs) {
+        super(root, execPolicy, telemetry, fallbackExecTimeoutMs);
+    }
+}
+class BaseLocalDirectorySandbox {
+    options;
+    execEnabled;
+    telemetry;
+    toolTimeoutMs;
+    constructor(options, execEnabled) {
+        this.options = options;
+        this.execEnabled = execEnabled;
+    }
+    configureHarnessContext(context) {
+        this.telemetry = context.telemetry;
+        // Spec 22 §2: exec timeout falls back to the configured harness toolTimeoutMs.
+        this.toolTimeoutMs = context.defaults.toolTimeoutMs;
+    }
+    async openRoot(opts, make) {
+        assertSafeIdSegment(opts.sessionId, 'sessionId');
+        assertSafeIdSegment(opts.runId, 'runId');
+        const active = this.options.coordinator?.get(opts.runId, opts.sessionId);
+        const spanAttrs = {
+            'harness.sandbox.adapter': 'local_directory_sandbox',
+            'harness.sandbox.operation': 'open',
+            'harness.sandbox.exec_enabled': this.execEnabled,
+            ...(active ? { 'harness.workspace.ref_hash': sha256Hex(active.workspaceRef) } : {}),
+            'harness.run.id': opts.runId,
+            'harness.session.id': opts.sessionId
+        };
+        const started = Date.now();
+        const run = async () => {
+            const root = active?.activePath ?? resolve(this.options.root, 'sessions', opts.sessionId, opts.runId);
+            await mkdir(join(root, 'workspace'), { recursive: true });
+            this.telemetry?.recordCounter('harness.local_sandbox.operations', 1, spanAttrs);
+            this.telemetry?.recordHistogram('harness.local_sandbox.operation.duration', (Date.now() - started) / 1000, spanAttrs);
+            return make(root);
+        };
+        return this.telemetry ? this.telemetry.span('harness.local_sandbox.open', spanAttrs, async () => run()) : run();
+    }
+}
+class FilesOnlyLocalDirectorySandbox extends BaseLocalDirectorySandbox {
+    capabilities = ['sandbox.fs', 'sandbox.persistent_fs'];
+    constructor(options) {
+        super(options, false);
+    }
+    async open(opts) {
+        return this.openRoot(opts, (root) => new FilesOnlyLocalSandboxSession(root, this.telemetry));
+    }
+}
+class ExecLocalDirectorySandbox extends BaseLocalDirectorySandbox {
+    execPolicy;
+    capabilities = ['sandbox.fs', 'sandbox.exec', 'sandbox.persistent_fs'];
+    constructor(options, execPolicy) {
+        super(options, true);
+        this.execPolicy = execPolicy;
+    }
+    async open(opts) {
+        return this.openRoot(opts, (root) => new ExecLocalSandboxSession(root, this.execPolicy, this.telemetry, this.toolTimeoutMs));
+    }
+}
+async function realpathExistingParent(path) {
+    let current = path;
+    while (current !== dirname(current)) {
+        try {
+            return await realpath(current);
+        }
+        catch {
+            current = dirname(current);
+        }
+    }
+    return undefined;
+}
+function globToRegExp(glob) {
+    const source = glob.split('*').map((part) => part.replace(/[\\^$+?.()|[\]{}]/g, '\\$&')).join('.*');
+    return new RegExp(`^${source}$`);
+}
+export function localDirectorySandbox(options) {
+    const exec = options.exec ?? false;
+    return exec === false ? new FilesOnlyLocalDirectorySandbox(options) : new ExecLocalDirectorySandbox(options, exec);
+}

package/dist/local/local-workspace.d.ts

@@ -0,0 +1,56 @@
+import type { AdapterCapability } from '../ports/capabilities.js';
+import type { HarnessAdapterContext } from '../ports/harness-context.js';
+import type { DurableWorkspacePolicy, DurableWorkspaceStore, DurableWorkspaceStoreInfo, WorkspaceAbortOptions, WorkspaceAbortResult, WorkspaceCheckpoint, WorkspaceCleanupOptions, WorkspaceCleanupResult, WorkspaceHandle, WorkspaceInspection, WorkspaceInspectionOptions, WorkspacePauseOptions, WorkspaceResumeOptions, WorkspaceStartOptions } from '../ports/workspace.js';
+export interface LocalWorkspaceCoordinator {
+    bind(runId: string, sessionId: string, workspaceRef: string, activePath: string): void;
+    get(runId: string, sessionId: string): {
+        workspaceRef: string;
+        activePath: string;
+    } | undefined;
+    unbind(runId: string, sessionId: string): void;
+}
+export declare function createLocalWorkspaceCoordinator(): LocalWorkspaceCoordinator;
+export interface LocalDirectoryWorkspaceStoreOptions {
+    /** Host root for durable workspaces. */
+    root: string;
+    /** Optional policy metadata reported by the adapter. */
+    policy?: Partial<DurableWorkspacePolicy>;
+    /** Internal coordinator shared with localDirectorySandbox. */
+    coordinator?: LocalWorkspaceCoordinator;
+}
+/** Host-directory durable workspace store used by localDurableExecution. */
+export declare class LocalDirectoryWorkspaceStore implements DurableWorkspaceStore {
+    readonly info: DurableWorkspaceStoreInfo;
+    readonly capabilities: readonly AdapterCapability[];
+    private readonly root;
+    private readonly coordinator;
+    /** In-process lookup caches; the persisted `meta.json` files stay authoritative. */
+    private readonly runIdIndex;
+    private readonly opKeyIndex;
+    private telemetry;
+    constructor(options: LocalDirectoryWorkspaceStoreOptions);
+    configureHarnessContext(context: HarnessAdapterContext): void;
+    /** Drops the run→sandbox coordinator binding once a durable run is finished/disposed. */
+    releaseRunBinding(runId: string, sessionId: string): void;
+    startWorkspace(opts: WorkspaceStartOptions): Promise<WorkspaceHandle>;
+    pauseWorkspace(opts: WorkspacePauseOptions): Promise<WorkspaceCheckpoint>;
+    resumeWorkspace(opts: WorkspaceResumeOptions): Promise<WorkspaceHandle>;
+    abortWorkspace(opts: WorkspaceAbortOptions): Promise<WorkspaceAbortResult>;
+    cleanupWorkspace(opts: WorkspaceCleanupOptions): Promise<WorkspaceCleanupResult>;
+    inspectWorkspace(opts: WorkspaceInspectionOptions): Promise<WorkspaceInspection>;
+    private workspacePath;
+    private activePath;
+    private checkpointPath;
+    private metaPath;
+    private readMeta;
+    /** Crash-atomic meta write: temp file plus rename (spec 21 §9 pause-failure semantics). */
+    private writeMeta;
+    private persistOp;
+    private evictFromIndexes;
+    private findPersistedOp;
+    private findByRun;
+    private findRefByCheckpoint;
+    private scanMetas;
+    private workspaceSpan;
+}
+export declare function localDirectoryWorkspaceStore(options: LocalDirectoryWorkspaceStoreOptions): DurableWorkspaceStore;