@abelxiaoxing/cadence 1.4.0 → 1.4.1

package/src/model-source.ts

@@ -0,0 +1,22 @@
+import type { Model, Provider } from "@earendil-works/pi-ai";
+
+/** Code-owned capability boundary. No session events, tools, UI or host context. */
+export interface ParentModelSource {
+  readonly model?: Model<string>;
+  readonly modelRegistry: {
+    getProvider(id: string): Provider | undefined;
+    getApiKeyAndHeaders(model: Model<string>): Promise<
+      | {
+          ok: true;
+          apiKey?: string;
+          headers?: Record<string, string | null>;
+          baseUrl?: string;
+          env?: Record<string, string>;
+        }
+      | { ok: false }
+    >;
+  };
+}
+export interface PackageContext extends ParentModelSource {
+  readonly cwd: string;
+}

package/src/package-candidate.ts

@@ -0,0 +1,224 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { runChildSession } from "./child-session.ts";
+import { LIMITS } from "./contracts.ts";
+import type { DurableWorkflowEngineOptions } from "./durable-contracts.ts";
+import type { ParentModelSource } from "./model-source.ts";
+import { runtimeForWorkerRoute } from "./parent-provider.ts";
+import type { WorkerRoutePolicy } from "./route-policy.ts";
+import { isSafeRegularFile } from "./safe-path.ts";
+import {
+  classifyCandidateContextRequest,
+  permitsContextRead,
+} from "./submit-tool.ts";
+import { transportFailureError } from "./transport-budget.ts";
+import type { DurableCandidateProposal } from "./workflow-policy.ts";
+
+function childRequestId(
+  operationId: string,
+  taskId: string,
+  phase: string,
+): string {
+  return `child-${createHash("sha256").update(`${operationId}\0${taskId}\0${phase}`).digest("hex").slice(0, 40)}`;
+}
+export async function proposePackageCandidate(
+  input: Parameters<DurableWorkflowEngineOptions["proposeCandidate"]>[0],
+  context: ParentModelSource | undefined,
+  implementationAgent: { content: string },
+): Promise<DurableCandidateProposal> {
+  if (!context) {
+    return { kind: "paused", code: "parent-context-unavailable" };
+  }
+  const phaseRuntime = await runtimeForWorkerRoute(
+    input.route as WorkerRoutePolicy,
+    context,
+    input.signal,
+    process.env,
+  );
+  if (!phaseRuntime.ok) {
+    if (phaseRuntime.failure.kind === "cancelled") {
+      return { kind: "operation-cancelled", code: "cancelled" };
+    }
+    throw new Error(phaseRuntime.failure.code);
+  }
+  const phase = input.task.phases[input.phase];
+  if (!phase) {
+    return { kind: "paused", code: "task-phase-unavailable" };
+  }
+  const taskPhases = Object.values(input.task.phases);
+  const executionBoundary = input.artifactCorrection
+    ? {
+        read: [
+          ...new Set(
+            taskPhases.flatMap((boundary) => [
+              ...boundary.read,
+              ...boundary.write,
+              ...boundary.delete,
+            ]),
+          ),
+        ].sort(),
+        write: [
+          ...new Set(taskPhases.flatMap((boundary) => boundary.write)),
+        ].sort(),
+        delete: [
+          ...new Set(taskPhases.flatMap((boundary) => boundary.delete)),
+        ].sort(),
+      }
+    : {
+        read: [
+          ...new Set(
+            taskPhases.flatMap((boundary) => [
+              ...boundary.read,
+              ...boundary.write,
+              ...boundary.delete,
+            ]),
+          ),
+        ].sort(),
+        write: [...phase.write],
+        delete: [...phase.delete],
+      };
+  executionBoundary.read = [
+    ...new Set([
+      ...executionBoundary.read,
+      ...(input.contextReadPaths ?? []).filter(
+        (relative) =>
+          permitsContextRead(relative, input.task.roots) &&
+          isSafeRegularFile(input.workspaceRoot, relative),
+      ),
+    ]),
+  ].sort();
+  const phaseContract = {
+    candidateId: input.candidateArtifact.identity.candidateId,
+    taskId: input.taskId,
+    phase: input.phase,
+    readSet: executionBoundary.read,
+    writeSet: executionBoundary.write,
+    deleteSet: executionBoundary.delete,
+    verification: structuredClone(phase.verification),
+    agentsImpact: input.task.agents.impact,
+    agentsTarget: input.task.agents.target ?? null,
+    agentsManagedOnly: true,
+    agentsWriteAllowed: false,
+    impactClosure: structuredClone(input.task.impactClosure),
+    ...(input.artifactCorrection
+      ? { artifactCorrection: structuredClone(input.artifactCorrection) }
+      : {}),
+    ...(input.contextRequest
+      ? { requestedContext: structuredClone(input.contextRequest) }
+      : {}),
+    ...(input.recoveryFeedback
+      ? { recoveryFeedback: structuredClone(input.recoveryFeedback) }
+      : {}),
+    ...(input.repair
+      ? {
+          repair: {
+            attempt: input.repair.attempt,
+            attribution: input.repair.attribution,
+            failureIdentities: [...input.repair.failureIdentities],
+            verification: structuredClone(input.task.repairVerification),
+            inBoundaryOnly: true,
+          },
+        }
+      : {}),
+  };
+  const child = await runChildSession({
+    cwd: input.workspaceRoot,
+    modelRuntime: phaseRuntime.modelRuntime,
+    model: phaseRuntime.model,
+    systemPrompt: [
+      implementationAgent.content,
+      input.task.objective,
+      input.task.context.agents,
+      input.task.context.contract,
+      "Use recoveryFeedback to change the failing approach. For compact-patch, prefer exact replace operations and omit unchanged bodies; submit one complete atomic patch. Never repeat an unchanged failing submission or weaken verification to obtain a pass.",
+      `<phase-contract>${JSON.stringify(phaseContract)}</phase-contract>`,
+    ].join("\n\n"),
+    requestId: childRequestId(input.operationId, input.taskId, input.phase),
+    taskId: input.taskId,
+    role: "implementation-worker",
+    phase: input.phase,
+    output: "diff",
+    roots: input.task.roots.map((root) =>
+      path.resolve(input.workspaceRoot, root),
+    ),
+    allowedPaths: [
+      ...new Set([
+        ...executionBoundary.read,
+        ...executionBoundary.write,
+        ...executionBoundary.delete,
+      ]),
+    ],
+    timeoutMs: LIMITS.phaseTimeoutMs,
+    signal: input.signal,
+    ledgerProjection: input.ledgerProjection,
+    candidateArtifact: input.candidateArtifact,
+    onStreamStart: input.onRequestStart,
+    onStreamHeaders: input.onHeaders,
+    onStreamProgress: input.onProgress,
+  });
+  if (!child.ok) {
+    if (child.failure.kind === "transport") {
+      throw transportFailureError(child.failure.code);
+    }
+    if (child.failure.kind === "cancelled") {
+      return { kind: "operation-cancelled", code: "cancelled" };
+    }
+    if (child.failure.kind === "approval-boundary") {
+      return { kind: "approval-needed", code: child.failure.code };
+    }
+    if (child.failure.kind === "execution-limit") {
+      return { kind: "paused", code: "needs-task-split" };
+    }
+    if (child.failure.kind === "result-limit") {
+      return { kind: "retryable", code: "needs-task-split" };
+    }
+    const attemptDiagnostic = {
+      finalCategory: child.classification.finalCategory,
+      submitAttempts: child.classification.attempts,
+      schema: child.classification.schema,
+      identityMismatch: Object.entries(child.classification.identity)
+        .filter(([, matches]) => !matches)
+        .map(([dimension]) => dimension),
+    };
+    return child.failure.kind === "environment" ||
+      child.failure.kind === "verification-adapter"
+      ? { kind: "paused", code: child.failure.code, attemptDiagnostic }
+      : { kind: "retryable", code: child.failure.code, attemptDiagnostic };
+  }
+  const result = child.result;
+  if (result.kind === "context-request") {
+    return classifyCandidateContextRequest(result, {
+      phase: input.phase,
+      contextReadRoots: input.task.roots,
+      readPaths: phase.read,
+      writePaths: phase.write,
+      deletePaths: phase.delete,
+      taskPaths: [
+        ...new Set(
+          Object.values(input.task.phases).flatMap((boundary) => [
+            ...boundary.read,
+            ...boundary.write,
+            ...boundary.delete,
+          ]),
+        ),
+      ],
+      redWritePaths: input.task.phases.red.write,
+      agents: {
+        impact: input.task.agents.impact,
+        ...(input.task.agents.target
+          ? { target: input.task.agents.target }
+          : {}),
+      },
+    });
+  }
+  if (result.kind !== "sealed-candidate") {
+    return { kind: "retryable", code: "candidate-diff-invalid" };
+  }
+  return {
+    kind: "sealed-candidate",
+    candidateId: result.candidateId,
+    artifactHash: result.artifactHash,
+    bytes: result.bytes,
+    paths: [...result.paths],
+  };
+}

package/src/package-workflow.ts

@@ -0,0 +1,253 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { WorkflowActivityUpdate } from "./activity-contracts.ts";
+import { loadAgentDefinitions } from "./agent-registry.ts";
+import type {
+  DesignEvidenceResult,
+  StructuredVerificationContract,
+} from "./contracts.ts";
+import { validateControlCommand } from "./control-contracts.ts";
+import { DesignController } from "./design-control.ts";
+import type { PackageContext } from "./model-source.ts";
+import { inspectOpenSpecDelivery } from "./openspec-cli.ts";
+import { proposePackageCandidate } from "./package-candidate.ts";
+import { packageDeliverySource } from "./package-delivery.ts";
+import {
+  changeVerificationResult,
+  executePackageVerification,
+  phaseVerificationResult,
+} from "./package-verification.ts";
+import {
+  inspectRoutePolicy,
+  loadRoutePolicy,
+  type RoutePolicyResolution,
+  unavailableRoutePolicy,
+} from "./route-policy.ts";
+import { resolveStateRoot } from "./state-root.ts";
+import { captureVerificationEnvironmentIdentity } from "./verification-environment.ts";
+import { openDurableWorkflowEngine } from "./workflow-engine.ts";
+export interface PackageWorkflowService {
+  execute(
+    command: unknown,
+    context?: PackageContext,
+    signal?: AbortSignal,
+    onActivity?: (event: WorkflowActivityUpdate) => void,
+  ): Promise<Record<string, unknown>>;
+  executeDesign(request: unknown): Promise<Record<string, unknown>>;
+  executeAmendment(
+    change: string,
+    batchId: string,
+    request: unknown,
+  ): Promise<Record<string, unknown>>;
+  assertDesignRun(runId: string): void;
+  recordDesignEvidence(input: {
+    runId: string;
+    evidence: DesignEvidenceResult;
+  }): unknown;
+  close(): void | Promise<void>;
+}
+
+function affectedVerification(
+  task: Parameters<
+    Parameters<typeof openDurableWorkflowEngine>[0]["proposeCandidate"]
+  >[0]["task"],
+): StructuredVerificationContract {
+  if (task.affectedVerification) {
+    return structuredClone(task.affectedVerification);
+  }
+  const finalPhase = task.phases.refactor ?? task.phases.green;
+  const verification = structuredClone(finalPhase.verification);
+  const affected = [...new Set(task.impactClosure.affectedSuite)].sort();
+  if (affected.length === 0) return verification;
+  if (verification.kind === "vitest") {
+    return { ...verification, testFiles: affected };
+  }
+  if (verification.kind === "steps") {
+    return {
+      ...verification,
+      steps: verification.steps.map((step) =>
+        step.kind === "vitest" ? { ...step, testFiles: affected } : step,
+      ),
+    };
+  }
+  return verification;
+}
+
+export function openPackageWorkflowService(
+  initialContext: PackageContext,
+): PackageWorkflowService {
+  const consumerRoot = path.resolve(initialContext.cwd);
+  const routeResolution = loadRoutePolicy({
+    cwd: consumerRoot,
+    home: homedir(),
+    ...(initialContext.model ? { parentModel: initialContext.model } : {}),
+  });
+  const stateRoot = resolveStateRoot({
+    consumerRoot,
+    xdgStateHome: process.env.XDG_STATE_HOME,
+  });
+  const contexts = new AsyncLocalStorage<PackageContext>();
+  const design = DesignController.open({
+    consumerRoot,
+    stateRoot,
+    inspectOpenSpec: inspectOpenSpecDelivery,
+  });
+  const implementationAgent = loadAgentDefinitions().find(
+    (agent) => agent.role === "implementation-worker",
+  );
+  if (!implementationAgent) {
+    throw new Error("implementation-worker-agent-unavailable");
+  }
+  const hostLimit = (name: string, fallback: number): number => {
+    const value =
+      process.env[name] === undefined ? fallback : Number(process.env[name]);
+    if (!Number.isSafeInteger(value) || value < 1)
+      throw new Error("verification-host-limit-invalid");
+    return value;
+  };
+  const maxReportBytes = hostLimit(
+    "ABEL_VERIFICATION_MAX_REPORT_BYTES",
+    64 * 1024 * 1024,
+  );
+  const workHardLimit = hostLimit("ABEL_WORK_MAX_UNITS", 512);
+  const engine = openDurableWorkflowEngine({
+    workHardLimit,
+    verificationPolicy: "report-file-v4",
+    verificationEnvironment: (plan, signal) =>
+      captureVerificationEnvironmentIdentity(
+        consumerRoot,
+        [
+          ...plan.tasks.flatMap((task) => [
+            ...Object.values(task.phases).map((phase) => phase.verification),
+            task.affectedVerification,
+            task.repairVerification,
+          ]),
+          plan.verification.baseline.fullSuite,
+          plan.verification.change.fullSuite,
+          plan.verification.change.postApply,
+          ...(plan.verification.agentsCheckpoint.verification
+            ? [plan.verification.agentsCheckpoint.verification]
+            : []),
+        ],
+        signal,
+      ),
+    consumerRoot,
+    stateRoot,
+    deliverySource: packageDeliverySource(consumerRoot, {
+      verifyGateProof: (input) => design.verifyGateProof(input),
+      verifyFinalizedDelivery: (input) => design.verifyFinalizedDelivery(input),
+    }),
+    routePolicy: routeResolution.ok
+      ? routeResolution.policy
+      : unavailableRoutePolicy(),
+    proposeCandidate: (input) =>
+      proposePackageCandidate(input, contexts.getStore(), implementationAgent),
+    verifyPhase: async (input) =>
+      phaseVerificationResult(
+        await executePackageVerification({
+          maxReportBytes,
+          executionWritePaths: input.executionWritePaths,
+          root: input.root,
+          dependencyOwner: consumerRoot,
+          verification: input.verification,
+          signal: input.signal,
+        }),
+      ),
+    verifyChange: async (input) => {
+      const verifications = input.verification
+        ? [input.verification]
+        : input.plan.tasks.map((task) => affectedVerification(task));
+      for (const verification of verifications) {
+        const result = await executePackageVerification({
+          maxReportBytes,
+          executionWritePaths: input.plan.tasks.flatMap((task) =>
+            Object.values(task.phases).flatMap((phase) => [
+              ...phase.write,
+              ...phase.delete,
+            ]),
+          ),
+          root: input.root,
+          dependencyOwner: consumerRoot,
+          verification,
+          signal: input.signal,
+        });
+        const observed = changeVerificationResult(result);
+        if (!observed.ok) return observed;
+      }
+      return {
+        ok: true,
+        exitCode: 0,
+        classification: "expected-green",
+      };
+    },
+  });
+  return {
+    async execute(
+      command: unknown,
+      context = initialContext,
+      signal,
+      onActivity,
+    ) {
+      const operationRouteResolution = loadRoutePolicy({
+        cwd: consumerRoot,
+        home: homedir(),
+        ...(context.model ? { parentModel: context.model } : {}),
+      });
+      engine.updateRoutePolicy(
+        operationRouteResolution.ok
+          ? operationRouteResolution.policy
+          : unavailableRoutePolicy(),
+      );
+      const validation = validateControlCommand(command);
+      if (!validation.ok) {
+        const error = new Error(validation.code);
+        error.name = "ControlCommandError";
+        throw error;
+      }
+      return contexts.run(context, async () => {
+        const outcome = await engine.execute(
+          validation.value,
+          signal,
+          onActivity,
+        );
+        const routePolicy = visibleRoutePolicyStatus(
+          operationRouteResolution,
+          engine.routePolicyStatus(),
+        );
+        return { ...outcome, routePolicy };
+      });
+    },
+    executeDesign(request: unknown) {
+      return design.execute(request);
+    },
+    executeAmendment(change: string, batchId: string, request: unknown) {
+      return engine.amend(change, batchId, request, (assertAuthority) =>
+        design.executeWithAuthority(request, assertAuthority),
+      );
+    },
+    assertDesignRun(runId: string) {
+      design.assertDesignRun(runId);
+    },
+    recordDesignEvidence(input) {
+      return design.recordEvidence(input);
+    },
+    async close() {
+      contexts.disable();
+      await engine.close();
+      design.close();
+    },
+  };
+}
+
+function visibleRoutePolicyStatus(
+  resolution: RoutePolicyResolution,
+  brokerStatus: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!resolution.ok) return inspectRoutePolicy(resolution);
+  const inspected = brokerStatus ?? inspectRoutePolicy(resolution);
+  return {
+    ...inspected,
+    source: { kind: resolution.source.kind },
+  };
+}

package/src/packet-runtime.ts

@@ -1,6 +1,5 @@
 import path from "node:path";
 import type { Usage } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Activation, type ActivationState } from "./activation.ts";
 import { loadAgentDefinitions } from "./agent-registry.ts";
 import {
@@ -15,51 +14,34 @@ import {
   type PacketEnvelope,
   validatePacketEnvelope,
 } from "./contracts.ts";
-import type { ParentPayloadBridge } from "./parent-payload-bridge.ts";
+import type { PackageContext } from "./model-source.ts";
 import { runtimeForWorkerRoute } from "./parent-provider.ts";
 import {
   loadRoutePolicy,
   type RoutePolicy,
   type WorkerRole,
 } from "./route-policy.ts";
+import {
+  isTransportTimeoutCode,
+  transportFailureError,
+} from "./transport-budget.ts";
 import { type BrokerActivityUpdate, RunWorkerBroker } from "./worker-broker.ts";
 
 export const PACKET_ACTIONS = ["run", "cancel", "finish"] as const;
 export type PacketAction = (typeof PACKET_ACTIONS)[number];
 
-export type PacketActivityState =
-  | "queued"
-  | "connecting"
-  | "waiting-first-response"
-  | "running"
-  | "retrying"
-  | "completed"
-  | "failed"
-  | "cancelled"
-  | "timed-out";
-
-export type PacketFailureReason =
-  | "subagent failed"
-  | "subagent cancelled"
-  | "phase timed out";
-
-export interface PacketActivityEvent {
-  state: PacketActivityState;
-  requestId: string;
-  role: string;
-  phase: string;
-  objective: string;
-  sequence: number;
-  attempt?: number;
-  maxAttempts?: number;
-  code?: string;
-  wait?: string;
-  failureReason?: PacketFailureReason;
-}
+import type {
+  PacketActivityEvent,
+  PacketActivityObserver,
+  PacketActivityState,
+} from "./activity-contracts.ts";
 
-export type PacketActivityObserver = (
-  event: PacketActivityEvent,
-) => void | Promise<void>;
+export type {
+  PacketActivityEvent,
+  PacketActivityObserver,
+  PacketActivityState,
+  PacketFailureReason,
+} from "./activity-contracts.ts";
 
 export type PacketDispatchResult =
   | {
@@ -78,7 +60,6 @@ export type PacketDispatchResult =
 
 export interface PacketRuntimeOptions {
   activation?: Activation;
-  parentPayloadBridge: ParentPayloadBridge;
   routePolicy?: RoutePolicy;
   routePolicyHome?: string;
   environment?: Readonly<Record<string, string | undefined>>;
@@ -86,10 +67,7 @@ export interface PacketRuntimeOptions {
   childRunner?: PacketChildRunner;
 }
 
-export type PacketContext = Pick<
-  ExtensionContext,
-  "cwd" | "model" | "modelRegistry"
->;
+export type PacketContext = PackageContext;
 
 export type PacketChildRunner = (input: {
   packet: PacketEnvelope;
@@ -162,7 +140,6 @@ function syntheticChildFailure(
 export class PacketRuntime {
   readonly activation: Activation;
   readonly limits = LIMITS;
-  readonly #parentPayloadBridge: ParentPayloadBridge;
   readonly #routePolicy?: RoutePolicy;
   readonly #routePolicyHome?: string;
   readonly #environment: Readonly<Record<string, string | undefined>>;
@@ -178,7 +155,6 @@ export class PacketRuntime {
 
   constructor(options: PacketRuntimeOptions) {
     this.activation = options.activation ?? new Activation();
-    this.#parentPayloadBridge = options.parentPayloadBridge;
     this.#routePolicy = options.routePolicy;
     this.#routePolicyHome = options.routePolicyHome;
     this.#environment = options.environment ?? process.env;
@@ -375,10 +351,8 @@ export class PacketRuntime {
         const phase = await runtimeForWorkerRoute(
           attempt.route,
           context,
-          this.#parentPayloadBridge,
           attempt.signal,
           this.#environment,
-          { onResponse: attempt.onHeaders },
         );
         if (!phase.ok) {
           if (phase.failure.kind === "cancelled") {
@@ -422,19 +396,23 @@ export class PacketRuntime {
           ],
           timeoutMs: LIMITS.phaseTimeoutMs,
           signal: attempt.signal,
-          failureOverride: phase.failureOverride,
+          onStreamStart: attempt.onRequestStart,
+          onStreamHeaders: attempt.onHeaders,
           onStreamProgress: attempt.onProgress,
         });
         brokerUsage.add(`attempt:${childAttempt++}`, child.usage);
         if (!child.ok && child.failure.kind === "transport") {
-          throw new Error(child.failure.code);
+          throw transportFailureError(child.failure.code);
         }
         return { kind: "child" as const, child };
       },
     });
     if (!routed.ok) {
       const cancelled = routed.state === "cancelled" || signal.aborted;
-      const timedOut = !cancelled && routed.code === "phase-timeout";
+      const timedOut =
+        !cancelled &&
+        (isTransportTimeoutCode(routed.code) ||
+          routed.code === "phase-timeout");
       return withBrokerUsage(
         syntheticChildFailure(
           cancelled ? "packet cancelled" : routed.code,
@@ -443,7 +421,9 @@ export class PacketRuntime {
             : timedOut
               ? {
                   kind: "transport",
-                  code: "timeout",
+                  code: isTransportTimeoutCode(routed.code)
+                    ? routed.code
+                    : "timeout",
                   stage: "child-timeout",
                 }
               : {
@@ -582,7 +562,6 @@ export class PacketRuntime {
     await this.cancel();
     this.#brokers.clear();
     this.#brokerPolicies.clear();
-    this.#parentPayloadBridge.clear();
   }
 
   get state(): ActivationState {