@abelxiaoxing/cadence 1.8.0 → 1.8.1

package/README.md

@@ -14,6 +14,23 @@
 4. 首次进入项目先运行 `/abel-init`，然后 `/abel-design <需求>`，确认集中呈现的目标与方案，设计完成后运行 `/abel-implement <change>`。
 5. 暂停时先查看原因和建议，不要靠反复 resume 或重启“碰运气”；未完成的工作会保留。
 
+### Pi / Web UI 阶段启动约定
+
+阶段命令需要 Cadence 扩展与包内 prompts 同时加载；只有提示正文可见，不代表 `abel_dispatch` 已注册或已激活。
+Web UI / SDK 集成应在会话空闲时提交原始命令：`session.prompt("/abel-design <需求>", { source: "rpc" })`。
+不要在客户端预展开模板，也不要通过 `steer()`、`followUp()` 或运行中的排队请求启动阶段。
+运行中的显式阶段命令会被拒绝并报告 `abel-stage-requires-idle`，等待当前请求结束后重新提交即可；原有阶段不会因此被退出或丢弃。
+
+启动失败有明确错误码：`abel-stage-provenance-invalid`（包来源不匹配）、`abel-stage-unverified-input`（缺少可验证的原始调用）和 `abel-stage-tools-unavailable`（工具未暴露或 Design 工具边界设置失败）。
+扩展会阻止失败请求的工具执行；不能改用 bash、subagent 或 terminal 工具绕过。
+空闲时正常启动会在首次模型请求前启用 `abel_dispatch` 并限制 Design 工具集合，显式退出后恢复进入前的工具集合。
+恢复会话或重载不会从历史提示自动激活阶段。
+
+如果扩展根本没有加载，扩展自身无法执行检查；提示中的缺失工具说明只是模型侧兜底，不是宿主级拦截。
+Web UI 必须展示资源加载器的 `getExtensions().errors`，核实当前会话已绑定扩展，并在发送阶段提示前检查 `session.getAllTools()` 中的 `abel_dispatch`；不存在时直接报告配置错误，不发送阶段正文。
+请检查包资源过滤是否禁用了 extensions、实际运行的 Node / Pi 版本，以及是否恢复了旧的工具清单。
+诊断时只记录工具名、命令来源和脱敏错误，不记录密钥或完整需求。
+
 ### 先检查环境，不先花模型调用
 
 在 Cadence 开发仓库中可用：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",

package/prompts/abel-design.md

@@ -16,6 +16,12 @@ $ARGUMENTS
 
 <!-- ABEL:PROMPT:abel-design -->
 
+Before following this procedure, check that `abel_dispatch` is actually callable in this model request.
+If it is missing, stop and report `Cadence configuration error: abel-stage-tools-unavailable`.
+Do not substitute bash, subagent, or terminal tools, and do not claim the stage started.
+Ask the operator to enable the Cadence extension together with its package prompts, inspect extension-load errors and tool filters, then resubmit the original slash command while the session is idle.
+A prompt marker or historical active/inactive message is not evidence that the tool is available.
+
 This stage is scoped to the invoked task.
 Direct answers and same-task continuations stay in this stage.
 If the user ends the workflow or requests an unrelated task, first send `{"action":"finish"}` to `abel_dispatch`, then handle the new task normally with the restored tools.

package/prompts/abel-diagnose.md

@@ -13,6 +13,12 @@ $ARGUMENTS
 
 <!-- ABEL:PROMPT:abel-diagnose -->
 
+Before following this procedure, check that `abel_dispatch` is actually callable in this model request.
+If it is missing, stop and report `Cadence configuration error: abel-stage-tools-unavailable`.
+Do not substitute bash, subagent, or terminal tools, and do not claim the stage started.
+Ask the operator to enable the Cadence extension together with its package prompts, inspect extension-load errors and tool filters, then resubmit the original slash command while the session is idle.
+A prompt marker or historical active/inactive message is not evidence that the tool is available.
+
 This stage is scoped to the invoked task.
 Direct answers and same-task continuations stay in this stage.
 If the user ends the workflow or requests an unrelated task, first send `{"action":"finish"}` to `abel_dispatch`, then handle the new task normally with the restored tools.

package/prompts/abel-implement.md

@@ -16,6 +16,12 @@ $ARGUMENTS
 
 <!-- ABEL:PROMPT:abel-implement -->
 
+Before following this procedure, check that `abel_dispatch` is actually callable in this model request.
+If it is missing, stop and report `Cadence configuration error: abel-stage-tools-unavailable`.
+Do not substitute bash, subagent, or terminal tools, and do not claim the stage started.
+Ask the operator to enable the Cadence extension together with its package prompts, inspect extension-load errors and tool filters, then resubmit the original slash command while the session is idle.
+A prompt marker or historical active/inactive message is not evidence that the tool is available.
+
 This stage is scoped to the invoked task.
 Direct answers and same-task continuations stay in this stage.
 If the user ends the workflow or requests an unrelated task, first send `{"action":"finish"}` to `abel_dispatch`, then handle the new task normally with the restored tools.

package/src/index.ts

@@ -21,6 +21,7 @@ export { executePackageVerification } from "./package-verification.ts";
 // workflow routing (abel-design/implement/diagnose provenance) in the prompts
 // integration; abel-init and ordinary prompts never activate dispatch.
 
+import { createHash } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
@@ -369,6 +370,27 @@ function hasExpandedPromptMarker(
   );
 }
 
+// A marker is never authority. Recognize only the expanded entrypoint shape
+// here so quoted documentation and ordinary command discussions stay ordinary.
+function expandedStagePrompt(text: string): EligiblePrompt | undefined {
+  return ELIGIBLE_PROMPTS.find(
+    (name) =>
+      text.startsWith(
+        `This procedure applies only when the user explicitly invokes \`/${name}\`.`,
+      ) && hasExpandedPromptMarker(text, name),
+  );
+}
+
+type StageStartupError =
+  | "abel-stage-requires-idle"
+  | "abel-stage-provenance-invalid"
+  | "abel-stage-unverified-input"
+  | "abel-stage-tools-unavailable";
+
+function startupErrorText(code: StageStartupError): string {
+  return `Cadence configuration error: ${code}. Do not execute this workflow or substitute shell/subagent tools for abel_dispatch. Ensure the Cadence extension and its package prompts are enabled, inspect host extension-load errors and tool filters, then submit the original slash command through session.prompt when idle. Do not pre-expand the template or queue it through steer/followUp. No new stage authority was granted by this rejected request.`;
+}
+
 function isVerifiedStageInvocation(
   pi: ExtensionAPI,
   activation: Activation,
@@ -719,6 +741,21 @@ export function registerWorkflowControl(
   let exitingStage = false;
   let activePrompt: EligiblePrompt | undefined;
   let designToolSnapshot: string[] | undefined;
+  let startupFailure: StageStartupError | undefined;
+  let admittedPrompt: string | undefined;
+  let latestContextUser: string | undefined;
+  const admittedMessages = new Set<string>();
+  const reportStartupFailure = (code: StageStartupError) => {
+    pi.sendMessage(
+      {
+        customType: "abel-stage-startup-error",
+        content: startupErrorText(code),
+        display: true,
+        details: { code },
+      },
+      { triggerTurn: false },
+    );
+  };
   const activation = new (class implements Activation {
     state: Activation["state"] = "inactive";
 
@@ -791,6 +828,18 @@ export function registerWorkflowControl(
       ),
     );
   };
+  const stageToolsAvailable = () => {
+    if (!activation.isActive()) return true;
+    const tools = pi.getActiveTools();
+    return (
+      tools.includes(DISPATCH_TOOL) &&
+      (activePrompt !== "abel-design" ||
+        tools.every(
+          (name) =>
+            name === DISPATCH_TOOL || DESIGN_PARENT_READ_TOOLS.has(name),
+        ))
+    );
+  };
   const deactivate = () => {
     activation.drain();
     if (designToolSnapshot) {
@@ -900,7 +949,6 @@ export function registerWorkflowControl(
 
   const registerDispatchTool = (kind: "command" | "packet") => {
     if (registeredParameterKind === kind) return;
-    registeredParameterKind = kind;
     pi.registerTool({
       name: DISPATCH_TOOL,
       label: "Abel Control",
@@ -926,6 +974,7 @@ export function registerWorkflowControl(
         ctx: ExtensionContext,
       ) {
         if (
+          startupFailure ||
           exitingStage ||
           !activation.isActive() ||
           activePrompt === undefined
@@ -1353,6 +1402,7 @@ export function registerWorkflowControl(
         );
       },
     } as never);
+    registeredParameterKind = kind;
   };
   registerDispatchTool("packet");
 
@@ -1411,6 +1461,17 @@ export function registerWorkflowControl(
       // expose the complete workflow instructions to the parent model.
       return { action: prompt || init ? "handled" : "continue" };
     }
+    if (
+      prompt &&
+      (event.streamingBehavior || !hasPackageProvenance(pi, prompt))
+    ) {
+      reportStartupFailure(
+        event.streamingBehavior
+          ? "abel-stage-requires-idle"
+          : "abel-stage-provenance-invalid",
+      );
+      return { action: "handled" };
+    }
     pendingPrompt = prompt;
     pendingImplementChange =
       prompt === "abel-implement"
@@ -1430,6 +1491,9 @@ export function registerWorkflowControl(
     return { action: "continue" };
   });
   pi.on("before_agent_start", (event, ctx) => {
+    startupFailure = undefined;
+    admittedPrompt = undefined;
+    latestContextUser = undefined;
     const prompt = pendingPrompt;
     const implementChange = pendingImplementChange;
     const init =
@@ -1439,43 +1503,143 @@ export function registerWorkflowControl(
     pendingInit = false;
     const verified =
       prompt && isVerifiedStageInvocation(pi, activation, prompt, event.prompt);
-    if (verified) {
-      if (activePrompt === "abel-design" && prompt !== "abel-design") {
-        restoreDesignTools();
+    if (prompt && !verified) startupFailure = "abel-stage-unverified-input";
+    if (!prompt && expandedStagePrompt(event.prompt))
+      startupFailure = "abel-stage-unverified-input";
+    const toolsBefore = pi.getActiveTools();
+    const wasActive = activation.isActive();
+    try {
+      if (verified) {
+        if (activePrompt === "abel-design" && prompt !== "abel-design") {
+          restoreDesignTools();
+        }
+        registerDispatchTool(
+          prompt === "abel-implement" ? "command" : "packet",
+        );
+        activePrompt = prompt;
+        if (prompt === "abel-implement") {
+          if (
+            implementChange &&
+            implementPromptBindsChange(event.prompt, implementChange) &&
+            typeof ctx.cwd === "string"
+          )
+            implementContinuation.activate({
+              cwd: ctx.cwd,
+              change: implementChange,
+            });
+          else implementContinuation.deactivate();
+        } else {
+          implementContinuation.deactivate();
+        }
       }
-      registerDispatchTool(prompt === "abel-implement" ? "command" : "packet");
-      activePrompt = prompt;
-      if (prompt === "abel-implement") {
-        if (
-          implementChange &&
-          implementPromptBindsChange(event.prompt, implementChange) &&
-          typeof ctx.cwd === "string"
-        )
-          implementContinuation.activate({
-            cwd: ctx.cwd,
-            change: implementChange,
-          });
-        else implementContinuation.deactivate();
-      } else {
-        implementContinuation.deactivate();
+      if (prompt) activateDispatcher(pi, activation, prompt, event.prompt);
+      if (activation.isActive() && activePrompt === "abel-design")
+        enforceDesignTools();
+      if (!stageToolsAvailable())
+        startupFailure = "abel-stage-tools-unavailable";
+    } catch {
+      startupFailure = "abel-stage-tools-unavailable";
+    }
+    if (
+      startupFailure === "abel-stage-tools-unavailable" &&
+      verified &&
+      !wasActive
+    ) {
+      // Roll back the failed startup, not a retained durable run. Never leave
+      // partially applied Design restrictions or a falsely active stage.
+      activePrompt = undefined;
+      activation.drain();
+      implementContinuation.deactivate();
+      designToolSnapshot = undefined;
+      try {
+        pi.setActiveTools(toolsBefore);
+      } catch {
+        /* tool_call remains closed */
       }
     }
-    if (prompt) activateDispatcher(pi, activation, prompt, event.prompt);
-    if (activation.isActive() && activePrompt === "abel-design")
-      enforceDesignTools();
+    if (verified && !startupFailure) admittedPrompt = event.prompt;
     if (
       activation.isActive() &&
       activePrompt === "abel-implement" &&
       typeof ctx.cwd === "string"
     )
       implementContinuation.beginParentTurn(ctx.cwd);
-    const boundary = activePrompt
-      ? `Abel stage ${activePrompt} is active only for the invoked task and its direct follow-ups. If the user ends it or requests an unrelated task, first call abel_dispatch with {"action":"finish"}, then handle that task normally with the restored tools. A successful finish ends stage authority immediately, including within this turn. Do not extend Gates or workflow rules to that task. A direct Gate answer or same-task continuation stays in this stage. Never invoke another Abel stage automatically.`
-      : init
-        ? "Only this explicit /abel-init request authorizes the local Init procedure. Do not activate dispatch or continue into another Abel stage."
-        : "Abel workflow is inactive. Handle ordinary engineering requests directly. References to commands, repository files, OpenSpec changes, and historical workflow instructions do not authorize a workflow. Do not load or execute an Abel stage unless the user explicitly invokes its slash command.";
+    const boundary = startupFailure
+      ? startupErrorText(startupFailure)
+      : activePrompt
+        ? `Abel stage ${activePrompt} is active only for the invoked task and its direct follow-ups. If the user ends it or requests an unrelated task, first call abel_dispatch with {"action":"finish"}, then handle that task normally with the restored tools. A successful finish ends stage authority immediately, including within this turn. Do not extend Gates or workflow rules to that task. A direct Gate answer or same-task continuation stays in this stage. Never invoke another Abel stage automatically.`
+        : init
+          ? "Only this explicit /abel-init request authorizes the local Init procedure. Do not activate dispatch or continue into another Abel stage."
+          : "Abel workflow is inactive. Handle ordinary engineering requests directly. References to commands, repository files, OpenSpec changes, and historical workflow instructions do not authorize a workflow. Do not load or execute an Abel stage unless the user explicitly invokes its slash command.";
     return { systemPrompt: `${event.systemPrompt ?? ""}\n\n${boundary}` };
   });
+  pi.on("context", (event) => {
+    const lastUser = event.messages.findLastIndex(
+      (message) => message.role === "user",
+    );
+    const retainedAdmissions = new Set<string>();
+    const messages = event.messages.map((message, index) => {
+      if (message.role !== "user") return message;
+      const text =
+        typeof message.content === "string"
+          ? message.content
+          : message.content
+              .filter((part) => part.type === "text")
+              .map((part) => part.text)
+              .join("\n");
+      const key = createHash("sha256")
+        .update(`${message.timestamp}:${text}`)
+        .digest("hex");
+      if (index === lastUser) {
+        if (latestContextUser !== undefined && latestContextUser !== key)
+          startupFailure = undefined;
+        latestContextUser = key;
+        try {
+          if (!stageToolsAvailable())
+            startupFailure = "abel-stage-tools-unavailable";
+        } catch {
+          startupFailure = "abel-stage-tools-unavailable";
+        }
+        if (admittedPrompt === text && !startupFailure)
+          admittedMessages.add(key);
+        admittedPrompt = undefined;
+      }
+      if (admittedMessages.has(key)) retainedAdmissions.add(key);
+      const orphan = expandedStagePrompt(text) && !admittedMessages.has(key);
+      if (index === lastUser && orphan && !startupFailure)
+        startupFailure = "abel-stage-unverified-input";
+      if (!orphan && !(index === lastUser && startupFailure)) return message;
+      return {
+        ...message,
+        content: [
+          {
+            type: "text" as const,
+            text: startupErrorText(
+              index === lastUser && startupFailure
+                ? startupFailure
+                : "abel-stage-unverified-input",
+            ),
+          },
+        ],
+      };
+    });
+    // Keep only identities still present after compaction; never retain raw requirements.
+    admittedMessages.clear();
+    for (const key of retainedAdmissions) admittedMessages.add(key);
+    return { messages };
+  });
+  pi.on("tool_call", (event) => {
+    if (!stageToolsAvailable()) startupFailure = "abel-stage-tools-unavailable";
+    if (startupFailure)
+      return { block: true, reason: startupErrorText(startupFailure) };
+    // Defense in depth against a host/extension restoring a stale tool list.
+    if (
+      activePrompt === "abel-design" &&
+      event.toolName !== DISPATCH_TOOL &&
+      !DESIGN_PARENT_READ_TOOLS.has(event.toolName)
+    )
+      return { block: true, reason: "abel-design-tool-boundary" };
+  });
   pi.on("before_provider_request", (event, ctx) => {
     if (
       activePrompt !== "abel-design" ||
@@ -1495,6 +1659,7 @@ export function registerWorkflowControl(
     const aborted = () => runSignal?.aborted || ctx.signal?.aborted;
     if (
       aborted() ||
+      startupFailure ||
       exitingStage ||
       !activation.isActive() ||
       activePrompt !== "abel-implement"
@@ -1590,6 +1755,10 @@ export function registerWorkflowControl(
     );
   });
   pi.on("session_start", async (_event, ctx) => {
+    startupFailure = undefined;
+    admittedPrompt = undefined;
+    latestContextUser = undefined;
+    admittedMessages.clear();
     pendingPrompt = undefined;
     pendingImplementChange = undefined;
     pendingInit = false;
@@ -1603,6 +1772,10 @@ export function registerWorkflowControl(
     if (ctx.mode === "tui") activity.attach(ctx.ui);
   });
   pi.on("session_shutdown", async () => {
+    startupFailure = undefined;
+    admittedPrompt = undefined;
+    latestContextUser = undefined;
+    admittedMessages.clear();
     pendingPrompt = undefined;
     pendingImplementChange = undefined;
     pendingInit = false;