@abelxiaoxing/cadence 1.0.0 → 1.0.1

package/README.md

@@ -1,41 +1,69 @@
 # @abelxiaoxing/cadence
 
-Prompts, skills, and a private orchestration extension exposing the Abel four-stage workflow:
+[![npm](https://img.shields.io/npm/v/@abelxiaoxing/cadence)](https://www.npmjs.com/package/@abelxiaoxing/cadence)
+[![GitHub](https://img.shields.io/github/license/abelxiaoxing/cadence)](https://github.com/abelxiaoxing/cadence)
 
-- `/abel-init [project-path]` — initialize OpenSpec and repair AGENTS indexes.
-- `/abel-design <requirement> | --change <change_name>` — parallelize read-only exploration and design a dependency/conflict-aware task DAG through Gate A and Gate B.
-- `/abel-implement <change_name>` — orchestrate task-local professional Agents over the approved DAG with delegated Red-Green-Refactor and parent-owned verification.
-- `/abel-diagnose <problem-description>` — verify a root cause before a minimal repair.
+**Cadence** 是一个面向 pi 的规范驱动四阶段工作流扩展包，内置私有代理编排：
 
-The package is standalone: one repository, one manifest, one lockfile, no workspace, no reference-monorepo checkout, and no dependency on an external Subagent package.
-Loading the package registers a private extension and four package-owned professional Agents; the `abel_dispatch` tool is registered but inactive unless a verified Design, Implement, or Diagnose stage activates it.
+- `/abel-init [project-path]` — 初始化 OpenSpec 并修复 AGENTS 索引。
+- `/abel-design <requirement> | --change <change_name>` — 并行只读探索，设计依赖/冲突感知的任务 DAG，经由 Gate A（行为契约）与 Gate B（技术契约）双重批准。
+- `/abel-implement <change_name>` — 在已批准的 DAG 上编排任务级专业代理，委派 Red-Green-Refactor，由父代理执行验证。
+- `/abel-diagnose <problem-description>` — 先验证根因，再做最小修复。
 
-The shared workflow rules live once in the bundled `abel-workflow` skill.
+包是独立的：单一仓库、单一清单、单一 lockfile，无 workspace、无参考仓库检出、不依赖任何外部 Subagent 包。
+加载本包会注册一个私有扩展与四个包内专业 Agent；`abel_dispatch` 工具注册但保持未激活，只有经过验证的 Design、Implement 或 Diagnose 阶段才会激活它。
 
-## Install
+共享工作流规则统一收录于包内 `abel-workflow` skill。
+
+交互式 TUI 中，经过验证的 `abel_dispatch` run 会显示紧凑的 Subagent 角色、请求、阶段、目标、耗时和状态，并在编辑器上方临时汇总仍在排队或运行的 Agents。
+
+该显示只保留有限的终态摘要；不会显示子会话、工具活动、路径、模型身份、隐藏推理、完整引用或完整 diff。
+
+print、JSON 和 RPC 模式保持原有结果与事件行为不变。
+
+## 安装（Install）
+
+### 在 pi 中快速安装（推荐）
+
+```sh
+$ pi install npm:@abelxiaoxing/cadence
+Installed npm:@abelxiaoxing/cadence
+```
+
+也可以使用 npm 或 bun：
 
 ```sh
 npm install -g @abelxiaoxing/cadence
-# or with bun: bun add -g @abelxiaoxing/cadence
+# 或使用 bun：bun add -g @abelxiaoxing/cadence
 ```
 
-Loading paths, all verified:
+已验证的加载路径：
 
-- **npm package** — install `@abelxiaoxing/cadence` from the npm registry at user or project scope; Pi discovers the four prompts, four skills, the private extension, and the package-owned Agents.
-- **Local package directory** — point Pi at this repository's absolute or relative path (for example `./pi-abelpackages`).
-  Pi discovers the same resources.
-- **Installed tarball directory** — run `bun pm pack --destination <tmp>` to produce a real tarball, install or unpack it into an isolated directory, and point Pi at that directory.
-  The tarball file itself is never passed to Pi as a local package.
+- **npm 包（npm package）** — 从 npm registry 以用户级或项目级 scope 安装 `@abelxiaoxing/cadence`；Pi 发现四个 prompts、四个 skills、私有扩展与包内 Agents。
+- **本地包目录（local package directory）** — 将 Pi 指向本仓库的绝对路径或相对路径（absolute or relative path，例如 `./cadence`），Pi 发现同样的资源。
+- **已安装 tarball 目录（installed tarball directory）** — 运行 `bun pm pack --destination <tmp>` 生成真实 tarball（.tgz），安装或解压到隔离目录后指向该目录；tarball 文件本身永远不会被当作本地包传给 Pi。
 
-The package never inspects or classifies the Pi host version, never claims a version range, and never installs from the relocated reference repository source.
+本包从不检查或分类 Pi 主机版本，不声明任何版本范围，也不从参考仓库源安装。
 
-## Development
+## 开发（Development）
 
 ```sh
 bun install
-bun run check       # syntax + type checks
+bun run check       # 语法 + 类型检查
 bun run lint        # biome + rumdl
-bun run test        # complete suite
-bun run test:target <files>   # targeted tests
-bun run check:agents          # AGENTS index validation
+bun run test        # 完整测试套件
+bun run test:target <files>   # 定向测试
+bun run check:agents          # AGENTS 索引校验
 ```
+
+## 验证（Verification）
+
+```sh
+bun run verify      # check && lint && test && pack:check（发布前全套校验）
+bun run pack:check  # 真实 tarball 39 成员清单校验
+bun run traceability:check   # 81 条 Requirement/Scenario 引用精确解析
+```
+
+## 许可（License）
+
+MIT — 详见 [LICENSE](LICENSE) 与 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Prompts, skills, and a private orchestration extension exposing the Abel four-stage workflow (/abel-init, /abel-design, /abel-implement, /abel-diagnose) with package-owned professional Agents.",
   "license": "MIT",
   "type": "module",
@@ -48,11 +48,13 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
     "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.2",
     "@types/node": "^22.15.3",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",

package/prompts/abel-design.md

@@ -10,6 +10,7 @@ argument-hint: "<requirement> | --change <change_name>"
 $ARGUMENTS
 </abel-request>
 
+<!-- ABEL:PROMPT:abel-design -->
 <!-- ABEL:START -->
 # 不可协商规则（最高优先级）
 

package/prompts/abel-diagnose.md

@@ -10,6 +10,7 @@ Read the complete value inside `<abel-request>` without a second whitespace-toke
 $ARGUMENTS
 </abel-request>
 
+<!-- ABEL:PROMPT:abel-diagnose -->
 The request must uniquely identify one or more existing bugs.
 If required input is missing or ambiguous, stop and ask for the missing or disambiguating information instead of guessing.
 

package/prompts/abel-implement.md

@@ -10,6 +10,7 @@ argument-hint: "<change_name>"
 $ARGUMENTS
 </abel-request>
 
+<!-- ABEL:PROMPT:abel-implement -->
 <!-- ABEL:START -->
 **参数**：从 `<abel-request>` 读取必需的 `<change_name>`。
 

package/src/child-session.ts

@@ -16,6 +16,20 @@ import {
   type SubmitClassification,
 } from "./submit-tool.ts";
 
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
 const ZERO_USAGE: Usage = {
   input: 0,
   output: 0,
@@ -78,6 +92,8 @@ function wrapScopedTools(roots: string[]) {
     );
 }
 
+export type ChildFailureKind = "failed" | "cancelled" | "timed-out";
+
 export async function runChildSession(input: {
   cwd: string;
   modelRuntime: ModelRuntime;
@@ -89,6 +105,7 @@ export async function runChildSession(input: {
   output: "evidence" | "diff";
   roots: string[];
   timeoutMs: number;
+  signal?: AbortSignal;
 }): Promise<
   | {
       ok: true;
@@ -102,6 +119,7 @@ export async function runChildSession(input: {
   | {
       ok: false;
       error: string;
+      failureKind: ChildFailureKind;
       disposeCount: number;
       classification: SubmitClassification;
     }
@@ -118,10 +136,18 @@ export async function runChildSession(input: {
   let disposeCount = 0;
   const usage = new UsageAggregator();
   const abort = new AbortController();
-  const timer = setTimeout(
-    () => abort.abort(new Error("child phase timeout")),
-    input.timeoutMs,
-  );
+  const forwardCancellation = () =>
+    abort.abort(input.signal?.reason ?? new Error("child phase cancelled"));
+  if (input.signal?.aborted) forwardCancellation();
+  else
+    input.signal?.addEventListener("abort", forwardCancellation, {
+      once: true,
+    });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    abort.abort(new Error("child phase timeout"));
+  }, input.timeoutMs);
   let session:
     | Awaited<ReturnType<typeof createAgentSession>>["session"]
     | undefined;
@@ -160,7 +186,8 @@ export async function runChildSession(input: {
     };
   };
   try {
-    ({ session } = await createAgentSession({
+    abort.signal.throwIfAborted();
+    const creation = createAgentSession({
       cwd: input.cwd,
       modelRuntime: input.modelRuntime,
       model: input.model,
@@ -173,7 +200,16 @@ export async function runChildSession(input: {
         compaction: { enabled: false },
         retry: { enabled: false, maxRetries: 0, provider: { maxRetries: 0 } },
       }),
-    }));
+    });
+    try {
+      ({ session } = await abortable(creation, abort.signal));
+    } catch (error) {
+      void creation
+        .then(({ session: lateSession }) => lateSession.dispose())
+        .catch(() => undefined);
+      throw error;
+    }
+    abort.signal.throwIfAborted();
     unsubscribe = session.subscribe((event) => {
       if (event.type === "message_end" && event.message.role === "assistant") {
         usage.add(
@@ -185,6 +221,7 @@ export async function runChildSession(input: {
     const onAbort = () => void session?.abort();
     abort.signal.addEventListener("abort", onAbort, { once: true });
     try {
+      if (abort.signal.aborted) throw abort.signal.reason;
       await Promise.race([
         session.prompt(input.systemPrompt, { expandPromptTemplates: false }),
         new Promise<never>((_, reject) =>
@@ -206,6 +243,7 @@ export async function runChildSession(input: {
       return {
         ok: false,
         error: "child did not retain exactly one structural submission",
+        failureKind: "failed",
         disposeCount,
         classification,
       };
@@ -223,6 +261,7 @@ export async function runChildSession(input: {
       return {
         ok: false,
         error: "final assistant message is not one structural submit",
+        failureKind: "failed",
         disposeCount,
         classification,
       };
@@ -239,14 +278,22 @@ export async function runChildSession(input: {
     };
   } catch (error) {
     disposeOnce();
+    const failureKind: ChildFailureKind = timedOut
+      ? "timed-out"
+      : input.signal !== undefined &&
+          (input.signal.aborted || abort.signal.reason === input.signal.reason)
+        ? "cancelled"
+        : "failed";
     return {
       ok: false,
       error: (error as Error).message,
+      failureKind,
       disposeCount,
       classification: classifySession(),
     };
   } finally {
     clearTimeout(timer);
+    input.signal?.removeEventListener("abort", forwardCancellation);
     unsubscribe?.();
     disposeOnce();
   }

package/src/index.ts

@@ -3,15 +3,97 @@
 // the active set at session start. Eligible-stage activation is wired by the
 // workflow routing (abel-design/implement/diagnose provenance) in the prompts
 // integration; abel-init and ordinary prompts never activate dispatch.
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { deactivateTool } from "./activation.ts";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { type Activation, activateTool, deactivateTool } from "./activation.ts";
 import { ACTIONS } from "./contracts.ts";
 import { Runtime } from "./runtime.ts";
+import {
+  ACTIVITY_DETAILS_KEY,
+  ActivityController,
+  renderActivityCall,
+  renderActivityResult,
+} from "./subagent-activity.ts";
 
 export const DISPATCH_TOOL = "abel_dispatch";
 
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const ELIGIBLE_PROMPTS = [
+  "abel-design",
+  "abel-implement",
+  "abel-diagnose",
+] as const;
+type EligiblePrompt = (typeof ELIGIBLE_PROMPTS)[number];
+
+function invokedPrompt(text: string): EligiblePrompt | undefined {
+  const name = text.match(/^\/([^\s]+)(?:\s|$)/)?.[1];
+  return ELIGIBLE_PROMPTS.find((candidate) => candidate === name);
+}
+
+function promptMarker(name: EligiblePrompt): string {
+  return `<!-- ABEL:PROMPT:${name} -->`;
+}
+
+function hasPackageProvenance(pi: ExtensionAPI, name: EligiblePrompt): boolean {
+  const commands = pi
+    .getCommands()
+    .filter((candidate) => candidate.name === name);
+  return (
+    commands.length === 1 &&
+    commands[0]?.source === "prompt" &&
+    commands[0].sourceInfo.origin === "package" &&
+    commands[0].sourceInfo.baseDir === PACKAGE_ROOT &&
+    commands[0].sourceInfo.path === join(PACKAGE_ROOT, "prompts", `${name}.md`)
+  );
+}
+
+function hasExpandedPromptMarker(
+  prompt: string,
+  name: EligiblePrompt,
+): boolean {
+  const requestEnd = prompt.lastIndexOf("</abel-request>");
+  if (requestEnd < 0) return false;
+  const body = prompt.slice(requestEnd + "</abel-request>".length);
+  const marker = promptMarker(name);
+  return (
+    body.includes(marker) && body.indexOf(marker) === body.lastIndexOf(marker)
+  );
+}
+
+function activateDispatcher(
+  pi: ExtensionAPI,
+  activation: Activation,
+  name: EligiblePrompt,
+  prompt: string,
+): void {
+  if (
+    !hasPackageProvenance(pi, name) ||
+    !hasExpandedPromptMarker(prompt, name)
+  ) {
+    return;
+  }
+  if (!activation.isActive()) {
+    if (activation.state !== "inactive") return;
+    activation.request();
+    activation.activate();
+  }
+  const active = pi.getActiveTools();
+  if (!active.includes(DISPATCH_TOOL)) {
+    pi.setActiveTools(activateTool(active, DISPATCH_TOOL));
+  }
+}
+
 export default function register(pi: ExtensionAPI): void {
   const runtime = new Runtime();
+  const activity = new ActivityController();
 
   pi.registerTool({
     name: DISPATCH_TOOL,
@@ -34,30 +116,78 @@ export default function register(pi: ExtensionAPI): void {
       required: ["action"],
     },
     async execute(
-      _toolCallId: string,
+      toolCallId: string,
       params: { action?: string; request?: unknown; resultId?: string },
-      _signal: AbortSignal | undefined,
-      _onUpdate: unknown,
-      ctx: import("@earendil-works/pi-coding-agent").ExtensionContext,
+      signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+      ctx: ExtensionContext,
     ) {
       const action = typeof params?.action === "string" ? params.action : "";
-      const result = await runtime.execute(action, params, ctx);
+      const validRun =
+        action === "run" && runtime.validateRequest(params.request).ok;
+      const tuiRun = ctx.mode === "tui" && validRun;
+      const result = tuiRun
+        ? await runtime.execute(
+            action,
+            params,
+            ctx,
+            signal,
+            activity.observe(
+              toolCallId,
+              onUpdate as ((result: unknown) => void) | undefined,
+            ),
+          )
+        : await runtime.execute(action, params, ctx, signal);
+      const display = tuiRun
+        ? activity.finalize(toolCallId, result)
+        : undefined;
+      const details = display
+        ? { ...result, [ACTIVITY_DETAILS_KEY]: display }
+        : result;
       if (result.ok) {
         return {
           content: [{ type: "text", text: JSON.stringify(result) }],
-          details: result,
+          details,
           usage: result.usage,
         };
       }
       return {
         content: [{ type: "text", text: result.error }],
-        details: result,
+        details,
         isError: true,
       };
     },
+    renderCall(args: unknown, theme: Theme, _context: unknown) {
+      return renderActivityCall(args, theme);
+    },
+    renderResult(
+      result: AgentToolResult<unknown>,
+      options: ToolRenderResultOptions,
+      theme: Theme,
+      _context: unknown,
+    ) {
+      return renderActivityResult(result, options, theme);
+    },
   } as never);
 
-  pi.on("session_start", () => {
+  let pendingPrompt: EligiblePrompt | undefined;
+
+  pi.on("input", (event) => {
+    pendingPrompt = invokedPrompt(event.text);
+    return { action: "continue" };
+  });
+
+  pi.on("before_agent_start", (event) => {
+    const prompt = pendingPrompt;
+    pendingPrompt = undefined;
+    if (prompt)
+      activateDispatcher(pi, runtime.activation, prompt, event.prompt);
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    pendingPrompt = undefined;
+    activity.detach();
+    if (ctx.mode === "tui") activity.attach(ctx.ui);
     // Restore the default: dispatch is inactive unless a verified stage
     // reactivates it through the activation helpers.
     const active = pi.getActiveTools();
@@ -66,8 +196,10 @@ export default function register(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("session_shutdown", () => {
-    runtime.drain();
+  pi.on("session_shutdown", async () => {
+    activity.detach();
+    await runtime.drain();
+    activity.clear();
     const active = pi.getActiveTools();
     if (active.includes(DISPATCH_TOOL)) {
       pi.setActiveTools(deactivateTool(active, DISPATCH_TOOL));

package/src/parent-provider.ts

@@ -10,12 +10,19 @@ import {
 
 export async function runtimeForProvider(
   provider: Provider,
+  signal?: AbortSignal,
 ): Promise<ModelRuntime> {
-  const runtime = await ModelRuntime.create({
-    credentials: new InMemoryCredentialStore(),
-    modelsPath: null,
-    refreshOnCreate: false,
-  });
+  signal?.throwIfAborted();
+  const runtime = await abortable(
+    ModelRuntime.create({
+      credentials: new InMemoryCredentialStore(),
+      modelsPath: null,
+      refreshOnCreate: false,
+      signal,
+    }),
+    signal,
+  );
+  signal?.throwIfAborted();
   runtime.registerNativeProvider(provider);
   return runtime;
 }
@@ -69,17 +76,39 @@ export function phaseProvider(
 
 export async function runtimeFromContext(
   ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  signal?: AbortSignal,
 ): Promise<{ modelRuntime: ModelRuntime; model: Model<string> }> {
+  signal?.throwIfAborted();
   if (!ctx.model) throw new Error("parent model is unavailable");
   const parent = ctx.modelRegistry.getProvider(ctx.model.provider);
   if (!parent) throw new Error("parent Provider is unavailable");
-  const resolved = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+  const resolved = await abortable(
+    ctx.modelRegistry.getApiKeyAndHeaders(ctx.model),
+    signal,
+  );
   if (!resolved.ok) throw new Error(resolved.error);
+  signal?.throwIfAborted();
   const provider = phaseProvider(parent, resolved);
-  const modelRuntime = await runtimeForProvider(provider);
+  const modelRuntime = await runtimeForProvider(provider, signal);
+  signal?.throwIfAborted();
   const model = {
     ...ctx.model,
     baseUrl: resolved.baseUrl ?? ctx.model.baseUrl,
   } as Model<string>;
   return { modelRuntime, model };
 }
+
+function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  signal.throwIfAborted();
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}