@abelxiaoxing/cadence 1.0.8 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "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",
@@ -53,8 +53,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
     "@types/node": "^22.15.3",
     "rumdl": "^0.2.10",
     "typescript": "^6.0.3",

package/src/child-session.ts

@@ -157,6 +157,39 @@ function isSingleStructuralSubmit(message: AssistantMessage | undefined) {
   );
 }
 
+function safeChildError(failure: ChildFailure): string {
+  switch (failure.kind) {
+    case "environment":
+      return failure.code === "child-session-create-failed"
+        ? "child session creation failed"
+        : "child environment unavailable";
+    case "transport":
+      switch (failure.code) {
+        case "child-timeout":
+        case "timeout":
+          return "child phase timeout";
+        case "child-no-final-assistant":
+          return "child produced no final assistant";
+        case "child-provider-stream-aborted":
+          return "child provider stream aborted";
+        case "child-provider-stream-error":
+        case "transport-failure":
+          return "child provider stream failed";
+      }
+      return "child provider stream failed";
+    case "artifact":
+      return failure.code === "child-no-structural-submit"
+        ? "child produced no structural submission"
+        : "child structural submission is invalid";
+    case "cancelled":
+      return "child phase cancelled";
+    case "stale":
+    case "approval-boundary":
+    case "result-limit":
+      return "child result rejected";
+  }
+}
+
 export type ChildSessionResult =
   | {
       ok: true;
@@ -192,6 +225,7 @@ export async function runChildSession(input: {
   allowedPaths?: string[];
   timeoutMs: number;
   signal?: AbortSignal;
+  failureOverride?: () => ChildFailure | undefined;
 }): Promise<ChildSessionResult> {
   const submit = createSubmitTool({
     requestId: input.requestId,
@@ -255,23 +289,46 @@ export async function runChildSession(input: {
       identity: submit.getIdentity(),
     };
   };
-  const transportFailed = (): boolean => {
+  const transportFailure = ():
+    | Extract<ChildFailure, { kind: "transport" }>
+    | undefined => {
     const final = session?.messages
       .filter((message) => message.role === "assistant")
       .at(-1);
-    if (final === undefined) return true;
+    if (final === undefined) {
+      return {
+        kind: "transport",
+        code: "child-no-final-assistant",
+        stage: "child-finalization",
+      };
+    }
     if (final.stopReason === "error") {
-      return (
-        submit.getAttempts() === 0 &&
+      return submit.getAttempts() === 0 &&
         !final.content.some(
           (content) =>
             content.type === "toolCall" &&
             content.name === "abel_submit_result",
         )
-      );
+        ? {
+            kind: "transport",
+            code: "child-provider-stream-error",
+            stage: "child-provider-stream",
+          }
+        : undefined;
     }
-    return final.stopReason === "aborted";
+    if (final.stopReason === "aborted") {
+      return {
+        kind: "transport",
+        code: "child-provider-stream-aborted",
+        stage: "child-provider-stream",
+      };
+    }
+    return undefined;
   };
+  const noStructuralSubmit = (): ChildFailure =>
+    submit.getAttempts() === 0
+      ? { kind: "artifact", code: "child-no-structural-submit" }
+      : { kind: "artifact", code: "invalid-structural-result" };
   try {
     abort.signal.throwIfAborted();
     const creation = createAgentSession({
@@ -331,22 +388,19 @@ export async function runChildSession(input: {
     const attempts = submit.getAttempts();
     const classification = classifySession();
     if (!result || attempts !== 1) {
-      const transportFailure = transportFailed();
       const failure =
         submit.getFailure() ??
-        (transportFailure
-          ? ({ kind: "transport", code: "transport-failure" } as const)
-          : ({
-              kind: "artifact",
-              code: "invalid-structural-result",
-            } as const));
+        input.failureOverride?.() ??
+        transportFailure() ??
+        noStructuralSubmit();
+      const isTransport = failure.kind === "transport";
       disposeOnce();
       return {
         ok: false,
-        error: "child did not retain exactly one structural submission",
+        error: safeChildError(failure),
         failure,
         failureKind: "failed",
-        transportFailure,
+        transportFailure: isTransport,
         disposeCount,
         usage: usage.total(),
         classification,
@@ -355,11 +409,15 @@ export async function runChildSession(input: {
     const assistants = session.messages.filter((m) => m.role === "assistant");
     const final = assistants.at(-1);
     if (!isSingleStructuralSubmit(final)) {
+      const failure = {
+        kind: "artifact",
+        code: "invalid-structural-result",
+      } as const;
       disposeOnce();
       return {
         ok: false,
-        error: "final assistant message is not one structural submit",
-        failure: { kind: "artifact", code: "invalid-structural-result" },
+        error: safeChildError(failure),
+        failure,
         failureKind: "failed",
         transportFailure: false,
         disposeCount,
@@ -390,22 +448,35 @@ export async function runChildSession(input: {
         ? "cancelled"
         : "failed";
     const classification = classifySession();
-    const transportFailure = transportFailed();
     const failure: ChildFailure = timedOut
-      ? { kind: "transport", code: "timeout" }
+      ? {
+          kind: "transport",
+          code: "child-timeout",
+          stage: "child-timeout",
+        }
       : failureKind === "cancelled"
         ? { kind: "cancelled", code: "cancelled" }
-        : (submit.getFailure() ??
-          (transportFailure
-            ? { kind: "transport", code: "transport-failure" }
-            : { kind: "artifact", code: "invalid-structural-result" }));
+        : session === undefined
+          ? {
+              kind: "environment",
+              code: "child-session-create-failed",
+              stage: "child-session-create",
+            }
+          : (submit.getFailure() ??
+            input.failureOverride?.() ??
+            transportFailure() ??
+            noStructuralSubmit());
+    const isTransport = failure.kind === "transport";
     disposeOnce();
     return {
       ok: false,
-      error: (error as Error).message,
+      error:
+        failure.kind === "cancelled" && error instanceof Error
+          ? error.message
+          : safeChildError(failure),
       failure,
       failureKind,
-      transportFailure,
+      transportFailure: isTransport,
       disposeCount,
       usage: usage.total(),
       classification,

package/src/contracts.ts

@@ -74,6 +74,7 @@ export const ARTIFACT_FAILURE_CODES = [
   "invalid-diff-bytes",
   "invalid-snapshot",
   "invalid-structural-result",
+  "child-no-structural-submit",
   "invalid-verification-contract",
   "lockfile-bound-mismatch",
   "noncanonical-path",
@@ -108,6 +109,7 @@ export const ENVIRONMENT_FAILURE_CODES = [
   "checkout-failed",
   "clone-alternates",
   "clone-failed",
+  "child-session-create-failed",
   "dependency-path-unsafe",
   "git-apply-check-unavailable",
   "git-apply-failed",
@@ -115,6 +117,11 @@ export const ENVIRONMENT_FAILURE_CODES = [
   "git-ignore-check-failed",
   "git-index-unavailable",
   "invalid-subagent-endpoint",
+  "parent-bridge-capture-not-ready",
+  "parent-bridge-generation-invalidated",
+  "parent-bridge-model-key-mismatch",
+  "parent-bridge-provider-not-installed",
+  "parent-bridge-session-unavailable",
   "root-unavailable",
   "sandbox-runtime-unavailable",
 ] as const;
@@ -126,18 +133,39 @@ export const APPROVAL_BOUNDARY_CODES = [
   "verification-contract-insufficient",
   "agents-contract-insufficient",
 ] as const;
-export const CHILD_TRANSPORT_CODES = ["timeout", "transport-failure"] as const;
+export const CHILD_TRANSPORT_CODES = [
+  "child-no-final-assistant",
+  "child-provider-stream-aborted",
+  "child-provider-stream-error",
+  "child-timeout",
+  "timeout",
+  "transport-failure",
+] as const;
+export const FAILURE_STAGES = [
+  "phase-runtime",
+  "child-session-create",
+  "child-provider-stream",
+  "child-finalization",
+  "child-timeout",
+] as const;
 
 export type ArtifactFailureCode = (typeof ARTIFACT_FAILURE_CODES)[number];
 export type StaleFailureCode = (typeof STALE_FAILURE_CODES)[number];
 export type EnvironmentFailureCode = (typeof ENVIRONMENT_FAILURE_CODES)[number];
 export type ApprovalBoundaryCode = (typeof APPROVAL_BOUNDARY_CODES)[number];
 export type ChildTransportCode = (typeof CHILD_TRANSPORT_CODES)[number];
+export type FailureStage = (typeof FAILURE_STAGES)[number];
+
+export interface SafeFailureDiagnostic {
+  code: ChildTransportCode;
+  stage: FailureStage;
+}
 
 export type EnvironmentFailure = {
   kind: "environment";
   code: EnvironmentFailureCode;
   message?: string;
+  stage?: FailureStage;
 };
 
 export type CandidateFailure =
@@ -150,7 +178,11 @@ export type CandidateFailure =
 
 export type ChildFailure =
   | CandidateFailure
-  | { kind: "transport"; code: ChildTransportCode };
+  | {
+      kind: "transport";
+      code: ChildTransportCode;
+      stage?: FailureStage;
+    };
 
 export type CandidateRejection =
   | {
@@ -165,6 +197,7 @@ export type TaskFailure =
   | {
       kind: "attempts-exhausted";
       cause: "artifact" | "stale" | "transport";
+      lastFailure?: SafeFailureDiagnostic;
     }
   | {
       kind: "checkpoint-attempts-exhausted";

package/src/parent-payload-bridge.ts

@@ -27,6 +27,23 @@ export interface ParentPayloadCapture {
   readonly onPayload: ParentPayloadCallback;
 }
 
+export type ParentBridgeFailureCode =
+  | "parent-bridge-session-unavailable"
+  | "parent-bridge-provider-not-installed"
+  | "parent-bridge-capture-not-ready"
+  | "parent-bridge-model-key-mismatch"
+  | "parent-bridge-generation-invalidated";
+
+export class ParentPayloadBridgeError extends Error {
+  readonly code: ParentBridgeFailureCode;
+
+  constructor(code: ParentBridgeFailureCode) {
+    super(code);
+    this.name = "ParentPayloadBridgeError";
+    this.code = code;
+  }
+}
+
 export interface ParentProviderRegistry {
   getProvider(provider: string): Provider | undefined;
   registerProvider(provider: Provider): void;
@@ -217,6 +234,32 @@ export class ParentPayloadBridge {
     return capture;
   }
 
+  diagnoseCapture(
+    modelKey: ParentModelKey,
+    registry: Pick<ParentProviderRegistry, "getProvider">,
+  ): ParentBridgeFailureCode | undefined {
+    const state = this.state;
+    if (!state?.active) return "parent-bridge-session-unavailable";
+    const current = registry.getProvider(modelKey.provider);
+    if (!current || !this.isWrappedProvider(current)) {
+      return "parent-bridge-provider-not-installed";
+    }
+    const capture = state.ready.get(modelKeyId(modelKey));
+    if (capture && sameModelKey(capture.modelKey, modelKey)) {
+      return this.unwrapProvider(current) === capture.delegate
+        ? undefined
+        : "parent-bridge-provider-not-installed";
+    }
+    if (
+      [...state.ready.values()].some(
+        (ready) => ready.modelKey.provider === modelKey.provider,
+      )
+    ) {
+      return "parent-bridge-model-key-mismatch";
+    }
+    return "parent-bridge-capture-not-ready";
+  }
+
   wrapProvider(delegate: Provider): Provider {
     const original = this.unwrapProvider(delegate);
     const stream = (
@@ -265,7 +308,9 @@ export class ParentPayloadBridge {
     childOnPayload?: ParentPayloadCallback,
     signal?: AbortSignal,
   ): Promise<Record<string, unknown>> {
-    if (!capture) throw new Error("parent payload bridge is unavailable");
+    if (!capture) {
+      throw new ParentPayloadBridgeError("parent-bridge-capture-not-ready");
+    }
     const requestedKey = modelKeyFor(model);
     const state = this.requireCurrentCapture(capture, requestedKey);
     signal?.throwIfAborted();
@@ -360,13 +405,13 @@ export class ParentPayloadBridge {
     model: Model<string>,
     provisional: ProvisionalCapture | undefined,
   ): Promise<void> {
-    let successful = false;
     try {
       for await (const event of source) {
-        if (event.type === "done") successful = true;
+        if (event.type === "done") {
+          if (provisional) this.commitCapture(provisional);
+        }
         output.push(event);
       }
-      if (successful && provisional) this.commitCapture(provisional);
     } catch {
       const error = streamFailure(model);
       output.push({ type: "error", reason: "error", error });
@@ -401,20 +446,32 @@ export class ParentPayloadBridge {
     modelKey: ParentModelKey,
   ): GenerationState {
     const state = this.state;
+    if (!capture) {
+      throw new ParentPayloadBridgeError("parent-bridge-capture-not-ready");
+    }
     if (
-      !capture ||
       !state?.active ||
       this.captureStates.get(capture) !== state ||
       capture.generation !== state.generation ||
-      capture.sessionId !== state.sessionId ||
-      !sameModelKey(capture.modelKey, modelKey) ||
-      state.ready.get(modelKeyId(modelKey)) !== capture
+      capture.sessionId !== state.sessionId
     ) {
-      throw new Error("parent payload bridge is unavailable");
+      throw new ParentPayloadBridgeError(
+        "parent-bridge-generation-invalidated",
+      );
+    }
+    if (!sameModelKey(capture.modelKey, modelKey)) {
+      throw new ParentPayloadBridgeError("parent-bridge-model-key-mismatch");
+    }
+    if (state.ready.get(modelKeyId(modelKey)) !== capture) {
+      throw new ParentPayloadBridgeError("parent-bridge-capture-not-ready");
     }
     return state;
   }
 
+  private isWrappedProvider(provider: Provider): boolean {
+    return Reflect.get(provider, PROVIDER_WRAPPER) !== undefined;
+  }
+
   private unwrapProvider(provider: Provider): Provider {
     let current = provider;
     const seen = new Set<Provider>();

package/src/parent-provider.ts

@@ -14,10 +14,11 @@ import {
   ModelRuntime,
 } from "@earendil-works/pi-coding-agent";
 import type { ChildFailure } from "./contracts.ts";
-import type {
-  ParentPayloadBridge,
-  ParentPayloadCallback,
-  ParentPayloadCapture,
+import {
+  type ParentPayloadBridge,
+  ParentPayloadBridgeError,
+  type ParentPayloadCallback,
+  type ParentPayloadCapture,
 } from "./parent-payload-bridge.ts";
 import type { SubagentEndpoint } from "./subagent-endpoint.ts";
 
@@ -145,7 +146,12 @@ type PhaseRuntimeFailure = Extract<
 >;
 
 export type PhaseRuntimeResult =
-  | { ok: true; modelRuntime: ModelRuntime; model: Model<string> }
+  | {
+      ok: true;
+      modelRuntime: ModelRuntime;
+      model: Model<string>;
+      failureOverride?: () => PhaseRuntimeFailure | undefined;
+    }
   | { ok: false; error: string; failure: PhaseRuntimeFailure };
 
 function phaseRuntimeFailure(
@@ -170,15 +176,28 @@ function phasePayloadCallback(
   payloadBridge: PhasePayloadBridge,
   childOnPayload: ParentPayloadCallback | undefined,
   signal: AbortSignal | undefined,
+  diagnostic?: { failure?: PhaseRuntimeFailure },
 ): ParentPayloadCallback {
-  return (payload, model) =>
-    payloadBridge.bridge.composePayload(
-      payloadBridge.capture,
-      payload,
-      model,
-      childOnPayload,
-      signal,
-    );
+  return async (payload, model) => {
+    try {
+      return await payloadBridge.bridge.composePayload(
+        payloadBridge.capture,
+        payload,
+        model,
+        childOnPayload,
+        signal,
+      );
+    } catch (error) {
+      if (error instanceof ParentPayloadBridgeError && diagnostic) {
+        diagnostic.failure = {
+          kind: "environment",
+          code: error.code,
+          stage: "child-provider-stream",
+        };
+      }
+      throw error;
+    }
+  };
 }
 
 export async function runtimeForProvider(
@@ -209,6 +228,7 @@ export function phaseProvider(
     env?: Record<string, string>;
   },
   payloadBridge: PhasePayloadBridge,
+  diagnostic?: { failure?: PhaseRuntimeFailure },
 ): Provider {
   return {
     ...parent,
@@ -232,6 +252,7 @@ export function phaseProvider(
         payloadBridge,
         options?.onPayload as ParentPayloadCallback | undefined,
         options?.signal,
+        diagnostic,
       );
       return parent.stream(model, context, {
         ...options,
@@ -247,6 +268,7 @@ export function phaseProvider(
         payloadBridge,
         options?.onPayload as ParentPayloadCallback | undefined,
         options?.signal,
+        diagnostic,
       );
       return parent.streamSimple(model, context, {
         ...options,
@@ -321,31 +343,55 @@ export async function runtimeFromContext(
   const effectiveModelKey = modelKeyFor(model);
   const capture = payloadBridge.capture(effectiveModelKey, ctx.modelRegistry);
   if (!capture) {
+    const code =
+      payloadBridge.diagnoseCapture(effectiveModelKey, ctx.modelRegistry) ??
+      "parent-bridge-capture-not-ready";
     return phaseRuntimeFailure(
-      { kind: "transport", code: "transport-failure" },
-      "parent payload bridge is unavailable",
+      { kind: "environment", code, stage: "phase-runtime" },
+      code,
     );
   }
-  const captureIsReady = () => {
+  const captureFailure = () => {
     const currentModel = ctx.model;
-    return (
-      currentModel !== undefined &&
-      sameSelectedModel(currentModel, selectedModelKey) &&
+    if (
+      currentModel === undefined ||
+      !sameSelectedModel(currentModel, selectedModelKey)
+    ) {
+      return "parent-bridge-model-key-mismatch" as const;
+    }
+    if (
       payloadBridge.capture(effectiveModelKey, ctx.modelRegistry) === capture
+    ) {
+      return undefined;
+    }
+    return (
+      payloadBridge.diagnoseCapture(effectiveModelKey, ctx.modelRegistry) ??
+      "parent-bridge-capture-not-ready"
     );
   };
-  if (!captureIsReady()) {
+  const initialCaptureFailure = captureFailure();
+  if (initialCaptureFailure) {
     return phaseRuntimeFailure(
-      { kind: "transport", code: "transport-failure" },
-      "parent payload bridge is unavailable",
+      {
+        kind: "environment",
+        code: initialCaptureFailure,
+        stage: "phase-runtime",
+      },
+      initialCaptureFailure,
     );
   }
   const delegate = capture.delegate;
   if (!delegate) throw new Error("parent Provider is unavailable");
-  const provider = phaseProvider(delegate, resolved, {
-    bridge: payloadBridge,
-    capture,
-  });
+  const diagnostic: { failure?: PhaseRuntimeFailure } = {};
+  const provider = phaseProvider(
+    delegate,
+    resolved,
+    {
+      bridge: payloadBridge,
+      capture,
+    },
+    diagnostic,
+  );
   let modelRuntime: ModelRuntime;
   try {
     modelRuntime = await runtimeForProvider(provider, signal);
@@ -354,13 +400,23 @@ export async function runtimeFromContext(
     throw error;
   }
   if (signal?.aborted) return cancelledPhaseRuntime();
-  if (!captureIsReady()) {
+  const finalCaptureFailure = captureFailure();
+  if (finalCaptureFailure) {
     return phaseRuntimeFailure(
-      { kind: "transport", code: "transport-failure" },
-      "parent payload bridge is unavailable",
+      {
+        kind: "environment",
+        code: finalCaptureFailure,
+        stage: "phase-runtime",
+      },
+      finalCaptureFailure,
     );
   }
-  return { ok: true, modelRuntime, model };
+  return {
+    ok: true,
+    modelRuntime,
+    model,
+    failureOverride: () => diagnostic.failure,
+  };
 }
 
 function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {

package/src/runtime.ts

@@ -521,6 +521,25 @@ function attemptFailureCause(
   }
 }
 
+function attemptsExhaustedFailure(failure: ChildFailure): TaskFailure {
+  const cause = attemptFailureCause(failure);
+  if (failure.kind !== "transport") {
+    return { kind: "attempts-exhausted", cause };
+  }
+  return {
+    kind: "attempts-exhausted",
+    cause,
+    lastFailure: {
+      code: failure.code,
+      stage:
+        failure.stage ??
+        (failure.code === "child-timeout" || failure.code === "timeout"
+          ? "child-timeout"
+          : "child-provider-stream"),
+    },
+  };
+}
+
 function assertNever(value: never): never {
   throw new Error(`unhandled candidate failure: ${JSON.stringify(value)}`);
 }
@@ -1397,6 +1416,7 @@ export class Runtime {
       ],
       timeoutMs: LIMITS.phaseTimeoutMs,
       signal,
+      failureOverride: phase.failureOverride,
     });
     if (signal.aborted)
       return {
@@ -1901,12 +1921,7 @@ export class Runtime {
     const firstTerminal = terminalTaskFailure(firstFailure);
     if (firstTerminal) return finish(block(firstTerminal));
     if (launchIndex === 1) {
-      return finish(
-        block({
-          kind: "attempts-exhausted",
-          cause: attemptFailureCause(firstFailure),
-        }),
-      );
+      return finish(block(attemptsExhaustedFailure(firstFailure)));
     }
     if (firstFailure.kind === "artifact" || firstFailure.kind === "stale") {
       task.state = {
@@ -1940,12 +1955,7 @@ export class Runtime {
     }
     const secondTerminal = terminalTaskFailure(secondFailure);
     if (secondTerminal) return finish(block(secondTerminal));
-    return finish(
-      block({
-        kind: "attempts-exhausted",
-        cause: attemptFailureCause(secondFailure),
-      }),
-    );
+    return finish(block(attemptsExhaustedFailure(secondFailure)));
   }
 
   private captureUsage(