@praxis-ai/praxis 0.1.0

package/dist/agentCore/agent_runtimeImplementation/runtime.execEngine/execEngineRuntime.js

@@ -0,0 +1,102 @@
+/*
+ * 文件定位：Agent 运行态实现层 / 执行引擎运行态绑定面。
+ * 核心目的：承载 exec Engine Runtime 这一能力位点。
+ * 能力要求1：需要把文件名表达的能力落实成清晰的类型、输入输出和最小行为。
+ * 能力要求2：如果后续发现语义不足，应优先补接口契约，而不是把逻辑散落到相邻文件。
+ * 边界：承托和治理运行态，不吞并执行引擎、模型适配器或官方模块内部实现。
+ * 对接：需要服务 applicationSurface、officialModuleSurface、governancePlane、invocationMethod 和 inspection/debug 等运行面。
+ * 实现提示：先补稳定类型契约、最小可测行为和清晰错误边界，再接入真实执行逻辑。
+ */
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function cleanList(values) {
+    return [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
+}
+function normalizeCaller(caller) {
+    const normalized = {
+        kind: caller.kind,
+        id: caller.id.trim(),
+    };
+    const moduleId = caller.moduleId?.trim();
+    if (moduleId !== undefined && moduleId.length > 0) {
+        normalized.moduleId = moduleId;
+    }
+    const sessionId = caller.sessionId?.trim();
+    if (sessionId !== undefined && sessionId.length > 0) {
+        normalized.sessionId = sessionId;
+    }
+    return normalized;
+}
+function failure(code, message, boundary) {
+    return {
+        ok: false,
+        error: { code, message, boundary, publicSafe: true },
+        events: ["runtime.execEngine.rejected"],
+    };
+}
+function normalizeBinding(binding) {
+    const surface = binding.surface?.trim();
+    const bindingId = binding.bindingId?.trim();
+    if (!hasText(surface)) {
+        return failure("MISSING_BINDING_SURFACE", "execEngine runtime bindings require a surface", "binding");
+    }
+    if (!hasText(bindingId)) {
+        return failure("MISSING_BINDING_ID", "execEngine runtime bindings require a bindingId", "binding");
+    }
+    if (binding.ready === false) {
+        return failure("BINDING_NOT_READY", `execEngine binding ${bindingId} is not ready`, "binding");
+    }
+    return {
+        surface,
+        bindingId,
+        ready: true,
+        capabilities: cleanList(binding.capabilities),
+        metadata: binding.metadata ?? {},
+    };
+}
+export function createExecEngineRuntime(request) {
+    if (request === undefined || !hasText(request.runtimeId)) {
+        return failure("MISSING_RUNTIME_ID", "execEngine runtime requires a runtimeId", "input");
+    }
+    if (request.caller === undefined || !hasText(request.caller.id)) {
+        return failure("MISSING_CALLER", "execEngine runtime requires an application, module, or runtime caller", "input");
+    }
+    if (request.runtimeReady === false) {
+        return failure("RUNTIME_NOT_READY", "execEngine runtime can only bind through a ready runtime host", "runtime-state");
+    }
+    if (request.contract?.accepted === false) {
+        return failure("CONTRACT_REJECTED", request.contract.reason ?? "execEngine runtime was rejected by contract surface", "contract");
+    }
+    if (request.governance?.accepted === false) {
+        return failure("GOVERNANCE_REJECTED", request.governance.reason ?? "execEngine runtime was rejected by governance", "governance");
+    }
+    if ((request.bindings ?? []).length === 0) {
+        return failure("MISSING_BINDINGS", "execEngine runtime requires at least one narrow binding", "input");
+    }
+    const bindings = [];
+    for (const binding of request.bindings ?? []) {
+        const normalized = normalizeBinding(binding);
+        if ("ok" in normalized) {
+            return normalized;
+        }
+        bindings.push(normalized);
+    }
+    return {
+        ok: true,
+        runtime: {
+            runtimeId: request.runtimeId.trim(),
+            caller: normalizeCaller(request.caller),
+            route: "runtime.execEngine",
+            phase: "bound",
+            bindings,
+            bindingIds: bindings.map((binding) => binding.bindingId),
+            surfaces: bindings.map((binding) => binding.surface),
+            governanceChecked: true,
+            contractChecked: true,
+            dryRun: true,
+            unsafeSideEffects: false,
+        },
+        events: ["runtime.execEngine.bound"],
+    };
+}

package/dist/agentCore/agent_runtimeImplementation/runtime.execEngine/execEngineStateBridge.d.ts

@@ -0,0 +1,53 @@
+import type { ExecEngineRuntimeCaller, ExecEngineRuntimeGate } from "./execEngineRuntime.js";
+export type ExecEngineStateBridgeBoundary = "input" | "contract" | "governance" | "runtime-state" | "state";
+export type ExecEngineStatePhase = "unbound" | "bound" | "ready" | "running" | "paused" | "failed";
+export type ExecEngineStateBridgeErrorCode = "MISSING_RUNTIME_ID" | "MISSING_CALLER" | "MISSING_STATE" | "MISSING_STATE_ID" | "MISSING_PHASE" | "UNKNOWN_PHASE" | "RUNTIME_NOT_READY" | "CONTRACT_REJECTED" | "GOVERNANCE_REJECTED";
+export type ExecEngineStateBridgeError = {
+    code: ExecEngineStateBridgeErrorCode;
+    message: string;
+    boundary: ExecEngineStateBridgeBoundary;
+    publicSafe: true;
+};
+export type ExecEngineStateInput = {
+    stateId?: string;
+    phase?: ExecEngineStatePhase | string;
+    cursor?: string;
+    revision?: number;
+    updatedAt?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ExecEngineStateBridgeRequest = {
+    runtimeId?: string;
+    caller?: ExecEngineRuntimeCaller;
+    state?: ExecEngineStateInput;
+    runtimeReady?: boolean;
+    contract?: ExecEngineRuntimeGate;
+    governance?: ExecEngineRuntimeGate;
+};
+export type ExecEngineStateSnapshot = {
+    bridgeId: string;
+    runtimeId: string;
+    caller: ExecEngineRuntimeCaller;
+    stateId: string;
+    phase: ExecEngineStatePhase;
+    cursor?: string;
+    revision: number;
+    updatedAt?: string;
+    metadata: Readonly<Record<string, unknown>>;
+    route: "runtime.execEngine.stateBridge";
+    readonly: true;
+    contractChecked: true;
+    governanceChecked: true;
+    dryRun: true;
+    unsafeSideEffects: false;
+};
+export type ExecEngineStateBridgeResult = {
+    ok: true;
+    snapshot: ExecEngineStateSnapshot;
+    events: readonly string[];
+} | {
+    ok: false;
+    error: ExecEngineStateBridgeError;
+    events: readonly string[];
+};
+export declare function bridgeExecEngineState(request?: ExecEngineStateBridgeRequest): ExecEngineStateBridgeResult;

package/dist/agentCore/agent_runtimeImplementation/runtime.execEngine/execEngineStateBridge.js

@@ -0,0 +1,91 @@
+/*
+ * 文件定位：Agent 运行态实现层 / 执行引擎运行态绑定面。
+ * 核心目的：承载 exec Engine State Bridge 这一能力位点。
+ * 能力要求1：需要把文件名表达的能力落实成清晰的类型、输入输出和最小行为。
+ * 能力要求2：如果后续发现语义不足，应优先补接口契约，而不是把逻辑散落到相邻文件。
+ * 边界：承托和治理运行态，不吞并执行引擎、模型适配器或官方模块内部实现。
+ * 对接：需要服务 applicationSurface、officialModuleSurface、governancePlane、invocationMethod 和 inspection/debug 等运行面。
+ * 实现提示：先补稳定类型契约、最小可测行为和清晰错误边界，再接入真实执行逻辑。
+ */
+const knownStatePhases = new Set(["unbound", "bound", "ready", "running", "paused", "failed"]);
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isExecEngineStatePhase(value) {
+    return knownStatePhases.has(value);
+}
+function normalizeCaller(caller) {
+    const normalized = {
+        kind: caller.kind,
+        id: caller.id.trim(),
+    };
+    const moduleId = caller.moduleId?.trim();
+    if (moduleId !== undefined && moduleId.length > 0) {
+        normalized.moduleId = moduleId;
+    }
+    const sessionId = caller.sessionId?.trim();
+    if (sessionId !== undefined && sessionId.length > 0) {
+        normalized.sessionId = sessionId;
+    }
+    return normalized;
+}
+function failure(code, message, boundary) {
+    return {
+        ok: false,
+        error: { code, message, boundary, publicSafe: true },
+        events: ["runtime.execEngine.stateBridge.rejected"],
+    };
+}
+export function bridgeExecEngineState(request) {
+    if (request === undefined || !hasText(request.runtimeId)) {
+        return failure("MISSING_RUNTIME_ID", "execEngine state bridge requires a runtimeId", "input");
+    }
+    if (request.caller === undefined || !hasText(request.caller.id)) {
+        return failure("MISSING_CALLER", "execEngine state bridge requires a caller", "input");
+    }
+    if (request.state === undefined) {
+        return failure("MISSING_STATE", "execEngine state bridge requires a state input", "input");
+    }
+    if (!hasText(request.state.stateId)) {
+        return failure("MISSING_STATE_ID", "execEngine state bridge requires a stateId", "input");
+    }
+    if (!hasText(request.state.phase)) {
+        return failure("MISSING_PHASE", "execEngine state bridge requires a phase", "input");
+    }
+    const phase = request.state.phase.trim();
+    if (!isExecEngineStatePhase(phase)) {
+        return failure("UNKNOWN_PHASE", `execEngine state phase ${phase} is not recognized by this bridge`, "state");
+    }
+    if (request.runtimeReady === false) {
+        return failure("RUNTIME_NOT_READY", "execEngine state bridge requires a ready runtime host", "runtime-state");
+    }
+    if (request.contract?.accepted === false) {
+        return failure("CONTRACT_REJECTED", request.contract.reason ?? "execEngine state bridge was rejected by contract surface", "contract");
+    }
+    if (request.governance?.accepted === false) {
+        return failure("GOVERNANCE_REJECTED", request.governance.reason ?? "execEngine state bridge was rejected by governance", "governance");
+    }
+    const runtimeId = request.runtimeId.trim();
+    const stateId = request.state.stateId.trim();
+    return {
+        ok: true,
+        snapshot: {
+            bridgeId: `${runtimeId}:state:${stateId}`,
+            runtimeId,
+            caller: normalizeCaller(request.caller),
+            stateId,
+            phase,
+            cursor: request.state.cursor?.trim() || undefined,
+            revision: request.state.revision ?? 0,
+            updatedAt: request.state.updatedAt?.trim() || undefined,
+            metadata: request.state.metadata ?? {},
+            route: "runtime.execEngine.stateBridge",
+            readonly: true,
+            contractChecked: true,
+            governanceChecked: true,
+            dryRun: true,
+            unsafeSideEffects: false,
+        },
+        events: ["runtime.execEngine.stateBridge.snapshotted"],
+    };
+}

package/dist/agentCore/agent_runtimeImplementation/runtime.execEngine/mcpRuntimeAdapter.d.ts

@@ -0,0 +1,23 @@
+import type { BaseToolExecutorPort } from "../../agent_executionEngine/basic_toolLayer/baseTools/baseToolExecutorPort.js";
+export type McpRuntimeTransportKind = "stdio" | "http" | "sse";
+export type McpRuntimeServerProfile = {
+    serverId: string;
+    transport: "stdio";
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    timeoutMs?: number;
+    framing?: "content-length" | "line-json";
+} | {
+    serverId: string;
+    transport: "http" | "sse";
+    url: string;
+    sseUrl?: string;
+    headers?: Readonly<Record<string, string>>;
+    timeoutMs?: number;
+};
+export type McpRuntimeAdapterOptions = {
+    servers: readonly McpRuntimeServerProfile[];
+};
+export declare function createMcpRuntimeAdapter(options: McpRuntimeAdapterOptions): NonNullable<BaseToolExecutorPort["mcp"]>;