@mplp/runtime-minimal 1.0.0

package/src/orchestrator/single-agent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { FlowContract, MplpEvent } from "@mplp/coordination";
+import type { SingleAgentFlowOutput } from "@mplp/coordination";
+import type { RuntimeContext } from "../types/runtime-context";
+import type { RuntimeResult } from "../types/runtime-result";
+import type { RuntimeModuleRegistry } from "../registry/modules-registry";
+import type { ValueStateLayer } from "../vsl";
+export interface SingleAgentRunParams {
+    flow: FlowContract<SingleAgentFlowOutput>;
+    runtimeContext: RuntimeContext;
+    modules: RuntimeModuleRegistry;
+    vsl: ValueStateLayer;
+    emitEvent?: (event: MplpEvent) => void;
+}
+export declare function runSingleAgentFlow(params: SingleAgentRunParams): Promise<RuntimeResult<SingleAgentFlowOutput>>;

package/src/orchestrator/single-agent.js

@@ -0,0 +1,117 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleAgentFlow = runSingleAgentFlow;
+const modules_registry_1 = require("../registry/modules-registry");
+async function runSingleAgentFlow(params) {
+    const { flow, runtimeContext, modules, vsl, emitEvent } = params;
+    let ctx = { ...runtimeContext };
+    const localEmit = (event) => {
+        ctx.events.push(event);
+        if (emitEvent)
+            emitEvent(event);
+    };
+    try {
+        await vsl.saveSnapshot(ctx.ids.runId, ctx);
+        for (const step of flow.steps) {
+            const handler = (0, modules_registry_1.getModuleHandler)(modules, step.module);
+            if (!handler) {
+                return {
+                    success: false,
+                    context: ctx,
+                    error: {
+                        code: "MODULE_NOT_REGISTERED",
+                        message: `No handler registered for module "${step.module}"`
+                    }
+                };
+            }
+            localEmit({
+                id: `${ctx.ids.runId}:${step.module}:start`,
+                kind: "pipeline.stage",
+                timestamp: new Date().toISOString(),
+                runId: ctx.ids.runId,
+                module: step.module,
+                payload: {
+                    stage: step.module,
+                    status: "started"
+                }
+            });
+            const result = await handler({
+                input: step.input,
+                ctx: ctx.coordination,
+                emitEvent: localEmit
+            });
+            if (step.module === "context") {
+                ctx.coordination.context = result.output.context;
+            }
+            else if (step.module === "plan") {
+                ctx.coordination.plan = result.output.plan;
+            }
+            else if (step.module === "confirm") {
+                ctx.coordination.confirm = result.output.confirm;
+            }
+            else if (step.module === "trace") {
+                ctx.coordination.trace = result.output.trace;
+            }
+            if (result.events && result.events.length > 0) {
+                await vsl.appendEvents(ctx.ids.runId, result.events);
+                ctx.events.push(...result.events);
+            }
+            localEmit({
+                id: `${ctx.ids.runId}:${step.module}:completed`,
+                kind: "pipeline.stage",
+                timestamp: new Date().toISOString(),
+                runId: ctx.ids.runId,
+                module: step.module,
+                payload: {
+                    stage: step.module,
+                    status: "completed"
+                }
+            });
+            await vsl.saveSnapshot(ctx.ids.runId, ctx);
+        }
+        const output = {
+            context: ctx.coordination.context,
+            plan: ctx.coordination.plan,
+            confirm: ctx.coordination.confirm,
+            trace: ctx.coordination.trace
+        };
+        return {
+            success: true,
+            context: ctx,
+            output
+        };
+    }
+    catch (err) {
+        localEmit({
+            id: `${ctx.ids.runId}:runtime:error`,
+            kind: "runtime.error",
+            timestamp: new Date().toISOString(),
+            runId: ctx.ids.runId,
+            payload: {
+                code: "RUNTIME_EXCEPTION",
+                message: String(err?.message ?? err),
+                stack: err?.stack
+            }
+        });
+        return {
+            success: false,
+            context: ctx,
+            error: {
+                code: "RUNTIME_EXCEPTION",
+                message: String(err?.message ?? err)
+            }
+        };
+    }
+}

package/src/orchestrator/single-agent.ts

@@ -0,0 +1,139 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { FlowContract, MplpEvent } from "@mplp/coordination";
+import type { SingleAgentFlowOutput } from "@mplp/coordination";
+import type { RuntimeContext } from "../types/runtime-context";
+import type { RuntimeResult } from "../types/runtime-result";
+import type { RuntimeModuleRegistry } from "../registry/modules-registry";
+import { getModuleHandler } from "../registry/modules-registry";
+import type { ValueStateLayer } from "../vsl";
+import type { EmitEvent } from "@mplp/coordination";
+
+export interface SingleAgentRunParams {
+    flow: FlowContract<SingleAgentFlowOutput>;
+    runtimeContext: RuntimeContext;
+    modules: RuntimeModuleRegistry;
+    vsl: ValueStateLayer;
+    emitEvent?: (event: MplpEvent) => void;
+}
+
+export async function runSingleAgentFlow(
+    params: SingleAgentRunParams
+): Promise<RuntimeResult<SingleAgentFlowOutput>> {
+    const { flow, runtimeContext, modules, vsl, emitEvent } = params;
+    let ctx = { ...runtimeContext };
+
+    const localEmit: EmitEvent = (event) => {
+        ctx.events.push(event);
+        if (emitEvent) emitEvent(event);
+    };
+
+    try {
+        await vsl.saveSnapshot(ctx.ids.runId, ctx);
+
+        for (const step of flow.steps) {
+            const handler: any = getModuleHandler(modules, step.module);
+            if (!handler) {
+                return {
+                    success: false,
+                    context: ctx,
+                    error: {
+                        code: "MODULE_NOT_REGISTERED",
+                        message: `No handler registered for module "${step.module}"`
+                    }
+                };
+            }
+
+            localEmit({
+                id: `${ctx.ids.runId}:${step.module}:start`,
+                kind: "pipeline.stage",
+                timestamp: new Date().toISOString(),
+                runId: ctx.ids.runId,
+                module: step.module,
+                payload: {
+                    stage: step.module,
+                    status: "started"
+                }
+            } as any);
+
+            const result = await handler({
+                input: step.input,
+                ctx: ctx.coordination,
+                emitEvent: localEmit
+            });
+
+            if (step.module === "context") {
+                ctx.coordination.context = (result as any).output.context;
+            } else if (step.module === "plan") {
+                ctx.coordination.plan = (result as any).output.plan;
+            } else if (step.module === "confirm") {
+                ctx.coordination.confirm = (result as any).output.confirm;
+            } else if (step.module === "trace") {
+                ctx.coordination.trace = (result as any).output.trace;
+            }
+
+            if (result.events && result.events.length > 0) {
+                await vsl.appendEvents(ctx.ids.runId, result.events);
+                ctx.events.push(...result.events);
+            }
+
+            localEmit({
+                id: `${ctx.ids.runId}:${step.module}:completed`,
+                kind: "pipeline.stage",
+                timestamp: new Date().toISOString(),
+                runId: ctx.ids.runId,
+                module: step.module,
+                payload: {
+                    stage: step.module,
+                    status: "completed"
+                }
+            } as any);
+
+            await vsl.saveSnapshot(ctx.ids.runId, ctx);
+        }
+
+        const output: SingleAgentFlowOutput = {
+            context: ctx.coordination.context!,
+            plan: ctx.coordination.plan!,
+            confirm: ctx.coordination.confirm!,
+            trace: ctx.coordination.trace!
+        };
+
+        return {
+            success: true,
+            context: ctx,
+            output
+        };
+    } catch (err: any) {
+        localEmit({
+            id: `${ctx.ids.runId}:runtime:error`,
+            kind: "runtime.error",
+            timestamp: new Date().toISOString(),
+            runId: ctx.ids.runId,
+            payload: {
+                code: "RUNTIME_EXCEPTION",
+                message: String(err?.message ?? err),
+                stack: err?.stack
+            }
+        } as any);
+
+        return {
+            success: false,
+            context: ctx,
+            error: {
+                code: "RUNTIME_EXCEPTION",
+                message: String(err?.message ?? err)
+            }
+        };
+    }
+}

package/src/registry/modules-registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { ContextModuleHandler, PlanModuleHandler, ConfirmModuleHandler, TraceModuleHandler, RoleModuleHandler, ExtensionModuleHandler, DialogModuleHandler, CollabModuleHandler, CoreModuleHandler, NetworkModuleHandler } from "@mplp/coordination";
+export interface RuntimeModuleRegistry {
+    context?: ContextModuleHandler;
+    plan?: PlanModuleHandler;
+    confirm?: ConfirmModuleHandler;
+    trace?: TraceModuleHandler;
+    role?: RoleModuleHandler;
+    extension?: ExtensionModuleHandler;
+    dialog?: DialogModuleHandler;
+    collab?: CollabModuleHandler;
+    core?: CoreModuleHandler;
+    network?: NetworkModuleHandler;
+}
+export declare function getModuleHandler(registry: RuntimeModuleRegistry, moduleName: string): unknown;

package/src/registry/modules-registry.js

@@ -0,0 +1,41 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getModuleHandler = getModuleHandler;
+function getModuleHandler(registry, moduleName) {
+    switch (moduleName) {
+        case "context":
+            return registry.context;
+        case "plan":
+            return registry.plan;
+        case "confirm":
+            return registry.confirm;
+        case "trace":
+            return registry.trace;
+        case "role":
+            return registry.role;
+        case "extension":
+            return registry.extension;
+        case "dialog":
+            return registry.dialog;
+        case "collab":
+            return registry.collab;
+        case "core":
+            return registry.core;
+        case "network":
+            return registry.network;
+        default:
+            return undefined;
+    }
+}

package/src/registry/modules-registry.ts

@@ -0,0 +1,67 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type {
+    ContextModuleHandler,
+    PlanModuleHandler,
+    ConfirmModuleHandler,
+    TraceModuleHandler,
+    RoleModuleHandler,
+    ExtensionModuleHandler,
+    DialogModuleHandler,
+    CollabModuleHandler,
+    CoreModuleHandler,
+    NetworkModuleHandler
+} from "@mplp/coordination";
+
+export interface RuntimeModuleRegistry {
+    context?: ContextModuleHandler;
+    plan?: PlanModuleHandler;
+    confirm?: ConfirmModuleHandler;
+    trace?: TraceModuleHandler;
+    role?: RoleModuleHandler;
+    extension?: ExtensionModuleHandler;
+    dialog?: DialogModuleHandler;
+    collab?: CollabModuleHandler;
+    core?: CoreModuleHandler;
+    network?: NetworkModuleHandler;
+}
+
+export function getModuleHandler(
+    registry: RuntimeModuleRegistry,
+    moduleName: string
+): unknown {
+    switch (moduleName) {
+        case "context":
+            return registry.context;
+        case "plan":
+            return registry.plan;
+        case "confirm":
+            return registry.confirm;
+        case "trace":
+            return registry.trace;
+        case "role":
+            return registry.role;
+        case "extension":
+            return registry.extension;
+        case "dialog":
+            return registry.dialog;
+        case "collab":
+            return registry.collab;
+        case "core":
+            return registry.core;
+        case "network":
+            return registry.network;
+        default:
+            return undefined;
+    }
+}

package/src/types/runtime-context.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { CoordinationContext } from "@mplp/coordination";
+import type { MplpEvent } from "@mplp/coordination";
+export interface RuntimeIds {
+    runId: string;
+    projectId?: string;
+    correlationId?: string;
+}
+export interface RuntimeOptions {
+    maxRetries?: number;
+    snapshotEveryStep?: boolean;
+}
+export interface RuntimeContext {
+    ids: RuntimeIds;
+    coordination: CoordinationContext;
+    events: MplpEvent[];
+    options?: RuntimeOptions;
+}

package/src/types/runtime-context.js

@@ -0,0 +1,14 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/types/runtime-context.ts

@@ -0,0 +1,32 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { CoordinationContext } from "@mplp/coordination";
+import type { MplpEvent } from "@mplp/coordination";
+
+export interface RuntimeIds {
+    runId: string;
+    projectId?: string;
+    correlationId?: string;
+}
+
+export interface RuntimeOptions {
+    maxRetries?: number;
+    snapshotEveryStep?: boolean;
+}
+
+export interface RuntimeContext {
+    ids: RuntimeIds;
+    coordination: CoordinationContext;
+    events: MplpEvent[];
+    options?: RuntimeOptions;
+}

package/src/types/runtime-result.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { RuntimeContext } from "./runtime-context";
+export interface RuntimeErrorInfo {
+    code: string;
+    message: string;
+}
+export interface RuntimeResult<TOutput = unknown> {
+    success: boolean;
+    output?: TOutput;
+    context: RuntimeContext;
+    error?: RuntimeErrorInfo;
+}

package/src/types/runtime-result.js

@@ -0,0 +1,14 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/types/runtime-result.ts

@@ -0,0 +1,25 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { RuntimeContext } from "./runtime-context";
+
+export interface RuntimeErrorInfo {
+    code: string;
+    message: string;
+}
+
+export interface RuntimeResult<TOutput = unknown> {
+    success: boolean;
+    output?: TOutput;
+    context: RuntimeContext;
+    error?: RuntimeErrorInfo;
+}

package/src/vsl/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { RuntimeContext } from "../types/runtime-context";
+import type { MplpEvent } from "@mplp/coordination";
+export interface ValueStateLayer {
+    saveSnapshot(runId: string, context: RuntimeContext): Promise<void>;
+    loadSnapshot(runId: string): Promise<RuntimeContext | null>;
+    appendEvents(runId: string, events: MplpEvent[]): Promise<void>;
+    getEvents(runId: string): Promise<MplpEvent[]>;
+}
+/**
+ * InMemoryVSL
+ *
+ * Simple in-memory implementation for reference and tests.
+ */
+export declare class InMemoryVSL implements ValueStateLayer {
+    private snapshots;
+    private events;
+    saveSnapshot(runId: string, context: RuntimeContext): Promise<void>;
+    loadSnapshot(runId: string): Promise<RuntimeContext | null>;
+    appendEvents(runId: string, newEvents: MplpEvent[]): Promise<void>;
+    getEvents(runId: string): Promise<MplpEvent[]>;
+}

package/src/vsl/index.js

@@ -0,0 +1,40 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryVSL = void 0;
+/**
+ * InMemoryVSL
+ *
+ * Simple in-memory implementation for reference and tests.
+ */
+class InMemoryVSL {
+    constructor() {
+        this.snapshots = new Map();
+        this.events = new Map();
+    }
+    async saveSnapshot(runId, context) {
+        this.snapshots.set(runId, { ...context });
+    }
+    async loadSnapshot(runId) {
+        return this.snapshots.get(runId) ?? null;
+    }
+    async appendEvents(runId, newEvents) {
+        const existing = this.events.get(runId) ?? [];
+        this.events.set(runId, existing.concat(newEvents));
+    }
+    async getEvents(runId) {
+        return this.events.get(runId) ?? [];
+    }
+}
+exports.InMemoryVSL = InMemoryVSL;

package/src/vsl/index.ts

@@ -0,0 +1,48 @@
+/**
+ * MPLP Protocol v1.0.0 — Frozen Specification
+ * Freeze Date: 2025-12-03
+ * Status: FROZEN (no breaking changes permitted)
+ * Governance: MPLP Protocol Governance Committee (MPGC)
+ *
+ * © 2025 邦士（北京）网络科技有限公司. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+import type { RuntimeContext } from "../types/runtime-context";
+import type { MplpEvent } from "@mplp/coordination";
+
+export interface ValueStateLayer {
+    saveSnapshot(runId: string, context: RuntimeContext): Promise<void>;
+    loadSnapshot(runId: string): Promise<RuntimeContext | null>;
+    appendEvents(runId: string, events: MplpEvent[]): Promise<void>;
+    getEvents(runId: string): Promise<MplpEvent[]>;
+}
+
+/**
+ * InMemoryVSL
+ *
+ * Simple in-memory implementation for reference and tests.
+ */
+export class InMemoryVSL implements ValueStateLayer {
+    private snapshots = new Map<string, RuntimeContext>();
+    private events = new Map<string, MplpEvent[]>();
+
+    async saveSnapshot(runId: string, context: RuntimeContext): Promise<void> {
+        this.snapshots.set(runId, { ...context });
+    }
+
+    async loadSnapshot(runId: string): Promise<RuntimeContext | null> {
+        return this.snapshots.get(runId) ?? null;
+    }
+
+    async appendEvents(runId: string, newEvents: MplpEvent[]): Promise<void> {
+        const existing = this.events.get(runId) ?? [];
+        this.events.set(runId, existing.concat(newEvents));
+    }
+
+    async getEvents(runId: string): Promise<MplpEvent[]> {
+        return this.events.get(runId) ?? [];
+    }
+}