@abot-ai/runtime 1.3.0 → 1.3.1

package/dist/scripts/init-runtime.js

@@ -1,7 +1,8 @@
 import { constants } from "node:fs";
 import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { initializeConfiguredRuntimeDirectories } from "./runtime-setup-directories.js";
 import { buildModelConfig, buildProviderConfig, DEFAULT_ROOT_RESPONSE_METHODOLOGY_FILES, isRecord, parseBaseUrl, parseProvider, readJsonObject, resolveRuntimePackageRoot, writeJsonObject, } from "./runtime-setup-files.js";
 import { getInitNextSteps, getInitUsage, } from "./runtime-setup-presentation.js";
 const ENV_FILE = ".env";
@@ -13,16 +14,6 @@ const CONFIG_EXAMPLE_FILE = join("examples", "runtime.config.example.json");
 const REQUEST_RUNNER_CONFIG_EXAMPLE_FILE = join("examples", "request-runner.config.example.json");
 const MODEL_CONFIG_EXAMPLE_FILE = join("examples", "models", "default.config.json");
 const REQUIRED_ENV_LINE = "LLM_RUNTIME_CONFIG_FILE=local/runtime.config.json";
-const RUNTIME_DIRS = [
-    join(".runtime", "compiled"),
-    join(".runtime", "shared", "logs"),
-    join(".runtime", "prod"),
-    join(".runtime", "prod", "sandbox"),
-    join(".runtime", "prod", "sessions"),
-    join(".runtime", "dev"),
-    join(".runtime", "dev", "sandbox"),
-    join(".runtime", "dev", "sessions"),
-];
 function requireValue(argv, index, flag) {
     const value = argv[index + 1]?.trim();
     if (!value || value.startsWith("--")) {
@@ -238,7 +229,7 @@ export async function runInitRuntime(argv = process.argv.slice(2), runOptions =
     if (modelConfigStatus !== "kept") {
         await configureModelProfile(modelConfigPath, options.provider, options.model);
     }
-    await Promise.all(RUNTIME_DIRS.map((runtimeDir) => mkdir(join(options.rootDir, runtimeDir), { recursive: true })));
+    const runtimeDirectories = await initializeConfiguredRuntimeDirectories(options.rootDir, configPath);
     console.log([
         "abot initialized",
         `root: ${options.rootDir}`,
@@ -250,7 +241,7 @@ export async function runInitRuntime(argv = process.argv.slice(2), runOptions =
         `${LOCAL_REQUEST_RUNNER_CONFIG_FILE}: ${requestRunnerConfigStatus}`,
         `${LOCAL_MODEL_CONFIG_FILE}: ${modelConfigStatus}`,
         ...methodologyStatuses.map(({ relativePath, status }) => `${relativePath}: ${status}`),
-        "created runtime directories: .runtime/compiled, .runtime/shared/logs, .runtime/prod, .runtime/dev",
+        `initialized runtime directories: ${runtimeDirectories.map((directory) => relative(options.rootDir, directory) || ".").join(", ")}`,
         "",
         ...getInitNextSteps(commandMode),
     ].join("\n"));

package/dist/scripts/runtime-setup-directories.d.ts

@@ -0,0 +1,2 @@
+/** Initialize the preserved configuration's output roots without moving existing state. */
+export declare function initializeConfiguredRuntimeDirectories(rootDir: string, configPath: string): Promise<string[]>;

package/dist/scripts/runtime-setup-directories.js

@@ -0,0 +1,38 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { loadRuntimeConfig } from "../src/runtime/config.js";
+import { RUNTIME_LOGS_DIR_NAME } from "../src/runtime/config/layout.js";
+import { isRecord, readJsonObject, } from "./runtime-setup-files.js";
+function configuredEnvironmentIds(config) {
+    if (!isRecord(config.environment))
+        return [undefined];
+    if (!isRecord(config.environment.profiles))
+        return [undefined];
+    const profileIds = Object.keys(config.environment.profiles);
+    const hasConfiguredEnvironments = profileIds.length > 0;
+    return hasConfiguredEnvironments ? profileIds : [undefined];
+}
+function runtimeOwnedDirectories(paths) {
+    return [
+        paths.runtimeDir,
+        paths.agentWorkDir,
+        paths.sessionsDir,
+        paths.attachmentsDir,
+        paths.sharedDir,
+        paths.compiledDir,
+        dirname(paths.traceFile),
+        join(paths.sharedDir, RUNTIME_LOGS_DIR_NAME),
+    ];
+}
+/** Initialize the preserved configuration's output roots without moving existing state. */
+export async function initializeConfiguredRuntimeDirectories(rootDir, configPath) {
+    const config = await readJsonObject(configPath);
+    // Resolve every environment before creating any directories. This preserves the
+    // canonical guard against silently reassigning existing shared runtime state.
+    const configurations = configuredEnvironmentIds(config).map((profileId) => loadRuntimeConfig({ rootDir, configPath, profileId }));
+    const directories = [
+        ...new Set(configurations.flatMap(({ paths }) => runtimeOwnedDirectories(paths))),
+    ];
+    await Promise.all(directories.map((directory) => mkdir(directory, { recursive: true })));
+    return directories;
+}

package/dist/src/shared/directory-authority/bootstrap.d.ts

@@ -0,0 +1 @@
+export declare function directoryAuthorityScript(mode: "task" | "command", messageLimit: number, task?: (input: never) => unknown): string;

package/dist/src/shared/directory-authority/bootstrap.js

@@ -0,0 +1,118 @@
+/**
+ * This function is serialized into a fresh Node process. It must remain
+ * closure-free and use only node: built-ins; the starting cwd is untrusted
+ * until its identity has been compared with the inherited directory handle.
+ */
+function directoryAuthorityBootstrap(mode, messageLimit, task) {
+    const fs = require("node:fs");
+    function fail(code, message) {
+        throw Object.assign(new Error(message), { code });
+    }
+    function verifyDirectoryAuthority() {
+        const expected = fs.fstatSync(3, { bigint: true });
+        const actual = fs.statSync(".", { bigint: true });
+        const matchesHeldDirectory = expected.isDirectory() &&
+            actual.isDirectory() &&
+            expected.dev === actual.dev &&
+            expected.ino === actual.ino;
+        if (matchesHeldDirectory)
+            return;
+        fail("directory_authority_changed", "The directory changed before the operation could establish its authority.");
+    }
+    function readRequest() {
+        const fd = mode === "task" ? 0 : 4;
+        const chunk = Buffer.alloc(64 * 1024);
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const length = fs.readSync(fd, chunk, 0, chunk.length, null);
+            if (length === 0)
+                break;
+            total += length;
+            if (total > messageLimit) {
+                fail("directory_authority_request_too_large", "The directory operation input exceeds the bridge byte limit.");
+            }
+            chunks.push(Buffer.from(chunk.subarray(0, length)));
+        }
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    function reportFailure(error) {
+        const detail = error;
+        const code = typeof detail?.code === "string"
+            ? detail.code.slice(0, 256)
+            : "directory_authority_failed";
+        const message = typeof detail?.message === "string"
+            ? detail.message.slice(0, 4096)
+            : "The directory operation failed.";
+        let encoded;
+        try {
+            encoded = JSON.stringify({
+                ok: false,
+                error: { code, message, data: detail?.data },
+            });
+            if (Buffer.byteLength(encoded) > messageLimit)
+                throw new Error();
+        }
+        catch {
+            encoded = JSON.stringify({ ok: false, error: { code, message } });
+        }
+        writeResponse(mode === "task" ? 1 : 2, encoded);
+        process.exitCode = mode === "task" ? 0 : 125;
+    }
+    function writeResponse(fd, encoded) {
+        const bytes = Buffer.from(encoded);
+        let offset = 0;
+        while (offset < bytes.length) {
+            offset += fs.writeSync(fd, bytes, offset, bytes.length - offset);
+        }
+    }
+    async function runTask(input) {
+        if (!task)
+            fail("directory_authority_failed", "The directory task is missing.");
+        const result = await task(input);
+        const encoded = JSON.stringify({ ok: true, result });
+        if (Buffer.byteLength(encoded) > messageLimit) {
+            fail("directory_authority_result_too_large", "The directory operation result exceeds the bridge byte limit.");
+        }
+        writeResponse(1, encoded);
+    }
+    function runCommand(input) {
+        const { spawn } = require("node:child_process");
+        const command = input;
+        // Omitting cwd inherits the kernel-pinned authority. Resolving cwd() back
+        // into a pathname here would reopen the race this bridge prevents.
+        const child = spawn(command.command, command.args, {
+            stdio: ["ignore", "inherit", "inherit"],
+            env: process.env,
+        });
+        child.once("error", reportFailure);
+        child.once("exit", (code, signal) => {
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            if (typeof code === "number")
+                process.exitCode = code;
+        });
+    }
+    try {
+        verifyDirectoryAuthority();
+        const input = readRequest();
+        if (mode === "command") {
+            runCommand(input);
+            return;
+        }
+        void runTask(input).catch(reportFailure);
+    }
+    catch (error) {
+        reportFailure(error);
+    }
+}
+export function directoryAuthorityScript(mode, messageLimit, task) {
+    const taskSource = task ? `(${task.toString()})` : "undefined";
+    // tsx preserves nested function names with esbuild's __name annotation.
+    // Include that annotation's definition so the same trusted task works in
+    // development and in the production bundle without rewriting its source.
+    const preserveFunctionName = "const __name=(target,value)=>Object.defineProperty(target,'name',{value,configurable:true});";
+    return `${preserveFunctionName}(${directoryAuthorityBootstrap.toString()})(${JSON.stringify(mode)},${messageLimit},${taskSource});`;
+}

package/dist/src/shared/directory-authority/command.d.ts

@@ -0,0 +1,8 @@
+import { type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+import { type DirectoryAuthorityLocation } from "./protocol.js";
+export declare function spawnDirectoryAuthorityCommand(input: DirectoryAuthorityLocation & Readonly<{
+    command: string;
+    args: readonly string[];
+    env?: NodeJS.ProcessEnv;
+}>): ChildProcessByStdio<null, Readable, Readable>;

package/dist/src/shared/directory-authority/command.js

@@ -0,0 +1,27 @@
+import { spawn } from "node:child_process";
+import { directoryAuthorityScript } from "./bootstrap.js";
+import { assertDirectoryAuthorityLocation, authorityEnvironment, AUTHORITY_MESSAGE_LIMIT, encodeAuthorityRequest, } from "./protocol.js";
+export function spawnDirectoryAuthorityCommand(input) {
+    assertDirectoryAuthorityLocation(input);
+    const request = encodeAuthorityRequest({
+        command: input.command,
+        args: input.args,
+    });
+    const child = spawn(process.execPath, [
+        "--input-type=commonjs",
+        "-e",
+        directoryAuthorityScript("command", AUTHORITY_MESSAGE_LIMIT),
+    ], {
+        cwd: input.directoryPath,
+        env: authorityEnvironment(input.env),
+        detached: true,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe", input.directoryFd, "pipe"],
+    });
+    const requestPipe = child.stdio[4];
+    // An early authority failure may close the request pipe before the parent
+    // finishes writing. The process result remains the authoritative error.
+    requestPipe?.on("error", () => undefined);
+    requestPipe?.end(request);
+    return child;
+}

package/dist/src/shared/directory-authority/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class DirectoryAuthorityError extends Error {
+    readonly code: string;
+    readonly data?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: string, message: string, data?: Readonly<Record<string, unknown>> | undefined);
+}

package/dist/src/shared/directory-authority/errors.js

@@ -0,0 +1,10 @@
+export class DirectoryAuthorityError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "DirectoryAuthorityError";
+    }
+}

package/dist/src/shared/directory-authority/index.d.ts

@@ -0,0 +1,3 @@
+export { spawnDirectoryAuthorityCommand } from "./command.js";
+export { DirectoryAuthorityError } from "./errors.js";
+export { runDirectoryAuthorityTask } from "./task.js";

package/dist/src/shared/directory-authority/index.js

@@ -0,0 +1,3 @@
+export { spawnDirectoryAuthorityCommand } from "./command.js";
+export { DirectoryAuthorityError } from "./errors.js";
+export { runDirectoryAuthorityTask } from "./task.js";

package/dist/src/shared/directory-authority/protocol.d.ts

@@ -0,0 +1,11 @@
+export declare const AUTHORITY_MESSAGE_LIMIT: number;
+export declare const AUTHORITY_STDERR_LIMIT: number;
+export declare const AUTHORITY_TASK_TIMEOUT_MS = 30000;
+export type DirectoryAuthorityLocation = Readonly<{
+    directoryPath: string;
+    directoryFd: number;
+}>;
+export declare function assertDirectoryAuthorityLocation(location: DirectoryAuthorityLocation): void;
+export declare function authorityEnvironment(environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function encodeAuthorityRequest(input: unknown): string;
+export declare function decodeAuthorityResult<Result>(output: string): Result;

package/dist/src/shared/directory-authority/protocol.js

@@ -0,0 +1,62 @@
+import { isAbsolute } from "node:path";
+import { DirectoryAuthorityError } from "./errors.js";
+export const AUTHORITY_MESSAGE_LIMIT = 8 * 1024 * 1024;
+export const AUTHORITY_STDERR_LIMIT = 16 * 1024;
+export const AUTHORITY_TASK_TIMEOUT_MS = 30_000;
+export function assertDirectoryAuthorityLocation(location) {
+    if (!isAbsolute(location.directoryPath)) {
+        throw new DirectoryAuthorityError("directory_authority_invalid_path", "The directory authority requires an absolute starting path.");
+    }
+    const hasOpenDescriptorNumber = Number.isInteger(location.directoryFd) && location.directoryFd >= 0;
+    if (hasOpenDescriptorNumber)
+        return;
+    throw new DirectoryAuthorityError("directory_authority_invalid_fd", "The directory authority requires an open directory descriptor.");
+}
+export function authorityEnvironment(environment = process.env) {
+    const sanitized = { ...environment };
+    delete sanitized.NODE_OPTIONS;
+    delete sanitized.NODE_PATH;
+    return sanitized;
+}
+export function encodeAuthorityRequest(input) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(input);
+    }
+    catch {
+        throw new DirectoryAuthorityError("directory_authority_invalid_request", "The directory operation input must be JSON serializable.");
+    }
+    if (encoded === undefined) {
+        throw new DirectoryAuthorityError("directory_authority_invalid_request", "The directory operation input must be JSON serializable.");
+    }
+    if (Buffer.byteLength(encoded) <= AUTHORITY_MESSAGE_LIMIT)
+        return encoded;
+    throw new DirectoryAuthorityError("directory_authority_request_too_large", "The directory operation input exceeds the bridge byte limit.");
+}
+function isAuthorityMessageObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function decodeAuthorityResult(output) {
+    let message;
+    try {
+        message = JSON.parse(output);
+    }
+    catch {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid response.");
+    }
+    if (!isAuthorityMessageObject(message)) {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid response.");
+    }
+    if (message.ok === true)
+        return message.result;
+    const hasAuthorityError = message.ok === false && isAuthorityMessageObject(message.error);
+    if (!hasAuthorityError) {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid response.");
+    }
+    const { code, message: explanation, data, } = message.error;
+    const hasErrorDescription = typeof code === "string" && typeof explanation === "string";
+    if (!hasErrorDescription) {
+        throw new DirectoryAuthorityError("directory_authority_protocol_error", "The directory operation returned an invalid error response.");
+    }
+    throw new DirectoryAuthorityError(code, explanation, isAuthorityMessageObject(data) ? data : undefined);
+}

package/dist/src/shared/directory-authority/task.d.ts

@@ -0,0 +1,7 @@
+import { type DirectoryAuthorityLocation } from "./protocol.js";
+export declare function runDirectoryAuthorityTask<Input, Result>(input: DirectoryAuthorityLocation & Readonly<{
+    input: Input;
+    task: (input: Input) => Result | Promise<Result>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}>): Promise<Result>;

package/dist/src/shared/directory-authority/task.js

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import { directoryAuthorityScript } from "./bootstrap.js";
+import { DirectoryAuthorityError } from "./errors.js";
+import { assertDirectoryAuthorityLocation, authorityEnvironment, AUTHORITY_MESSAGE_LIMIT, AUTHORITY_STDERR_LIMIT, AUTHORITY_TASK_TIMEOUT_MS, decodeAuthorityResult, encodeAuthorityRequest, } from "./protocol.js";
+export async function runDirectoryAuthorityTask(input) {
+    assertDirectoryAuthorityLocation(input);
+    const request = encodeAuthorityRequest(input.input);
+    const timeoutMs = input.timeoutMs ?? AUTHORITY_TASK_TIMEOUT_MS;
+    const hasPositiveDeadline = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    if (!hasPositiveDeadline) {
+        throw new DirectoryAuthorityError("directory_authority_invalid_timeout", "The directory operation deadline must be a positive finite duration.");
+    }
+    if (input.signal?.aborted) {
+        throw new DirectoryAuthorityError("directory_authority_aborted", "The directory operation was cancelled before it started.");
+    }
+    const child = spawn(process.execPath, [
+        "--input-type=commonjs",
+        "-e",
+        directoryAuthorityScript("task", AUTHORITY_MESSAGE_LIMIT, input.task),
+    ], {
+        cwd: input.directoryPath,
+        env: authorityEnvironment(),
+        detached: true,
+        windowsHide: true,
+        stdio: ["pipe", "pipe", "pipe", input.directoryFd],
+    });
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const stderrChunks = [];
+        let bytes = 0;
+        let stderrBytes = 0;
+        let failure;
+        const stop = (error) => {
+            if (failure)
+                return;
+            failure = error;
+            if (typeof child.pid === "number") {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                    return;
+                }
+                catch {
+                    // A process which has already exited may no longer own its group.
+                }
+            }
+            child.kill("SIGKILL");
+        };
+        const onAbort = () => stop(new DirectoryAuthorityError("directory_authority_aborted", "The directory operation was cancelled."));
+        const timer = setTimeout(() => stop(new DirectoryAuthorityError("directory_authority_timeout", "The directory operation exceeded its deadline.")), timeoutMs);
+        timer.unref();
+        input.signal?.addEventListener("abort", onAbort, { once: true });
+        if (input.signal?.aborted)
+            onAbort();
+        child.stdout.on("data", (chunk) => {
+            bytes += chunk.length;
+            if (bytes > AUTHORITY_MESSAGE_LIMIT) {
+                stop(new DirectoryAuthorityError("directory_authority_result_too_large", "The directory operation result exceeds the bridge byte limit."));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            const remaining = Math.max(AUTHORITY_STDERR_LIMIT - stderrBytes, 0);
+            if (remaining === 0)
+                return;
+            stderrChunks.push(chunk.subarray(0, remaining));
+            stderrBytes += Math.min(chunk.length, remaining);
+        });
+        child.stdin.on("error", () => undefined);
+        child.once("error", (error) => {
+            failure ??= new DirectoryAuthorityError("directory_authority_unavailable", `The directory operation could not start: ${error.message}`);
+        });
+        child.once("close", (code, signal) => {
+            clearTimeout(timer);
+            input.signal?.removeEventListener("abort", onAbort);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            if (code !== 0) {
+                reject(new DirectoryAuthorityError("directory_authority_failed", "The directory operation process did not complete successfully.", {
+                    exitCode: code,
+                    signal,
+                    stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                }));
+                return;
+            }
+            try {
+                resolve(decodeAuthorityResult(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        child.stdin.end(request);
+    });
+}

package/docs/plugins.md

@@ -300,13 +300,19 @@ Node filesystem APIs do not provide inode compare-and-swap, so a completely
 independent writer that ignores this coordination can still race in the final
 existing-file commit window. Consumers that require stronger multi-process
 coordination must place the work root behind a versioned or transactional store.
-Mutation path traversal requires Linux procfs and no-follow file-descriptor
-support. The plugin fails closed when either safety primitive is unavailable.
-
-The bundled `local-search` plugin also requires Linux procfs and no-follow
-file-descriptor support. It holds the selected file or directory through a
-stable descriptor for the complete ripgrep invocation and fails closed when
-that authority cannot be established.
+Mutation path traversal requires no-follow directory handles. On Linux the
+plugin anchors operations through procfs. On macOS an isolated Node child
+inherits the held directory handle, verifies its current directory against
+that handle, and performs basename-relative operations from the pinned current
+directory. Each descendant transition is verified before mutation. The parent
+Runtime never changes its current directory, and unavailable authority fails
+closed. Directory inspection uses the same platform-specific authority.
+
+The bundled `local-search` plugin holds the selected file or directory through
+a stable descriptor for the complete ripgrep invocation. Linux directory
+searches use procfs; macOS searches inherit the verified current directory of
+an isolated Node child. File content searches use the held input descriptor on
+both platforms. A search fails closed when its authority cannot be established.
 
 All output and structured data must be bounded at the producer. The shared SDK
 reserves wrapper headroom by rejecting plugin results above 128 KiB before they
@@ -316,8 +322,8 @@ and rendered text. A truncated success reports machine-readable truncation
 metadata; an operation that cannot produce a truthful bounded result fails
 explicitly.
 
-The bundled `exec` plugin is intentionally a Linux-only integration with
-non-interactive `/bin/bash`. Its configured working directory is constrained to
+The bundled `exec` plugin supports Linux and macOS with non-interactive
+`/bin/bash`. Commands must use utilities available on the host. Its configured working directory is constrained to
 agent-work or workspace roots, but the shell runs with the Runtime process
 permissions and is not an operating-system sandbox.
 

package/package.json

@@ -174,5 +174,5 @@
   },
   "type": "module",
   "types": "./dist/src/runtime/index.d.ts",
-  "version": "1.3.0"
+  "version": "1.3.1"
 }

package/plugins/exec/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "exec",
   "version": "1.0.0",
-  "description": "Execute, observe, and cancel bounded non-interactive Linux /bin/bash processes.",
+  "description": "Execute, observe, and cancel bounded non-interactive /bin/bash processes on Linux and macOS.",
   "extensions": {
     "ai.abot.runtime": {
       "version": 1,
@@ -19,7 +19,7 @@
       "capabilities": {
         "exec": {
           "catalogGroups": ["read", "write", "exec"],
-          "description": "Execute one bounded non-interactive Linux /bin/bash command. The explicit cwd must resolve inside agent work or the configured workspace; `.` means the agent-work root and `workspace/...` selects the workspace. The shell itself runs with the runtime process permissions and is not an operating-system sandbox. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it. Prefer dedicated inspection and file-mutation capabilities when they can express the task.",
+          "description": "Execute one bounded non-interactive /bin/bash command on Linux or macOS. The explicit cwd must resolve inside agent work or the configured workspace; `.` means the agent-work root and `workspace/...` selects the workspace. The shell itself runs with the runtime process permissions and is not an operating-system sandbox. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it. Prefer dedicated inspection and file-mutation capabilities when they can express the task.",
           "routingCapability": "filesystem_inspection",
           "developmentRoles": ["inspect", "establish", "verify", "auxiliary"],
           "eventPresentation": {
@@ -31,7 +31,7 @@
           "skills": ["exec_skill"],
           "operations": {
             "execute_command": {
-              "summary": "Execute one bounded non-interactive Linux /bin/bash command in an explicit existing agent-work or workspace directory. The cwd boundary is not an OS sandbox. Full-access availability does not authorize servers, GUI automation, installs, service changes, background work, or other sensitive effects.",
+              "summary": "Execute one bounded non-interactive /bin/bash command on Linux or macOS in an explicit existing agent-work or workspace directory. The cwd boundary is not an OS sandbox. Full-access availability does not authorize servers, GUI automation, installs, service changes, background work, or other sensitive effects.",
               "input": {
                 "type": "object",
                 "additionalProperties": false,

package/plugins/exec/skills/exec_skill/SKILL.md

@@ -1,7 +1,7 @@
 # Exec Skill
 
 - Use `exec` for narrow shell-native discovery or verification when a dedicated tool is insufficient.
-- `exec` v1 is available only on Linux with executable `/bin/bash`; it does not select a Windows shell or another fallback shell.
+- `exec` is available on Linux and macOS with executable `/bin/bash`; it does not select a Windows shell or another fallback shell. Commands must use the utilities and options available on the host.
 - Resolve `.` and ordinary relative `cwd` values from the configured agent work directory. They are never rewritten to the active Worker working directory. Use `workspace/...` only when the configured workspace is explicitly intended.
 - Always provide an explicit existing `cwd`. For an existing project, use its project path. To create a new project, use an existing parent `cwd` (normally `.`) and create the project path in the command.
 - The cwd is restricted to configured roots, but the shell runs with the runtime process permissions and is not an operating-system sandbox.

package/plugins/exec/source/process-manager.ts

@@ -1,6 +1,4 @@
 import { spawn, type ChildProcessByStdio } from "node:child_process";
-import { constants } from "node:fs";
-import { access } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import type { Readable } from "node:stream";
 import { StringDecoder } from "node:string_decoder";
@@ -8,13 +6,13 @@ import { StringDecoder } from "node:string_decoder";
 import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
 
 import { ExecPluginError } from "./errors.js";
+import { assertSupportedShell, EXEC_SHELL } from "./shell-platform.js";
 import type {
   ExecProcessSnapshot,
   ExecStreamSnapshot,
   ExecTerminationReason,
 } from "./types.js";
 
-const EXEC_SHELL = "/bin/bash";
 const COMPLETED_PROCESS_RETENTION_MS = 5 * 60_000;
 const MAX_ACTIVE_PROCESSES_PER_SCOPE = 4;
 
@@ -115,23 +113,6 @@ export type ExecProcessManager = Readonly<{
   release(processId: string, scope: string): Promise<void>;
 }>;
 
-async function assertSupportedShell(): Promise<void> {
-  if (process.platform !== "linux") {
-    throw new ExecPluginError(
-      "exec_platform_unsupported",
-      "The exec plugin v1 requires Linux and /bin/bash.",
-    );
-  }
-  try {
-    await access(EXEC_SHELL, constants.X_OK);
-  } catch {
-    throw new ExecPluginError(
-      "exec_shell_unavailable",
-      "The exec plugin cannot start because executable /bin/bash is unavailable.",
-    );
-  }
-}
-
 export function createExecProcessManager(): ExecProcessManager {
   const processes = new Map<string, ManagedExecProcess>();
 

package/plugins/exec/source/shell-platform.ts

@@ -0,0 +1,29 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+
+import { ExecPluginError } from "./errors.js";
+
+export const EXEC_SHELL = "/bin/bash";
+
+function isSupportedExecPlatform(platform: NodeJS.Platform): boolean {
+  return platform === "linux" || platform === "darwin";
+}
+
+export async function assertSupportedShell(
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  if (!isSupportedExecPlatform(platform)) {
+    throw new ExecPluginError(
+      "exec_platform_unsupported",
+      "The exec plugin requires Linux or macOS and executable /bin/bash.",
+    );
+  }
+  try {
+    await access(EXEC_SHELL, constants.X_OK);
+  } catch {
+    throw new ExecPluginError(
+      "exec_shell_unavailable",
+      "The exec plugin cannot start because executable /bin/bash is unavailable.",
+    );
+  }
+}