@mplp/sdk-ts 1.0.1 → 1.0.3

package/schemas/mplp-plan.schema.json

@@ -0,0 +1,199 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.mplp.dev/v1.0/mplp-plan.schema.json",
+  "title": "MPLP Plan Module – Core Protocol v1.0",
+  "description": "Plan Module Core Protocol: Describes the plan objects and their lifecycle minimal required semantics (Core Profile) in multi-agent collaboration.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "$ref": "common/metadata.schema.json",
+      "description": "[PROTOCOL-CORE] MPLP protocol schema metadata (version, source, cross-cutting tags, etc.)."
+    },
+    "plan_id": {
+      "$ref": "common/identifiers.schema.json",
+      "description": "[PROTOCOL-CORE] Global unique identifier for the Plan."
+    },
+    "context_id": {
+      "$ref": "common/identifiers.schema.json",
+      "description": "[PROTOCOL-CORE] Identifier of the Context this Plan belongs to."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "[PROTOCOL-CORE] Plan title (brief description for humans and Agents)."
+    },
+    "objective": {
+      "type": "string",
+      "minLength": 1,
+      "description": "[PROTOCOL-CORE] Description of the objective to be achieved by the Plan."
+    },
+    "status": {
+      "type": "string",
+      "description": "[PROTOCOL-CORE] Status of the Plan in its lifecycle.",
+      "enum": [
+        "draft",
+        "proposed",
+        "approved",
+        "in_progress",
+        "completed",
+        "cancelled",
+        "failed"
+      ]
+    },
+    "steps": {
+      "type": "array",
+      "description": "[PROTOCOL-CORE] List of core steps decomposed from the Plan.",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/plan_step_core"
+      }
+    },
+    "trace": {
+      "$ref": "common/trace-base.schema.json",
+      "description": "[PROTOCOL-CORE] Main execution trace reference associated with this Plan."
+    },
+    "events": {
+      "type": "array",
+      "description": "[PROTOCOL-CORE] List of key events directly associated with this Plan (changes, approvals, status transitions, etc.).",
+      "items": {
+        "$ref": "common/events.schema.json"
+      }
+    }
+  },
+  "required": [
+    "meta",
+    "plan_id",
+    "context_id",
+    "title",
+    "objective",
+    "status",
+    "steps"
+  ],
+  "$defs": {
+    "plan_core_properties": {
+      "type": "object",
+      "properties": {
+        "meta": {
+          "$ref": "common/metadata.schema.json",
+          "description": "[PROTOCOL-CORE] MPLP protocol schema metadata (version, source, cross-cutting tags, etc.)."
+        },
+        "plan_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Global unique identifier for the Plan."
+        },
+        "context_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Identifier of the Context this Plan belongs to."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "[PROTOCOL-CORE] Plan title (brief description for humans and Agents)."
+        },
+        "objective": {
+          "type": "string",
+          "minLength": 1,
+          "description": "[PROTOCOL-CORE] Description of the objective to be achieved by the Plan."
+        },
+        "status": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Status of the Plan in its lifecycle.",
+          "enum": [
+            "draft",
+            "proposed",
+            "approved",
+            "in_progress",
+            "completed",
+            "cancelled",
+            "failed"
+          ]
+        },
+        "steps": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] List of core steps decomposed from the Plan.",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/plan_step_core"
+          }
+        },
+        "trace": {
+          "$ref": "common/trace-base.schema.json",
+          "description": "[PROTOCOL-CORE] Main execution trace reference associated with this Plan."
+        },
+        "events": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] List of key events directly associated with this Plan (changes, approvals, status transitions, etc.).",
+          "items": {
+            "$ref": "common/events.schema.json"
+          }
+        }
+      },
+      "required": [
+        "meta",
+        "plan_id",
+        "context_id",
+        "title",
+        "objective",
+        "status",
+        "steps"
+      ]
+    },
+    "plan_step_core": {
+      "type": "object",
+      "description": "[PROTOCOL-CORE] Minimal required semantics for a plan step (excluding execution engine, scheduling policy implementation details).",
+      "additionalProperties": false,
+      "properties": {
+        "step_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Global unique identifier for the step."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "[PROTOCOL-CORE] Content of the work to be completed in the step."
+        },
+        "status": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Current status of the step.",
+          "enum": [
+            "pending",
+            "in_progress",
+            "completed",
+            "blocked",
+            "skipped",
+            "failed"
+          ]
+        },
+        "dependencies": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] List of other step IDs that this step depends on.",
+          "items": {
+            "$ref": "common/identifiers.schema.json"
+          }
+        },
+        "agent_role": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Identifier of the role responsible for this step (should correspond to role_id in Role module)."
+        },
+        "order_index": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "[PROTOCOL-CORE] Sort index in the current Plan, used for defining execution order or display order."
+        }
+      },
+      "required": [
+        "step_id",
+        "description",
+        "status"
+      ]
+    }
+  },
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/mplp-role.schema.json

@@ -0,0 +1,145 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.mplp.dev/v1.0/mplp-role.schema.json",
+  "title": "MPLP Role Module – Core Protocol v1.0",
+  "description": "Role Module Core Protocol: Describes the minimal required semantics (Core Profile) for capability declarations, permission declarations, and behavioral identity models in multi-agent systems.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "$ref": "common/metadata.schema.json",
+      "description": "[PROTOCOL-CORE] MPLP protocol schema metadata (version, source, cross-cutting tags, etc.)."
+    },
+    "governance": {
+      "type": "object",
+      "description": "[PROTOCOL-CORE] Governance metadata for lifecycle management, truth domain authority, and locking status.",
+      "properties": {
+        "lifecyclePhase": {
+          "type": "string",
+          "description": "Current phase in the lifecycle fence (e.g., 'design', 'implementation', 'review')."
+        },
+        "truthDomain": {
+          "type": "string",
+          "description": "The truth domain this object belongs to (e.g., 'requirements', 'architecture')."
+        },
+        "locked": {
+          "type": "boolean",
+          "description": "If true, this object cannot be modified except by specific governance overrides."
+        },
+        "lastConfirmRef": {
+          "$ref": "common/common-types.schema.json#/definitions/Ref",
+          "description": "Reference to the last Confirm decision that validated this state."
+        }
+      },
+      "additionalProperties": false
+    },
+    "role_id": {
+      "$ref": "common/identifiers.schema.json",
+      "description": "[PROTOCOL-CORE] Global unique identifier for the Role."
+    },
+    "name": {
+      "type": "string",
+      "description": "[PROTOCOL-CORE] Human-readable name of the role (e.g., 'planner', 'reviewer', 'executor')."
+    },
+    "description": {
+      "type": "string",
+      "description": "[PROTOCOL-CORE] Detailed description of the role function, for humans and Agents."
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "[PROTOCOL-CORE] List of capability/permission tags possessed by the role (e.g., 'plan.create', 'confirm.approve').",
+      "items": {
+        "type": "string"
+      }
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "[PROTOCOL-CORE] Role creation time (ISO 8601)."
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "[PROTOCOL-CORE] Role last update time (ISO 8601)."
+    },
+    "trace": {
+      "$ref": "common/trace-base.schema.json",
+      "description": "[PROTOCOL-CORE] Audit trace reference associated with this role."
+    },
+    "events": {
+      "type": "array",
+      "description": "[PROTOCOL-CORE] List of key events directly related to this role (creation, permission changes, deactivation, etc.).",
+      "items": {
+        "$ref": "common/events.schema.json"
+      }
+    }
+  },
+  "required": [
+    "meta",
+    "role_id",
+    "name"
+  ],
+  "$defs": {
+    "role_core_properties": {
+      "type": "object",
+      "properties": {
+        "meta": {
+          "$ref": "common/metadata.schema.json",
+          "description": "[PROTOCOL-CORE] MPLP protocol schema metadata (version, source, cross-cutting tags, etc.)."
+        },
+        "role_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Global unique identifier for the Role."
+        },
+        "name": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Human-readable name of the role (e.g., 'planner', 'reviewer', 'executor')."
+        },
+        "description": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Detailed description of the role function, for humans and Agents."
+        },
+        "capabilities": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] List of capability/permission tags possessed by the role (e.g., 'plan.create', 'confirm.approve').",
+          "items": {
+            "type": "string"
+          }
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "[PROTOCOL-CORE] Role creation time (ISO 8601)."
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "[PROTOCOL-CORE] Role last update time (ISO 8601)."
+        },
+        "trace": {
+          "$ref": "common/trace-base.schema.json",
+          "description": "[PROTOCOL-CORE] Audit trace reference associated with this role."
+        },
+        "events": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] List of key events directly related to this role (creation, permission changes, deactivation, etc.).",
+          "items": {
+            "$ref": "common/events.schema.json"
+          }
+        }
+      },
+      "required": [
+        "meta",
+        "role_id",
+        "name"
+      ]
+    }
+  },
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/schemas/mplp-trace.schema.json

@@ -0,0 +1,222 @@
+{
+  "$comment": "MPLP v1.0.0 FROZEN – © 2025 邦士（北京）网络科技有限公司 – Apache-2.0 – Governance: MPGC",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.mplp.dev/v1.0/mplp-trace.schema.json",
+  "title": "MPLP Trace Module – Core Protocol v1.0",
+  "description": "Trace Module Core Protocol: Describes the minimal required semantics (Core Profile) for execution trace resources (Trace) and their key segments and events.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "$ref": "common/metadata.schema.json",
+      "description": "[PROTOCOL-CORE] MPLP protocol and schema metadata."
+    },
+    "governance": {
+      "type": "object",
+      "description": "[PROTOCOL-CORE] Governance metadata for lifecycle management, truth domain authority, and locking status.",
+      "properties": {
+        "lifecyclePhase": {
+          "type": "string",
+          "description": "Current phase in the lifecycle fence (e.g., 'design', 'implementation', 'review')."
+        },
+        "truthDomain": {
+          "type": "string",
+          "description": "The truth domain this object belongs to (e.g., 'requirements', 'architecture')."
+        },
+        "locked": {
+          "type": "boolean",
+          "description": "If true, this object cannot be modified except by specific governance overrides."
+        },
+        "lastConfirmRef": {
+          "$ref": "common/common-types.schema.json#/definitions/Ref",
+          "description": "Reference to the last Confirm decision that validated this state."
+        }
+      },
+      "additionalProperties": false
+    },
+    "trace_id": {
+      "$ref": "common/identifiers.schema.json",
+      "description": "[PROTOCOL-CORE] Global unique identifier for the Trace."
+    },
+    "context_id": {
+      "$ref": "common/identifiers.schema.json",
+      "description": "[PROTOCOL-CORE] Identifier of the Context this Trace belongs to."
+    },
+    "plan_id": {
+      "$ref": "common/identifiers.schema.json",
+      "description": "[PROTOCOL-CORE] Identifier of the Plan associated with this Trace (if any)."
+    },
+    "root_span": {
+      "$ref": "common/trace-base.schema.json",
+      "description": "[PROTOCOL-CORE] Root span definition of the Trace (follows L1 trace-base structure)."
+    },
+    "status": {
+      "type": "string",
+      "description": "[PROTOCOL-CORE] Current status of the Trace.",
+      "enum": [
+        "pending",
+        "running",
+        "completed",
+        "failed",
+        "cancelled"
+      ]
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "[PROTOCOL-CORE] Trace start time (ISO 8601)."
+    },
+    "finished_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "[PROTOCOL-CORE] Trace finish time (ISO 8601, optional if not finished)."
+    },
+    "segments": {
+      "type": "array",
+      "description": "[PROTOCOL-CORE] Key execution segments in the Trace (can correspond to multiple spans or phased aggregations).",
+      "items": {
+        "$ref": "#/$defs/trace_segment_core"
+      }
+    },
+    "events": {
+      "type": "array",
+      "description": "[PROTOCOL-CORE] List of events directly related to this Trace (errors, retries, status changes, etc.).",
+      "items": {
+        "$ref": "common/events.schema.json"
+      }
+    }
+  },
+  "required": [
+    "meta",
+    "trace_id",
+    "context_id",
+    "root_span",
+    "status"
+  ],
+  "$defs": {
+    "trace_core_properties": {
+      "type": "object",
+      "properties": {
+        "meta": {
+          "$ref": "common/metadata.schema.json",
+          "description": "[PROTOCOL-CORE] MPLP protocol and schema metadata."
+        },
+        "trace_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Global unique identifier for the Trace."
+        },
+        "context_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Identifier of the Context this Trace belongs to."
+        },
+        "plan_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Identifier of the Plan associated with this Trace (if any)."
+        },
+        "root_span": {
+          "$ref": "common/trace-base.schema.json",
+          "description": "[PROTOCOL-CORE] Root span definition of the Trace (follows L1 trace-base structure)."
+        },
+        "status": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Current status of the Trace.",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "cancelled"
+          ]
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "[PROTOCOL-CORE] Trace start time (ISO 8601)."
+        },
+        "finished_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "[PROTOCOL-CORE] Trace finish time (ISO 8601, optional if not finished)."
+        },
+        "segments": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] Key execution segments in the Trace (can correspond to multiple spans or phased aggregations).",
+          "items": {
+            "$ref": "#/$defs/trace_segment_core"
+          }
+        },
+        "events": {
+          "type": "array",
+          "description": "[PROTOCOL-CORE] List of events directly related to this Trace (errors, retries, status changes, etc.).",
+          "items": {
+            "$ref": "common/events.schema.json"
+          }
+        }
+      },
+      "required": [
+        "meta",
+        "trace_id",
+        "context_id",
+        "root_span",
+        "status"
+      ]
+    },
+    "trace_segment_core": {
+      "type": "object",
+      "description": "[PROTOCOL-CORE] Key segments in execution tracing, used to express an auditable execution interval at the protocol layer.",
+      "additionalProperties": false,
+      "properties": {
+        "segment_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Segment identifier."
+        },
+        "parent_segment_id": {
+          "$ref": "common/identifiers.schema.json",
+          "description": "[PROTOCOL-CORE] Parent segment identifier (optional if root segment)."
+        },
+        "label": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Segment label/name, for human and Agent identification of the interval."
+        },
+        "status": {
+          "type": "string",
+          "description": "[PROTOCOL-CORE] Segment status.",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "cancelled",
+            "skipped"
+          ]
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "[PROTOCOL-CORE] Segment start time."
+        },
+        "finished_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "[PROTOCOL-CORE] Segment finish time (optional if not finished)."
+        },
+        "attributes": {
+          "type": "object",
+          "description": "[PROTOCOL-CORE] Key context attributes related to this segment (key-value form, for tracing and audit).",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "segment_id",
+        "label",
+        "status"
+      ]
+    }
+  },
+  "x-mplp-meta": {
+    "protocolVersion": "1.0.0",
+    "frozen": true,
+    "freezeDate": "2025-12-03",
+    "governance": "MPGC"
+  }
+}

package/src/builders/confirm-builder.ts

@@ -1,44 +0,0 @@
-/**
- * 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 { Confirm, Plan, validateConfirm } from "@mplp/core";
-import { v4 as uuidv4 } from "uuid";
-
-export interface CreateConfirmOptions {
-    status: "approved" | "rejected" | "pending" | "cancelled";
-    requestedByRole?: string;
-    reason?: string;
-}
-
-export function createConfirm(plan: Plan, options: CreateConfirmOptions): Confirm {
-    const confirm: Confirm = {
-        meta: {
-            protocol_version: "1.0.0",
-            schema_version: "1.0.0",
-            created_at: new Date().toISOString()
-        },
-        confirm_id: uuidv4(),
-        target_type: "plan",
-        target_id: plan.plan_id,
-        status: options.status,
-        requested_by_role: options.requestedByRole || "system",
-        requested_at: new Date().toISOString(),
-        ...(options.reason && { reason: options.reason })
-    };
-
-    const validation = validateConfirm(confirm);
-    if (!validation.ok) {
-        throw new Error(`Invalid Confirm generated: ${JSON.stringify(validation.errors)}`);
-    }
-
-    return confirm;
-}

package/src/builders/context-builder.ts

@@ -1,56 +0,0 @@
-/**
- * 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 { Context, validateContext } from "@mplp/core";
-import { v4 as uuidv4 } from "uuid";
-
-export interface CreateContextOptions {
-    title: string;
-    root: {
-        domain: string;
-        environment: string;
-        entry_point?: string;
-    };
-    summary?: string;
-    tags?: string[];
-    language?: string;
-    owner_role?: string;
-    constraints?: Record<string, any>;
-    metadata?: Record<string, any>;
-}
-
-export function createContext(options: CreateContextOptions): Context {
-    const context: Context = {
-        meta: {
-            protocol_version: "1.0.0",
-            schema_version: "1.0.0",
-            created_at: new Date().toISOString()
-        },
-        context_id: uuidv4(),
-        root: options.root,
-        title: options.title,
-        status: "active",
-        ...(options.summary && { summary: options.summary }),
-        ...(options.tags && { tags: options.tags }),
-        ...(options.language && { language: options.language }),
-        ...(options.owner_role && { owner_role: options.owner_role }),
-        ...(options.constraints && { constraints: options.constraints }),
-        ...options.metadata
-    };
-
-    const validation = validateContext(context);
-    if (!validation.ok) {
-        throw new Error(`Invalid Context generated: ${JSON.stringify(validation.errors)}`);
-    }
-
-    return context;
-}