@abelxiaoxing/cadence 1.0.1 → 1.0.2

package/src/child-session.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import type { Model, Usage } from "@earendil-works/pi-ai";
 import {
   createAgentSession,
@@ -66,9 +67,22 @@ export class UsageAggregator {
   }
 }
 
-function wrapScopedTools(roots: string[]) {
+function wrapScopedTools(
+  roots: string[],
+  cwd: string,
+  allowedPaths?: string[],
+) {
   const order = ["read", "grep", "find", "ls"];
-  return createScopedTools({ roots })
+  return createScopedTools({
+    roots,
+    ...(allowedPaths
+      ? {
+          allowedPaths: allowedPaths.map((relative) =>
+            path.resolve(cwd, relative),
+          ),
+        }
+      : {}),
+  })
     .sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name))
     .map((scoped) =>
       defineTool({
@@ -100,10 +114,12 @@ export async function runChildSession(input: {
   model: Model<string>;
   systemPrompt: string;
   requestId: string;
+  taskId?: string;
   role: string;
   phase?: string;
   output: "evidence" | "diff";
   roots: string[];
+  allowedPaths?: string[];
   timeoutMs: number;
   signal?: AbortSignal;
 }): Promise<
@@ -120,17 +136,19 @@ export async function runChildSession(input: {
       ok: false;
       error: string;
       failureKind: ChildFailureKind;
+      transportFailure: boolean;
       disposeCount: number;
       classification: SubmitClassification;
     }
 > {
   const submit = createSubmitTool({
     requestId: input.requestId,
+    taskId: input.taskId,
     role: input.role,
     phase: input.phase ?? "red",
     output: input.output,
   });
-  const readTools = wrapScopedTools(input.roots);
+  const readTools = wrapScopedTools(input.roots, input.cwd, input.allowedPaths);
   const customTools = [...readTools, submit.tool];
   const toolNames = customTools.map((tool) => tool.name);
   let disposeCount = 0;
@@ -185,6 +203,23 @@ export async function runChildSession(input: {
       identity: submit.getIdentity(),
     };
   };
+  const transportFailed = (): boolean => {
+    const final = session?.messages
+      .filter((message) => message.role === "assistant")
+      .at(-1);
+    if (final === undefined) return true;
+    if (final.stopReason === "error") {
+      return (
+        submit.getAttempts() === 0 &&
+        !final.content.some(
+          (content) =>
+            content.type === "toolCall" &&
+            content.name === "abel_submit_result",
+        )
+      );
+    }
+    return final.stopReason === "aborted";
+  };
   try {
     abort.signal.throwIfAborted();
     const creation = createAgentSession({
@@ -239,11 +274,13 @@ export async function runChildSession(input: {
     const attempts = submit.getAttempts();
     const classification = classifySession();
     if (!result || attempts !== 1) {
+      const transportFailure = transportFailed();
       disposeOnce();
       return {
         ok: false,
         error: "child did not retain exactly one structural submission",
         failureKind: "failed",
+        transportFailure,
         disposeCount,
         classification,
       };
@@ -262,6 +299,7 @@ export async function runChildSession(input: {
         ok: false,
         error: "final assistant message is not one structural submit",
         failureKind: "failed",
+        transportFailure: false,
         disposeCount,
         classification,
       };
@@ -277,19 +315,22 @@ export async function runChildSession(input: {
       classification,
     };
   } catch (error) {
-    disposeOnce();
     const failureKind: ChildFailureKind = timedOut
       ? "timed-out"
       : input.signal !== undefined &&
           (input.signal.aborted || abort.signal.reason === input.signal.reason)
         ? "cancelled"
         : "failed";
+    const classification = classifySession();
+    const transportFailure = transportFailed();
+    disposeOnce();
     return {
       ok: false,
       error: (error as Error).message,
       failureKind,
+      transportFailure,
       disposeCount,
-      classification: classifySession(),
+      classification,
     };
   } finally {
     clearTimeout(timer);

package/src/contracts.ts

@@ -21,6 +21,20 @@ export const PHASES = [
   "review",
 ] as const;
 
+export const RECOVERY_CODES = [
+  "mechanical-redispatch-exhausted",
+  "implementation-artifact-delivery-blocked",
+  "environment-blocked",
+  "design-required",
+] as const;
+
+export type RecoveryCode = (typeof RECOVERY_CODES)[number];
+export type RecoveryNext =
+  | "finish-unaffected"
+  | "correct-artifact"
+  | "repair-environment"
+  | "return-to-design";
+
 export const LIMITS = {
   maxActiveChildSessions: 4,
   maxRequestsPerBatch: 8,
@@ -30,10 +44,20 @@ export const LIMITS = {
 } as const;
 
 const NONCANONICAL = /(^|\/)\.\.(\/|$)|(^|\/)\/|^\//;
+const SNAPSHOT_SHA256 = /^[a-f0-9]{64}$/;
+
+export interface VerificationContract {
+  id: string;
+  argv: string[];
+  classification: "expected-red" | "expected-green" | "expected-refactor";
+  expectedFailure?: string;
+  minTests: number;
+}
 
 export interface RequestEnvelope {
   stage: string;
   role: string;
+  taskId?: string;
   id: string;
   phase: string;
   objective: string;
@@ -47,9 +71,23 @@ export interface RequestEnvelope {
     verificationLock?: string;
   };
   output: string;
+  verification?: VerificationContract;
   snapshot?: unknown;
 }
 
+export interface RecoveryRecord {
+  code: RecoveryCode;
+  taskId: string;
+  requestId: string;
+  phase: string;
+  launchIndex: 0 | 1;
+  branchBlocked: true;
+  dependentsBlocked: true;
+  partialResultUsable: false;
+  independentResultsPreserved: true;
+  next: RecoveryNext;
+}
+
 export function isValidRelativePath(p: unknown): p is string {
   return (
     typeof p === "string" &&
@@ -63,6 +101,115 @@ export function isValidRelativePath(p: unknown): p is string {
   );
 }
 
+export function validateVerificationContract(
+  value: unknown,
+): { ok: true; value: VerificationContract } | { ok: false; reason: string } {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return { ok: false, reason: "invalid verification contract" };
+  const contract = value as Record<string, unknown>;
+  if (
+    typeof contract.id !== "string" ||
+    contract.id.length === 0 ||
+    contract.id.length > 128 ||
+    !Array.isArray(contract.argv) ||
+    contract.argv.some(
+      (part) =>
+        typeof part !== "string" ||
+        part.length === 0 ||
+        /[;&|`$<>\n\r]/u.test(part) ||
+        part.includes("\0"),
+    ) ||
+    !["expected-red", "expected-green", "expected-refactor"].includes(
+      String(contract.classification),
+    ) ||
+    !Number.isSafeInteger(contract.minTests) ||
+    (contract.minTests as number) < 1
+  ) {
+    return { ok: false, reason: "invalid verification contract" };
+  }
+  const argv = contract.argv as string[];
+  const check =
+    argv.length === 3 &&
+    argv[0] === "bun" &&
+    argv[1] === "run" &&
+    argv[2] === "check";
+  const target =
+    argv.length >= 4 &&
+    argv[0] === "bun" &&
+    argv[1] === "run" &&
+    argv[2] === "test:target" &&
+    argv
+      .slice(3)
+      .every((part) => part.startsWith("test/") && isValidRelativePath(part));
+  if (!check && !target)
+    return { ok: false, reason: "verification argv is not approved" };
+  if (
+    contract.classification === "expected-red"
+      ? typeof contract.expectedFailure !== "string" ||
+        contract.expectedFailure.length === 0
+      : contract.expectedFailure !== undefined
+  ) {
+    return { ok: false, reason: "invalid expected failure identity" };
+  }
+  return { ok: true, value: contract as unknown as VerificationContract };
+}
+
+function validateImplementationSnapshot(
+  snapshot: unknown,
+  paths: string[],
+): string | null {
+  if (
+    snapshot === undefined ||
+    snapshot === null ||
+    typeof snapshot !== "object" ||
+    Array.isArray(snapshot)
+  ) {
+    return "invalid snapshot";
+  }
+  const bounds = snapshot as Record<string, unknown>;
+  for (const [path, value] of Object.entries(bounds)) {
+    if (
+      !isValidRelativePath(path) ||
+      value === null ||
+      typeof value !== "object" ||
+      Array.isArray(value)
+    ) {
+      return "invalid snapshot";
+    }
+    const entry = value as Record<string, unknown>;
+    if (entry.kind === "file") {
+      if (
+        typeof entry.sha256 !== "string" ||
+        !SNAPSHOT_SHA256.test(entry.sha256) ||
+        typeof entry.bytes !== "number" ||
+        !Number.isSafeInteger(entry.bytes) ||
+        entry.bytes < 0
+      ) {
+        return "invalid snapshot";
+      }
+    } else if (entry.kind === "dir") {
+      if (
+        typeof entry.manifest !== "string" ||
+        !SNAPSHOT_SHA256.test(entry.manifest)
+      ) {
+        return "invalid snapshot";
+      }
+    } else if (entry.kind === "absent") {
+      if (entry.absent !== true) return "invalid snapshot";
+    } else {
+      return "invalid snapshot";
+    }
+  }
+  if (
+    [...new Set(paths)].some(
+      (path) => !Object.prototype.hasOwnProperty.call(bounds, path),
+    )
+  ) {
+    return "snapshot does not cover declared paths";
+  }
+  return null;
+}
+
 export function validateRequestEnvelope(
   value: unknown,
 ): { ok: true; value: RequestEnvelope } | { ok: false; reason: string } {
@@ -98,6 +245,23 @@ export function validateRequestEnvelope(
   ) {
     return { ok: false, reason: "invalid request id" };
   }
+  if (
+    env.taskId !== undefined &&
+    (typeof env.taskId !== "string" ||
+      env.taskId.length === 0 ||
+      env.taskId.length > 128)
+  ) {
+    return { ok: false, reason: "invalid task id" };
+  }
+  // Implementation phases use a phase-local request id and carry their stable
+  // task identity explicitly. Other packets keep id as task id.
+  if (
+    env.stage === "abel-implement" &&
+    env.output === "diff" &&
+    env.taskId === undefined
+  ) {
+    return { ok: false, reason: "missing required field: taskId" };
+  }
   if (
     typeof env.phase !== "string" ||
     !(PHASES as readonly string[]).includes(env.phase)
@@ -155,6 +319,45 @@ export function validateRequestEnvelope(
   if (!(OUTPUT_KINDS as readonly string[]).includes(env.output as string)) {
     return { ok: false, reason: `invalid output kind: ${String(env.output)}` };
   }
+  if (env.verification !== undefined) {
+    const verification = validateVerificationContract(env.verification);
+    if (!verification.ok) {
+      return {
+        ok: false,
+        reason: verification.reason,
+      };
+    }
+  }
+  if (env.stage === "abel-implement" && env.output === "diff") {
+    if (env.verification === undefined) {
+      return { ok: false, reason: "missing required field: verification" };
+    }
+    const expectedClassification = {
+      red: "expected-red",
+      green: "expected-green",
+      refactor: "expected-refactor",
+    }[String(env.phase)];
+    if (
+      expectedClassification === undefined ||
+      (env.verification as VerificationContract).classification !==
+        expectedClassification
+    ) {
+      return {
+        ok: false,
+        reason:
+          "verification classification does not match implementation phase",
+      };
+    }
+  }
+  if (env.stage === "abel-implement" && env.output === "diff") {
+    const snapshotReason = validateImplementationSnapshot(env.snapshot, [
+      ...(decl.read as string[]),
+      ...(decl.write as string[]),
+    ]);
+    if (snapshotReason !== null) {
+      return { ok: false, reason: snapshotReason };
+    }
+  }
   if (
     env.snapshot !== undefined &&
     (env.snapshot === null || typeof env.snapshot !== "object")
@@ -172,68 +375,196 @@ export function diffWritePaths(diffText: string): {
   if (typeof diffText !== "string" || diffText.length === 0) {
     throw new Error("empty diff");
   }
-  if (/^GIT binary patch|^Binary files /.test(diffText)) {
-    throw new Error("binary diff is not supported");
-  }
-  const lines = diffText.split("\n");
-  if (lines.some((line) => /^copy (from|to) /.test(line))) {
-    throw new Error("copy records are not supported");
-  }
-  if (lines.some((line) => /^rename (from|to) /.test(line))) {
-    throw new Error("rename records are not supported");
-  }
-  const paths: string[] = [];
-  let sawHeader = false;
-  let pendingOld: string | null = null;
+  const hasFinalLf = diffText.endsWith("\n");
+  const lines = (hasFinalLf ? diffText.slice(0, -1) : diffText).split("\n");
+
   for (const line of lines) {
-    if (/^old mode /.test(line) || /^new mode /.test(line)) {
+    if (/^(?:GIT binary patch|Binary files )/.test(line)) {
+      throw new Error("binary diff is not supported");
+    }
+    if (/^(?:copy|rename) (?:from|to) /.test(line)) {
+      throw new Error(`${line.split(" ", 1)[0]} records are not supported`);
+    }
+    if (/^(?:old|new) mode /.test(line)) {
       throw new Error("mode transitions are not supported");
     }
-    if (/^(new|deleted) file mode /.test(line)) {
-      const mode = line.split(" ").pop();
-      if (mode === "160000") {
-        throw new Error("submodule mode is not supported");
-      }
-      if (mode !== "100644" && mode !== "100755") {
-        throw new Error(`non-regular file mode is not supported: ${mode}`);
+    const mode = /^(?:new file mode|deleted file mode) (.+)$/.exec(line);
+    if (mode) requireRegularFileMode(mode[1]);
+  }
+
+  const paths: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (!isFileSectionStart(lines[i])) {
+      if (paths.length === 0) {
+        throw new Error("diff has no ordinary text headers");
       }
-      continue;
+      throw new Error(`unconsumed diff content: ${lines[i]}`);
     }
-    if (line.startsWith("--- ") && !line.startsWith("--- /dev/null")) {
-      pendingOld = parseHeaderPath(line.slice(4));
-      continue;
+
+    let gitTarget: string | null = null;
+    if (lines[i].startsWith("diff --git ")) {
+      gitTarget = parseGitTarget(lines[i]);
+      i++;
     }
-    if (line.startsWith("+++ ")) {
-      const newPath = parseHeaderPath(line.slice(4));
-      let target: string;
-      if (newPath === null) {
-        if (pendingOld === null) {
-          throw new Error("diff header pair is malformed");
-        }
-        target = pendingOld;
-      } else {
-        target = newPath;
-        if (pendingOld !== null && pendingOld !== newPath) {
-          throw new Error("mismatched old/new diff targets");
+
+    let operation: "add" | "delete" | null = null;
+    const mode = /^(new file mode|deleted file mode) (.+)$/.exec(
+      lines[i] ?? "",
+    );
+    if (mode) {
+      operation = mode[1] === "new file mode" ? "add" : "delete";
+      i++;
+    }
+    if (lines[i]?.startsWith("index ")) {
+      parseIndexMetadata(lines[i]);
+      i++;
+    }
+
+    if (!lines[i]?.startsWith("--- ")) {
+      throw new Error("file section is missing an ordinary --- header");
+    }
+    const oldPath = parseHeaderPath(lines[i].slice(4), "a");
+    i++;
+    if (!lines[i]?.startsWith("+++ ")) {
+      throw new Error("diff header pair is malformed");
+    }
+    const newPath = parseHeaderPath(lines[i].slice(4), "b");
+    i++;
+
+    if (oldPath === null && newPath === null) {
+      throw new Error("diff header pair has no target");
+    }
+    if (oldPath !== null && newPath !== null && oldPath !== newPath) {
+      throw new Error("mismatched old/new diff targets");
+    }
+    const target = oldPath ?? newPath;
+    if (target === null) throw new Error("diff header pair has no target");
+    if (gitTarget !== null && gitTarget !== target) {
+      throw new Error("mismatched diff --git and text targets");
+    }
+    if (
+      (operation === "add" && oldPath !== null) ||
+      (operation === "delete" && newPath !== null)
+    ) {
+      throw new Error("create/delete metadata does not match text headers");
+    }
+    if (paths.includes(target)) throw new Error("duplicate diff targets");
+    paths.push(target);
+
+    let sawHunk = false;
+    while (lines[i]?.startsWith("@@")) {
+      const hunk = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?: .*)?$/.exec(
+        lines[i],
+      );
+      if (!hunk) throw new Error(`invalid hunk header: ${lines[i]}`);
+      const range = [
+        Number(hunk[1]),
+        Number(hunk[2] ?? "1"),
+        Number(hunk[3]),
+        Number(hunk[4] ?? "1"),
+      ];
+      if (!range.every(Number.isSafeInteger)) {
+        throw new Error("hunk range exceeds supported integer bounds");
+      }
+      let oldRemaining = range[1];
+      let newRemaining = range[3];
+      sawHunk = true;
+      i++;
+
+      while (oldRemaining > 0 || newRemaining > 0) {
+        if (i >= lines.length) throw new Error("hunk body underflow");
+        const body = lines[i];
+        switch (body[0]) {
+          case " ":
+            if (oldRemaining === 0 || newRemaining === 0) {
+              throw new Error("hunk body overflow");
+            }
+            oldRemaining--;
+            newRemaining--;
+            break;
+          case "-":
+            if (oldRemaining === 0) throw new Error("hunk body overflow");
+            oldRemaining--;
+            break;
+          case "+":
+            if (newRemaining === 0) throw new Error("hunk body overflow");
+            newRemaining--;
+            break;
+          default:
+            throw new Error("hunk body underflow");
         }
+        i++;
+        if (lines[i] === "\") i++;
       }
-      pendingOld = null;
-      if (paths.includes(target)) throw new Error("duplicate diff targets");
-      paths.push(target);
-      sawHeader = true;
+    }
+    if (!sawHunk) {
+      throw new Error("file section has no valid unified-diff hunk");
     }
   }
-  if (!sawHeader || paths.length === 0) {
-    throw new Error("diff has no ordinary text headers");
-  }
+
+  if (!hasFinalLf) throw new Error("diff must end with LF");
   return { paths, kind: "text" };
 }
 
-function parseHeaderPath(header: string): string | null {
+function isFileSectionStart(line: string | undefined): boolean {
+  return (
+    line?.startsWith("diff --git ") === true ||
+    line?.startsWith("new file mode ") === true ||
+    line?.startsWith("deleted file mode ") === true ||
+    line?.startsWith("index ") === true ||
+    line?.startsWith("--- ") === true
+  );
+}
+
+function parseGitTarget(line: string): string {
+  const prefix = "diff --git a/";
+  if (!line.startsWith(prefix)) throw new Error("malformed diff --git header");
+  const rest = line.slice(prefix.length);
+  for (
+    let separator = rest.indexOf(" b/");
+    separator >= 0;
+    separator = rest.indexOf(" b/", separator + 1)
+  ) {
+    const oldPath = rest.slice(0, separator);
+    const newPath = rest.slice(separator + 3);
+    if (oldPath === newPath) return requireCanonicalDiffPath(oldPath);
+  }
+  throw new Error("mismatched diff --git targets");
+}
+
+function parseIndexMetadata(line: string): void {
+  const index = /^index [0-9a-f]+\.\.[0-9a-f]+(?: ([0-7]{6}))?$/.exec(line);
+  if (!index) throw new Error("malformed index metadata");
+  if (index[1]) requireRegularFileMode(index[1]);
+}
+
+function requireRegularFileMode(mode: string): void {
+  if (mode === "160000") {
+    throw new Error("submodule mode is not supported: 160000");
+  }
+  if (mode !== "100644" && mode !== "100755") {
+    throw new Error(`non-regular file mode is not supported: ${mode}`);
+  }
+}
+
+function parseHeaderPath(header: string, prefix: "a" | "b"): string | null {
   if (header === "/dev/null") return null;
-  const path = header.replace(/^\s*(a|b)\//, "");
-  if (!isValidRelativePath(path)) {
-    throw new Error(`noncanonical or escaping diff path: ${header}`);
+  const other = prefix === "a" ? "b" : "a";
+  if (header.startsWith(`${other}/`)) {
+    throw new Error("mismatched old/new diff header prefixes");
+  }
+  const path = header.startsWith(`${prefix}/`) ? header.slice(2) : header;
+  return requireCanonicalDiffPath(path);
+}
+
+function requireCanonicalDiffPath(path: string): string {
+  if (
+    !isValidRelativePath(path) ||
+    path.trim() !== path ||
+    /[\r\n\t]/.test(path)
+  ) {
+    throw new Error(`noncanonical or escaping diff path: ${path}`);
   }
   return path;
 }