@praxis-ai/praxis 0.1.1 → 0.1.2

package/dist/runtimeImplementation/runtime.sandboxPlane/sandboxCommandRunner.js

@@ -4,9 +4,10 @@
  * 边界：工具 handler 不感知本文件；executor port 负责把真实进程执行交给本 runner。
  */
 import { spawn } from "node:child_process";
-import { mkdir, mkdtemp, readdir, rm, stat, writeFile } from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
+import { createRaxcellSandboxProvider } from "./raxcellSandboxProvider.js";
+import { resolveRaxcellBinaryPath } from "./sandboxRuntimeProvider.js";
+import { runSandboxPolicyMiddleware, } from "./sandboxPolicyMiddleware.js";
 import { createWorkspaceRollbackSandboxPlan, createWorkspaceRollbackSnapshot, finalizeWorkspaceRollbackSnapshot, restoreWorkspaceRollbackSnapshot, } from "./workspaceRollbackSandbox.js";
 export const sandboxCommandRunnerDescriptor = {
     surface: "runtime.sandboxPlane.sandboxCommandRunner",
@@ -31,8 +32,6 @@ function truncate(value, maxBytes) {
     return output;
 }
 function defaultModeFor(profile) {
-    if (profile === "bapr")
-        return "none";
     if (profile === "yolo")
         return "workspace-rollback";
     return "isolated";
@@ -80,191 +79,10 @@ function sandboxProviderUnavailable(input, providerFamily) {
     const preparedStatus = input.preparedSandbox?.probe.status ?? "not-prepared";
     return new Error(`${providerFamily} sandbox is not ready for isolated execution (${preparedStatus})`);
 }
-function secretMaskScript(filesystem) {
-    if (!filesystem.protectSecrets)
-        return "";
-    const patterns = filesystem.secretGlobs.map((glob) => `-name '${glob.replaceAll("'", "'\\''")}'`).join(" -o ");
-    return `find /workspace -maxdepth 3 -type f \\( ${patterns} \\) -print0 2>/dev/null | while IFS= read -r -d '' file; do :; done`;
-}
-function secretPatternMatches(name) {
-    return name === ".env" || name.startsWith(".env.");
-}
-async function collectSecretFiles(root, current = root, depth = 0, out = []) {
-    if (depth > 4)
-        return out;
-    let entries;
-    try {
-        entries = await readdir(current, { withFileTypes: true });
-    }
-    catch {
-        return out;
-    }
-    for (const entry of entries) {
-        const absolute = path.join(current, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === ".git" || entry.name === "node_modules" || entry.name === ".rax_workspace")
-                continue;
-            await collectSecretFiles(root, absolute, depth + 1, out);
-            continue;
-        }
-        if (!entry.isFile() || !secretPatternMatches(entry.name))
-            continue;
-        try {
-            const info = await stat(absolute);
-            if (info.isFile())
-                out.push(path.relative(root, absolute).split(path.sep).join("/"));
-        }
-        catch {
-            // Ignore files that disappeared between directory scan and stat.
-        }
-    }
-    return out;
-}
 function isInsidePath(root, candidate) {
     const relative = path.relative(root, candidate);
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
-function sandboxPathForRoot(root, workspaceRoot) {
-    if (root === workspaceRoot)
-        return "/workspace";
-    if (isInsidePath(workspaceRoot, root)) {
-        return path.posix.join("/workspace", path.relative(workspaceRoot, root).split(path.sep).join("/"));
-    }
-    return root;
-}
-function sandboxCwdForHost(hostCwd, filesystem) {
-    const roots = [...new Set([
-            filesystem.workspaceRoot,
-            ...filesystem.allowedReadRoots,
-            ...filesystem.allowedWriteRoots,
-        ])].sort((left, right) => right.length - left.length);
-    for (const root of roots) {
-        if (!isInsidePath(root, hostCwd))
-            continue;
-        const rootDest = sandboxPathForRoot(root, filesystem.workspaceRoot);
-        const relative = path.relative(root, hostCwd);
-        if (relative === "")
-            return rootDest;
-        return path.posix.join(rootDest, relative.split(path.sep).join("/"));
-    }
-    throw new Error(`sandbox cwd ${hostCwd} is outside sandbox filesystem roots`);
-}
-function sandboxPathParentDirs(target) {
-    const normalized = path.posix.resolve(target.split(path.sep).join(path.posix.sep));
-    if (normalized === "/workspace" || normalized.startsWith("/workspace/"))
-        return [];
-    const segments = normalized.split("/").filter(Boolean);
-    const dirs = [];
-    for (let index = 0; index < segments.length - 1; index += 1) {
-        const dir = `/${segments.slice(0, index + 1).join("/")}`;
-        if (dir === "/tmp" || dir === "/dev" || dir === "/proc" || dir === "/usr" || dir === "/bin" || dir === "/lib" || dir === "/lib64" || dir === "/etc")
-            continue;
-        dirs.push(dir);
-    }
-    return dirs;
-}
-async function linuxBubblewrapPlan(input, base) {
-    if (process.platform !== "linux") {
-        return {
-            program: input.command,
-            args: input.args ?? [],
-            metadata: { ...base.metadata, providerUnavailable: "linux-bubblewrap is only executable on Linux" },
-        };
-    }
-    const tempDir = await mkdtemp(path.join(os.tmpdir(), "praxis-bwrap-"));
-    const home = path.join(tempDir, "home");
-    const tmp = path.join(tempDir, "tmp");
-    await Promise.all([mkdir(home, { recursive: true }), mkdir(tmp, { recursive: true })]);
-    const command = [input.command, ...(input.args ?? [])];
-    const networkArgs = base.network === "allow" ? ["--share-net"] : ["--unshare-net"];
-    const sandboxCwd = sandboxCwdForHost(base.cwd, base.filesystem);
-    const mountArgs = [
-        "--unshare-pid",
-        "--unshare-ipc",
-        "--unshare-uts",
-        ...networkArgs,
-        "--die-with-parent",
-        "--new-session",
-        "--ro-bind-try",
-        "/usr",
-        "/usr",
-        "--ro-bind-try",
-        "/bin",
-        "/bin",
-        "--ro-bind-try",
-        "/lib",
-        "/lib",
-        "--ro-bind-try",
-        "/lib64",
-        "/lib64",
-        "--ro-bind-try",
-        "/etc",
-        "/etc",
-        "--dev",
-        "/dev",
-        "--proc",
-        "/proc",
-        "--tmpfs",
-        "/tmp",
-        "--bind",
-        home,
-        "/sandbox-home",
-        "--setenv",
-        "HOME",
-        "/sandbox-home",
-        "--setenv",
-        "TMPDIR",
-        "/tmp",
-        "--setenv",
-        "PRAXIS_SANDBOX",
-        "linux-bubblewrap",
-        "--chdir",
-        sandboxCwd,
-    ];
-    const workspaceMountFlag = base.filesystem.readonlyRoot ? "--ro-bind" : "--bind";
-    mountArgs.push(workspaceMountFlag, base.filesystem.workspaceRoot, "/workspace");
-    const mountedReadTargets = new Set(["/workspace"]);
-    const mountedWriteTargets = new Set();
-    const writableDestinations = new Set(base.filesystem.allowedWriteRoots.map((root) => sandboxPathForRoot(root, base.filesystem.workspaceRoot)));
-    for (const readRoot of base.filesystem.allowedReadRoots) {
-        const dest = sandboxPathForRoot(readRoot, base.filesystem.workspaceRoot);
-        if (writableDestinations.has(dest))
-            continue;
-        if (mountedReadTargets.has(dest) || mountedWriteTargets.has(dest))
-            continue;
-        if (dest !== "/workspace") {
-            for (const parent of sandboxPathParentDirs(dest))
-                mountArgs.push("--dir", parent);
-            mountArgs.push("--ro-bind-try", readRoot, dest);
-        }
-        mountedReadTargets.add(dest);
-    }
-    for (const writeRoot of base.filesystem.allowedWriteRoots) {
-        if (writeRoot === base.filesystem.workspaceRoot)
-            continue;
-        const dest = sandboxPathForRoot(writeRoot, base.filesystem.workspaceRoot);
-        if (mountedWriteTargets.has(dest))
-            continue;
-        for (const parent of sandboxPathParentDirs(dest))
-            mountArgs.push("--dir", parent);
-        mountArgs.push("--bind-try", writeRoot, dest);
-        mountedWriteTargets.add(dest);
-    }
-    if (base.filesystem.protectSecrets) {
-        const mask = path.join(tempDir, "secret-mask");
-        await writeFile(mask, "", { mode: 0o000 });
-        const secretFiles = await collectSecretFiles(base.filesystem.workspaceRoot);
-        for (const name of secretFiles)
-            mountArgs.push("--ro-bind-try", mask, path.posix.join("/workspace", name));
-    }
-    mountArgs.push("/usr/bin/env", ...command);
-    return {
-        program: "bwrap",
-        args: mountArgs,
-        cleanup: async () => { await rm(tempDir, { recursive: true, force: true }); },
-        metadata: { ...base.metadata, tempDir, secretMaskScript: secretMaskScript(base.filesystem) },
-    };
-}
 function seatbeltString(value) {
     return value
         .replace(/\\/gu, "\\\\")
@@ -352,7 +170,7 @@ export async function createSandboxCommandPlan(input) {
     if (providerFamily === "linux-bubblewrap") {
         if (input.preparedSandbox?.ready !== true)
             throw sandboxProviderUnavailable(input, providerFamily);
-        plan = { ...base, ...(await linuxBubblewrapPlan(input, base)) };
+        plan = { ...base, program: input.command, args: input.args ?? [] };
     }
     else if (providerFamily === "macos-containerization") {
         if (input.preparedSandbox !== undefined && input.preparedSandbox.ready !== true)
@@ -412,6 +230,227 @@ function parseSandboxDenial(plan, stderr, exitCode) {
     }
     return undefined;
 }
+function providerFromOptions(options) {
+    if (options.sandboxProvider !== undefined)
+        return options.sandboxProvider;
+    const binaryPath = resolveRaxcellBinaryPath();
+    return binaryPath === undefined
+        ? undefined
+        : createRaxcellSandboxProvider({ binaryPath });
+}
+function toProviderRunRequest(input, plan) {
+    return {
+        kind: "runtime.sandboxPlane.provider.runRequest",
+        action: {
+            actionId: input.invocationId,
+            runtimeId: input.runtimeId,
+            sessionId: input.sessionId,
+            toolId: input.toolId,
+            ownerRuntime: "praxis",
+            intentLabel: `${input.toolId} command`,
+            metadata: input.metadata ?? {},
+        },
+        command: {
+            argv: [input.command, ...(input.args ?? [])],
+            cwd: plan.cwd,
+            env: plan.env,
+            stdin: null,
+        },
+        policy: {
+            profile: input.policyProfile,
+            sandboxId: input.sandbox.sandboxId,
+            sandboxMode: plan.mode,
+            network: plan.network,
+            process: { spawn: true },
+            resources: {
+                timeoutMs: input.timeoutMs ?? input.sandbox.resourceLimits.timeoutMs,
+                maxOutputBytes: input.maxOutputBytes ?? input.sandbox.resourceLimits.maxOutputBytes,
+                maxProcesses: input.sandbox.resourceLimits.maxProcesses,
+            },
+        },
+        filesystem: {
+            workspaceRoot: plan.filesystem.workspaceRoot,
+            read: plan.filesystem.allowedReadRoots,
+            write: plan.filesystem.allowedWriteRoots,
+            readonlyRoot: plan.filesystem.readonlyRoot,
+            protectSecrets: plan.filesystem.protectSecrets,
+        },
+        policyGrants: input.policyGrants ?? [],
+        fallback: { mode: "none" },
+        metadata: {
+            providerFamily: plan.providerFamily,
+            requestedProviderFamily: plan.requestedProviderFamily ?? "",
+            policyProfile: plan.policyProfile,
+            secretGlobs: plan.filesystem.secretGlobs,
+            protectSecrets: plan.filesystem.protectSecrets,
+            approvalAccepted: input.approval?.accepted === true,
+            approvalGrantedBy: input.approval?.grantedBy ?? null,
+        },
+    };
+}
+function grantAccessForGap(gap) {
+    const access = [...new Set((gap.required ?? [])
+            .map((value) => value.toLowerCase())
+            .filter((value) => value === "read" || value === "write"))];
+    return access.length > 0 ? access : ["read"];
+}
+function resolvePraxisDynamicShellPath(request, rawPath) {
+    const home = request.command.env.HOME ?? process.env.HOME;
+    if (home === undefined || home.trim().length === 0)
+        return undefined;
+    if (rawPath === "$HOME" || rawPath === "${HOME}" || rawPath === "~")
+        return path.resolve(home);
+    for (const prefix of ["$HOME/", "${HOME}/", "~/"]) {
+        if (rawPath.startsWith(prefix))
+            return path.resolve(home, rawPath.slice(prefix.length));
+    }
+    return undefined;
+}
+function replaceShellPathToken(value, rawPath, resolvedPath) {
+    return value.split(rawPath).join(resolvedPath);
+}
+function rewriteDynamicShellPathRequest(context) {
+    const rawPath = context.gap.path;
+    if (rawPath.trim().length === 0)
+        return undefined;
+    const resolvedPath = resolvePraxisDynamicShellPath(context.request, rawPath);
+    if (resolvedPath === undefined)
+        return undefined;
+    return {
+        ...context.request,
+        command: {
+            ...context.request.command,
+            argv: context.request.command.argv.map((value) => replaceShellPathToken(value, rawPath, resolvedPath)),
+        },
+        policyGrants: [
+            ...context.request.policyGrants,
+            {
+                reason: context.gap.reason,
+                path: resolvedPath,
+                access: grantAccessForGap(context.gap),
+                grantedBy: typeof context.request.metadata.approvalGrantedBy === "string"
+                    ? context.request.metadata.approvalGrantedBy
+                    : "praxis-human-approval",
+            },
+        ],
+    };
+}
+function defaultEnvironmentGapDecision(context) {
+    const gap = context.environmentGap;
+    if (context.request.metadata.approvalAccepted === true && gap.reason === "path-outside-declared-roots") {
+        return {
+            type: "grant",
+            grants: [{
+                    reason: gap.reason,
+                    path: gap.path,
+                    access: grantAccessForGap(gap),
+                    grantedBy: typeof context.request.metadata.approvalGrantedBy === "string"
+                        ? context.request.metadata.approvalGrantedBy
+                        : "praxis-human-approval",
+                }],
+        };
+    }
+    if (context.request.metadata.approvalAccepted === true && gap.reason === "shell-dynamic-path-unresolved") {
+        const request = rewriteDynamicShellPathRequest({ request: context.request, gap });
+        if (request !== undefined) {
+            return { type: "rewrite", request, reason: "Praxis resolved approved dynamic shell path before sandbox lowering" };
+        }
+    }
+    if (gap.reason !== "cwd-outside-declared-roots") {
+        return { type: "deny", reason: gap.publicSafeMessage };
+    }
+    const cwd = path.resolve(gap.path);
+    const writeRoot = context.request.filesystem.write.find((root) => isInsidePath(root, cwd));
+    if (writeRoot !== undefined) {
+        return {
+            type: "grant",
+            grants: [{ reason: gap.reason, path: gap.path, access: ["write"], grantedBy: "praxis-policy" }],
+        };
+    }
+    const readRoot = context.request.filesystem.read.find((root) => isInsidePath(root, cwd));
+    if (readRoot !== undefined) {
+        return {
+            type: "grant",
+            grants: [{ reason: gap.reason, path: gap.path, access: ["read"], grantedBy: "praxis-policy" }],
+        };
+    }
+    return { type: "deny", reason: gap.publicSafeMessage };
+}
+async function runProviderSandboxCommand(input, plan, options) {
+    const provider = providerFromOptions(options);
+    if (provider === undefined) {
+        return {
+            ok: false,
+            plan,
+            error: {
+                code: "SANDBOX_DENIED",
+                message: "Raxcell sandbox provider is not configured",
+                publicSafe: true,
+                denial: {
+                    kind: "runtime.sandboxPlane.command.denial",
+                    code: "SANDBOX_PROVIDER_UNAVAILABLE",
+                    message: "Raxcell sandbox provider is not configured",
+                    needsApproval: false,
+                    publicSafe: true,
+                },
+            },
+            events: [...plan.events, "runtime.sandboxPlane.command.denied"],
+            metadata: { providerFamily: plan.providerFamily, providerUnavailable: "raxcell provider is not configured" },
+        };
+    }
+    const middlewareResult = await runSandboxPolicyMiddleware({
+        provider,
+        request: toProviderRunRequest(input, plan),
+        decideEnvironmentGap: async ({ request, environmentGap }) => options.decideEnvironmentGap?.({ request, environmentGap }) ?? defaultEnvironmentGapDecision({ request, environmentGap }),
+        audit: options.audit,
+    });
+    if (!middlewareResult.ok) {
+        return {
+            ok: false,
+            plan,
+            error: {
+                code: "SANDBOX_DENIED",
+                message: middlewareResult.error.message,
+                publicSafe: true,
+                denial: {
+                    kind: "runtime.sandboxPlane.command.denial",
+                    code: middlewareResult.error.code === "SANDBOX_PREPARE_FAILED" ? "SANDBOX_PROVIDER_UNAVAILABLE" : "SANDBOX_PERMISSION_DENIED",
+                    message: middlewareResult.error.message,
+                    needsApproval: false,
+                    publicSafe: true,
+                },
+            },
+            stdout: "",
+            stderr: "",
+            events: [...plan.events, ...middlewareResult.events, "runtime.sandboxPlane.command.denied"],
+            metadata: { providerFamily: plan.providerFamily, middlewareError: middlewareResult.error.code },
+        };
+    }
+    return {
+        ok: true,
+        plan: {
+            ...plan,
+            metadata: {
+                ...plan.metadata,
+                providerPrepare: middlewareResult.prepared,
+                providerRequest: middlewareResult.request,
+            },
+        },
+        exitCode: middlewareResult.result.exitCode ?? 0,
+        stdout: middlewareResult.result.stdout,
+        stderr: middlewareResult.result.stderr,
+        events: [...plan.events, ...middlewareResult.events, "runtime.sandboxPlane.command.completed"],
+        metadata: {
+            providerFamily: plan.providerFamily,
+            providerId: provider.providerId,
+            ...(middlewareResult.result.timedOut ? { timedOut: true } : {}),
+            providerRun: {
+                denial: middlewareResult.result.denial ?? null,
+                filesystemLowering: middlewareResult.result.filesystemLowering ?? null,
+            },
+        },
+    };
+}
 function spawnPlan(plan, input) {
     return new Promise((resolve, reject) => {
         const child = spawn(plan.program, [...plan.args], {
@@ -505,6 +544,11 @@ export async function runSandboxCommand(input, options = {}) {
                 metadata: { providerFamily: plan.providerFamily, providerUnavailable: "remote-worker adapter is not configured" },
             };
         }
+        if (plan.providerFamily === "linux-bubblewrap") {
+            const result = await runProviderSandboxCommand(input, plan, options);
+            await plan.cleanup?.();
+            return result;
+        }
         const remote = plan.providerFamily === "remote-worker"
             ? await options.remoteWorker?.(input, plan)
             : undefined;

package/dist/runtimeImplementation/runtime.sandboxPlane/sandboxPolicyMiddleware.d.ts

@@ -0,0 +1,175 @@
+import type { BaseToolPolicyProfile } from "../runtimeAgentManifest.js";
+import type { SandboxCommandNetworkPolicy } from "./sandboxCommandRunner.js";
+export type SandboxProviderFamily = "host-observed" | "workspace-policy" | "workspace-rollback" | "linux-bubblewrap" | "macos-containerization" | "windows-sandbox" | "remote-worker" | "external";
+export type SandboxProviderPolicyGrant = {
+    reason: string;
+    path: string;
+    access?: readonly string[];
+    grantedBy?: string | null;
+};
+export type SandboxProviderFilesystemLoweredRoot = {
+    path: string;
+    access: "read" | "write" | "runtime" | "scratch" | "runtime-link";
+    source: "declared" | "backend-runtime" | "policy-grant";
+};
+export type SandboxProviderFilesystemLoweringReport = {
+    declaredRoots: readonly SandboxProviderFilesystemLoweredRoot[];
+    runtimeRoots: readonly SandboxProviderFilesystemLoweredRoot[];
+    policyGrants: readonly SandboxProviderPolicyGrant[];
+    warnings: readonly {
+        code: string;
+        message: string;
+    }[];
+    effects?: readonly {
+        path?: string;
+        pattern?: string;
+        rawToken: string;
+        access: "read" | "write" | "readwrite";
+        command: string;
+        reason: string;
+        confidence: "high" | "medium" | "low";
+        warning?: string;
+    }[];
+};
+export type SandboxProviderBackendArtifact = {
+    backend: SandboxProviderFamily;
+    format: string;
+    arguments: readonly string[];
+    data: Readonly<Record<string, unknown>>;
+    warnings: readonly {
+        code: string;
+        message: string;
+    }[];
+};
+export type SandboxProviderEnvironmentGap = {
+    reason: string;
+    path: string;
+    required?: readonly string[];
+    publicSafeMessage: string;
+};
+export type SandboxProviderDenial = {
+    code: string;
+    message: string;
+    publicSafe: true;
+};
+export type SandboxProviderRunRequest = {
+    kind: "runtime.sandboxPlane.provider.runRequest";
+    action: {
+        actionId: string;
+        runtimeId: string;
+        sessionId: string;
+        toolId: string;
+        ownerRuntime: "praxis" | string;
+        intentLabel: string;
+        metadata: Readonly<Record<string, unknown>>;
+    };
+    command: {
+        argv: readonly string[];
+        cwd: string;
+        env: Readonly<Record<string, string | undefined>>;
+        stdin: string | null;
+    };
+    policy: {
+        profile: BaseToolPolicyProfile;
+        sandboxId: string;
+        sandboxMode: "none" | "workspace-rollback" | "isolated";
+        network: SandboxCommandNetworkPolicy;
+        process: Readonly<Record<string, unknown>>;
+        resources: Readonly<Record<string, unknown>>;
+    };
+    filesystem: {
+        workspaceRoot: string;
+        read: readonly string[];
+        write: readonly string[];
+        readonlyRoot: boolean;
+        protectSecrets: boolean;
+    };
+    policyGrants: readonly SandboxProviderPolicyGrant[];
+    fallback: {
+        mode: string;
+    };
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type SandboxProviderPrepareRunResult = {
+    kind: "runtime.sandboxPlane.provider.prepareRunResult";
+    ok: boolean;
+    providerFamily: SandboxProviderFamily;
+    denial?: SandboxProviderDenial | null;
+    environmentGap?: SandboxProviderEnvironmentGap | null;
+    filesystemLowering?: SandboxProviderFilesystemLoweringReport | null;
+    backendArtifacts: readonly SandboxProviderBackendArtifact[];
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type SandboxProviderRunResult = {
+    kind: "runtime.sandboxPlane.provider.runResult";
+    ok: boolean;
+    providerFamily: SandboxProviderFamily;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    denial?: SandboxProviderDenial | null;
+    environmentGap?: SandboxProviderEnvironmentGap | null;
+    filesystemLowering?: SandboxProviderFilesystemLoweringReport | null;
+    metadata: Readonly<Record<string, unknown>>;
+};
+export type SandboxExecutionProviderPort = {
+    providerId: string;
+    providerFamily: SandboxProviderFamily;
+    prepareRun(request: SandboxProviderRunRequest): Promise<SandboxProviderPrepareRunResult>;
+    run(request: SandboxProviderRunRequest): Promise<SandboxProviderRunResult>;
+};
+export type SandboxPolicyMiddlewareEnvironmentGapDecision = {
+    type: "grant";
+    grants: readonly SandboxProviderPolicyGrant[];
+} | {
+    type: "rewrite";
+    request: SandboxProviderRunRequest;
+    reason: string;
+} | {
+    type: "deny";
+    reason: string;
+};
+export type SandboxPolicyMiddlewareResult = {
+    ok: true;
+    request: SandboxProviderRunRequest;
+    prepared: SandboxProviderPrepareRunResult;
+    result: SandboxProviderRunResult;
+    events: readonly string[];
+} | {
+    ok: false;
+    request: SandboxProviderRunRequest;
+    prepared?: SandboxProviderPrepareRunResult;
+    error: {
+        code: "SANDBOX_PREPARE_FAILED" | "SANDBOX_DENIED" | "SANDBOX_RUN_FAILED";
+        message: string;
+        publicSafe: true;
+        denial?: SandboxProviderDenial | null;
+    };
+    events: readonly string[];
+};
+export type SandboxPolicyMiddlewareAuditEvent = {
+    type: string;
+    actionId: string;
+    sessionId: string;
+    toolId: string;
+    providerId: string;
+    providerFamily: SandboxProviderFamily;
+    payload: Readonly<Record<string, unknown>>;
+};
+export declare const sandboxPolicyMiddlewareDescriptor: {
+    readonly surface: "runtime.sandboxPlane.sandboxPolicyMiddleware";
+    readonly policyOwner: "praxis";
+    readonly providerRole: "environment-and-execution";
+    readonly publicSafe: true;
+};
+export declare function runSandboxPolicyMiddleware(input: {
+    provider: SandboxExecutionProviderPort;
+    request: SandboxProviderRunRequest;
+    decideEnvironmentGap?: (context: {
+        request: SandboxProviderRunRequest;
+        prepared: SandboxProviderPrepareRunResult;
+        environmentGap: SandboxProviderEnvironmentGap;
+    }) => Promise<SandboxPolicyMiddlewareEnvironmentGapDecision> | SandboxPolicyMiddlewareEnvironmentGapDecision;
+    audit?: (event: SandboxPolicyMiddlewareAuditEvent) => Promise<void> | void;
+}): Promise<SandboxPolicyMiddlewareResult>;