@xzzpig/pi-openspec-x 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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
+  retains the current user-dispatch attempt without allowing an unverified
+  message to authorize a report; a new user dispatch creates a fresh attempt.
+- Include the extension's generated public type declaration in the package.
+
 ## 0.2.0
 
 Child report tools are now scoped to the subagents that own them, and the

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/dist/public.d.ts

@@ -0,0 +1,48 @@
+import { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+/**
+ * pi-openspec-x extension entry point.
+ *
+ * pi-sandbox is probed lazily through a dynamic import (dependencies.ts): on
+ * success the three opsx sandbox profiles (D4: opsx-planner / opsx-agent /
+ * opsx-reviewer) are registered into pi-sandbox's runtime registry — in-memory
+ * for the session lifetime, never written to a user's sandbox.json, a
+ * user-defined same-name profile always keeping priority. On failure the
+ * reason is recorded as dependency state and the extension continues: the
+ * official-track skills and every other capability keep working, and a later
+ * request for a restricted mode is refused with a typed
+ * OpsxDependencyMissingError (fail-closed) instead of the extension (or the
+ * official track) dying at load time.
+ *
+ * Registers the resources_discover handler, which:
+ * - generates (and caches, keyed by CLI version) the official-track
+ *   openspec-* skills under `<agentDir>/cache/pi-openspec-x/skills/` and
+ *   exposes the directory to pi via `skillPaths`;
+ * - warns once per project when static `<cwd>/.pi/skills/openspec-*`
+ *   directories collide with the generated skills.
+ *
+ * Registers the session_start handler that clears a stale `active_agent`
+ * identity left in the session file by an earlier session (pi-agent-role's
+ * semantics; see mode.ts).
+ *
+ * Registers the three child reporting tools (report_gap_analysis,
+ * report_plan_review, report_work) through the role-specific child-only
+ * extensions declared in agents.ts (design D1): each tool is registered into
+ * its own subagent's process and never into the main session, so the parent's
+ * tool declaration and prompt rules stay free of them.
+ *
+ * pi-subagents is probed the same lazy way: on success the four opsx
+ * subagents (opsx-gap-analysis / opsx-plan-review / opsx-worker / opsx-reviewer) are
+ * registered into pi-subagents' runtime registry via the owner's event bus
+ * (D3). A missing pi-subagents costs only the enhanced flow's subagents —
+ * the official track and direct main-session implementation are unaffected.
+ * Because the owner listener only exists once pi-subagents has loaded (load
+ * order between extensions is not guaranteed), a failed init-time attempt is
+ * retried on session_start.
+ *
+ * Missing openspec CLI: no skills are registered and no error escapes — a
+ * one-time notice is sent instead.
+ */
+declare function piOpenspecX(pi: ExtensionAPI): Promise<void>;
+
+export { piOpenspecX as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xzzpig/pi-openspec-x",
-  "version": "0.2.0",
+  "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",
@@ -25,6 +25,7 @@
   "files": [
     "index.ts",
     "src",
+    "dist",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -36,20 +37,25 @@
     ]
   },
   "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.0.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",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs"
   }
 }

package/src/child-report-reader.ts

@@ -12,12 +12,12 @@
  * ingestion; it never adds a model-fillable parameter, and the parent
  * re-validates `report` against the original tool schema.
  *
- * The attempt is the anti-forgery anchor: `before_agent_start` records a fresh
- * random `attemptId` plus the SHA-256 of the actual prompt in a
- * `pi-openspec-x/child-report-attempt:v1` session entry. A report is only
- * attributable to the turn whose attempt it names, so a resumed child that
- * reuses the same session file cannot smuggle an earlier run's report into the
- * current dispatch.
+ * The attempt is the anti-forgery anchor: for each user dispatch,
+ * `before_agent_start` records a fresh random `attemptId` plus the SHA-256 of
+ * the actual prompt in a `pi-openspec-x/child-report-attempt:v1` session entry.
+ * A report is attributable only to the dispatch whose attempt it names, so a
+ * resumed child that reuses the same session file cannot smuggle an earlier
+ * run's report into the current dispatch.
  *
  * Deliberately NOT here: any reading of pi-subagents' private `AsyncStatus`
  * or lifecycle constants (design D3). This module declares the minimal v3
@@ -164,9 +164,9 @@ export function beginChildReportAttempt(
 /** Human-readable refusal text for a report that cannot be attributed. */
 export function attemptUnavailableMessage(agent: string): string {
   return (
-    `Report rejected: no child report attempt is recorded for ${agent} in this turn. ` +
+    `Report rejected: no child report attempt is recorded for ${agent} in this dispatch. ` +
     `The parent cannot attribute this report to a verified run, so it would be ignored; ` +
-    `the attempt entry is written by this extension at the start of every turn.`
+    `the attempt entry is written by this extension at the start of each user dispatch.`
   );
 }
 
@@ -175,7 +175,7 @@ export function attemptUnavailableMessage(agent: string): string {
  *
  * The wrapped tool keeps the original name, schema, confirmation text and
  * `sequential` execution mode; only `details` changes into the envelope. When
- * the current turn has no persisted attempt, the call fails explicitly instead
+ * the current dispatch has no persisted attempt, the call fails explicitly instead
  * of returning a report the parent would have to discard.
  */
 export function registerChildReportTool(
@@ -185,6 +185,13 @@ export function registerChildReportTool(
   let current: ChildReportAttemptOutcome | undefined;
 
   pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx) => {
+    // Pi 1.2+ also fires this hook when a custom message wakes the same child.
+    // It is not a new user dispatch: keep its existing attempt, or continue to
+    // reject reports if no dispatch has been recorded. Pi 1.1 never fired this
+    // hook for such a wake and has no messageType field.
+    if ("messageType" in event && event.messageType === "custom") return;
+    current = undefined;
+    if (!("prompt" in event) || typeof event.prompt !== "string") return;
     current = beginChildReportAttempt(pi, ctx, {
       agent: options.agent,
       prompt: event.prompt,

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: [
         {