@abelxiaoxing/cadence 1.0.2 → 1.0.3

package/src/index.ts

@@ -99,6 +99,14 @@ function activateDispatcher(
   }
 }
 
+function splitUsage(result: unknown): { payload: unknown; usage?: unknown } {
+  if (typeof result !== "object" || result === null || !("usage" in result)) {
+    return { payload: result };
+  }
+  const { usage, ...payload } = result as Record<string, unknown>;
+  return { payload, usage };
+}
+
 export default function register(pi: ExtensionAPI): void {
   const parentPayloadBridge = new ParentPayloadBridge();
   const runtime = new Runtime({ parentPayloadBridge });
@@ -108,7 +116,7 @@ export default function register(pi: ExtensionAPI): void {
     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, cancel work, or finish the stage. Inactive unless an eligible Abel stage verified its invocation.",
+      "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: {
@@ -121,12 +129,32 @@ export default function register(pi: ExtensionAPI): void {
           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)",
+        },
       },
       required: ["action"],
     },
     async execute(
       toolCallId: string,
-      params: { action?: string; request?: unknown; resultId?: string },
+      params: {
+        action?: string;
+        request?: unknown;
+        resultId?: string;
+        requestId?: string;
+        rejection?: unknown;
+        agentsCheckpoint?: unknown;
+      },
       signal: AbortSignal | undefined,
       onUpdate: AgentToolUpdateCallback<unknown> | undefined,
       ctx: ExtensionContext,
@@ -135,10 +163,11 @@ export default function register(pi: ExtensionAPI): void {
       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,
-            params,
+            operation,
             ctx,
             signal,
             activity.observe(
@@ -146,24 +175,21 @@ export default function register(pi: ExtensionAPI): void {
               onUpdate as ((result: unknown) => void) | undefined,
             ),
           )
-        : await runtime.execute(action, params, ctx, signal);
+        : await runtime.execute(action, operation, ctx, signal);
       const display = tuiRun
         ? activity.finalize(toolCallId, result)
         : undefined;
+      const { payload, usage } = splitUsage(result);
       const details = display
-        ? { ...result, [ACTIVITY_DETAILS_KEY]: display }
-        : result;
-      if (result.ok) {
-        return {
-          content: [{ type: "text", text: JSON.stringify(result) }],
-          details,
-          usage: result.usage,
-        };
-      }
+        ? {
+            ...(payload as Record<string, unknown>),
+            [ACTIVITY_DETAILS_KEY]: display,
+          }
+        : payload;
       return {
-        content: [{ type: "text", text: JSON.stringify(result) }],
+        content: [{ type: "text", text: JSON.stringify(payload) }],
         details,
-        isError: true,
+        ...(usage === undefined ? {} : { usage }),
       };
     },
     renderCall(args: unknown, theme: Theme, _context: unknown) {
@@ -207,7 +233,15 @@ export default function register(pi: ExtensionAPI): void {
       activateDispatcher(pi, runtime.activation, prompt, event.prompt);
   });
 
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
+    pendingPrompt = undefined;
+    activity.detach();
+    const active = pi.getActiveTools();
+    if (active.includes(DISPATCH_TOOL)) {
+      pi.setActiveTools(deactivateTool(active, DISPATCH_TOOL));
+    }
+    await runtime.drain();
+    activity.clear();
     const sessionId = ctx.sessionManager?.getSessionId?.();
     if (typeof sessionId === "string") {
       parentPayloadBridge.beginSession(sessionId);
@@ -217,15 +251,7 @@ export default function register(pi: ExtensionAPI): void {
     } else {
       parentPayloadBridge.clear();
     }
-    pendingPrompt = undefined;
-    activity.detach();
     if (ctx.mode === "tui") activity.attach(ctx.ui);
-    // Restore the default: dispatch is inactive unless a verified stage
-    // reactivates it through the activation helpers.
-    const active = pi.getActiveTools();
-    if (active.includes(DISPATCH_TOOL)) {
-      pi.setActiveTools(deactivateTool(active, DISPATCH_TOOL));
-    }
   });
 
   pi.on("model_select", (event, ctx) => {

package/src/parent-provider.ts

@@ -7,6 +7,7 @@ import {
   type ExtensionContext,
   ModelRuntime,
 } from "@earendil-works/pi-coding-agent";
+import type { ChildFailure } from "./contracts.ts";
 import type {
   ParentPayloadBridge,
   ParentPayloadCallback,
@@ -18,6 +19,33 @@ export interface PhasePayloadBridge {
   readonly capture: ParentPayloadCapture;
 }
 
+type PhaseRuntimeFailure = Extract<
+  ChildFailure,
+  { kind: "cancelled" | "environment" | "transport" }
+>;
+
+export type PhaseRuntimeResult =
+  | { ok: true; modelRuntime: ModelRuntime; model: Model<string> }
+  | { ok: false; error: string; failure: PhaseRuntimeFailure };
+
+function phaseRuntimeFailure(
+  failure: PhaseRuntimeFailure,
+  error: string,
+): Extract<PhaseRuntimeResult, { ok: false }> {
+  return { ok: false, error, failure };
+}
+
+function cancelledPhaseRuntime(): Extract<PhaseRuntimeResult, { ok: false }> {
+  return phaseRuntimeFailure(
+    { kind: "cancelled", code: "cancelled" },
+    "child phase cancelled",
+  );
+}
+
+function isCancellation(error: unknown, signal?: AbortSignal): boolean {
+  return signal?.aborted === true && error === signal.reason;
+}
+
 function phasePayloadCallback(
   payloadBridge: PhasePayloadBridge,
   childOnPayload: ParentPayloadCallback | undefined,
@@ -137,44 +165,82 @@ export async function runtimeFromContext(
   ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
   payloadBridge: ParentPayloadBridge,
   signal?: AbortSignal,
-): Promise<{ modelRuntime: ModelRuntime; model: Model<string> }> {
-  signal?.throwIfAborted();
-  if (!ctx.model) throw new Error("parent model is unavailable");
+): Promise<PhaseRuntimeResult> {
+  if (signal?.aborted) return cancelledPhaseRuntime();
+  if (!ctx.model) {
+    return phaseRuntimeFailure(
+      { kind: "environment", code: "sandbox-runtime-unavailable" },
+      "parent model is unavailable",
+    );
+  }
   const selectedModel = ctx.model;
   const selectedModelKey = modelKeyFor(selectedModel);
-  const resolved = await abortable(
-    ctx.modelRegistry.getApiKeyAndHeaders(selectedModel),
-    signal,
-  );
-  if (!resolved.ok) throw new Error(resolved.error);
-  signal?.throwIfAborted();
+  let resolved: Awaited<
+    ReturnType<typeof ctx.modelRegistry.getApiKeyAndHeaders>
+  >;
+  try {
+    resolved = await abortable(
+      ctx.modelRegistry.getApiKeyAndHeaders(selectedModel),
+      signal,
+    );
+  } catch (error) {
+    if (isCancellation(error, signal)) return cancelledPhaseRuntime();
+    throw error;
+  }
+  if (!resolved.ok) {
+    return phaseRuntimeFailure(
+      { kind: "environment", code: "sandbox-runtime-unavailable" },
+      "phase authentication is unavailable",
+    );
+  }
+  if (signal?.aborted) return cancelledPhaseRuntime();
   const model = {
     ...selectedModel,
     baseUrl: resolved.baseUrl ?? selectedModel.baseUrl,
   } as Model<string>;
   const effectiveModelKey = modelKeyFor(model);
   const capture = payloadBridge.capture(effectiveModelKey, ctx.modelRegistry);
-  if (!capture) throw new Error("parent payload bridge is unavailable");
-  const requireReadyCapture = () => {
-    if (
-      !ctx.model ||
-      !sameSelectedModel(ctx.model, selectedModelKey) ||
-      payloadBridge.capture(effectiveModelKey, ctx.modelRegistry) !== capture
-    ) {
-      throw new Error("parent payload bridge is unavailable");
-    }
+  if (!capture) {
+    return phaseRuntimeFailure(
+      { kind: "transport", code: "transport-failure" },
+      "parent payload bridge is unavailable",
+    );
+  }
+  const captureIsReady = () => {
+    const currentModel = ctx.model;
+    return (
+      currentModel !== undefined &&
+      sameSelectedModel(currentModel, selectedModelKey) &&
+      payloadBridge.capture(effectiveModelKey, ctx.modelRegistry) === capture
+    );
   };
-  requireReadyCapture();
+  if (!captureIsReady()) {
+    return phaseRuntimeFailure(
+      { kind: "transport", code: "transport-failure" },
+      "parent payload bridge is unavailable",
+    );
+  }
   const delegate = capture.delegate;
   if (!delegate) throw new Error("parent Provider is unavailable");
   const provider = phaseProvider(delegate, resolved, {
     bridge: payloadBridge,
     capture,
   });
-  const modelRuntime = await runtimeForProvider(provider, signal);
-  signal?.throwIfAborted();
-  requireReadyCapture();
-  return { modelRuntime, model };
+  let modelRuntime: ModelRuntime;
+  try {
+    modelRuntime = await runtimeForProvider(provider, signal);
+  } catch (error) {
+    if (isCancellation(error, signal)) return cancelledPhaseRuntime();
+    throw error;
+  }
+  if (signal?.aborted) return cancelledPhaseRuntime();
+  if (!captureIsReady()) {
+    return phaseRuntimeFailure(
+      { kind: "transport", code: "transport-failure" },
+      "parent payload bridge is unavailable",
+    );
+  }
+  return { ok: true, modelRuntime, model };
 }
 
 function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {

package/src/patch.ts

@@ -1,7 +1,23 @@
 import { spawn } from "node:child_process";
+import {
+  copyFileSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { preflightCandidate } from "./candidate-preflight.ts";
-import { diffWritePaths } from "./contracts.ts";
-import { isCurrent } from "./file-snapshot.ts";
+import {
+  type AgentsCheckpointRequest,
+  type ApplyCandidateResult,
+  type CandidateFailure,
+  diffWritePaths,
+  validateAgentsCheckpointRequest,
+} from "./contracts.ts";
+import { type Bound, isCurrent } from "./file-snapshot.ts";
 import type { ResultStore } from "./result-store.ts";
 
 interface CommandResult {
@@ -58,8 +74,223 @@ async function git(
   });
 }
 
-function cancellationFailure(): { ok: false; error: string } {
-  return { ok: false, error: "candidate application cancelled" };
+function failure(value: CandidateFailure): {
+  ok: false;
+  failure: CandidateFailure;
+} {
+  return { ok: false, failure: value };
+}
+
+function cancellationFailure(): {
+  ok: false;
+  failure: CandidateFailure;
+} {
+  return failure({ kind: "cancelled", code: "cancelled" });
+}
+
+type AgentsCheckpointResult =
+  | {
+      ok: true;
+      target: string;
+      agentsImpact: AgentsCheckpointRequest["agentsImpact"];
+      checkExitCode: 0;
+      applyExitCode: 0;
+    }
+  | {
+      ok: false;
+      failure: CandidateFailure;
+    };
+
+const AGENTS_START = "<!-- ABEL:AGENTS-INDEX:START -->";
+const AGENTS_END = "<!-- ABEL:AGENTS-INDEX:END -->";
+const NONREGULAR_AGENTS_TARGET = Symbol("nonregular AGENTS target");
+
+function managedParts(text: string): { prefix: string; suffix: string } | null {
+  const lines = text.split("\n");
+  const starts: Array<{ line: number; start: number; end: number }> = [];
+  const ends: Array<{ line: number; start: number; end: number }> = [];
+  let offset = 0;
+  for (const [line, value] of lines.entries()) {
+    const range = { line, start: offset, end: offset + value.length };
+    if (value === AGENTS_START) starts.push(range);
+    if (value === AGENTS_END) ends.push(range);
+    offset = range.end + 1;
+  }
+  if (
+    starts.length !== 1 ||
+    ends.length !== 1 ||
+    starts[0].line >= ends[0].line
+  ) {
+    return null;
+  }
+  return {
+    prefix: text.slice(0, starts[0].start),
+    suffix: text.slice(ends[0].end),
+  };
+}
+
+function checkpointContentIsScoped(
+  impact: AgentsCheckpointRequest["agentsImpact"],
+  before: string | null,
+  after: string | null,
+): boolean {
+  const beforeParts = before === null ? null : managedParts(before);
+  const afterParts = after === null ? null : managedParts(after);
+  if (impact === "update-existing") {
+    return (
+      beforeParts !== null &&
+      afterParts !== null &&
+      beforeParts.prefix === afterParts.prefix &&
+      beforeParts.suffix === afterParts.suffix
+    );
+  }
+  if (impact === "create-index") {
+    return (
+      before === null &&
+      afterParts !== null &&
+      afterParts.prefix.trim() === "" &&
+      afterParts.suffix.trim() === ""
+    );
+  }
+  if (beforeParts === null) return false;
+  if (after === null) {
+    return beforeParts.prefix.trim() === "" && beforeParts.suffix.trim() === "";
+  }
+  return (
+    managedParts(after) === null &&
+    after === `${beforeParts.prefix}${beforeParts.suffix}`
+  );
+}
+
+function regularText(
+  root: string,
+  target: string,
+): string | null | typeof NONREGULAR_AGENTS_TARGET {
+  const resolvedRoot = path.resolve(root);
+  const absolute = path.resolve(resolvedRoot, target);
+  if (
+    absolute === resolvedRoot ||
+    !absolute.startsWith(`${resolvedRoot}${path.sep}`)
+  ) {
+    throw new Error("AGENTS target escapes the root");
+  }
+  const stat = lstatSync(absolute, { throwIfNoEntry: false });
+  if (!stat) return null;
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    return NONREGULAR_AGENTS_TARGET;
+  }
+  return readFileSync(absolute, "utf8");
+}
+
+export async function applyAgentsCheckpoint(
+  root: string,
+  value: unknown,
+  signal?: AbortSignal,
+): Promise<AgentsCheckpointResult> {
+  const validation = validateAgentsCheckpointRequest(value);
+  if (!validation.ok) {
+    return failure({ kind: "artifact", code: "invalid-checkpoint-contract" });
+  }
+  const request = validation.value;
+  if (signal?.aborted) {
+    return cancellationFailure();
+  }
+  const before = regularText(root, request.agentsTarget);
+  if (before === NONREGULAR_AGENTS_TARGET) {
+    return failure({ kind: "artifact", code: "nonregular-mode" });
+  }
+  if (!isCurrent(root, request.snapshot as Bound)) {
+    return failure({ kind: "stale", code: "stale-snapshot" });
+  }
+  let targets: string[];
+  try {
+    targets = diffWritePaths(request.diff).paths;
+  } catch {
+    return failure({ kind: "artifact", code: "invalid-diff" });
+  }
+  if (targets.length !== 1 || targets[0] !== request.agentsTarget) {
+    return failure({ kind: "artifact", code: "agents-target-mismatch" });
+  }
+
+  let temp: string | undefined;
+  try {
+    if (
+      (request.agentsImpact === "create-index" && before !== null) ||
+      (request.agentsImpact !== "create-index" && before === null)
+    ) {
+      return failure({ kind: "artifact", code: "agents-impact-mismatch" });
+    }
+    temp = mkdtempSync(path.join(tmpdir(), "cadence-agents-checkpoint-"));
+    if (before !== null) {
+      const temporaryTarget = path.join(temp, request.agentsTarget);
+      mkdirSync(path.dirname(temporaryTarget), { recursive: true });
+      copyFileSync(path.join(root, request.agentsTarget), temporaryTarget);
+    }
+    const bytes = Buffer.from(request.diff, "utf8");
+    const candidateCheck = await git(
+      temp,
+      ["apply", "--check", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+      signal,
+    );
+    if (candidateCheck.cancelled || signal?.aborted) {
+      return cancellationFailure();
+    }
+    if (candidateCheck.code !== 0) {
+      return failure({ kind: "artifact", code: "git-apply-check-failed" });
+    }
+    const candidateApply = await git(
+      temp,
+      ["apply", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+      signal,
+    );
+    if (candidateApply.cancelled || signal?.aborted) {
+      return cancellationFailure();
+    }
+    if (candidateApply.code !== 0) {
+      return failure({ kind: "artifact", code: "git-apply-failed" });
+    }
+    const after = regularText(temp, request.agentsTarget);
+    if (after === NONREGULAR_AGENTS_TARGET) {
+      return failure({ kind: "artifact", code: "nonregular-mode" });
+    }
+    if (!checkpointContentIsScoped(request.agentsImpact, before, after)) {
+      return failure({ kind: "artifact", code: "outside-managed-region" });
+    }
+    if (!isCurrent(root, request.snapshot as Bound)) {
+      return failure({ kind: "stale", code: "stale-snapshot" });
+    }
+    const check = await git(
+      root,
+      ["apply", "--check", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+      signal,
+    );
+    if (check.cancelled || signal?.aborted) {
+      return cancellationFailure();
+    }
+    if (check.code !== 0) {
+      return failure({ kind: "stale", code: "git-apply-check-failed" });
+    }
+    const apply = await git(
+      root,
+      ["apply", "--recount", "--whitespace=nowarn", "-"],
+      bytes,
+    );
+    if (apply.code !== 0) {
+      return failure({ kind: "environment", code: "git-apply-failed" });
+    }
+    return {
+      ok: true,
+      target: request.agentsTarget,
+      agentsImpact: request.agentsImpact,
+      checkExitCode: 0,
+      applyExitCode: 0,
+    };
+  } finally {
+    if (temp) rmSync(temp, { recursive: true, force: true });
+  }
 }
 
 export async function applyRetainedPatch(input: {
@@ -67,29 +298,22 @@ export async function applyRetainedPatch(input: {
   id: string;
   store: ResultStore;
   signal?: AbortSignal;
-}): Promise<
-  | { ok: true; targets: string[]; checkExitCode: 0; applyExitCode: 0 }
-  | { ok: false; error: string }
-> {
+}): Promise<ApplyCandidateResult> {
   if (input.signal?.aborted) return cancellationFailure();
-  const retained = input.store.get(input.id);
-  if (!retained) return { ok: false, error: "retained result not found" };
+  const retained = input.store.resolveForApply(input.id);
   if (retained.root !== input.root)
-    return { ok: false, error: "retained result root mismatch" };
+    throw new Error("retained result root mismatch");
   if (!retained.verification && !isCurrent(input.root, retained.snapshot))
-    return { ok: false, error: "stale file snapshot" };
+    return failure({ kind: "stale", code: "stale-snapshot" });
 
   let targets: string[];
   try {
     targets = diffWritePaths(retained.diff.toString("utf8")).paths;
-  } catch (error) {
-    return { ok: false, error: (error as Error).message };
+  } catch {
+    return failure({ kind: "artifact", code: "invalid-diff" });
   }
   if (targets.some((path) => !retained.writeSet.includes(path))) {
-    return {
-      ok: false,
-      error: "patch target is outside the declared write set",
-    };
+    return failure({ kind: "artifact", code: "write-set-mismatch" });
   }
 
   if (retained.verification) {
@@ -98,15 +322,13 @@ export async function applyRetainedPatch(input: {
       !retained.lockfile ||
       !retained.dependencyTarget
     ) {
-      return {
-        ok: false,
-        error: "retained candidate preflight inputs are incomplete",
-      };
+      throw new Error("retained candidate preflight inputs are incomplete");
     }
     const preflight = await preflightCandidate({
       root: input.root,
       diff: retained.diff,
       writeSet: retained.writeSet,
+      approvedDependencies: retained.approvedDependencies,
       snapshot: retained.snapshot,
       baseline: retained.baseline,
       verification: retained.verification,
@@ -116,13 +338,25 @@ export async function applyRetainedPatch(input: {
       signal: input.signal,
     });
     if (!preflight.ok) {
-      return {
-        ok: false,
-        error: `candidate preflight rejected: ${preflight.class}:${preflight.code}`,
-      };
+      switch (preflight.kind) {
+        case "artifact":
+          return failure({
+            kind: preflight.kind,
+            code: preflight.code,
+            ...(preflight.excerpt ? { evidence: [preflight.excerpt] } : {}),
+          });
+        case "stale":
+          return failure({ kind: preflight.kind, code: preflight.code });
+        case "environment":
+          return failure({ kind: preflight.kind, code: preflight.code });
+        case "approval-boundary":
+          return failure({ kind: preflight.kind, code: preflight.code });
+        case "cancelled":
+          return failure({ kind: preflight.kind, code: preflight.code });
+      }
     }
     if (!isCurrent(input.root, retained.snapshot)) {
-      return { ok: false, error: "stale file snapshot after preflight" };
+      return failure({ kind: "stale", code: "stale-snapshot" });
     }
   }
   if (input.signal?.aborted) return cancellationFailure();
@@ -135,10 +369,7 @@ export async function applyRetainedPatch(input: {
   );
   if (numstat.cancelled || input.signal?.aborted) return cancellationFailure();
   if (numstat.code !== 0 || numstat.stdout.includes(Buffer.from("-\t-\t"))) {
-    return {
-      ok: false,
-      error: `git numstat screening failed: ${numstat.stderr.toString("utf8")}`,
-    };
+    return failure({ kind: "artifact", code: "invalid-diff" });
   }
   const summary = await git(
     input.root,
@@ -153,7 +384,7 @@ export async function applyRetainedPatch(input: {
       summary.stdout.toString("utf8"),
     )
   ) {
-    return { ok: false, error: "git summary screening rejected the patch" };
+    return failure({ kind: "artifact", code: "invalid-diff" });
   }
   const check = await git(
     input.root,
@@ -163,10 +394,7 @@ export async function applyRetainedPatch(input: {
   );
   if (check.cancelled || input.signal?.aborted) return cancellationFailure();
   if (check.code !== 0)
-    return {
-      ok: false,
-      error: `git apply --check failed: ${check.stderr.toString("utf8")}`,
-    };
+    return failure({ kind: "artifact", code: "git-apply-check-failed" });
   if (input.signal?.aborted) return cancellationFailure();
   const apply = await git(
     input.root,
@@ -174,10 +402,10 @@ export async function applyRetainedPatch(input: {
     retained.diff,
   );
   if (apply.code !== 0)
-    return {
-      ok: false,
-      error: `git apply failed: ${apply.stderr.toString("utf8")}`,
-    };
+    return failure({ kind: "environment", code: "git-apply-failed" });
   input.store.discard(input.id);
-  return { ok: true, targets, checkExitCode: 0, applyExitCode: 0 };
+  return {
+    ok: true,
+    result: { targets, checkExitCode: 0, applyExitCode: 0 },
+  };
 }