@sweny-ai/core 0.1.123 → 0.1.124

package/dist/agent-env.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Agent execution floor: scoped environment + SDK sandbox settings.
+ *
+ * Threat: the Claude Code subprocess runs model-chosen shell commands over
+ * attacker-influenceable input (issue bodies, alerts, fetched pages). Before
+ * this module it inherited the full `process.env` (every CI secret) and ran
+ * Bash with unrestricted network egress. Two controls live here:
+ *
+ *  1. {@link scopeAgentEnv}: the subprocess env is an allowlist, not a copy.
+ *     On by default in CI, off locally (full env, as before); see
+ *     {@link resolveEnvScope}.
+ *  2. {@link resolveAgentSandbox}: the SDK `sandbox` option is enabled with a
+ *     network allowlist and the agent's own credentials denied to sandboxed
+ *     commands. `auto` (default in CI) falls back to unsandboxed with one loud
+ *     warning when the host cannot sandbox; `strict` fails closed.
+ *
+ * Configuration (env wins over `.sweny.yml`, see `applyAgentFileConfig` in
+ * cli/config-file.ts):
+ *   SWENY_ENV_SCOPE                / env-scope                on | off (default: on in CI, off locally)
+ *   SWENY_ENV_PASSTHROUGH          / env-passthrough          extra var names ("*" = inherit all)
+ *   SWENY_SANDBOX                  / sandbox                  auto | strict | off (default: auto in CI, off locally)
+ *   SWENY_SANDBOX_ALLOWED_DOMAINS  / sandbox-allowed-domains  extra hosts for sandboxed commands
+ */
+import type { SandboxSettings } from "@anthropic-ai/claude-agent-sdk";
+import type { Logger, Skill } from "./types.js";
+/**
+ * Exact variable names always passed to the agent subprocess.
+ *
+ * Process basics (PATH, HOME, shell, temp), locale/TZ, proxy + CA settings
+ * (corporate egress), CI identity vars (no tokens), and Claude Code runtime
+ * knobs. Credentials are NOT in this list except via the ANTHROPIC_/CLAUDE_
+ * prefixes below, which the agent needs to authenticate at all.
+ */
+export declare const AGENT_ENV_ALLOWLIST: readonly string[];
+/**
+ * Prefixes always passed: locale (`LC_*`) and the agent's own backend config
+ * (`ANTHROPIC_*` incl. API key / auth token / base URL, `CLAUDE_*` incl.
+ * `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CONFIG_DIR`).
+ */
+export declare const AGENT_ENV_PREFIXES: readonly string[];
+/** The agent's own credentials. Needed by Claude Code, never by the commands it runs. */
+export declare const AGENT_AUTH_VARS: readonly string[];
+/** Split a comma/whitespace separated list, dropping empties. */
+export declare function parseList(v: string | undefined): string[];
+export interface BuildAgentEnvOpts {
+    /** Per-call names to include (a node's declared skill env vars). */
+    extraVars?: readonly string[];
+    /** Operator passthrough list (`env-passthrough`). `"*"` inherits everything. */
+    passthrough?: readonly string[];
+    logger?: Pick<Logger, "warn">;
+}
+/**
+ * Whether the agent env is scoped to the allowlist. `SWENY_ENV_SCOPE` (or the
+ * explicit value) `on|true|1` / `off|false|0` wins everywhere; otherwise on
+ * when `CI` is truthy and off locally, so local runs keep the full env that
+ * e2e/test workflows rely on (DATABASE_URL, BASE_URL, NODE_ENV, ...).
+ */
+export declare function resolveEnvScope(env: Record<string, string | undefined>, explicit?: boolean, logger?: Pick<Logger, "warn">): boolean;
+/** Max names listed in the withheld-vars warning before "and N more". */
+export declare const WITHHELD_WARNING_CAP = 30;
+/**
+ * One-line warning naming the withheld variables. Names only, never values;
+ * sorted; capped at {@link WITHHELD_WARNING_CAP}.
+ */
+export declare function formatWithheldWarning(withheld: readonly string[]): string;
+/**
+ * Scope the agent env and report which variable names were withheld.
+ * `withheld` holds names only; values never leave `source`.
+ */
+export declare function scopeAgentEnv(source: Record<string, string | undefined>, opts?: BuildAgentEnvOpts): {
+    env: Record<string, string>;
+    withheld: string[];
+};
+/**
+ * Build the agent subprocess env from `source` using the allowlist.
+ *
+ * Kept: {@link AGENT_ENV_ALLOWLIST}, {@link AGENT_ENV_PREFIXES}, `AWS_*` when
+ * `CLAUDE_CODE_USE_BEDROCK` is set, Vertex vars when `CLAUDE_CODE_USE_VERTEX`
+ * is set, `extraVars`, and `passthrough`. Everything else is dropped. Nullish
+ * values are always dropped. Pure: never mutates `source`.
+ */
+export declare function buildAgentEnv(source: Record<string, string | undefined>, opts?: BuildAgentEnvOpts): Record<string, string>;
+/** What one node's agent call may see: env var names and network hosts. */
+export interface AgentAccess {
+    envVars: string[];
+    domains: string[];
+}
+/** Hosts reachable by sandboxed commands in every node: source hosting + package registries. */
+export declare const DEFAULT_SANDBOX_DOMAINS: readonly string[];
+/** Provider hosts added when a node references the built-in skill. */
+export declare const SKILL_SANDBOX_DOMAINS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Resolve a node's access from its `skills:` list: every env var named by a
+ * referenced skill's config fields, plus that skill's provider hosts.
+ * Unknown skill ids contribute nothing (the executor validates them).
+ */
+export declare function resolveAgentAccess(skillIds: readonly string[], skills: Map<string, Skill>): AgentAccess;
+/**
+ * `off`: never sandbox (default for local runs, so "it's your repo" keeps
+ * working: private registries, docker, cargo, go). `auto` (default when CI is
+ * truthy): sandbox when the host supports it, otherwise warn once and run
+ * unsandboxed so unattended CI never breaks on a missing dependency.
+ * `strict`: sandbox or fail closed.
+ */
+export type SandboxMode = "off" | "auto" | "strict";
+/**
+ * Parse the sandbox mode from the explicit `mode` or `SWENY_SANDBOX`.
+ * Accepts `off|false|0`, `auto`, `strict|on|true|1` (`on` is an alias for
+ * `strict`). Unset or unknown (with a warning) uses the default: `auto` when
+ * `CI` is truthy, `off` otherwise. An explicit value always wins.
+ */
+export declare function resolveSandboxMode(env: Record<string, string | undefined>, mode?: string, logger?: Pick<Logger, "warn">): SandboxMode;
+/**
+ * Probe whether the SDK sandbox can start on this host. Returns a reason
+ * string when it cannot, undefined when it looks supported.
+ *
+ * macOS uses the built-in `sandbox-exec`. Linux needs `bwrap` (bubblewrap)
+ * and `socat` on PATH, and bwrap must be able to create a namespace
+ * (`bwrapCheck`, a real `bwrap ... true` run by default). Anything else is
+ * unsupported.
+ */
+export declare function checkSandboxSupport(platform?: NodeJS.Platform, pathEnv?: string, exists?: (p: string) => boolean, bwrapCheck?: () => string | undefined): string | undefined;
+/**
+ * The SDK sandbox settings used when the sandbox is on.
+ *
+ * - `failIfUnavailable`: true under `strict` (the SDK errors instead of
+ *   running unsandboxed); false under `auto`, so a host that passes the
+ *   preflight but still cannot start the sandbox degrades instead of failing.
+ * - `allowUnsandboxedCommands: false`: the model cannot escape via the
+ *   `dangerouslyDisableSandbox` parameter. Required, because nodes run under
+ *   `bypassPermissions` (#365) which would otherwise auto-approve the escape.
+ * - `network.allowedDomains` + `strictAllowlist`: non-listed hosts are denied
+ *   deterministically rather than prompted (no prompt exists headless).
+ * - `credentials`: the agent's own Anthropic credentials are unset for
+ *   sandboxed commands, and the Claude Code credentials file is unreadable.
+ */
+export declare function buildSandboxSettings(domains: readonly string[], opts?: {
+    failIfUnavailable?: boolean;
+    home?: string;
+}): SandboxSettings;
+export interface ResolveAgentSandboxOpts {
+    env: Record<string, string | undefined>;
+    /** Explicit mode (client option); falls back to `env.SWENY_SANDBOX`. */
+    mode?: SandboxMode;
+    /** Explicit extra hosts (client option); falls back to `env.SWENY_SANDBOX_ALLOWED_DOMAINS`. */
+    allowedDomains?: readonly string[];
+    /** Per-node hosts from {@link resolveAgentAccess}. */
+    nodeDomains?: readonly string[];
+    /** Preflight probe; test seam. Defaults to {@link checkSandboxSupport}, cached per process. */
+    probe?: () => string | undefined;
+    logger?: Pick<Logger, "warn">;
+}
+export interface AgentSandboxResolution {
+    mode: SandboxMode;
+    /** SDK `sandbox` option; absent when running unsandboxed. */
+    settings?: SandboxSettings;
+    /** `strict` only: the host cannot sandbox. Callers must fail the call. */
+    error?: string;
+    /** `auto` only: the host cannot sandbox, running unsandboxed. Log it loudly, once. */
+    warning?: string;
+}
+/**
+ * Resolve the `sandbox` query option for one agent call.
+ *
+ * - `off`: no settings.
+ * - supported host: `{ settings }`.
+ * - unsupported host under `auto`: `{ warning }`, run unsandboxed (back-compat:
+ *   unattended CI must not break on a missing dependency).
+ * - unsupported host under `strict`: `{ error }`, fail closed.
+ */
+export declare function resolveAgentSandbox(opts: ResolveAgentSandboxOpts): AgentSandboxResolution;

package/dist/agent-env.js

@@ -0,0 +1,393 @@
+/**
+ * Agent execution floor: scoped environment + SDK sandbox settings.
+ *
+ * Threat: the Claude Code subprocess runs model-chosen shell commands over
+ * attacker-influenceable input (issue bodies, alerts, fetched pages). Before
+ * this module it inherited the full `process.env` (every CI secret) and ran
+ * Bash with unrestricted network egress. Two controls live here:
+ *
+ *  1. {@link scopeAgentEnv}: the subprocess env is an allowlist, not a copy.
+ *     On by default in CI, off locally (full env, as before); see
+ *     {@link resolveEnvScope}.
+ *  2. {@link resolveAgentSandbox}: the SDK `sandbox` option is enabled with a
+ *     network allowlist and the agent's own credentials denied to sandboxed
+ *     commands. `auto` (default in CI) falls back to unsandboxed with one loud
+ *     warning when the host cannot sandbox; `strict` fails closed.
+ *
+ * Configuration (env wins over `.sweny.yml`, see `applyAgentFileConfig` in
+ * cli/config-file.ts):
+ *   SWENY_ENV_SCOPE                / env-scope                on | off (default: on in CI, off locally)
+ *   SWENY_ENV_PASSTHROUGH          / env-passthrough          extra var names ("*" = inherit all)
+ *   SWENY_SANDBOX                  / sandbox                  auto | strict | off (default: auto in CI, off locally)
+ *   SWENY_SANDBOX_ALLOWED_DOMAINS  / sandbox-allowed-domains  extra hosts for sandboxed commands
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import * as path from "node:path";
+// ─── Scoped env ──────────────────────────────────────────────────
+/**
+ * Exact variable names always passed to the agent subprocess.
+ *
+ * Process basics (PATH, HOME, shell, temp), locale/TZ, proxy + CA settings
+ * (corporate egress), CI identity vars (no tokens), and Claude Code runtime
+ * knobs. Credentials are NOT in this list except via the ANTHROPIC_/CLAUDE_
+ * prefixes below, which the agent needs to authenticate at all.
+ */
+export const AGENT_ENV_ALLOWLIST = [
+    // process basics
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TERM",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "XDG_DATA_HOME",
+    "XDG_RUNTIME_DIR",
+    // Windows process basics
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "SystemRoot",
+    "ComSpec",
+    "PATHEXT",
+    // locale / time
+    "LANG",
+    "LANGUAGE",
+    "TZ",
+    // proxy + TLS trust
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "NO_PROXY",
+    "ALL_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "no_proxy",
+    "all_proxy",
+    "NODE_EXTRA_CA_CERTS",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    // CI identity (never tokens)
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITHUB_REPOSITORY",
+    "GITHUB_REPOSITORY_OWNER",
+    "GITHUB_WORKSPACE",
+    "GITHUB_SHA",
+    "GITHUB_REF",
+    "GITHUB_REF_NAME",
+    "GITHUB_HEAD_REF",
+    "GITHUB_BASE_REF",
+    "GITHUB_RUN_ID",
+    "GITHUB_RUN_NUMBER",
+    "GITHUB_SERVER_URL",
+    "GITHUB_API_URL",
+    "GITHUB_EVENT_NAME",
+    "RUNNER_OS",
+    "RUNNER_TEMP",
+    "GITLAB_CI",
+    "CI_PROJECT_DIR",
+    "CI_COMMIT_SHA",
+    "BUILDKITE",
+    "CIRCLECI",
+    "JENKINS_URL",
+    "TF_BUILD",
+    // Claude Code runtime knobs (not credentials)
+    "MAX_THINKING_TOKENS",
+    "MCP_TIMEOUT",
+    "MCP_TOOL_TIMEOUT",
+    "BASH_DEFAULT_TIMEOUT_MS",
+    "BASH_MAX_TIMEOUT_MS",
+    "DISABLE_TELEMETRY",
+    "DISABLE_AUTOUPDATER",
+    "DISABLE_ERROR_REPORTING",
+    "DISABLE_NON_ESSENTIAL_MODEL_CALLS",
+];
+/**
+ * Prefixes always passed: locale (`LC_*`) and the agent's own backend config
+ * (`ANTHROPIC_*` incl. API key / auth token / base URL, `CLAUDE_*` incl.
+ * `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CONFIG_DIR`).
+ */
+export const AGENT_ENV_PREFIXES = ["LC_", "ANTHROPIC_", "CLAUDE_"];
+/** Cloud-provider vars passed only when Claude Code is routed through that provider. */
+const BEDROCK_PREFIXES = ["AWS_"];
+const VERTEX_VARS = ["GOOGLE_APPLICATION_CREDENTIALS", "CLOUD_ML_REGION", "GOOGLE_CLOUD_PROJECT", "GCLOUD_PROJECT"];
+/** The agent's own credentials. Needed by Claude Code, never by the commands it runs. */
+export const AGENT_AUTH_VARS = [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+];
+function truthy(v) {
+    if (!v)
+        return false;
+    const s = v.trim().toLowerCase();
+    return s !== "" && s !== "0" && s !== "false" && s !== "no" && s !== "off";
+}
+/** Split a comma/whitespace separated list, dropping empties. */
+export function parseList(v) {
+    if (!v)
+        return [];
+    return v
+        .split(/[,\s]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Whether the agent env is scoped to the allowlist. `SWENY_ENV_SCOPE` (or the
+ * explicit value) `on|true|1` / `off|false|0` wins everywhere; otherwise on
+ * when `CI` is truthy and off locally, so local runs keep the full env that
+ * e2e/test workflows rely on (DATABASE_URL, BASE_URL, NODE_ENV, ...).
+ */
+export function resolveEnvScope(env, explicit, logger) {
+    if (explicit !== undefined)
+        return explicit;
+    const raw = (env.SWENY_ENV_SCOPE ?? "").trim().toLowerCase();
+    if (raw === "on" || raw === "true" || raw === "1")
+        return true;
+    if (raw === "off" || raw === "false" || raw === "0")
+        return false;
+    const fallback = truthy(env.CI);
+    if (raw !== "")
+        logger?.warn(`SWENY_ENV_SCOPE="${raw}" is not one of on|off; using ${fallback ? "on" : "off"}`);
+    return fallback;
+}
+/** Max names listed in the withheld-vars warning before "and N more". */
+export const WITHHELD_WARNING_CAP = 30;
+/**
+ * One-line warning naming the withheld variables. Names only, never values;
+ * sorted; capped at {@link WITHHELD_WARNING_CAP}.
+ */
+export function formatWithheldWarning(withheld) {
+    const names = [...withheld].sort();
+    const shown = names.slice(0, WITHHELD_WARNING_CAP).join(", ");
+    const more = names.length > WITHHELD_WARNING_CAP ? `, and ${names.length - WITHHELD_WARNING_CAP} more` : "";
+    return (`Agent env scoping withheld ${names.length} environment variable(s) from the agent: ${shown}${more}. ` +
+        `If a node's commands need any of them, add the names to env-passthrough ` +
+        `(SWENY_ENV_PASSTHROUGH), or set env-scope: off (SWENY_ENV_SCOPE=off).`);
+}
+/**
+ * Scope the agent env and report which variable names were withheld.
+ * `withheld` holds names only; values never leave `source`.
+ */
+export function scopeAgentEnv(source, opts = {}) {
+    const env = buildAgentEnv(source, opts);
+    const withheld = Object.keys(source).filter((k) => source[k] != null && !(k in env));
+    return { env, withheld };
+}
+/**
+ * Build the agent subprocess env from `source` using the allowlist.
+ *
+ * Kept: {@link AGENT_ENV_ALLOWLIST}, {@link AGENT_ENV_PREFIXES}, `AWS_*` when
+ * `CLAUDE_CODE_USE_BEDROCK` is set, Vertex vars when `CLAUDE_CODE_USE_VERTEX`
+ * is set, `extraVars`, and `passthrough`. Everything else is dropped. Nullish
+ * values are always dropped. Pure: never mutates `source`.
+ */
+export function buildAgentEnv(source, opts = {}) {
+    const passthrough = opts.passthrough ?? [];
+    if (passthrough.includes("*")) {
+        opts.logger?.warn("[sweny] env-passthrough contains '*': the agent inherits the full environment, including every secret.");
+        return Object.fromEntries(Object.entries(source).filter((e) => e[1] != null));
+    }
+    const exact = new Set([...AGENT_ENV_ALLOWLIST, ...(opts.extraVars ?? []), ...passthrough]);
+    const prefixes = [...AGENT_ENV_PREFIXES];
+    if (truthy(source.CLAUDE_CODE_USE_BEDROCK))
+        prefixes.push(...BEDROCK_PREFIXES);
+    if (truthy(source.CLAUDE_CODE_USE_VERTEX))
+        for (const v of VERTEX_VARS)
+            exact.add(v);
+    const out = {};
+    for (const [k, v] of Object.entries(source)) {
+        if (v == null)
+            continue;
+        if (exact.has(k) || prefixes.some((p) => k.startsWith(p)))
+            out[k] = v;
+    }
+    return out;
+}
+/** Hosts reachable by sandboxed commands in every node: source hosting + package registries. */
+export const DEFAULT_SANDBOX_DOMAINS = [
+    "github.com",
+    "api.github.com",
+    "codeload.github.com",
+    "uploads.github.com",
+    "*.githubusercontent.com",
+    "registry.npmjs.org",
+    "registry.yarnpkg.com",
+    "pypi.org",
+    "files.pythonhosted.org",
+    "proxy.golang.org",
+    "sum.golang.org",
+    "crates.io",
+    "static.crates.io",
+    "index.crates.io",
+    "rubygems.org",
+];
+/** Provider hosts added when a node references the built-in skill. */
+export const SKILL_SANDBOX_DOMAINS = {
+    github: ["github.com", "api.github.com", "uploads.github.com", "*.githubusercontent.com"],
+    linear: ["api.linear.app", "mcp.linear.app"],
+    sentry: ["sentry.io", "*.sentry.io"],
+    datadog: ["*.datadoghq.com", "*.datadoghq.eu", "*.ddog-gov.com"],
+    betterstack: ["*.betterstack.com", "*.betterstackdata.com"],
+    slack: ["slack.com", "*.slack.com"],
+    supabase: ["*.supabase.co"],
+    gitlab: ["gitlab.com"],
+};
+/**
+ * Resolve a node's access from its `skills:` list: every env var named by a
+ * referenced skill's config fields, plus that skill's provider hosts.
+ * Unknown skill ids contribute nothing (the executor validates them).
+ */
+export function resolveAgentAccess(skillIds, skills) {
+    const envVars = new Set();
+    const domains = new Set();
+    for (const id of skillIds) {
+        const skill = skills.get(id);
+        for (const field of Object.values(skill?.config ?? {})) {
+            if (field.env)
+                envVars.add(field.env);
+        }
+        for (const d of SKILL_SANDBOX_DOMAINS[id] ?? [])
+            domains.add(d);
+    }
+    return { envVars: [...envVars], domains: [...domains] };
+}
+/**
+ * Parse the sandbox mode from the explicit `mode` or `SWENY_SANDBOX`.
+ * Accepts `off|false|0`, `auto`, `strict|on|true|1` (`on` is an alias for
+ * `strict`). Unset or unknown (with a warning) uses the default: `auto` when
+ * `CI` is truthy, `off` otherwise. An explicit value always wins.
+ */
+export function resolveSandboxMode(env, mode, logger) {
+    const raw = (mode ?? env.SWENY_SANDBOX ?? "").trim().toLowerCase();
+    if (raw === "off" || raw === "false" || raw === "0")
+        return "off";
+    if (raw === "strict" || raw === "on" || raw === "true" || raw === "1")
+        return "strict";
+    if (raw === "auto")
+        return "auto";
+    const fallback = truthy(env.CI) ? "auto" : "off";
+    if (raw !== "")
+        logger?.warn(`SWENY_SANDBOX="${raw}" is not one of off|auto|strict; using ${fallback}`);
+    return fallback;
+}
+/** Functional bubblewrap check: can it actually create a sandbox on this host? */
+function bwrapWorks() {
+    try {
+        execFileSync("bwrap", ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc", "true"], {
+            stdio: ["ignore", "ignore", "pipe"],
+            timeout: 10_000,
+        });
+        return undefined;
+    }
+    catch (err) {
+        const stderr = String(err.stderr ?? err.message ?? "").trim();
+        const userns = /user namespace|uid map|setting up uid|Operation not permitted|Permission denied/i.test(stderr);
+        return (`bwrap cannot create a sandbox (${stderr.split("\n")[0] || "unknown error"})` +
+            (userns
+                ? "; unprivileged user namespaces look restricted (Ubuntu 23.10+: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0)"
+                : ""));
+    }
+}
+/**
+ * Probe whether the SDK sandbox can start on this host. Returns a reason
+ * string when it cannot, undefined when it looks supported.
+ *
+ * macOS uses the built-in `sandbox-exec`. Linux needs `bwrap` (bubblewrap)
+ * and `socat` on PATH, and bwrap must be able to create a namespace
+ * (`bwrapCheck`, a real `bwrap ... true` run by default). Anything else is
+ * unsupported.
+ */
+export function checkSandboxSupport(platform = process.platform, pathEnv = process.env.PATH ?? "", exists = existsSync, bwrapCheck = bwrapWorks) {
+    if (platform === "darwin")
+        return undefined;
+    if (platform !== "linux")
+        return `the Claude Code sandbox does not support platform "${platform}"`;
+    const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+    const missing = ["bwrap", "socat"].filter((bin) => !dirs.some((d) => exists(path.join(d, bin))));
+    if (missing.length > 0) {
+        return `missing ${missing.join(" and ")} on PATH (install: sudo apt-get install -y bubblewrap socat)`;
+    }
+    return bwrapCheck();
+}
+let cachedProbe;
+/** {@link checkSandboxSupport} for this host, computed once per process. */
+function defaultProbe() {
+    if (!cachedProbe)
+        cachedProbe = { result: checkSandboxSupport() };
+    return cachedProbe.result;
+}
+/**
+ * The SDK sandbox settings used when the sandbox is on.
+ *
+ * - `failIfUnavailable`: true under `strict` (the SDK errors instead of
+ *   running unsandboxed); false under `auto`, so a host that passes the
+ *   preflight but still cannot start the sandbox degrades instead of failing.
+ * - `allowUnsandboxedCommands: false`: the model cannot escape via the
+ *   `dangerouslyDisableSandbox` parameter. Required, because nodes run under
+ *   `bypassPermissions` (#365) which would otherwise auto-approve the escape.
+ * - `network.allowedDomains` + `strictAllowlist`: non-listed hosts are denied
+ *   deterministically rather than prompted (no prompt exists headless).
+ * - `credentials`: the agent's own Anthropic credentials are unset for
+ *   sandboxed commands, and the Claude Code credentials file is unreadable.
+ */
+export function buildSandboxSettings(domains, opts = {}) {
+    return {
+        enabled: true,
+        failIfUnavailable: opts.failIfUnavailable ?? true,
+        autoAllowBashIfSandboxed: true,
+        allowUnsandboxedCommands: false,
+        network: {
+            allowedDomains: [...new Set(domains)],
+            strictAllowlist: true,
+        },
+        credentials: {
+            envVars: AGENT_AUTH_VARS.map((name) => ({ name, mode: "deny" })),
+            files: [{ path: path.join(opts.home ?? homedir(), ".claude", ".credentials.json"), mode: "deny" }],
+        },
+    };
+}
+/**
+ * Resolve the `sandbox` query option for one agent call.
+ *
+ * - `off`: no settings.
+ * - supported host: `{ settings }`.
+ * - unsupported host under `auto`: `{ warning }`, run unsandboxed (back-compat:
+ *   unattended CI must not break on a missing dependency).
+ * - unsupported host under `strict`: `{ error }`, fail closed.
+ */
+export function resolveAgentSandbox(opts) {
+    const mode = resolveSandboxMode(opts.env, opts.mode, opts.logger);
+    if (mode === "off")
+        return { mode };
+    const reason = (opts.probe ?? defaultProbe)();
+    if (reason) {
+        if (mode === "strict") {
+            return {
+                mode,
+                error: `Agent sandbox is required (SWENY_SANDBOX=strict) but unavailable: ${reason}. ` +
+                    `Refusing to run the agent unsandboxed. Fix the host, or set SWENY_SANDBOX=auto to fall back with a warning.`,
+            };
+        }
+        return {
+            mode,
+            warning: `Agent sandbox unavailable: ${reason}. Running agent shell commands UNSANDBOXED ` +
+                `(network and filesystem unrestricted; env scoping and untrusted-input fencing still apply). ` +
+                `Fix the host to sandbox, set SWENY_SANDBOX=strict (or \`sandbox: strict\` in .sweny.yml) to fail instead, ` +
+                `or SWENY_SANDBOX=off to silence this.`,
+        };
+    }
+    const extra = opts.allowedDomains ?? parseList(opts.env.SWENY_SANDBOX_ALLOWED_DOMAINS);
+    return {
+        mode,
+        settings: buildSandboxSettings([...DEFAULT_SANDBOX_DOMAINS, ...(opts.nodeDomains ?? []), ...extra], {
+            failIfUnavailable: mode === "strict",
+        }),
+    };
+}

package/dist/browser.d.ts

@@ -13,9 +13,9 @@
  *   - `buildWorkflow` / `refineWorkflow` — depend on the Claude interface.
  *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, NodeToolFilter, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, NodeOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
 export { consoleLogger } from "./types.js";
-export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
+export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 export type { SkillValidationResult } from "./skills/index.js";
 export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";

package/dist/browser.js

@@ -18,7 +18,7 @@ export { consoleLogger } from "./types.js";
 // function from types.ts, which is already proven browser-safe (schema.ts
 // imports it). A Studio dropdown rendering evaluator kinds, or validating a
 // skill id, needs these without hardcoding the members.
-export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
+export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
 // Skills (browser-safe — no filesystem access, no `process.env` reads)
 export { github, linear, slack, sentry, datadog, betterstack, notification, supabase, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 // Schema & validation