@xzzpig/pi-openspec-x 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.2 — 2026-11-05
+
+- Require Pi 1.5.0 or newer and build tool parameter schemas with
+  `@earendil-works/pi-schema` instead of TypeBox. Preserve existing required
+  fields, bounds, and open/closed-object validation semantics.
+
 ## 0.2.1
 
 - Support Pi 1.2+ custom-message wakeups in child report handlers. A wakeup

package/README.md

@@ -2,6 +2,9 @@
 
 把 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 的规范驱动流程接进 pi coding agent：从**当前安装的 openspec CLI** 现场提取官方 skill，并提供 `/opsx:plan`（深度计划 + 缺口分析 / 计划审查门）与 `/opsx:implement`（代理实现 / 主会话直实现 + 最终整体审查门）两条增强流程。
 
+Requires **Pi >=1.5.0 <2**. Tool schemas use `@earendil-works/pi-schema`,
+which is declared as a Pi peer dependency.
+
 ```bash
 pi install npm:@xzzpig/pi-openspec-x
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzzpig/pi-openspec-x",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "OpenSpec workflow for the pi coding agent: spec-driven planning and implementation via dedicated subagents, sandboxed /opsx:plan and /opsx:implement commands.",
   "keywords": [
     "pi-package",
@@ -37,19 +37,21 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=1.0.0 <2",
-    "@earendil-works/pi-coding-agent": ">=1.0.0 <2",
+    "@earendil-works/pi-ai": ">=1.5.0 <2",
+    "@earendil-works/pi-coding-agent": ">=1.5.0 <2",
     "@xzzpig/pi-goal-x": "*",
     "@xzzpig/pi-sandbox": "*",
-    "@xzzpig/pi-subagents": "*"
+    "@xzzpig/pi-subagents": "*",
+    "@earendil-works/pi-schema": ">=1.5.0 <2"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
     "@types/node": "24.12.4",
     "rollup": "^4.62.2",
     "rollup-plugin-dts": "^6.4.1",
     "typescript": "5.9.3",
-    "vitest": "4.1.8"
+    "vitest": "4.1.8",
+    "@earendil-works/pi-schema": "1.5.0"
   },
   "scripts": {
     "test": "vitest run",

package/src/plan-gate.ts

@@ -17,7 +17,16 @@
  * reads the recorded approval from disk, so approval survives a restart and a
  * fresh session cannot bypass the gate.
  */
-import { Type } from "@earendil-works/pi-ai";
+import {
+  arr,
+  lit,
+  num,
+  obj,
+  opt,
+  str,
+  union,
+  type Static,
+} from "@earendil-works/pi-schema";
 import {
   defineTool,
   type ExtensionAPI,
@@ -43,61 +52,57 @@ import {
 export const OPSX_PLAN_GAP_ANALYSIS_TOOL_NAME = "opsx_plan_gap_analysis";
 export const OPSX_PLAN_VERDICT_TOOL_NAME = "opsx_plan_verdict";
 
-const usageSchema = Type.Optional(
-  Type.Object(
+const usageSchema = opt(
+  obj(
     {
-      input: Type.Number(),
-      output: Type.Number(),
-      cacheRead: Type.Number(),
-      cacheWrite: Type.Number(),
-      turns: Type.Number(),
+      input: num(),
+      output: num(),
+      cacheRead: num(),
+      cacheWrite: num(),
+      turns: num(),
     },
-    { additionalProperties: false },
+    { open: false },
   ),
 );
 
-const gapAnalysisParams = Type.Object(
+const gapAnalysisParams = obj(
   {
-    findings: Type.Array(
-      Type.String({
+    findings: arr(
+      str({
         description: "One concrete gap, specific enough to act on.",
       }),
       { description: "Gap-analysis findings; may be empty." },
     ),
-    summary: Type.Optional(Type.String()),
-    changeId: Type.Optional(
-      Type.String({
+    summary: opt(str()),
+    changeId: opt(
+      str({
         description:
           "OpenSpec change id; defaults to this session's active plan flow.",
       }),
     ),
   },
-  { additionalProperties: false },
+  { open: false },
 );
 
-const planReviewParams = Type.Object(
+const planReviewParams = obj(
   {
-    verdict: Type.Union([
-      Type.Literal("OKAY"),
-      Type.Literal("ITERATE"),
-      Type.Literal("REJECT"),
-    ]),
-    blockers: Type.Optional(
-      Type.Array(Type.String(), {
+    verdict: union([lit("OKAY"), lit("ITERATE"), lit("REJECT")]),
+    blockers: opt(
+      arr(str(), {
         description:
           "Blocking issues; at most three, each new relative to earlier rounds.",
       }),
     ),
-    summary: Type.Optional(Type.String()),
+    summary: opt(str()),
     usage: usageSchema,
-    changeId: Type.Optional(
-      Type.String({
+    changeId: opt(
+      str({
         description:
           "OpenSpec change id; defaults to this session's active plan flow.",
       }),
     ),
   },
-  { additionalProperties: false },
+  { open: false },
 );
 
 /**
@@ -149,7 +154,13 @@ export function registerPlanGateTools(pi: ExtensionAPI): void {
       ],
       parameters: gapAnalysisParams,
       executionMode: "sequential",
-      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      async execute(
+        _toolCallId,
+        params: Static<typeof gapAnalysisParams>,
+        _signal,
+        _onUpdate,
+        ctx,
+      ) {
         const resolved = requireChangeId(ctx, params.changeId);
         if ("error" in resolved) {
           return toolText(resolved.error);
@@ -181,7 +192,13 @@ export function registerPlanGateTools(pi: ExtensionAPI): void {
       ],
       parameters: planReviewParams,
       executionMode: "sequential",
-      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      async execute(
+        _toolCallId,
+        params: Static<typeof planReviewParams>,
+        _signal,
+        _onUpdate,
+        ctx,
+      ) {
         const resolved = requireChangeId(ctx, params.changeId);
         if ("error" in resolved) {
           return toolText(resolved.error);

package/src/report-tools.ts

@@ -22,7 +22,17 @@
  * call returns. There is no progress bar here — a tool may be called any
  * number of times; projection of the calls is a later concern.
  */
-import { Type } from "@earendil-works/pi-ai";
+import {
+  arr,
+  bool,
+  lit,
+  num,
+  obj,
+  opt,
+  str,
+  union,
+  type Static,
+} from "@earendil-works/pi-schema";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 
 export const REPORT_GAP_ANALYSIS_TOOL_NAME = "report_gap_analysis";
@@ -33,20 +43,20 @@ export const REPORT_WORK_TOOL_NAME = "report_work";
  * One located finding. `location` is free-form ("src/cli.ts:42",
  * "tasks.md#Step 3") because artifact sections do not always map to lines.
  */
-const findingItem = Type.Object(
+const findingItem = obj(
   {
-    description: Type.String({
+    description: str({
       description:
         "The finding itself, specific enough to act on without re-deriving it.",
     }),
-    location: Type.Optional(
-      Type.String({
+    location: opt(
+      str({
         description:
           "Where the finding applies: file path, and line or section when known.",
       }),
     ),
   },
-  { additionalProperties: false },
+  { open: false },
 );
 
 /**
@@ -54,158 +64,150 @@ const findingItem = Type.Object(
  * 百分比，或等效字段). Optional: a report that carries no progress simply leaves
  * the parent's board unchanged.
  */
-const progressField = Type.Optional(
-  Type.Object(
+const progressField = opt(
+  obj(
     {
-      phase: Type.String({
+      phase: str({
         description:
           "The stage this update belongs to, e.g. reading, analyzing, editing, verifying.",
       }),
-      percentage: Type.Number({
+      percentage: num({
         description: "How far through this stage the agent is, 0 to 100.",
         minimum: 0,
         maximum: 100,
       }),
-      label: Type.Optional(
-        Type.String({
+      label: opt(
+        str({
           description:
             "Short human-readable detail for the board; defaults to the phase name.",
         }),
       ),
     },
-    { additionalProperties: false },
+    { open: false },
   ),
 );
 
-const gapAnalysisParams = Type.Object(
+const gapAnalysisParams = obj(
   {
     progress: progressField,
-    intentType: Type.String({
+    intentType: str({
       description:
         "Classified user intent, e.g. refactor, build-from-scratch, mid-sized, collaborative, architecture, or research.",
     }),
-    confidence: Type.Number({
+    confidence: num({
       description: "Confidence in the intent classification, from 0 to 1.",
       minimum: 0,
       maximum: 1,
     }),
-    contradictions: Type.Array(findingItem, {
+    contradictions: arr(findingItem, {
       description: "Requirements or statements that conflict with each other.",
     }),
-    missingConstraints: Type.Array(findingItem, {
+    missingConstraints: arr(findingItem, {
       description:
         "Constraints the request implies but never states (platform, compatibility, performance, security, ...).",
     }),
-    scopeRisks: Type.Array(findingItem, {
+    scopeRisks: arr(findingItem, {
       description:
         "Scope-inflation or gold-plating risks, including premature abstraction and over-validation.",
     }),
-    unvalidatedAssumptions: Type.Array(findingItem, {
+    unvalidatedAssumptions: arr(findingItem, {
       description:
         "Assumptions the plan relies on without evidence (environment, behavior, availability).",
     }),
-    missingAcceptanceCriteria: Type.Array(findingItem, {
+    missingAcceptanceCriteria: arr(findingItem, {
       description:
         "Outcomes that lack an agent-executable acceptance criterion (no 'user manually tests' criteria).",
     }),
-    summary: Type.String({
+    summary: str({
       description: "One-paragraph synthesis of the analysis.",
     }),
   },
-  { additionalProperties: false },
+  { open: false },
 );
 
-const planReviewParams = Type.Object(
+const planReviewParams = obj(
   {
     progress: progressField,
-    verdict: Type.Union(
-      [Type.Literal("OKAY"), Type.Literal("ITERATE"), Type.Literal("REJECT")],
-      {
-        description:
-          "OKAY: executable as written. ITERATE: workable after targeted, non-blocking revisions. REJECT: not executable as written.",
-      },
-    ),
-    issues: Type.Array(
-      Type.Object(
+    verdict: union([lit("OKAY"), lit("ITERATE"), lit("REJECT")], {
+      description:
+        "OKAY: executable as written. ITERATE: workable after targeted, non-blocking revisions. REJECT: not executable as written.",
+    }),
+    issues: arr(
+      obj(
         {
-          severity: Type.Union(
-            [
-              Type.Literal("blocker"),
-              Type.Literal("major"),
-              Type.Literal("minor"),
-            ],
-            { description: "How badly the issue threatens execution." },
-          ),
-          file: Type.Optional(
-            Type.String({
+          severity: union([lit("blocker"), lit("major"), lit("minor")], {
+            description: "How badly the issue threatens execution.",
+          }),
+          file: opt(
+            str({
               description: "Plan file the issue applies to, when located.",
             }),
           ),
-          line: Type.Optional(
-            Type.Number({
+          line: opt(
+            num({
               description: "Line number in that file, when known.",
             }),
           ),
-          description: Type.String({
+          description: str({
             description:
               "The issue, concrete and actionable (what to change, not a taste judgment).",
           }),
-          blocking: Type.Boolean({
+          blocking: bool({
             description:
               "True only for REJECT blockers; ITERATE/OKAY issues are never blocking.",
           }),
         },
-        { additionalProperties: false },
+        { open: false },
       ),
       { description: "Found issues; may be empty for a clean OKAY." },
     ),
-    summary: Type.String({
+    summary: str({
       description:
         "One-paragraph verdict rationale; for REJECT it must reference which earlier blockers (if any) are now resolved.",
     }),
   },
-  { additionalProperties: false },
+  { open: false },
 );
 
-const workReportParams = Type.Object(
+const workReportParams = obj(
   {
     progress: progressField,
-    taskId: Type.String({
+    taskId: str({
       description: "The dispatched task identifier (e.g. the tasks.md item).",
     }),
-    changedFiles: Type.Array(Type.String(), {
+    changedFiles: arr(str(), {
       description:
         "Every file this task created or modified, with paths relative to the project root.",
     }),
-    claims: Type.String({
+    claims: str({
       description:
         "What was done and what the result is. Only claims backed by evidence below.",
     }),
-    selfVerification: Type.Object(
+    selfVerification: obj(
       {
-        command: Type.Optional(
-          Type.String({
+        command: opt(
+          str({
             description:
               "The verification command actually run (e.g. build/test).",
           }),
         ),
-        result: Type.Optional(
-          Type.String({
+        result: opt(
+          str({
             description:
               "The real command output summary (exit status, failing/passing counts). Never invented.",
           }),
         ),
       },
-      { additionalProperties: false },
+      { open: false },
     ),
-    verificationPassed: Type.Optional(
-      Type.Boolean({
+    verificationPassed: opt(
+      bool({
         description:
           "Structured verdict: whether the verification actually passed. When provided the gate trusts it and does not parse the result text; when absent the result text is scanned heuristically.",
       }),
     ),
   },
-  { additionalProperties: false },
+  { open: false },
 );
 
 /** Count of non-empty finding lists, for the one-line confirmation text. */
@@ -238,7 +240,7 @@ export const reportGapAnalysisTool = defineTool({
   ],
   parameters: gapAnalysisParams,
   executionMode: "sequential",
-  async execute(_toolCallId, params) {
+  async execute(_toolCallId, params: Static<typeof gapAnalysisParams>) {
     return {
       content: [
         {
@@ -264,7 +266,7 @@ export const reportPlanReviewTool = defineTool({
   ],
   parameters: planReviewParams,
   executionMode: "sequential",
-  async execute(_toolCallId, params) {
+  async execute(_toolCallId, params: Static<typeof planReviewParams>) {
     const blocking = params.issues.filter((issue) => issue.blocking).length;
     return {
       content: [
@@ -291,7 +293,7 @@ export const reportWorkTool = defineTool({
   ],
   parameters: workReportParams,
   executionMode: "sequential",
-  async execute(_toolCallId, params) {
+  async execute(_toolCallId, params: Static<typeof workReportParams>) {
     return {
       content: [
         {