@xzzpig/pi-openspec-x 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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
+parent session no longer transcribes reports.
+
+- **Breaking:** `report_gap_analysis`, `report_plan_review` and `report_work`
+  are no longer registered in the main session. Each is loaded only by its own
+  opsx child extension (`subagentOnlyExtensions`), so a parent session sees
+  neither the tools nor their prompt rules.
+- Child reports are received by the plugin from native subagent results, the
+  canonical v3 session record and the native `status.json`, and are bound to a
+  specific flow, run and attempt nonce. No parent-side review tool is required.
+- Completion gating reads the accepted ready receipt of the task's latest run
+  rather than anything the parent model restates, so a failed, superseded or
+  stale-attempt report cannot authorize a tick.
+- A cold restart restores the flow, the gate and its dispatch observations from
+  the branch, so previously earned receipts keep working after a restart.
+- A new dispatch invalidates the task's earlier receipt; ordinary goals keep
+  their original behaviour and `--direct` flows keep their own completion
+  events without worker conditions.
+
 ## 0.1.0
 
 Initial release.

package/README.md

@@ -58,9 +58,13 @@ fail-closed：pi-sandbox 缺失时，`/opsx:plan` 与代理实现态会被拒绝
 计划态与代理实现态的写收敛由 pi-sandbox 的受限 profile 强制（fail-closed）：越界写被沙箱层拒绝并给出原因，读取不受限；进入受限模式前插件发出的模式契约已预先指明可写范围并把写入指引收敛回 `openspec/`。
 
 - **`--direct` 主会话直实现**：不切角色、不收紧权限；按 `tasks.md` 顺序实现、自行验证、验证通过才勾选，终点同样接最终审查门。
-- **`--agent` 代理实现**：进入 `opsx-agent` 受限模式（源码只读、构建产物可写），逐任务派发全写权限的 `opsx-worker`。派发提示词固定六段（任务 / 预期产出 / 所需工具 / 必须做 / 禁止做 / 上下文）；派发返回后逐文件核对 diff 与 `report_work` 声明、运行验证，**通过才勾选 tasks.md**，并同步 goal 任务树。
+- **`--agent` 代理实现**：进入 `opsx-agent` 受限模式（源码只读、构建产物可写），逐任务派发全写权限的 `opsx-worker`。派发提示词固定六段（任务 / 预期产出 / 所需工具 / 必须做 / 禁止做 / 上下文），其中任务段必须带独立行的 `[OPSX WORKER DISPATCH task=<taskId>]` 标记（新派发与 resume 都要带）；派发返回后逐文件核对 diff 与 worker 报告声明、运行验证，**通过才勾选 tasks.md**，并同步 goal 任务树。
 
-  “未审查不得勾选”是**强制门**：插件监听 `subagent`（`agent=opsx-worker`）、`report_work` 与 `update_goal_task` 三类工具流量，在 `update_goal_task status=complete` 的 `tool_call` 阶段拦截——没有观测到派发、没有对应的 `report_work`、报告声明与窗口 delta 不一致（漏报或多报文件）、或记录的验证明显失败时，勾选被 block 并返回具体原因。因此代理模式下**必须先 `report_work`（taskId / changedFiles / 验证命令与结果）再勾选**。同一任务反复派发且既无报告也无改动会被判为空转并提示一次。门拦的是 goal 任务树镜像的 `update_goal_task`；直接以 bash/write 改 `tasks.md` 复选框本身不被硬拦，由「goal 任务树不完整 → goal-x 完成事务拒绝」兜底，最终语义一致。直实现模式不设此门（无派发可核）。
+  三个上报工具（`report_gap_analysis` / `report_plan_review` / `report_work`）**只对各自的子角色可见**：gap-analysis 只见前者、plan-review 只见中间、opsx-worker 只见后者；主会话与其他角色（含 opsx-reviewer）既没有这些工具，也不会有它们的使用指引。插件从子运行的原生结果与规范会话记录里**自动接收**报告并关联到任务，**不需要主模型转录**，也不存在 `review_work` 之类的主会话验收工具。
+
+  “未审查不得勾选”是**强制门**：插件监听 `subagent`（`agent=opsx-worker`）与 `update_goal_task` 两类工具流量，在 `update_goal_task status=complete` 的 `tool_call` 阶段拦截——没有观测到派发、派发没有对应的**已接收**报告、报告声明与窗口 delta 不一致（漏报或多报文件）、或记录的验证明显失败时，勾选被 block 并返回具体原因。因此代理模式下**先派发、等报告自动落定、再勾选**。同一任务反复派发且既无报告也无改动会被判为空转并提示一次。门拦的是 goal 任务树镜像的 `update_goal_task`；直接以 bash/write 改 `tasks.md` 复选框本身不被硬拦，由「goal 任务树不完整 → goal-x 完成事务拒绝」兜底，最终语义一致。直实现模式不设此门（无派发可核）。
+
+  诊断：证据不可用（子运行失败且未留下可读取的规范记录、会话未持久化、分支/焦点在读取期间变化）时该任务的勾选**保持阻塞**并说明原因，不会用旧报告放行；超出资源预算（活跃子项、会话大小、单行长度、报告字节、上报次数、会话树节点）时报告**明确标记为不可用于门控**，同样不放行，而不是截断后当成功。
 
 两种模式都以持久目标为执行底座：插件把 `tasks.md` 组装成 objective（`Steps` + `Boundaries`/`Don'ts` + `Verification contract:`）交给 goal-x 的 `create_goal`（代理模式 `sisyphus`，直实现模式普通 autoContinue），任务清单经 `set_goal_tasks` 单向镜像。`tasks.md` 是任务权威源，goal 任务树上的手工改动不回流。
 

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.1.0",
+  "version": "0.2.1",
   "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,23 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.86.1 <0.88.0",
-    "@earendil-works/pi-coding-agent": ">=0.87.1 <0.88.0",
+    "@earendil-works/pi-ai": ">=1.0.0 <2",
+    "@earendil-works/pi-coding-agent": ">=1.0.0 <2",
     "@xzzpig/pi-goal-x": "*",
     "@xzzpig/pi-sandbox": "*",
     "@xzzpig/pi-subagents": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-coding-agent": "1.1.0",
     "@types/node": "24.12.4",
+    "rollup": "^4.62.2",
+    "rollup-plugin-dts": "^6.4.1",
     "typescript": "5.9.3",
     "vitest": "4.1.8"
   },
   "scripts": {
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs"
   }
 }

package/src/agent-prompts.ts

@@ -59,7 +59,8 @@ The parent gates purely on the verdict field. Approve workable plans; reject onl
 
 /**
  * opsx-worker — focused single-task executor. Full write; reports through
- * `report_work`.
+ * `report_work`, a tool only this role can see, whose payload the parent
+ * ingests automatically from the child run.
  */
 export const WORKER_SYSTEM_PROMPT = `You are the opsx worker: a focused task executor for the OpenSpec implementation flow. You execute exactly ONE dispatched task. You do not delegate further, you do not spawn subagents, you do not pick up neighboring tasks, and you do not refactor beyond the task.
 
@@ -78,6 +79,8 @@ Report through the report_work tool with:
 - claims: what you did and the result, precisely;
 - selfVerification: the command you ran and its actual result (exit status, pass/fail counts). Subagents lie — not you: your evidence must be real command output you personally observed. If verification failed and you could not fix it, report that honestly; a truthful failure is recoverable, an invented success is not.
 
+The parent reads this payload straight from your run; do not restate it in prose expecting the parent to transcribe it, and do not look for another tool to file it with.
+
 If the task cannot be completed as specified (missing prerequisite, contradictory requirements), stop early, change nothing you cannot justify, and report exactly what is blocking.`;
 
 /**

package/src/agents.ts

@@ -21,6 +21,7 @@
  * never collides with itself.
  */
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import type {
   ExtensionAPI,
   ExtensionHandler,
@@ -91,6 +92,27 @@ const SHARED_ISOLATION = {
 
 const reviewerProgressExtensionPath = resolveGoalAuditorProgressPath();
 
+/**
+ * Child-only report-tool extensions (design D1), one per reporting role.
+ *
+ * Absolute paths on purpose, exactly like the reviewer's goal-x extension: a
+ * child pi process runs in the audited workspace, not in this package's
+ * directory, so a relative specifier would not resolve. These entries are NOT
+ * listed in `package.json::pi.extensions` — the main session must never load
+ * them, and each registers exactly one tool for its own role.
+ */
+const CHILD_REPORT_EXTENSION_PATHS = {
+  "opsx-gap-analysis": fileURLToPath(
+    new URL("./child-report-extensions/gap-analysis.ts", import.meta.url),
+  ),
+  "opsx-plan-review": fileURLToPath(
+    new URL("./child-report-extensions/plan-review.ts", import.meta.url),
+  ),
+  "opsx-worker": fileURLToPath(
+    new URL("./child-report-extensions/worker.ts", import.meta.url),
+  ),
+};
+
 /** The four canonical runtime definitions, keyed by agent name. */
 export const OPSX_AGENT_DEFINITIONS: Record<
   OpsxAgentName,
@@ -108,6 +130,7 @@ export const OPSX_AGENT_DEFINITIONS: Record<
       "bash",
       REPORT_GAP_ANALYSIS_TOOL_NAME,
     ],
+    subagentOnlyExtensions: [CHILD_REPORT_EXTENSION_PATHS["opsx-gap-analysis"]],
     ...SHARED_ISOLATION,
     acceptanceRole: "read-only",
     thinking: "high",
@@ -116,6 +139,7 @@ export const OPSX_AGENT_DEFINITIONS: Record<
     description: "Read-only work-plan reviewer for the opsx planning flow",
     systemPrompt: PLAN_REVIEW_SYSTEM_PROMPT,
     tools: ["read", "grep", "find", "ls", REPORT_PLAN_REVIEW_TOOL_NAME],
+    subagentOnlyExtensions: [CHILD_REPORT_EXTENSION_PATHS["opsx-plan-review"]],
     ...SHARED_ISOLATION,
     acceptanceRole: "read-only",
     thinking: "high",
@@ -134,6 +158,7 @@ export const OPSX_AGENT_DEFINITIONS: Record<
       "ls",
       REPORT_WORK_TOOL_NAME,
     ],
+    subagentOnlyExtensions: [CHILD_REPORT_EXTENSION_PATHS["opsx-worker"]],
     ...SHARED_ISOLATION,
     acceptanceRole: "writer",
   },

package/src/child-report-extensions/gap-analysis.ts

@@ -0,0 +1,23 @@
+/**
+ * Child-only extension entry for opsx-gap-analysis (design D1).
+ *
+ * Loaded exclusively through that agent's `subagentOnlyExtensions`; it
+ * registers exactly one tool and never loads the main extension, so the gap
+ * analysis reporting tool exists only inside the gap-analysis child process.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerChildReportTool } from "../child-report-reader.ts";
+import { reportGapAnalysisTool } from "../report-tools.ts";
+
+/** Role this entry serves; must match the agent name in `agents.ts`. */
+export const GAP_ANALYSIS_CHILD_AGENT = "opsx-gap-analysis";
+
+export default function gapAnalysisChildReportExtension(
+  pi: ExtensionAPI,
+): void {
+  registerChildReportTool(pi, {
+    agent: GAP_ANALYSIS_CHILD_AGENT,
+    tool: reportGapAnalysisTool,
+  });
+}

package/src/child-report-extensions/plan-review.ts

@@ -0,0 +1,21 @@
+/**
+ * Child-only extension entry for opsx-plan-review (design D1).
+ *
+ * Loaded exclusively through that agent's `subagentOnlyExtensions`; it
+ * registers exactly one tool and never loads the main extension, so the plan
+ * review reporting tool exists only inside the plan-review child process.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerChildReportTool } from "../child-report-reader.ts";
+import { reportPlanReviewTool } from "../report-tools.ts";
+
+/** Role this entry serves; must match the agent name in `agents.ts`. */
+export const PLAN_REVIEW_CHILD_AGENT = "opsx-plan-review";
+
+export default function planReviewChildReportExtension(pi: ExtensionAPI): void {
+  registerChildReportTool(pi, {
+    agent: PLAN_REVIEW_CHILD_AGENT,
+    tool: reportPlanReviewTool,
+  });
+}

package/src/child-report-extensions/worker.ts

@@ -0,0 +1,26 @@
+/**
+ * Child-only extension entry for opsx-worker (design D1).
+ *
+ * Loaded exclusively through that agent's `subagentOnlyExtensions`; it
+ * registers exactly one tool and never loads the main extension, so the work
+ * report tool exists only inside the worker child process.
+ *
+ * The worker's Task section carries `[OPSX WORKER DISPATCH task=<taskId>]`.
+ * The attempt records that marker when the prompt names exactly one task; a
+ * resumed prompt without one is still recordable but cannot authorize a tick
+ * (design D3).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerChildReportTool } from "../child-report-reader.ts";
+import { reportWorkTool } from "../report-tools.ts";
+
+/** Role this entry serves; must match the agent name in `agents.ts`. */
+export const WORKER_CHILD_AGENT = "opsx-worker";
+
+export default function workerChildReportExtension(pi: ExtensionAPI): void {
+  registerChildReportTool(pi, {
+    agent: WORKER_CHILD_AGENT,
+    tool: reportWorkTool,
+  });
+}