@abelxiaoxing/cadence 1.0.6 → 1.0.8

package/agents/design-explorer.md

@@ -5,13 +5,18 @@ You are a package-owned read-only professional Agent for the `abel-design` stage
 You explore the repository ONLY through the scoped `read`, `grep`, `find`, and `ls` tools.
 You have no shell, edit, Git, network, or validation capability, and you never create or modify files.
 
-Your output is a compact structured evidence object returned through `abel_submit_result`, containing:
+Call `abel_submit_result` exactly once with one structured object.
+Do not emit a second submit, prose, or the legacy `conclusions`/`citations` shape.
+The object contains the matching `id`, `role: "design-explorer"`, `kind: "evidence"`, and:
 
-- the matching request id and your role name;
-- your bounded path scope and the exact files and directories you inspected;
-- concise conclusions with exact file-and-line citations;
-- constraints, dependencies, risks, and blocking questions;
-- write-set, verification-command, and AGENTS-impact hints for later tasks.
+- `packet_id` (exactly equal to the request id), `module_name`, `scope`, and
+  `files_read`;
+- `evidence`, where every item has `claim`, `path`, `line_start`, and
+  `line_end`;
+- `existing_structures`, `existing_conventions`, `constraints_discovered`,
+  `open_questions`, and `dependencies`;
+- `write_set_hints`, `validation_hints`, `agents_impact_hints`, `risks`, and
+  `success_criteria_hints`.
 
 You never return raw transcripts, hidden reasoning, or tool-call history.
 A packet is complete only when every claim is cited and every blocking question is explicit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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",

package/prompts/abel-design.md

@@ -54,6 +54,36 @@ $ARGUMENTS
 
 ## 阶段 1 —— 证据探索（只读）
 
+- 使用私有工具 `abel_dispatch` 的 `action: "run"` 派发探索包。
+  每个包对应一个独立 tool call，`request` 必须是单个 envelope；禁止使用 `requests` 数组或其他批量 wrapper。
+- 用户要求两个或更多并行包时，下一次 assistant response 必须只包含全部 sibling `abel_dispatch` tool calls，并在该同一 assistant turn（同一响应轮次）一次发齐；少发、先等一个结果、在后续 turn 补发均为调度失败，不得用串行重试或父代理并行读取冒充 Subagent。
+- Design 单包 envelope 的精确形状如下；字段名、固定值和数组形状不得猜测或改写：
+
+  ```json
+  {
+    "action": "run",
+    "request": {
+      "stage": "abel-design",
+      "role": "design-explorer",
+      "id": "unique-packet-id",
+      "phase": "evidence",
+      "objective": "bounded evidence objective for this packet",
+      "roots": ["."],
+      "context": {
+        "agents": "applicable AGENTS.md instructions",
+        "contract": "exact scope, retrieval, read-only, output, and budget contract"
+      },
+      "declared": {
+        "read": ["exact/relative/path"],
+        "write": [],
+        "conflicts": [],
+        "resources": []
+      },
+      "output": "evidence"
+    }
+  }
+  ```
+
 - 主 agent 只负责核实相关 AGENTS、拆分探索包、派发、校验证据、综合、澄清与 Gate 呈现；广泛代码库探索必须委派。
   主 agent 仅可为范围划分、引用抽查和冲突裁决做最小定向读取。
 - 默认并行派发多个只读探索子代理：优先按独立上下文边界拆分；只有一个边界时，按互不重叠的路径或符号证据面拆分。

package/src/contracts.ts

@@ -1401,7 +1401,7 @@ function requireCanonicalDiffPath(path: string): string {
   return path;
 }
 
-export interface EvidenceResult {
+export interface CompactEvidenceResult {
   id: string;
   role: string;
   kind: "evidence";
@@ -1414,6 +1414,34 @@ export interface EvidenceResult {
   hints: { writeSet: string[]; verification: string; agentsImpact: string };
 }
 
+export interface DesignEvidenceResult {
+  id: string;
+  role: "design-explorer";
+  kind: "evidence";
+  packet_id: string;
+  module_name: string;
+  scope: string[];
+  files_read: string[];
+  evidence: Array<{
+    claim: string;
+    path: string;
+    line_start: number;
+    line_end: number;
+  }>;
+  existing_structures: string[];
+  existing_conventions: string[];
+  constraints_discovered: string[];
+  open_questions: string[];
+  dependencies: string[];
+  write_set_hints: string[];
+  validation_hints: string[];
+  agents_impact_hints: string[];
+  risks: string[];
+  success_criteria_hints: string[];
+}
+
+export type EvidenceResult = CompactEvidenceResult | DesignEvidenceResult;
+
 export interface DiffResult {
   id: string;
   role: string;
@@ -1511,6 +1539,7 @@ export function validateEvidenceResult(value: unknown): {
     return { ok: false, reason: "missing result" };
   const r = value as Record<string, unknown>;
   if (r.kind !== "evidence") return { ok: false, reason: "wrong result kind" };
+  if (r.role === "design-explorer") return validateDesignEvidenceResult(r);
   const fields = [
     "id",
     "role",
@@ -1577,6 +1606,98 @@ export function validateEvidenceResult(value: unknown): {
   return { ok: true };
 }
 
+function validateDesignEvidenceResult(r: Record<string, unknown>): {
+  ok: boolean;
+  reason?: string;
+  failure?: CandidateFailure;
+} {
+  const fields = [
+    "id",
+    "role",
+    "kind",
+    "packet_id",
+    "module_name",
+    "scope",
+    "files_read",
+    "evidence",
+    "existing_structures",
+    "existing_conventions",
+    "constraints_discovered",
+    "open_questions",
+    "dependencies",
+    "write_set_hints",
+    "validation_hints",
+    "agents_impact_hints",
+    "risks",
+    "success_criteria_hints",
+  ] as const;
+  if (!hasExactKeys(r, fields)) {
+    return { ok: false, reason: "invalid Design evidence result fields" };
+  }
+  if (
+    !validIdentifier(r.id) ||
+    r.packet_id !== r.id ||
+    !validIdentifier(r.module_name)
+  ) {
+    return { ok: false, reason: "invalid Design evidence identity" };
+  }
+  if (!validatePathSet(r.scope) || r.scope.length === 0) {
+    return { ok: false, reason: "invalid Design evidence scope" };
+  }
+  if (!validatePathSet(r.files_read) || !validatePathSet(r.write_set_hints)) {
+    return { ok: false, reason: "invalid Design evidence path set" };
+  }
+  if (
+    !Array.isArray(r.evidence) ||
+    r.evidence.some(
+      (entry) =>
+        !hasExactKeys(entry, ["claim", "path", "line_start", "line_end"]) ||
+        typeof entry.claim !== "string" ||
+        entry.claim.length === 0 ||
+        !isValidRelativePath(entry.path) ||
+        !Number.isSafeInteger(entry.line_start) ||
+        !Number.isSafeInteger(entry.line_end) ||
+        (entry.line_start as number) < 1 ||
+        (entry.line_end as number) < (entry.line_start as number),
+    )
+  ) {
+    return { ok: false, reason: "invalid Design evidence citations" };
+  }
+  for (const field of [
+    "existing_structures",
+    "existing_conventions",
+    "constraints_discovered",
+    "open_questions",
+    "dependencies",
+    "validation_hints",
+    "agents_impact_hints",
+    "risks",
+    "success_criteria_hints",
+  ] as const) {
+    if (
+      !Array.isArray(r[field]) ||
+      !r[field].every((entry) => typeof entry === "string")
+    ) {
+      return {
+        ok: false,
+        reason: `invalid Design evidence field: ${field}`,
+      };
+    }
+  }
+  const serialized = JSON.stringify(r);
+  if (Buffer.byteLength(serialized, "utf8") > LIMITS.maxCompleteResultBytes) {
+    return {
+      ok: false,
+      reason: `result exceeds ${LIMITS.maxCompleteResultBytes} bytes`,
+      failure: {
+        kind: "result-limit",
+        limitBytes: LIMITS.maxCompleteResultBytes,
+      },
+    };
+  }
+  return { ok: true };
+}
+
 export function validateDiffResult(value: unknown): {
   ok: boolean;
   reason?: string;

package/src/index.ts

@@ -34,6 +34,117 @@ const ELIGIBLE_PROMPTS = [
 ] as const;
 type EligiblePrompt = (typeof ELIGIBLE_PROMPTS)[number];
 
+const GENERIC_REQUEST_SCHEMA = {
+  type: "object",
+  description:
+    "Stage-specific request envelope for action=run. The verified Abel prompt refreshes this schema before the stage's first model turn.",
+} as const;
+
+const DESIGN_REQUEST_SCHEMA = {
+  type: "object",
+  description:
+    "One bounded read-only design-explorer packet. Send one sibling abel_dispatch tool call per packet; do not wrap multiple packets in requests.",
+  properties: {
+    stage: {
+      type: "string",
+      enum: ["abel-design"],
+      description: "Exact verified workflow stage.",
+    },
+    role: {
+      type: "string",
+      enum: ["design-explorer"],
+      description: "Exact package-owned read-only Agent role.",
+    },
+    id: {
+      type: "string",
+      description:
+        "Unique packet and request identity, at most 128 characters.",
+    },
+    phase: {
+      type: "string",
+      enum: ["evidence"],
+      description: "Design exploration phase.",
+    },
+    objective: {
+      type: "string",
+      description: "Bounded evidence objective for this packet only.",
+    },
+    roots: {
+      type: "array",
+      items: { type: "string" },
+      description: 'Approved relative workspace roots, normally ["."].',
+    },
+    context: {
+      type: "object",
+      properties: {
+        agents: {
+          type: "string",
+          description: "Applicable AGENTS.md instructions for this packet.",
+        },
+        contract: {
+          type: "string",
+          description:
+            "Packet scope, retrieval, read-only, and structured-output contract.",
+        },
+      },
+      required: ["agents", "contract"],
+      additionalProperties: false,
+    },
+    declared: {
+      type: "object",
+      properties: {
+        read: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Exact relative files or directories this packet may read.",
+        },
+        write: {
+          type: "array",
+          items: { type: "string" },
+          description: "Must be empty for design-explorer.",
+        },
+        conflicts: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Declared conflict edges; normally empty for read-only packets.",
+        },
+        resources: {
+          type: "array",
+          items: { type: "string" },
+          description: "Declared exclusive resources; normally empty.",
+        },
+      },
+      required: ["read", "write", "conflicts", "resources"],
+      additionalProperties: false,
+    },
+    output: {
+      type: "string",
+      enum: ["evidence"],
+      description: "Exact structured child-result kind.",
+    },
+  },
+  required: [
+    "stage",
+    "role",
+    "id",
+    "phase",
+    "objective",
+    "roots",
+    "context",
+    "declared",
+    "output",
+  ],
+  additionalProperties: false,
+} as const;
+
+function requestSchemaForStage(name?: EligiblePrompt): object {
+  return name === "abel-design"
+    ? DESIGN_REQUEST_SCHEMA
+    : GENERIC_REQUEST_SCHEMA;
+}
+
 function invokedPrompt(text: string): EligiblePrompt | undefined {
   const name = text.match(/^\/([^\s]+)(?:\s|$)/)?.[1];
   return ELIGIBLE_PROMPTS.find((candidate) => candidate === name);
@@ -112,100 +223,105 @@ export default function register(pi: ExtensionAPI): void {
   const runtime = new Runtime({ parentPayloadBridge });
   const activity = new ActivityController();
 
-  pi.registerTool({
-    name: DISPATCH_TOOL,
-    label: "Abel Dispatch",
-    description:
-      "Private Abel workflow delegation: run bounded read-only evidence or Worker phase requests, apply or discard retained results, apply a parent-only stable AGENTS checkpoint, cancel work, or finish the stage. Inactive unless an eligible Abel stage verified its invocation.",
-    parameters: {
-      type: "object",
-      properties: {
-        action: { type: "string", enum: [...ACTIONS] },
-        request: {
-          type: "object",
-          description: "Request envelope for action=run",
-        },
-        resultId: {
-          type: "string",
-          description: "Retained result id for apply/discard",
-        },
-        requestId: {
-          type: "string",
-          description: "Current Implement apply/discard operation identity",
-        },
-        rejection: {
-          type: "object",
-          description: "Typed parent rejection for Implement discard",
+  const registerDispatchTool = (stage?: EligiblePrompt) => {
+    pi.registerTool({
+      name: DISPATCH_TOOL,
+      label: "Abel Dispatch",
+      description:
+        stage === "abel-design"
+          ? "Run exactly one bounded read-only design-explorer packet. When parallel packets are required, emit every sibling abel_dispatch call together in one assistant response before waiting for any result."
+          : "Private Abel workflow delegation: run bounded read-only evidence or Worker phase requests, apply or discard retained results, apply a parent-only stable AGENTS checkpoint, cancel work, or finish the stage. Inactive unless an eligible Abel stage verified its invocation.",
+      executionMode: "parallel",
+      parameters: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: [...ACTIONS] },
+          request: requestSchemaForStage(stage),
+          resultId: {
+            type: "string",
+            description: "Retained result id for apply/discard",
+          },
+          requestId: {
+            type: "string",
+            description: "Current Implement apply/discard operation identity",
+          },
+          rejection: {
+            type: "object",
+            description: "Typed parent rejection for Implement discard",
+          },
+          agentsCheckpoint: {
+            type: "object",
+            description:
+              "Parent-owned approved managed-block checkpoint for action=apply (mutually exclusive with resultId)",
+          },
         },
-        agentsCheckpoint: {
-          type: "object",
-          description:
-            "Parent-owned approved managed-block checkpoint for action=apply (mutually exclusive with resultId)",
+        required: ["action"],
+      },
+      async execute(
+        toolCallId: string,
+        params: {
+          action?: string;
+          request?: unknown;
+          resultId?: string;
+          requestId?: string;
+          rejection?: unknown;
+          agentsCheckpoint?: unknown;
         },
+        signal: AbortSignal | undefined,
+        onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+        ctx: ExtensionContext,
+      ) {
+        const action = typeof params?.action === "string" ? params.action : "";
+        const validRun =
+          action === "run" && runtime.validateRequest(params.request).ok;
+        const tuiRun = ctx.mode === "tui" && validRun;
+        const { action: _action, ...operation } = params;
+        const result = tuiRun
+          ? await runtime.execute(
+              action,
+              operation,
+              ctx,
+              signal,
+              activity.observe(
+                toolCallId,
+                onUpdate as ((result: unknown) => void) | undefined,
+              ),
+            )
+          : await runtime.execute(action, operation, ctx, signal);
+        const display = tuiRun
+          ? activity.finalize(toolCallId, result)
+          : undefined;
+        const { payload, usage } = splitUsage(result);
+        const details = display
+          ? {
+              ...(payload as Record<string, unknown>),
+              [ACTIVITY_DETAILS_KEY]: display,
+            }
+          : payload;
+        return {
+          content: [{ type: "text", text: JSON.stringify(payload) }],
+          details,
+          ...(usage === undefined ? {} : { usage }),
+        };
       },
-      required: ["action"],
-    },
-    async execute(
-      toolCallId: string,
-      params: {
-        action?: string;
-        request?: unknown;
-        resultId?: string;
-        requestId?: string;
-        rejection?: unknown;
-        agentsCheckpoint?: unknown;
+      renderCall(args: unknown, theme: Theme, _context: unknown) {
+        return renderActivityCall(args, theme);
       },
-      signal: AbortSignal | undefined,
-      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
-      ctx: ExtensionContext,
-    ) {
-      const action = typeof params?.action === "string" ? params.action : "";
-      const validRun =
-        action === "run" && runtime.validateRequest(params.request).ok;
-      const tuiRun = ctx.mode === "tui" && validRun;
-      const { action: _action, ...operation } = params;
-      const result = tuiRun
-        ? await runtime.execute(
-            action,
-            operation,
-            ctx,
-            signal,
-            activity.observe(
-              toolCallId,
-              onUpdate as ((result: unknown) => void) | undefined,
-            ),
-          )
-        : await runtime.execute(action, operation, ctx, signal);
-      const display = tuiRun
-        ? activity.finalize(toolCallId, result)
-        : undefined;
-      const { payload, usage } = splitUsage(result);
-      const details = display
-        ? {
-            ...(payload as Record<string, unknown>),
-            [ACTIVITY_DETAILS_KEY]: display,
-          }
-        : payload;
-      return {
-        content: [{ type: "text", text: JSON.stringify(payload) }],
-        details,
-        ...(usage === undefined ? {} : { usage }),
-      };
-    },
-    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);
+      renderResult(
+        result: AgentToolResult<unknown>,
+        options: ToolRenderResultOptions,
+        theme: Theme,
+        _context: unknown,
+      ) {
+        return renderActivityResult(result, options, theme);
+      },
+    } as never);
+  };
+
+  registerDispatchTool();
 
   let pendingPrompt: EligiblePrompt | undefined;
+  let activePrompt: EligiblePrompt | undefined;
 
   pi.on("input", (event) => {
     pendingPrompt = invokedPrompt(event.text);
@@ -215,10 +331,12 @@ export default function register(pi: ExtensionAPI): void {
   pi.on("before_agent_start", (event, ctx) => {
     const prompt = pendingPrompt;
     pendingPrompt = undefined;
-    if (
+    const verified =
       prompt &&
-      isVerifiedStageInvocation(pi, runtime.activation, prompt, event.prompt)
-    ) {
+      isVerifiedStageInvocation(pi, runtime.activation, prompt, event.prompt);
+    if (verified) {
+      activePrompt = prompt;
+      registerDispatchTool(prompt);
       const sessionId = ctx.sessionManager?.getSessionId?.();
       if (typeof sessionId === "string") {
         parentPayloadBridge.beginSession(sessionId);
@@ -233,8 +351,22 @@ export default function register(pi: ExtensionAPI): void {
       activateDispatcher(pi, runtime.activation, prompt, event.prompt);
   });
 
+  pi.on("before_provider_request", (event, ctx) => {
+    if (
+      activePrompt !== "abel-design" ||
+      ctx.model?.api !== "openai-responses" ||
+      event.payload === null ||
+      typeof event.payload !== "object" ||
+      Array.isArray(event.payload)
+    ) {
+      return;
+    }
+    return { ...event.payload, parallel_tool_calls: true };
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     pendingPrompt = undefined;
+    activePrompt = undefined;
     activity.detach();
     const active = pi.getActiveTools();
     if (active.includes(DISPATCH_TOOL)) {
@@ -268,6 +400,7 @@ export default function register(pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", async () => {
+    activePrompt = undefined;
     activity.detach();
     await runtime.drain();
     activity.clear();

package/src/runtime.ts

@@ -1821,9 +1821,19 @@ export class Runtime {
       };
     }
     if (!task) {
-      const result = await this.dispatchChild(agent, envelope, ctx, signal);
-      this.captureUsage(context, "launch:0", result.usage);
-      return this.withUsage(context, result);
+      const first = await this.dispatchChild(agent, envelope, ctx, signal);
+      this.captureUsage(context, "launch:0", first.usage);
+      const retryInvalidDesignResult =
+        !signal.aborted &&
+        envelope.stage === "abel-design" &&
+        !first.ok &&
+        first.failure?.kind === "artifact" &&
+        first.failure.code === "invalid-structural-result";
+      if (!retryInvalidDesignResult) return this.withUsage(context, first);
+
+      const second = await this.dispatchChild(agent, envelope, ctx, signal);
+      this.captureUsage(context, "launch:1", second.usage);
+      return this.withUsage(context, second);
     }
     if (task.workerIdentity !== workerIdentity(ctx.model)) {
       throw new Error("provider/model identity mismatch");

package/src/subagent-activity.ts

@@ -354,6 +354,21 @@ export function summarizeDispatchResult(
       blockingQuestions: value.blockingQuestions.length,
     };
   }
+  if (
+    value.kind === "evidence" &&
+    Array.isArray(value.evidence) &&
+    Array.isArray(value.existing_structures) &&
+    Array.isArray(value.risks) &&
+    Array.isArray(value.open_questions)
+  ) {
+    return {
+      kind: "evidence",
+      conclusions: value.existing_structures.length,
+      citations: value.evidence.length,
+      risks: value.risks.length,
+      blockingQuestions: value.open_questions.length,
+    };
+  }
   if (
     value.kind === "diff" &&
     typeof value.summary === "string" &&

package/src/submit-tool.ts

@@ -8,7 +8,7 @@ import {
   validateEvidenceResult,
 } from "./contracts.ts";
 
-const evidenceSchema = Type.Object({
+const compactEvidenceSchema = Type.Object({
   id: Type.String(),
   role: Type.String(),
   kind: Type.Literal("evidence"),
@@ -27,6 +27,40 @@ const evidenceSchema = Type.Object({
   }),
 });
 
+const designEvidenceSchema = Type.Object(
+  {
+    id: Type.String(),
+    role: Type.Literal("design-explorer"),
+    kind: Type.Literal("evidence"),
+    packet_id: Type.String(),
+    module_name: Type.String(),
+    scope: Type.Array(Type.String()),
+    files_read: Type.Array(Type.String()),
+    evidence: Type.Array(
+      Type.Object(
+        {
+          claim: Type.String(),
+          path: Type.String(),
+          line_start: Type.Integer({ minimum: 1 }),
+          line_end: Type.Integer({ minimum: 1 }),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+    existing_structures: Type.Array(Type.String()),
+    existing_conventions: Type.Array(Type.String()),
+    constraints_discovered: Type.Array(Type.String()),
+    open_questions: Type.Array(Type.String()),
+    dependencies: Type.Array(Type.String()),
+    write_set_hints: Type.Array(Type.String()),
+    validation_hints: Type.Array(Type.String()),
+    agents_impact_hints: Type.Array(Type.String()),
+    risks: Type.Array(Type.String()),
+    success_criteria_hints: Type.Array(Type.String()),
+  },
+  { additionalProperties: false },
+);
+
 const diffSchema = Type.Object({
   id: Type.String(),
   role: Type.String(),
@@ -85,7 +119,12 @@ export function createSubmitTool(input: {
     description:
       "Submit the one final structured Abel evidence or complete unified-diff result.",
     executionMode: "sequential",
-    parameters: input.output === "evidence" ? evidenceSchema : diffSchema,
+    parameters:
+      input.output === "evidence"
+        ? input.role === "design-explorer"
+          ? designEvidenceSchema
+          : compactEvidenceSchema
+        : diffSchema,
     async execute(_toolCallId, params) {
       attempts++;
       const value = params as unknown as Record<string, unknown>;
@@ -99,6 +138,12 @@ export function createSubmitTool(input: {
         throw new Error("submitted result is not an object");
       }
       if (value.id !== input.requestId) identity.request = false;
+      if (
+        input.role === "design-explorer" &&
+        value.packet_id !== input.requestId
+      ) {
+        identity.request = false;
+      }
       if (value.role !== input.role) identity.role = false;
       if (input.output === "diff") {
         if (value.taskId !== (input.taskId ?? input.requestId))