@nia-teams/four-tools 0.0.0-stage → 0.1.0

package/dist/core/tools/shell.js

@@ -0,0 +1,166 @@
+import { toolContracts } from '../contracts.js';
+import { safe, schema } from './shared.js';
+const signals = ['SIGINT', 'SIGTERM', 'SIGKILL'];
+const wireStatus = (status) => status === 'running' || status === 'error' ? status : 'stopped';
+export function signalExitCode(exitCode, signal) {
+    return signal === 'SIGINT'
+        ? 130
+        : signal === 'SIGTERM'
+            ? 143
+            : signal === 'SIGKILL'
+                ? 137
+                : (exitCode ?? 1);
+}
+export function createShellTool(env, options = {}) {
+    const background = (options.allowBackground ?? Boolean(env.terminals)) &&
+        Boolean(env.terminals);
+    const full = structuredClone(toolContracts.shell);
+    const common = {
+        command: full.inputSchema.properties.command,
+        cwd: full.inputSchema.properties.cwd,
+        timeout: full.inputSchema.properties.timeout,
+    };
+    return safe({
+        name: options.name ?? 'shell',
+        description: background
+            ? full.description
+            : 'Execute shell commands in the workspace. Run a one-shot command and wait for output. Timeout or cancellation terminates the process group.',
+        concurrency: 'parallel',
+        inputSchema: background ? full.inputSchema : schema(common, ['command']),
+        async execute(input, ctx = {}) {
+            const action = input.action || 'exec';
+            if (!background && action !== 'exec')
+                return 'Error: background terminals are unavailable';
+            const backend = background ? env.terminals : undefined;
+            if (action === 'terminal_list') {
+                const terminals = await backend.list();
+                if (!terminals.length)
+                    return 'No active terminals';
+                return terminals
+                    .map((t) => `${t.status === 'running' ? '[running]' : '[stopped]'} ${t.id} - ${t.name || '(unnamed)'}${t.command ? ` (${t.command})` : ''} [${t.linesBuffered || 0} lines]`)
+                    .join('\n');
+            }
+            if (action === 'terminal_read') {
+                if (!input.id)
+                    return 'Error: id is required for terminal_read';
+                const data = await backend.read({
+                    id: String(input.id),
+                    offset: input.offset,
+                    limit: input.limit,
+                });
+                const lines = data.lines ??
+                    (data.content.length
+                        ? data.content.replace(/\n$/, '').split('\n')
+                        : []);
+                let out = lines.length ? lines.join('\n') + '\n' : '';
+                out += `---\nstatus: ${wireStatus(data.status)}, total_lines: ${data.totalLines}`;
+                const next = data.nextOffset ??
+                    (data.endLine < data.totalLines
+                        ? Math.max(0, data.endLine)
+                        : undefined);
+                if (next !== undefined)
+                    out += `, next_offset: ${next}`;
+                return out;
+            }
+            if (action === 'terminal_signal') {
+                if (!input.id || !input.signal)
+                    return 'Error: id and signal are required for terminal_signal';
+                if (!signals.includes(input.signal))
+                    return 'Error: invalid signal';
+                await backend.signal({
+                    id: String(input.id),
+                    signal: input.signal,
+                });
+                return `Sent ${input.signal}`;
+            }
+            if (action === 'terminal_destroy') {
+                if (!input.id)
+                    return 'Error: id is required for terminal_destroy';
+                await backend.destroy({ id: String(input.id) });
+                return 'Terminal destroyed';
+            }
+            if (action !== 'exec' && action !== 'terminal_create')
+                return `Unknown action: ${action}`;
+            if (!input.command)
+                return `Error: command is required for ${action}`;
+            if (typeof input.command !== 'string')
+                return 'Error: command must be a string';
+            const command = input.command;
+            if (action === 'terminal_create' &&
+                (ctx.subagentId || ctx.metadata?.subagentId))
+                return 'Subagents cannot create background terminals. Run foreground shell exec work within this turn or report the blocker to the parent agent.';
+            const cwd = typeof input.cwd === 'string'
+                ? (await env.resolvePath(input.cwd, { mustExist: true })).resolvedPath
+                : undefined;
+            const environment = await options.hooks?.resolveEnv?.(ctx);
+            if (action === 'terminal_create') {
+                const info = await backend.create({
+                    command,
+                    cwd,
+                    env: environment,
+                    name: input.name,
+                    notifyOnExit: input.notifyOnExit !== false,
+                });
+                return `Terminal created\n  ID: ${info.id}\n  Name: ${info.name || '(unnamed)'}\n  Status: ${wireStatus(info.status)}${info.command ? `\n  Command: ${info.command}` : ''}`;
+            }
+            if (input.timeout !== undefined &&
+                (typeof input.timeout !== 'number' ||
+                    !Number.isFinite(input.timeout) ||
+                    input.timeout < 0))
+                return 'Error: timeout must be a finite, non-negative number of seconds';
+            // The production contract treats zero as the default foreground wait.
+            const seconds = input.timeout || 30;
+            const timeoutMs = Math.min(Math.trunc(seconds * 1000), 2 ** 31 - 1);
+            const started = Date.now();
+            const result = backend
+                ? await backend.execWithHandoff({
+                    command,
+                    cwd,
+                    env: environment,
+                    handoffAfterMs: timeoutMs,
+                    signal: ctx.signal,
+                    maxOutputBytes: options.maxOutputBytes,
+                })
+                : await env.exec(command, {
+                    cwd,
+                    env: environment,
+                    timeoutMs,
+                    signal: ctx.signal,
+                    maxOutputBytes: options.maxOutputBytes,
+                });
+            if ('completed' in result && !result.completed) {
+                const id = result.terminal.id;
+                const reason = (result.handoffReason ??
+                    (ctx.signal?.aborted ? 'abort' : 'timeout')) === 'abort'
+                    ? 'Foreground turn ended'
+                    : `Command timed out after ${seconds}s`;
+                let out = `${reason} — process still running in background.\nTerminal ID: ${id}\n`;
+                if (result.partialOutput)
+                    out += `\nPartial output so far:\n${result.partialOutput.length > 2000 ? result.partialOutput.substring(0, 2000) + '\n... (truncated)' : result.partialOutput}\n`;
+                out += `\nUse terminal_read with id="${id}" to check progress.`;
+                out += `\nUse terminal_signal with id="${id}" to send signals (SIGINT/SIGTERM/SIGKILL).`;
+                out += `\nUse terminal_destroy with id="${id}" to clean up when done.`;
+                return out;
+            }
+            let out = `$ ${command}${input.cwd ? ` (cwd: ${input.cwd})` : ''}\n---\n`;
+            const stdout = result.stdout ?? result.output, stderr = result.stderr;
+            if (stdout)
+                out += stdout + '\n';
+            if (stderr)
+                out += `[stderr] ${stderr}\n`;
+            if (result.spillPath)
+                out += `[Full output: ${result.spillPath}]\n`;
+            const exitCode = signalExitCode(result.exitCode, result.signal);
+            out += `---\nexit_code: ${exitCode}, duration: ${result.durationMs ?? Date.now() - started}ms`;
+            const guidance = exitCode === 0
+                ? await options.hooks?.afterExec?.({
+                    command,
+                    cwd,
+                    exitCode,
+                    context: ctx,
+                })
+                : undefined;
+            return guidance ? { content: out, guidance } : out;
+        },
+    });
+}

package/dist/core/tools/write.d.ts

@@ -0,0 +1,4 @@
+import type { ExecutionEnv } from '../env.js';
+import type { FourTool } from '../types.js';
+import { type FileToolOptions } from './shared.js';
+export declare function createWriteTool(env: ExecutionEnv, options?: FileToolOptions): FourTool;

package/dist/core/tools/write.js

@@ -0,0 +1,33 @@
+import { toolContracts } from '../contracts.js';
+import { defaultMutationQueue } from '../mutation-queue.js';
+import { aliases, safe, text } from './shared.js';
+export function createWriteTool(env, options = {}) {
+    return safe({
+        name: 'write',
+        ...structuredClone(toolContracts.write),
+        concurrency: 'parallel',
+        async execute(raw, ctx = {}) {
+            ctx.signal?.throwIfAborted();
+            const input = aliases(raw), content = text(input, 'content');
+            let displayPath = text(input, 'path');
+            const path = await env.resolvePath(displayPath);
+            if (displayPath === '~' || displayPath.startsWith('~/'))
+                displayPath = path.resolvedPath;
+            return (options.queue ?? defaultMutationQueue).run(env.id, path.canonicalPath, async () => {
+                await env.writeText(path.resolvedPath, content, {
+                    signal: ctx.signal,
+                });
+                const message = `File written: ${displayPath} (${content.length} chars)`;
+                const guidance = await options.hooks?.afterMutate?.({
+                    path: path.resolvedPath,
+                    canonicalPath: path.canonicalPath,
+                    operation: 'write',
+                    charCount: content.length,
+                    content: content,
+                    context: ctx,
+                });
+                return guidance ? { content: message, guidance } : message;
+            }, ctx.signal);
+        },
+    });
+}

package/dist/core/types.d.ts

@@ -0,0 +1,65 @@
+/** Mirrors the public ai/protocol contract without a runtime or type dependency. */
+export type Guidance = string | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'tool_loop_warning';
+    warningType: string;
+    toolName: string;
+    count: number;
+    message?: string;
+};
+export interface FourToolContext {
+    signal?: AbortSignal;
+    workspaceId?: string;
+    teamId?: string;
+    model?: string;
+    subagentId?: string;
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    turnId?: string;
+    toolCallId?: string;
+    aiPostContext?: Guidance[];
+}
+export type FourToolResult = string | {
+    content: string;
+    guidance?: Guidance[];
+};
+/** Hosts using a string-only tool bridge receive guidance via aiPostContext. */
+export interface NativeToolContext extends FourToolContext {
+    workspaceId: string;
+    teamId: string;
+    model: string;
+}
+export interface FourTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    concurrency?: 'parallel' | 'serial' | 'deferred';
+    execute(input: Record<string, unknown>, ctx: NativeToolContext): Promise<string>;
+    execute(input: Record<string, unknown>, ctx?: FourToolContext): Promise<FourToolResult>;
+}
+export interface MutationEvent {
+    path: string;
+    canonicalPath: string;
+    operation: 'write' | 'edit';
+    context: FourToolContext;
+    charCount?: number;
+    content?: string;
+}
+export interface ToolHooks {
+    afterRead?: (event: {
+        path: string;
+        canonicalPath: string;
+        content?: string;
+        context: FourToolContext;
+    }) => void | Guidance[] | Promise<void | Guidance[]>;
+    afterExec?: (event: {
+        command: string;
+        cwd?: string;
+        exitCode: number;
+        context: FourToolContext;
+    }) => void | Guidance[] | Promise<void | Guidance[]>;
+    afterMutate?: (event: MutationEvent) => void | Guidance[] | Promise<void | Guidance[]>;
+    resolveEnv?: (ctx: FourToolContext) => Record<string, string> | Promise<Record<string, string>>;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './core/index.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './core/index.js';

package/dist/node/index.d.ts

@@ -0,0 +1,16 @@
+export * from './posix-env.js';
+export * from './terminal-manager.js';
+export { signalProcessGroup } from './process-group.js';
+import { PosixNodeExecutionEnv, type NodeEnvOptions } from './posix-env.js';
+import { type FourToolsOptions, type FourTool } from '../index.js';
+export type NodeFourToolsOptions = NodeEnvOptions & FourToolsOptions;
+export declare function createNodeEnv(options?: NodeEnvOptions): PosixNodeExecutionEnv;
+export declare function createNodeFourTools(options?: NodeFourToolsOptions): {
+    env: PosixNodeExecutionEnv;
+    tools: FourTool[];
+};
+export type NodeTools = FourTool[] & {
+    env: PosixNodeExecutionEnv;
+    dispose(): Promise<void>;
+};
+export declare function createNodeTools(options?: NodeFourToolsOptions): NodeTools;

package/dist/node/index.js

@@ -0,0 +1,16 @@
+export * from './posix-env.js';
+export * from './terminal-manager.js';
+export { signalProcessGroup } from './process-group.js';
+import { PosixNodeExecutionEnv } from './posix-env.js';
+import { createFourTools, } from '../index.js';
+export function createNodeEnv(options = {}) {
+    return new PosixNodeExecutionEnv(options);
+}
+export function createNodeFourTools(options = {}) {
+    const env = createNodeEnv(options);
+    return { env, tools: createFourTools(env, options) };
+}
+export function createNodeTools(options = {}) {
+    const { env, tools } = createNodeFourTools(options);
+    return Object.assign(tools, { env, dispose: () => env.dispose() });
+}

package/dist/node/posix-env.d.ts

@@ -0,0 +1,46 @@
+import type { ExecutionEnv, Platform, FileStat, ExecOptions, ExecResult, TerminalExitEvent } from '../core/env.js';
+import { readRange } from './read-range.js';
+import { PosixTerminalManager } from './terminal-manager.js';
+export interface NodeEnvOptions {
+    id?: string;
+    cwd?: string;
+    homeDir?: string;
+    platform?: string;
+    shellPath?: string;
+    spillDir?: string;
+    terminalDir?: string;
+    terminals?: boolean;
+    onTerminalExit?: (event: TerminalExitEvent) => void | Promise<void>;
+    onTerminalError?: (error: unknown) => void;
+}
+export declare class PosixNodeExecutionEnv implements ExecutionEnv {
+    readonly id: string;
+    readonly platform: Platform;
+    readonly cwd: string;
+    readonly homeDir: string;
+    readonly spillDir: string;
+    readonly terminals?: PosixTerminalManager;
+    private readonly shellPath?;
+    constructor(options?: NodeEnvOptions);
+    getShell(): Promise<string>;
+    resolvePath(inputPath: string, options?: {
+        cwd?: string;
+        mustExist?: boolean;
+    }): Promise<{
+        resolvedPath: string;
+        canonicalPath: string;
+    }>;
+    stat(file: string): Promise<FileStat>;
+    readRange: typeof readRange;
+    readText(file: string, options?: {
+        maxBytes?: number;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    writeText(file: string, content: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        bytesWritten: number;
+    }>;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    dispose(): Promise<void>;
+}

package/dist/node/posix-env.js

@@ -0,0 +1,239 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import * as path from 'node:path/posix';
+import * as os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { readRange } from './read-range.js';
+import { startProcess } from './process-runner.js';
+import { PosixTerminalManager } from './terminal-manager.js';
+function missing(error) {
+    return ['ENOENT', 'ENOTDIR'].includes(error.code ?? '');
+}
+async function exists(file) {
+    try {
+        await fs.lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
+}
+async function canonical(file) {
+    try {
+        return await fs.realpath(file);
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+        // A dangling symlink still identifies its future target, not the symlink itself.
+        try {
+            const stat = await fs.lstat(file);
+            if (stat.isSymbolicLink())
+                return canonical(path.resolve(path.dirname(file), await fs.readlink(file)));
+        }
+        catch (e) {
+            if (!missing(e))
+                throw e;
+        }
+        const parent = path.dirname(file);
+        if (parent === file)
+            throw error;
+        return path.join(await canonical(parent), path.basename(file));
+    }
+}
+const variantKey = (value) => value
+    .normalize('NFC')
+    .replace(/\u202F/g, ' ')
+    .replace(/\u2019/g, "'");
+export class PosixNodeExecutionEnv {
+    id;
+    platform;
+    cwd;
+    homeDir;
+    spillDir;
+    terminals;
+    shellPath;
+    constructor(options = {}) {
+        const platform = options.platform ?? process.platform;
+        if (platform !== 'linux' && platform !== 'darwin')
+            throw new Error(`Unsupported platform: ${platform}; expected linux or darwin`);
+        this.platform = platform;
+        this.id = options.id ?? randomUUID();
+        this.cwd = path.resolve(options.cwd ?? process.cwd());
+        this.homeDir = options.homeDir ?? os.homedir();
+        this.spillDir =
+            options.spillDir ?? path.join(os.tmpdir(), `four-tools-${this.id}`);
+        this.shellPath = options.shellPath;
+        if (options.terminals !== false)
+            this.terminals = new PosixTerminalManager({
+                cwd: this.cwd,
+                platform,
+                terminalDir: options.terminalDir ?? path.join(this.spillDir, 'terminals'),
+                shell: () => this.getShell(),
+                onExit: options.onTerminalExit,
+                onError: options.onTerminalError,
+            });
+    }
+    async getShell() {
+        if (this.shellPath) {
+            await fs.access(this.shellPath, constants.X_OK);
+            return this.shellPath;
+        }
+        for (const shell of [
+            '/bin/bash',
+            ...(this.platform === 'darwin' ? ['/bin/zsh'] : []),
+            '/bin/sh',
+        ]) {
+            try {
+                await fs.access(shell, constants.X_OK);
+                return shell;
+            }
+            catch {
+                /* Probe the next POSIX shell. */
+            }
+        }
+        throw new Error('No executable POSIX shell found');
+    }
+    async resolvePath(inputPath, options = {}) {
+        const expand = (value) => path.resolve(options.cwd ?? this.cwd, value === '~'
+            ? this.homeDir
+            : value.startsWith('~/')
+                ? path.join(this.homeDir, value.slice(2))
+                : value);
+        let resolvedPath = expand(inputPath);
+        if (inputPath.startsWith('@') && !(await exists(resolvedPath)))
+            resolvedPath = expand(inputPath.slice(1));
+        if (options.mustExist && !(await exists(resolvedPath))) {
+            const names = await fs.readdir(path.dirname(resolvedPath));
+            const candidates = names.filter((name) => variantKey(name) === variantKey(path.basename(resolvedPath)));
+            if (candidates.length > 1)
+                throw new Error(`Ambiguous filename: ${inputPath}`);
+            if (!candidates.length)
+                throw new Error(`File not found: ${inputPath}`);
+            resolvedPath = path.join(path.dirname(resolvedPath), candidates[0]);
+        }
+        return { resolvedPath, canonicalPath: await canonical(resolvedPath) };
+    }
+    async stat(file) {
+        try {
+            const s = await fs.lstat(file);
+            return {
+                exists: true,
+                isDirectory: s.isDirectory(),
+                isSymbolicLink: s.isSymbolicLink(),
+                size: s.size,
+                mode: s.mode,
+                mtimeMs: s.mtimeMs,
+            };
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+            return {
+                exists: false,
+                isDirectory: false,
+                isSymbolicLink: false,
+                size: 0,
+                mode: 0,
+                mtimeMs: 0,
+            };
+        }
+    }
+    readRange = readRange;
+    async readText(file, options = {}) {
+        options.signal?.throwIfAborted();
+        const max = options.maxBytes ?? 16 * 1024 * 1024;
+        const handle = await fs.open(file, 'r');
+        try {
+            const parts = [];
+            let size = 0;
+            for (;;) {
+                options.signal?.throwIfAborted();
+                const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, max - size + 1));
+                const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+                if (!bytesRead)
+                    break;
+                size += bytesRead;
+                if (size > max)
+                    throw new Error(`File exceeds readText maxBytes (${max})`);
+                parts.push(chunk.subarray(0, bytesRead));
+            }
+            return Buffer.concat(parts, size).toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async writeText(file, content, options = {}) {
+        options.signal?.throwIfAborted();
+        const actualWritePath = await canonical(file);
+        await fs.mkdir(path.dirname(actualWritePath), { recursive: true });
+        let existingMode;
+        try {
+            existingMode = (await fs.stat(actualWritePath)).mode & 0o7777;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const tmpPath = path.join(path.dirname(actualWritePath), `.four-tools-${process.pid}-${randomUUID()}.tmp`);
+        const data = Buffer.from(content, 'utf8');
+        try {
+            const handle = await fs.open(tmpPath, 'wx', 0o666);
+            try {
+                await handle.writeFile(data, { signal: options.signal });
+                if (existingMode !== undefined)
+                    await handle.chmod(existingMode);
+                await handle.datasync();
+            }
+            finally {
+                await handle.close();
+            }
+            options.signal?.throwIfAborted();
+            try {
+                await fs.rename(tmpPath, actualWritePath);
+            }
+            catch (error) {
+                if (!['EXDEV', 'EACCES', 'EPERM'].includes(error.code ?? ''))
+                    throw error;
+                await fs.unlink(tmpPath);
+                await fs.writeFile(actualWritePath, data, {
+                    signal: options.signal,
+                    mode: existingMode ?? 0o666,
+                });
+                if (existingMode !== undefined)
+                    await fs.chmod(actualWritePath, existingMode);
+            }
+        }
+        catch (error) {
+            await fs.unlink(tmpPath).catch(() => { });
+            throw error;
+        }
+        return { bytesWritten: data.length };
+    }
+    async exec(command, options = {}) {
+        const running = await startProcess({
+            command,
+            cwd: options.cwd ?? this.cwd,
+            shell: await this.getShell(),
+            platform: this.platform,
+            logDir: this.spillDir,
+            options: { ...options, timeoutMs: options.timeoutMs ?? 30_000 },
+        });
+        try {
+            const result = await running.done;
+            if (!result.truncated)
+                await fs.unlink(running.logPath);
+            return result;
+        }
+        catch (error) {
+            await fs.unlink(running.logPath).catch(() => { });
+            throw error;
+        }
+    }
+    async dispose() {
+        await this.terminals?.dispose();
+    }
+}

package/dist/node/process-group.d.ts

@@ -0,0 +1,2 @@
+import type { Platform } from '../core/env.js';
+export declare function signalProcessGroup(pid: number, signal: NodeJS.Signals, platform: Platform): void;

package/dist/node/process-group.js

@@ -0,0 +1,30 @@
+export function signalProcessGroup(pid, signal, platform) {
+    const send = (sig) => {
+        try {
+            process.kill(-pid, sig);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ESRCH' && code !== 'EPERM')
+                throw error;
+            try {
+                process.kill(pid, sig);
+            }
+            catch (fallback) {
+                if (fallback.code !== 'ESRCH')
+                    throw fallback;
+            }
+        }
+    };
+    if (signal === 'SIGKILL' && platform === 'darwin') {
+        send('SIGSTOP');
+        try {
+            send('SIGKILL');
+        }
+        finally {
+            send('SIGCONT');
+        }
+    }
+    else
+        send(signal);
+}

package/dist/node/process-runner.d.ts

@@ -0,0 +1,43 @@
+import { type ChildProcess } from 'node:child_process';
+import type { ExecResult, ExecOptions, Platform } from '../core/env.js';
+export declare class OutputBuffer {
+    private head;
+    private tail;
+    total: number;
+    readonly max: number;
+    private readonly headMax;
+    constructor(max?: number);
+    add(chunk: Buffer): void;
+    get truncated(): boolean;
+    get text(): string;
+}
+export interface RunningProcess {
+    child: ChildProcess;
+    output: OutputBuffer;
+    logPath: string;
+    done: Promise<ExecResult>;
+    kill(signal?: NodeJS.Signals): void;
+}
+export declare function startProcess(input: {
+    command: string;
+    cwd: string;
+    shell: string;
+    platform: Platform;
+    logDir: string;
+    logId?: string;
+    options?: ExecOptions;
+}): Promise<RunningProcess>;
+/** Managed groups inherit regular log FDs; descendant output survives shell exit. */
+export interface ManagedProcess extends Omit<RunningProcess, 'output'> {
+    snapshot(): Promise<OutputBuffer>;
+    groupAlive(): boolean;
+}
+export declare function startManagedProcess(input: {
+    command: string;
+    cwd: string;
+    shell: string;
+    platform: Platform;
+    logDir: string;
+    logId: string;
+    options?: ExecOptions;
+}): Promise<ManagedProcess>;