@praxis-ai/praxis 0.1.1 → 0.1.2

package/dist/runtimeImplementation/runtime.mcpPlane/index.js

@@ -0,0 +1,167 @@
+/*
+ * 文件定位：Runtime MCP Plane / 官方 MCP 与 MCP+ 组件接入面。
+ * 核心目的：把标准 MCP server 声明、MCP+ exposure policy、runtime server profile、
+ * dynamic harness tools 和 application view 串成一条 OAO 可编译、可检查、可挂载的合同。
+ */
+import { compileMcpPlusManifest, lowerExposurePlanToMcpSurface, planExposure, } from "@praxis-ai/mcp-plus";
+export function mcpServer(serverId, input) {
+    return {
+        ...input,
+        serverId,
+        mode: input.mode ?? (input.manifest === undefined ? "native" : "mcp-plus"),
+    };
+}
+export const mcp = {
+    module(input) {
+        return {
+            kind: "praxis.mcp.module",
+            version: "praxis.mcp.v1",
+            servers: input.servers,
+            recommended: true,
+            metadata: input.metadata,
+        };
+    },
+    stdio(serverId, input) {
+        return mcpServer(serverId, { ...input, transport: "stdio" });
+    },
+    http(serverId, input) {
+        return mcpServer(serverId, { ...input, transport: "http" });
+    },
+    sse(serverId, input) {
+        return mcpServer(serverId, { ...input, transport: "sse" });
+    },
+    recommendedTools() {
+        return [
+            {
+                toolId: "mcp.use",
+                metadata: { source: "praxis.mcp.recommendedTools", toolProviderKind: "mcp-static" },
+            },
+            {
+                toolId: "mcp.resources",
+                metadata: { source: "praxis.mcp.recommendedTools", toolProviderKind: "mcp-static" },
+            },
+        ];
+    },
+};
+export function isMcpHarnessModuleSpec(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.kind === "praxis.mcp.module" && Array.isArray(record.servers);
+}
+export function mcpHarnessModuleFrom(input) {
+    const candidate = input.modules?.mcp;
+    return isMcpHarnessModuleSpec(candidate) ? candidate : undefined;
+}
+export function runtimeRequirementsForMcpModule(module) {
+    return module === undefined || module.servers.length === 0 ? [] : ["runtime.mcp"];
+}
+export function toMcpRuntimeServerProfile(server) {
+    if (server.transport === "stdio") {
+        return {
+            serverId: server.serverId,
+            transport: "stdio",
+            command: server.command,
+            args: server.args,
+            cwd: server.cwd,
+            env: server.env,
+            timeoutMs: server.timeoutMs,
+            framing: server.framing,
+        };
+    }
+    return {
+        serverId: server.serverId,
+        transport: server.transport,
+        url: server.url,
+        sseUrl: server.sseUrl,
+        headers: server.headers,
+        timeoutMs: server.timeoutMs,
+    };
+}
+export function buildMcpServerProfilesFromManifest(input) {
+    const module = mcpHarnessModuleFrom(input.harness);
+    return (module?.servers ?? []).map(toMcpRuntimeServerProfile);
+}
+export function createMcpApplicationStateView(module) {
+    return {
+        servers: (module?.servers ?? []).map((server) => ({
+            serverId: server.serverId,
+            mode: server.mode,
+            transport: server.transport,
+            title: server.title ?? server.manifest?.server.title,
+            summary: server.summary ?? server.manifest?.server.summary,
+            manifestPresent: server.manifest !== undefined,
+            status: "declared",
+            publicSafe: true,
+        })),
+        recommendedMode: "mcp-plus",
+        nativeCompatible: true,
+        publicSafe: true,
+    };
+}
+function toolIdPart(value) {
+    return value.replace(/[^a-zA-Z0-9_-]+/gu, ".").replace(/^\.+|\.+$/gu, "") || "tool";
+}
+function dynamicToolSpecForNativeTool(serverId, tool) {
+    return {
+        toolId: `mcp.${toolIdPart(serverId)}.${toolIdPart(tool.name)}`,
+        family: "mcp",
+        group: serverId,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        metadata: {
+            toolProviderKind: "mcp-static",
+            serverId,
+            nativeToolName: tool.name,
+            runtimeToolId: "mcp.use",
+            runtimeArguments: { serverId, toolName: tool.name },
+            source: "runtime.mcpPlane.dynamicTool",
+        },
+    };
+}
+function dynamicToolSpecsForSurface(serverId, surface) {
+    return surface.tools
+        .filter((tool) => tool.name !== "mcp_plus.expand")
+        .map((tool) => dynamicToolSpecForNativeTool(serverId, tool));
+}
+export function planMcpHarnessExposure(manifest, nativeToolInventoryByServerId, stateByServerId = {}) {
+    const module = mcpHarnessModuleFrom(manifest.harness);
+    const servers = (module?.servers ?? []).map((server) => {
+        const nativeTools = [...(nativeToolInventoryByServerId[server.serverId] ?? [])];
+        if (server.mode !== "mcp-plus" || server.manifest === undefined) {
+            const surface = {
+                tools: nativeTools,
+                sidecar: {
+                    serverCard: {
+                        id: server.serverId,
+                        title: server.title ?? server.serverId,
+                        summary: server.summary ?? "Native MCP server.",
+                        mode: "expanded",
+                    },
+                    toolIndex: [],
+                    skillIndex: [],
+                },
+            };
+            return {
+                serverId: server.serverId,
+                mode: "native",
+                surface,
+                dynamicToolSpecs: nativeTools.map((tool) => dynamicToolSpecForNativeTool(server.serverId, tool)),
+            };
+        }
+        const graph = compileMcpPlusManifest(server.manifest, nativeTools);
+        const state = {
+            serverId: server.serverId,
+            mode: stateByServerId[server.serverId]?.mode ?? "expanded",
+            activeTools: stateByServerId[server.serverId]?.activeTools ?? [],
+        };
+        const surface = lowerExposurePlanToMcpSurface(planExposure(graph, state));
+        return {
+            serverId: server.serverId,
+            mode: "mcp-plus",
+            surface,
+            dynamicToolSpecs: dynamicToolSpecsForSurface(server.serverId, surface),
+        };
+    });
+    return { servers };
+}

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

@@ -4,8 +4,6 @@
  * 边界：只规划沙箱强度和降级，不真正执行工具或回滚。
  */
 function requestedModeFor(profile) {
-    if (profile === "bapr")
-        return "none";
     if (profile === "yolo")
         return "workspace-rollback";
     return "isolated";

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

@@ -0,0 +1,19 @@
+import { RaxcellClient } from "@praxis-ai/raxcell";
+import type { RunRequest } from "@praxis-ai/raxcell";
+import type { SandboxExecutionProviderPort, SandboxProviderRunRequest } from "./sandboxPolicyMiddleware.js";
+export type RaxcellClientLike = Pick<RaxcellClient, "prepareRun" | "run">;
+export type RaxcellSandboxProviderOptions = {
+    client: RaxcellClientLike;
+    providerId?: string;
+} | {
+    binaryPath: string;
+    providerId?: string;
+};
+export declare const raxcellSandboxProviderDescriptor: {
+    readonly surface: "runtime.sandboxPlane.raxcellSandboxProvider";
+    readonly providerFamily: "linux-bubblewrap";
+    readonly policyOwner: "praxis";
+    readonly role: "environment-and-execution";
+};
+export declare function mapSandboxProviderRequestToRaxcell(request: SandboxProviderRunRequest): RunRequest;
+export declare function createRaxcellSandboxProvider(options: RaxcellSandboxProviderOptions): SandboxExecutionProviderPort;

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

@@ -0,0 +1,172 @@
+/*
+ * 文件定位：Agent 运行态实现层 / Raxcell 官方沙箱 provider。
+ * 核心目的：把 Praxis sandbox provider-neutral request 映射到 Raxcell prepareRun/run 协议。
+ * 边界：Raxcell 只提供环境事实与执行；策略、审批、fallback 决策仍归 Praxis middleware。
+ */
+import { RaxcellClient } from "@praxis-ai/raxcell";
+export const raxcellSandboxProviderDescriptor = {
+    surface: "runtime.sandboxPlane.raxcellSandboxProvider",
+    providerFamily: "linux-bubblewrap",
+    policyOwner: "praxis",
+    role: "environment-and-execution",
+};
+function clientFromOptions(options) {
+    if ("client" in options)
+        return options.client;
+    return new RaxcellClient({ binaryPath: options.binaryPath });
+}
+function cleanEnv(env) {
+    const output = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined)
+            output[key] = value;
+    }
+    return output;
+}
+function networkForRaxcell(value) {
+    if (value === "allow" || value === "deny")
+        return value;
+    return "deny";
+}
+function grantForRaxcell(grant) {
+    return {
+        reason: grant.reason,
+        path: grant.path,
+        access: grant.access === undefined ? undefined : [...grant.access],
+        grantedBy: grant.grantedBy ?? null,
+    };
+}
+export function mapSandboxProviderRequestToRaxcell(request) {
+    return {
+        kind: "raxcell.run.v1",
+        backendPreference: ["linux-bubblewrap"],
+        policyGrants: request.policyGrants.map(grantForRaxcell),
+        action: {
+            actionId: request.action.actionId,
+            ownerRuntime: request.action.ownerRuntime,
+            intentLabel: request.action.intentLabel,
+            metadata: {
+                runtimeId: request.action.runtimeId,
+                sessionId: request.action.sessionId,
+                toolId: request.action.toolId,
+                policyProfile: request.policy.profile,
+                sandboxId: request.policy.sandboxId,
+                sandboxMode: request.policy.sandboxMode,
+                ...request.action.metadata,
+                ...request.metadata,
+            },
+        },
+        command: {
+            argv: [...request.command.argv],
+            cwd: request.command.cwd,
+            env: cleanEnv(request.command.env),
+            stdin: request.command.stdin,
+        },
+        enforcement: {
+            profile: request.policy.profile,
+            filesystem: {
+                read: [...request.filesystem.read],
+                write: [...request.filesystem.write],
+            },
+            network: networkForRaxcell(request.policy.network),
+            process: request.policy.process,
+            resources: request.policy.resources,
+        },
+        fallback: request.fallback,
+    };
+}
+function providerFamily(value) {
+    if (value === "linux-bubblewrap")
+        return "linux-bubblewrap";
+    if (value === "host-observed")
+        return "host-observed";
+    if (value === "external")
+        return "external";
+    return "external";
+}
+function denial(value) {
+    if (value === null || value === undefined)
+        return null;
+    return {
+        code: value.code,
+        message: value.message,
+        publicSafe: true,
+    };
+}
+function environmentGap(value) {
+    if (value === null || value === undefined)
+        return null;
+    return {
+        reason: value.reason,
+        path: value.path ?? "",
+        required: value.required,
+        publicSafeMessage: value.publicSafeMessage,
+    };
+}
+function filesystemLowering(value) {
+    if (value === null || value === undefined)
+        return null;
+    return {
+        declaredRoots: value.declaredRoots,
+        runtimeRoots: value.runtimeRoots,
+        policyGrants: value.policyGrants,
+        warnings: value.warnings,
+        effects: value.effects,
+    };
+}
+function backendArtifacts(value) {
+    return value.map((artifact) => ({
+        backend: providerFamily(artifact.backend),
+        format: artifact.format,
+        arguments: artifact.arguments,
+        data: artifact.data,
+        warnings: artifact.warnings,
+    }));
+}
+function prepareResult(value) {
+    return {
+        kind: "runtime.sandboxPlane.provider.prepareRunResult",
+        ok: value.ok,
+        providerFamily: providerFamily(value.backend),
+        denial: denial(value.denial),
+        environmentGap: environmentGap(value.environmentGap ?? value.policyDecision),
+        filesystemLowering: filesystemLowering(value.filesystemLowering),
+        backendArtifacts: backendArtifacts(value.backendArtifacts),
+        metadata: {
+            raxcellKind: value.kind,
+            capabilityReport: value.capabilityReport,
+        },
+    };
+}
+function runResult(value) {
+    return {
+        kind: "runtime.sandboxPlane.provider.runResult",
+        ok: value.ok,
+        providerFamily: providerFamily(value.backend),
+        exitCode: value.exitCode,
+        stdout: value.stdout,
+        stderr: value.stderr,
+        timedOut: value.timedOut,
+        denial: denial(value.denial),
+        environmentGap: environmentGap(value.environmentGap ?? value.policyDecision),
+        filesystemLowering: filesystemLowering(value.filesystemLowering),
+        metadata: {
+            raxcellKind: value.kind,
+            fallback: value.fallback,
+            capabilityReport: value.capabilityReport,
+        },
+    };
+}
+export function createRaxcellSandboxProvider(options) {
+    const client = clientFromOptions(options);
+    return {
+        providerId: options.providerId ?? "raxcell",
+        providerFamily: "linux-bubblewrap",
+        async prepareRun(request) {
+            return prepareResult(await client.prepareRun(mapSandboxProviderRequestToRaxcell(request)));
+        },
+        async run(request) {
+            return runResult(await client.run(mapSandboxProviderRequestToRaxcell(request)));
+        },
+    };
+}

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

@@ -1,5 +1,6 @@
 import type { BaseToolPolicyProfile, SandboxSpec } from "../runtimeAgentManifest.js";
-import type { SandboxRuntimePrepareResult } from "./sandboxRuntimeProvider.js";
+import { type SandboxRuntimePrepareResult } from "./sandboxRuntimeProvider.js";
+import { type SandboxExecutionProviderPort, type SandboxPolicyMiddlewareAuditEvent, type SandboxPolicyMiddlewareEnvironmentGapDecision, type SandboxProviderEnvironmentGap, type SandboxProviderPolicyGrant, type SandboxProviderRunRequest } from "./sandboxPolicyMiddleware.js";
 import { type WorkspaceRollbackFinalizeResult, type WorkspaceRollbackSnapshot } from "./workspaceRollbackSandbox.js";
 export type SandboxCommandProviderFamily = "host-observed" | "workspace-policy" | "workspace-rollback" | "linux-bubblewrap" | "macos-containerization" | "windows-sandbox" | "remote-worker";
 export type SandboxCommandNetworkPolicy = "deny" | "allow" | "approval" | "provider-policy";
@@ -28,6 +29,11 @@ export type SandboxCommandRequest = {
     sandboxMode?: "none" | "workspace-rollback" | "isolated";
     filesystem?: Partial<SandboxCommandFilesystemPolicy>;
     network?: SandboxCommandNetworkPolicy;
+    policyGrants?: readonly SandboxProviderPolicyGrant[];
+    approval?: {
+        accepted: boolean;
+        grantedBy?: string;
+    };
     metadata?: Readonly<Record<string, unknown>>;
 };
 export type SandboxCommandPlan = {
@@ -95,6 +101,12 @@ export type SandboxRemoteWorkerAdapter = (request: SandboxCommandRequest, plan:
 }>;
 export type SandboxCommandRunnerOptions = {
     remoteWorker?: SandboxRemoteWorkerAdapter;
+    sandboxProvider?: SandboxExecutionProviderPort;
+    decideEnvironmentGap?: (context: {
+        request: SandboxProviderRunRequest;
+        environmentGap: SandboxProviderEnvironmentGap;
+    }) => Promise<SandboxPolicyMiddlewareEnvironmentGapDecision> | SandboxPolicyMiddlewareEnvironmentGapDecision;
+    audit?: (event: SandboxPolicyMiddlewareAuditEvent) => Promise<void> | void;
 };
 export declare const sandboxCommandRunnerDescriptor: {
     readonly surface: "runtime.sandboxPlane.sandboxCommandRunner";