@abelxiaoxing/cadence 1.4.0 → 1.4.1

package/src/subagent-activity.ts

@@ -12,8 +12,11 @@ import {
 import type {
   PacketActivityEvent,
   PacketActivityObserver,
-  PacketActivityState,
-} from "./packet-runtime.ts";
+} from "./activity-contracts.ts";
+import {
+  projectDesignDiagnostic,
+  type SafeDesignDiagnostic,
+} from "./design-diagnostics.ts";
 
 export const ACTIVITY_DETAILS_KEY = "activityDisplay" as const;
 export const ACTIVITY_WIDGET_KEY = "abel-subagents" as const;
@@ -22,51 +25,20 @@ export const ACTIVITY_REFRESH_MS = 100;
 export const ACTIVITY_WIDGET_MAX_LINES = 12;
 export const ACTIVITY_WIDGET_MIN_WIDTH = 3;
 
-export const WORKFLOW_ACTIVITY_STATES = [
-  "queued",
-  "connecting",
-  "waiting-first-response",
-  "running",
-  "validating",
-  "retrying",
-  "verifying",
-  "paused",
-  "approval-needed",
-  "applying",
-  "recovering",
-  "operation-cancelled",
-  "discarded",
-  "rejected",
-  "completed",
-] as const;
-
-export type WorkflowActivityState = (typeof WORKFLOW_ACTIVITY_STATES)[number];
-export type ActivityState = PacketActivityState | WorkflowActivityState;
-export type TerminalActivityState =
-  | Exclude<
-      PacketActivityState,
-      | "queued"
-      | "connecting"
-      | "waiting-first-response"
-      | "running"
-      | "retrying"
-    >
-  | WorkflowActivityState;
-
-export interface WorkflowActivityUpdate {
-  state: WorkflowActivityState;
-  stage?: "abel-design" | "abel-implement";
-  runId?: string;
-  change?: string;
-  taskId?: string;
-  phase?: string;
-  objective?: string;
-  code?: string;
-  attempt?: number;
-  maxAttempts?: number;
-  wait?: string;
-  legalCommands?: string[];
-}
+export type {
+  ActivityState,
+  TerminalActivityState,
+  WorkflowActivityState,
+  WorkflowActivityUpdate,
+} from "./activity-contracts.ts";
+export { WORKFLOW_ACTIVITY_STATES } from "./activity-contracts.ts";
+
+import type {
+  ActivityState,
+  TerminalActivityState,
+  WorkflowActivityState,
+  WorkflowActivityUpdate,
+} from "./activity-contracts.ts";
 
 export interface EvidenceActivitySummary {
   kind: "evidence";
@@ -224,7 +196,7 @@ export function sanitizeFailureReason(value: unknown, maxLength = 240): string {
 function safeDesignFailure(value: unknown): {
   operation: string;
   code: string;
-  diagnostics: Array<Record<string, string>>;
+  diagnostics: SafeDesignDiagnostic[];
 } | null {
   const failure = asRecord(value);
   if (
@@ -237,23 +209,9 @@ function safeDesignFailure(value: unknown): {
   ) {
     return null;
   }
-  const diagnostics = failure.diagnostics.flatMap((candidate) => {
-    const record = asRecord(candidate);
-    if (
-      !record ||
-      typeof record.code !== "string" ||
-      !SAFE_DESIGN_DETAIL_VALUE.test(record.code)
-    ) {
-      return [];
-    }
-    return [
-      Object.fromEntries(
-        Object.entries(record).filter(
-          ([, entry]) =>
-            typeof entry === "string" && SAFE_DESIGN_DETAIL_VALUE.test(entry),
-        ),
-      ) as Record<string, string>,
-    ];
+  const diagnostics = failure.diagnostics.slice(0, 64).flatMap((candidate) => {
+    const diagnostic = projectDesignDiagnostic(candidate);
+    return diagnostic ? [diagnostic] : [];
   });
   return {
     operation: failure.operation,
@@ -286,7 +244,10 @@ function renderDesignFailure(
   const lines = failure.diagnostics.map((diagnostic) => {
     const details = Object.entries(diagnostic)
       .filter(([key]) => key !== "code")
-      .map(([key, value]) => `${key}=${value}`)
+      .map(
+        ([key, value]) =>
+          `${key}=${Array.isArray(value) ? JSON.stringify(value) : value}`,
+      )
       .join(" · ");
     return `  - ${diagnostic.code}${details ? ` · ${details}` : ""}`;
   });
@@ -315,6 +276,7 @@ function stateGlyph(state: ActivityState, spinnerFrame = 0): string {
   switch (state) {
     case "queued":
       return "…";
+    case "preparing":
     case "connecting":
     case "waiting-first-response":
     case "running":
@@ -563,6 +525,8 @@ function workflowStateOf(
     case "ready":
     case "queued":
       return "queued";
+    case "preparing":
+      return "preparing";
     case "connecting":
       return "connecting";
     case "waiting-first-response":
@@ -681,6 +645,7 @@ function workflowWait(
   ) {
     return approval.gate;
   }
+  if (state === "preparing") return "worker-setup";
   if (state === "connecting") return "connection";
   if (state === "waiting-first-response") return "first-response";
   if (state === "retrying") return "bounded-policy";
@@ -867,6 +832,7 @@ function terminalState(
 } {
   return ![
     "queued",
+    "preparing",
     "connecting",
     "waiting-first-response",
     "running",

package/src/submit-tool.ts

@@ -17,65 +17,16 @@ import {
   validateDiffResult,
   validateEvidenceResult,
 } from "./contracts.ts";
+import {
+  completeEvidenceDraft,
+  evidenceDraftSchema,
+} from "./evidence-draft.ts";
 import {
   type BeginCandidateInput,
   TASK_LEDGER_LIMITS,
   type TaskLedger,
 } from "./task-ledger.ts";
 
-const compactEvidenceSchema = Type.Object({
-  id: Type.String(),
-  role: Type.String(),
-  kind: Type.Literal("evidence"),
-  conclusions: Type.Array(Type.String()),
-  citations: Type.Array(
-    Type.Object({ path: Type.String(), lines: Type.String() }),
-  ),
-  constraints: Type.Array(Type.String()),
-  dependencies: Type.Array(Type.String()),
-  risks: Type.Array(Type.String()),
-  blockingQuestions: Type.Array(Type.String()),
-  hints: Type.Object({
-    writeSet: Type.Array(Type.String()),
-    verification: Type.String(),
-    agentsImpact: Type.String(),
-  }),
-});
-
-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(),
@@ -881,13 +832,11 @@ export function createSubmitTool(input: {
     name: "abel_submit_result",
     label: "Submit Abel Result",
     description:
-      "Submit the one final structured Abel evidence or complete unified-diff result.",
+      "Submit one accepted final result. Evidence identity and omitted advisory fields are completed by this tool; keep citations, constraints, risks, and open questions explicit. After a rejection, correct once in this same session. Brief accompanying text is harmless.",
     executionMode: "sequential",
     parameters:
       input.output === "evidence"
-        ? input.role === "design-explorer"
-          ? designEvidenceSchema
-          : compactEvidenceSchema
+        ? evidenceDraftSchema(input.requestId, input.role)
         : diffSchema,
     async execute(_toolCallId, params) {
       attempts++;
@@ -916,7 +865,11 @@ export function createSubmitTool(input: {
         phase: true,
       };
       failure = undefined;
-      const value = params as unknown as Record<string, unknown>;
+      const value = (
+        input.output === "evidence"
+          ? completeEvidenceDraft(params, input.requestId, input.role)
+          : params
+      ) as Record<string, unknown>;
       if (value === null || typeof value !== "object") {
         identity.request = false;
         identity.role = false;
@@ -963,7 +916,15 @@ export function createSubmitTool(input: {
               stage: "structural-submit",
             });
         throw new Error(
-          validation.reason ?? "submitted result identity does not match",
+          JSON.stringify({
+            code: "code" in failure ? failure.code : failure.kind,
+            reason:
+              validation.reason ?? "submitted result identity does not match",
+            identityMismatch: Object.entries(identity)
+              .filter(([, matches]) => !matches)
+              .map(([field]) => field),
+            remainingCorrections: Math.max(0, 2 - attempts),
+          }),
         );
       }
       submitted = structuredClone(value) as unknown as

package/src/transport-budget.ts

@@ -0,0 +1,32 @@
+/** Request budgets describe observable model progress, never TCP/TLS events. */
+export const REQUEST_BOUNDS = Object.freeze({
+  firstProgressMs: 90_000,
+  streamIdleMs: 180_000,
+  cancellationDrainMs: 250,
+});
+export type TransportTimeoutCode =
+  | "first-progress-timeout"
+  | "stream-idle-timeout"
+  | "attempt-timeout";
+export class TransportTimeout extends Error {
+  readonly scope: "request" | "attempt";
+  constructor(readonly code: TransportTimeoutCode) {
+    super(code);
+    this.name = "TransportTimeout";
+    this.scope = code === "attempt-timeout" ? "attempt" : "request";
+  }
+}
+export function isTransportTimeoutCode(
+  code: string,
+): code is TransportTimeoutCode {
+  return [
+    "first-progress-timeout",
+    "stream-idle-timeout",
+    "attempt-timeout",
+  ].includes(code);
+}
+export function transportFailureError(code: string): Error {
+  return isTransportTimeoutCode(code)
+    ? new TransportTimeout(code)
+    : new Error("transport-failure");
+}

package/src/worker-broker.ts

@@ -5,11 +5,9 @@ import {
   type WorkerRole,
   type WorkerRoutePolicy,
 } from "./route-policy.ts";
+import { TransportTimeout } from "./transport-budget.ts";
 
 export const ROUTE_ATTEMPT_BOUNDS = Object.freeze({
-  connectMs: 10_000,
-  firstResponseMs: 90_000,
-  idleMs: 3 * 60_000,
   totalMs: 20 * 60_000,
   cooldownMs: 30_000,
   attemptsPerRoute: 2,
@@ -71,6 +69,7 @@ export interface RunWorkerAttemptInput<T> {
 export interface RouteAttemptContext {
   route: WorkerRoutePolicy;
   signal: AbortSignal;
+  onRequestStart(): void;
   onHeaders(): void;
   onProgress(): void;
 }
@@ -81,7 +80,7 @@ export interface BrokerAttemptEvidence {
 }
 
 export interface BrokerActivityUpdate {
-  state: "connecting" | "waiting-first-response" | "running" | "retrying";
+  state: "preparing" | "waiting-first-response" | "running" | "retrying";
   attempt: number;
   maxAttempts: number;
   code?: string;
@@ -100,12 +99,7 @@ function emitBrokerActivity(
 }
 
 class RouteAttemptStop extends Error {
-  readonly code:
-    | "connect-timeout"
-    | "first-response-timeout"
-    | "idle-timeout"
-    | "phase-timeout"
-    | "cancelled";
+  readonly code: "cancelled";
 
   constructor(code: RouteAttemptStop["code"]) {
     super(code);
@@ -182,7 +176,8 @@ function capable(
 }
 
 function safeFailureCode(error: unknown): string {
-  if (error instanceof RouteAttemptStop) return error.code;
+  if (error instanceof RouteAttemptStop || error instanceof TransportTimeout)
+    return error.code;
   return "transport-failure";
 }
 
@@ -331,59 +326,39 @@ export class WorkerBroker {
     onActivity?: (state: "waiting-first-response" | "running") => void,
   ): Promise<T> {
     const controller = new AbortController();
-    const timers = new Set<ReturnType<typeof setTimeout>>();
-    let headersSeen = false;
-    let connectTimer: ReturnType<typeof setTimeout> | undefined;
-    let firstResponseTimer: ReturnType<typeof setTimeout> | undefined;
-    let idleTimer: ReturnType<typeof setTimeout> | undefined;
-
-    const stop = (code: RouteAttemptStop["code"]) => {
-      if (!controller.signal.aborted)
-        controller.abort(new RouteAttemptStop(code));
-    };
-    const schedule = (code: RouteAttemptStop["code"], milliseconds: number) => {
-      const timer = setTimeout(() => stop(code), milliseconds);
-      timers.add(timer);
-      return timer;
-    };
-    const clear = (timer: ReturnType<typeof setTimeout> | undefined) => {
-      if (timer !== undefined) {
-        clearTimeout(timer);
-        timers.delete(timer);
-      }
-    };
-    const onParentAbort = () => stop("cancelled");
-    if (parentSignal?.aborted) stop("cancelled");
+    let accepting = true;
+    let running = false;
+    const onParentAbort = () =>
+      controller.abort(new RouteAttemptStop("cancelled"));
+    if (parentSignal?.aborted) onParentAbort();
     else parentSignal?.addEventListener("abort", onParentAbort, { once: true });
-
-    connectTimer = schedule("connect-timeout", ROUTE_ATTEMPT_BOUNDS.connectMs);
-    schedule("phase-timeout", ROUTE_ATTEMPT_BOUNDS.totalMs);
+    const timer = setTimeout(
+      () => controller.abort(new TransportTimeout("attempt-timeout")),
+      ROUTE_ATTEMPT_BOUNDS.totalMs,
+    );
     let removeAbortRace: () => void = () => {};
     try {
-      const execution = Promise.resolve().then(() =>
-        execute({
+      const execution = Promise.resolve().then(() => {
+        controller.signal.throwIfAborted();
+        return execute({
           route: structuredClone(route),
           signal: controller.signal,
+          onRequestStart: () => {
+            if (!accepting || controller.signal.aborted) return;
+            running = false;
+            onActivity?.("waiting-first-response");
+          },
           onHeaders: () => {
-            if (controller.signal.aborted || headersSeen) return;
-            headersSeen = true;
-            clear(connectTimer);
+            if (!accepting || controller.signal.aborted || running) return;
             onActivity?.("waiting-first-response");
-            firstResponseTimer = schedule(
-              "first-response-timeout",
-              ROUTE_ATTEMPT_BOUNDS.firstResponseMs,
-            );
           },
           onProgress: () => {
-            if (controller.signal.aborted) return;
-            clear(connectTimer);
-            clear(firstResponseTimer);
-            clear(idleTimer);
-            idleTimer = schedule("idle-timeout", ROUTE_ATTEMPT_BOUNDS.idleMs);
+            if (!accepting || controller.signal.aborted) return;
+            running = true;
             onActivity?.("running");
           },
-        }),
-      );
+        });
+      });
       // A timed-out Provider may ignore its AbortSignal and settle later. The
       // broker owns the bounded result, so absorb that late settlement.
       void execution.catch(() => undefined);
@@ -403,7 +378,8 @@ export class WorkerBroker {
       return await Promise.race([execution, aborted]);
     } finally {
       removeAbortRace();
-      for (const timer of timers) clearTimeout(timer);
+      accepting = false;
+      clearTimeout(timer);
       parentSignal?.removeEventListener("abort", onParentAbort);
     }
   }
@@ -483,10 +459,10 @@ export class WorkerBroker {
       ).length;
       const attempt = evidence.length + 1;
       emitBrokerActivity(input.onActivity, {
-        state: "connecting",
+        state: "preparing",
         attempt,
         maxAttempts,
-        wait: "connection",
+        wait: "worker-setup",
       });
       try {
         const value = await this.#attempt(
@@ -576,6 +552,7 @@ export class WorkerBroker {
         code:
           | "approval-boundary"
           | "route-not-declared"
+          | "endpoint-unavailable"
           | "route-capability-insufficient";
       } {
     const allowed = new Set(["runId", "role", "routeId", "requirements"]);
@@ -597,12 +574,15 @@ export class WorkerBroker {
       routeId: input.routeId,
     });
     if (!selection.ok) {
+      const route = this.#policy.routes[input.routeId];
       return {
         ok: false,
         code:
           selection.code === "route-not-declared"
             ? "route-not-declared"
-            : "route-capability-insufficient",
+            : route && capable(route, input.role, input.requirements ?? {})
+              ? "endpoint-unavailable"
+              : "route-capability-insufficient",
       };
     }
     return {

package/src/workflow-policy.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import type { WorkflowActivityUpdate } from "./activity-contracts.ts";
 import { compareCanonicalStrings } from "./canonical.ts";
 import {
   type ApprovalBoundaryCode,
@@ -18,7 +19,6 @@ import type { RoutePolicy } from "./route-policy.ts";
 import { canonicalJson } from "./run-state.ts";
 import type { OperationLease } from "./run-store.ts";
 import type { ResolvedStateRoot } from "./state-root.ts";
-import type { WorkflowActivityUpdate } from "./subagent-activity.ts";
 import {
   type CandidateContextBoundary,
   type CandidateContextRef,
@@ -185,59 +185,20 @@ export interface RedArtifactCorrection {
   contextRequest?: WorkflowContextRequest;
 }
 
-export type RecoveryActionRequest = {
-  kind: "affected-repair" | "cumulative-repair" | "red-correction";
-  attempt: number;
-};
-export type RecoveryActionDecision =
-  | { allowed: true }
-  | {
-      allowed: false;
-      code: "repair-attempts-exhausted" | "artifact-attempts-exhausted";
-    };
+export type {
+  RecoveryActionDecision,
+  RecoveryActionRequest,
+  WorkflowRecoveryFact,
+  WorkflowRecoveryFeedback,
+} from "./workflow-recovery-policy.ts";
+export { decideRecoveryAction } from "./workflow-recovery-policy.ts";
 
-/** One policy for every nested recovery action; execution services supply facts only. */
-export function decideRecoveryAction(
-  plan: ImplementPlan,
-  request: RecoveryActionRequest,
-  authority: { additionalAttempt?: boolean; verificationOnly?: boolean } = {},
-): RecoveryActionDecision {
-  const correction = request.kind === "red-correction";
-  const limit =
-    authority.additionalAttempt || authority.verificationOnly
-      ? 1
-      : correction
-        ? plan.verification.artifactCorrection.maxAttempts
-        : plan.verification.repair.maxAttempts;
-  return Number.isSafeInteger(request.attempt) &&
-    request.attempt > 0 &&
-    request.attempt <= limit
-    ? { allowed: true }
-    : {
-        allowed: false,
-        code: correction
-          ? "artifact-attempts-exhausted"
-          : "repair-attempts-exhausted",
-      };
-}
-
-export interface WorkflowRecoveryFeedback {
-  code: string;
-  attempt: number;
-  maxAttempts: number;
-  strategy:
-    | "revise-candidate"
-    | "refresh-candidate"
-    | "repair-verification"
-    | "compact-patch";
-  failureIdentities?: string[];
-}
-
-export interface WorkflowRecoveryFact {
-  key: string;
-  failures: number;
-  feedback: WorkflowRecoveryFeedback;
-}
+import type {
+  RecoveryActionDecision,
+  RecoveryActionRequest,
+  WorkflowRecoveryFact,
+  WorkflowRecoveryFeedback,
+} from "./workflow-recovery-policy.ts";
 
 export const APPROVAL_AUTHORITY_CATEGORIES = [
   "observable-behavior",

package/src/workflow-recovery-policy.ts

@@ -0,0 +1,95 @@
+import type { ImplementPlan } from "./implement-plan.ts";
+
+export type RecoveryActionRequest = {
+  kind: "affected-repair" | "cumulative-repair" | "red-correction";
+  attempt: number;
+};
+export type RecoveryActionDecision =
+  | { allowed: true }
+  | {
+      allowed: false;
+      code: "repair-attempts-exhausted" | "artifact-attempts-exhausted";
+    };
+
+/** One policy for every nested recovery action; execution services supply facts only. */
+export function decideRecoveryAction(
+  plan: ImplementPlan,
+  request: RecoveryActionRequest,
+  authority: { additionalAttempt?: boolean; verificationOnly?: boolean } = {},
+): RecoveryActionDecision {
+  const correction = request.kind === "red-correction";
+  const limit =
+    authority.additionalAttempt || authority.verificationOnly
+      ? 1
+      : correction
+        ? plan.verification.artifactCorrection.maxAttempts
+        : plan.verification.repair.maxAttempts;
+  return Number.isSafeInteger(request.attempt) &&
+    request.attempt > 0 &&
+    request.attempt <= limit
+    ? { allowed: true }
+    : {
+        allowed: false,
+        code: correction
+          ? "artifact-attempts-exhausted"
+          : "repair-attempts-exhausted",
+      };
+}
+
+export interface WorkflowRecoveryFeedback {
+  code: string;
+  attempt: number;
+  maxAttempts: number;
+  strategy:
+    | "revise-candidate"
+    | "refresh-candidate"
+    | "repair-verification"
+    | "compact-patch";
+  failureIdentities?: string[];
+}
+
+export interface WorkflowRecoveryFact {
+  key: string;
+  failures: number;
+  feedback: WorkflowRecoveryFeedback;
+}
+
+export function recoveryExhausted(
+  incident: WorkflowRecoveryFact | undefined,
+  maximum: number,
+  granted: boolean,
+): boolean {
+  return !granted && incident !== undefined && incident.failures >= maximum;
+}
+
+/** A grant is a recommendation until the state machine validates and records it in its lease transaction. */
+export function assessRecoveryGrant(input: {
+  current: boolean;
+  incident?: WorkflowRecoveryFact;
+  failureSequence: number;
+  requestedSequence: number;
+  reason: string;
+  previous: { route?: string | null; context?: string | null };
+  observed: { route?: string | null; context?: string | null };
+  budget?: { used: number; max_work: number };
+}): string | undefined {
+  if (
+    !input.current ||
+    !input.incident ||
+    input.incident.failures < input.incident.feedback.maxAttempts ||
+    input.failureSequence !== input.requestedSequence
+  )
+    return "recovery-request-stale";
+  if (
+    (input.reason === "route-changed" &&
+      (!input.previous.route ||
+        input.previous.route === input.observed.route)) ||
+    (input.reason === "context-extended" &&
+      (!input.previous.context ||
+        input.previous.context === input.observed.context))
+  )
+    return "recovery-evidence-unavailable";
+  if (!input.budget || input.budget.used >= input.budget.max_work)
+    return "change-work-budget-exhausted";
+  return undefined;
+}