@abelxiaoxing/cadence 1.0.0

package/src/file-snapshot.ts

@@ -0,0 +1,113 @@
+// File-level snapshots: content hashes for observed files, deterministic
+// directory-entry manifests for observed directories, and explicit absent
+// markers for proposed new paths. Currency is decided per bound path; no
+// global workspace revision participates.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface FileBound {
+  kind: "file";
+  sha256: string;
+  bytes: number;
+}
+
+export interface DirBound {
+  kind: "dir";
+  manifest: string;
+}
+
+export interface AbsentBound {
+  kind: "absent";
+  absent: true;
+}
+
+export type Bound = Record<string, FileBound | DirBound | AbsentBound>;
+
+function sha256(bytes: Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Snapshot one existing regular file under root. */
+export function snapshotFile(root: string, relPath: string): FileBound | null {
+  const abs = resolve(root, relPath);
+  const st = statSync(abs, { throwIfNoEntry: false });
+  if (!st?.isFile()) return null;
+  const bytes = readFileSync(abs);
+  return { sha256: sha256(bytes), bytes: bytes.length, kind: "file" };
+}
+
+/** Deterministic directory-entry manifest: hash of sorted name/type entries. */
+export function snapshotDirManifest(
+  root: string,
+  relDir: string,
+): DirBound | null {
+  const abs = resolve(root, relDir);
+  const st = statSync(abs, { throwIfNoEntry: false });
+  if (!st?.isDirectory()) return null;
+  const entries = readdirSync(abs, { withFileTypes: true })
+    .map((e) => `${e.name}:${e.isDirectory() ? "dir" : "file"}`)
+    .sort();
+  return { manifest: sha256(Buffer.from(entries.join("\n"))), kind: "dir" };
+}
+
+/** Build a bound map for the given file paths, observed directories, and absent markers. */
+export function snapshotFiles(
+  root: string,
+  files: string[],
+  opts: { absent?: string[] } = {},
+): Bound {
+  const bound: Bound = {};
+  for (const p of [...new Set(files)]) {
+    const entry = snapshotFile(root, p);
+    if (entry) bound[p] = entry;
+    else bound[p] = { kind: "absent", absent: true };
+  }
+  for (const p of opts.absent ?? [])
+    bound[p] = { kind: "absent", absent: true };
+  return bound;
+}
+
+/** Build a bound map for observed directories (deterministic manifests). */
+export function snapshotDirManifests(root: string, dirs: string[]): Bound {
+  const bound: Bound = {};
+  for (const p of [...new Set(dirs)]) {
+    const entry = snapshotDirManifest(root, p);
+    if (entry) bound[p] = entry;
+    else bound[p] = { kind: "absent", absent: true };
+  }
+  return bound;
+}
+
+/** Recapture each bound path and report whether the bound state is current. */
+export function isCurrent(root: string, bound: Bound): boolean {
+  for (const [rel, expected] of Object.entries(bound)) {
+    if (expected.kind === "dir") {
+      const now = snapshotDirManifest(root, rel);
+      if (!now || now.manifest !== expected.manifest) return false;
+      continue;
+    }
+    const abs = resolve(root, rel);
+    const exists = existsSync(abs);
+    if (expected.kind === "file") {
+      if (!exists) return false;
+      const st = statSync(abs);
+      if (!st.isFile()) return false;
+      const now = snapshotFile(root, rel);
+      if (
+        !now ||
+        now.sha256 !== expected.sha256 ||
+        now.bytes !== expected.bytes
+      )
+        return false;
+    } else if (expected.absent) {
+      if (exists) return false;
+    }
+  }
+  return true;
+}
+
+/** Merge bound maps (read observations + write targets). */
+export function mergeBounds(...bounds: Bound[]): Bound {
+  return Object.assign({}, ...bounds);
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+// Private workflow orchestration extension. Registers the abel_dispatch tool
+// on load, then keeps it inactive by default by removing only that name from
+// the active set at session start. Eligible-stage activation is wired by the
+// workflow routing (abel-design/implement/diagnose provenance) in the prompts
+// integration; abel-init and ordinary prompts never activate dispatch.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { deactivateTool } from "./activation.ts";
+import { ACTIONS } from "./contracts.ts";
+import { Runtime } from "./runtime.ts";
+
+export const DISPATCH_TOOL = "abel_dispatch";
+
+export default function register(pi: ExtensionAPI): void {
+  const runtime = new Runtime();
+
+  pi.registerTool({
+    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.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: [...ACTIONS] },
+        request: {
+          type: "object",
+          description: "Request envelope for action=run",
+        },
+        resultId: {
+          type: "string",
+          description: "Retained result id for apply/discard",
+        },
+      },
+      required: ["action"],
+    },
+    async execute(
+      _toolCallId: string,
+      params: { action?: string; request?: unknown; resultId?: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: import("@earendil-works/pi-coding-agent").ExtensionContext,
+    ) {
+      const action = typeof params?.action === "string" ? params.action : "";
+      const result = await runtime.execute(action, params, ctx);
+      if (result.ok) {
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }],
+          details: result,
+          usage: result.usage,
+        };
+      }
+      return {
+        content: [{ type: "text", text: result.error }],
+        details: result,
+        isError: true,
+      };
+    },
+  } as never);
+
+  pi.on("session_start", () => {
+    // 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("session_shutdown", () => {
+    runtime.drain();
+    const active = pi.getActiveTools();
+    if (active.includes(DISPATCH_TOOL)) {
+      pi.setActiveTools(deactivateTool(active, DISPATCH_TOOL));
+    }
+  });
+}

package/src/parent-provider.ts

@@ -0,0 +1,85 @@
+import {
+  InMemoryCredentialStore,
+  type Model,
+  type Provider,
+} from "@earendil-works/pi-ai";
+import {
+  type ExtensionContext,
+  ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+
+export async function runtimeForProvider(
+  provider: Provider,
+): Promise<ModelRuntime> {
+  const runtime = await ModelRuntime.create({
+    credentials: new InMemoryCredentialStore(),
+    modelsPath: null,
+    refreshOnCreate: false,
+  });
+  runtime.registerNativeProvider(provider);
+  return runtime;
+}
+
+export function phaseProvider(
+  parent: Provider,
+  auth: {
+    apiKey?: string;
+    headers?: Record<string, string | null>;
+    baseUrl?: string;
+    env?: Record<string, string>;
+  },
+): Provider {
+  return {
+    ...parent,
+    baseUrl: auth.baseUrl ?? parent.baseUrl,
+    headers: { ...parent.headers, ...auth.headers },
+    auth: {
+      apiKey: {
+        name: "Abel phase-local parent auth",
+        resolve: async () => ({
+          auth: {
+            apiKey: auth.apiKey,
+            headers: auth.headers,
+            baseUrl: auth.baseUrl,
+          },
+          env: auth.env,
+        }),
+      },
+    },
+    stream(model, context, options) {
+      return parent.stream(model, context, {
+        ...options,
+        apiKey: auth.apiKey,
+        headers: { ...auth.headers, ...options?.headers },
+        env: { ...auth.env, ...options?.env },
+        maxRetries: 0,
+      } as never);
+    },
+    streamSimple(model, context, options) {
+      return parent.streamSimple(model, context, {
+        ...options,
+        apiKey: auth.apiKey,
+        headers: { ...auth.headers, ...options?.headers },
+        env: { ...auth.env, ...options?.env },
+        maxRetries: 0,
+      });
+    },
+  };
+}
+
+export async function runtimeFromContext(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+): Promise<{ modelRuntime: ModelRuntime; model: Model<string> }> {
+  if (!ctx.model) throw new Error("parent model is unavailable");
+  const parent = ctx.modelRegistry.getProvider(ctx.model.provider);
+  if (!parent) throw new Error("parent Provider is unavailable");
+  const resolved = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+  if (!resolved.ok) throw new Error(resolved.error);
+  const provider = phaseProvider(parent, resolved);
+  const modelRuntime = await runtimeForProvider(provider);
+  const model = {
+    ...ctx.model,
+    baseUrl: resolved.baseUrl ?? ctx.model.baseUrl,
+  } as Model<string>;
+  return { modelRuntime, model };
+}

package/src/patch.ts

@@ -0,0 +1,113 @@
+import { spawn } from "node:child_process";
+import { diffWritePaths } from "./contracts.ts";
+import { isCurrent } from "./file-snapshot.ts";
+import type { ResultStore } from "./result-store.ts";
+
+interface CommandResult {
+  code: number;
+  stdout: Buffer;
+  stderr: Buffer;
+}
+
+async function git(
+  root: string,
+  args: string[],
+  input: Buffer,
+): Promise<CommandResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("git", args, {
+      cwd: root,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.stdout.on("data", (b: Buffer) => stdout.push(b));
+    child.stderr.on("data", (b: Buffer) => stderr.push(b));
+    child.on("error", reject);
+    child.on("close", (code) =>
+      resolve({
+        code: code ?? 1,
+        stdout: Buffer.concat(stdout),
+        stderr: Buffer.concat(stderr),
+      }),
+    );
+    child.stdin.end(input);
+  });
+}
+
+export async function applyRetainedPatch(input: {
+  root: string;
+  id: string;
+  store: ResultStore;
+}): Promise<
+  | { ok: true; targets: string[]; checkExitCode: 0; applyExitCode: 0 }
+  | { ok: false; error: string }
+> {
+  const retained = input.store.get(input.id);
+  if (!retained) return { ok: false, error: "retained result not found" };
+  if (retained.root !== input.root)
+    return { ok: false, error: "retained result root mismatch" };
+  if (!isCurrent(input.root, retained.snapshot))
+    return { ok: false, error: "stale file snapshot" };
+
+  let targets: string[];
+  try {
+    targets = diffWritePaths(retained.diff.toString("utf8")).paths;
+  } catch (error) {
+    return { ok: false, error: (error as Error).message };
+  }
+  if (targets.some((path) => !retained.writeSet.includes(path))) {
+    return {
+      ok: false,
+      error: "patch target is outside the declared write set",
+    };
+  }
+
+  const numstat = await git(
+    input.root,
+    ["apply", "--numstat", "-z", "--recount", "-"],
+    retained.diff,
+  );
+  if (numstat.code !== 0 || numstat.stdout.includes(Buffer.from("-\t-\t"))) {
+    return {
+      ok: false,
+      error: `git numstat screening failed: ${numstat.stderr.toString("utf8")}`,
+    };
+  }
+  const summary = await git(
+    input.root,
+    ["apply", "--summary", "--recount", "-"],
+    retained.diff,
+  );
+  if (
+    summary.code !== 0 ||
+    /rename|copy|mode change|create mode 160000/i.test(
+      summary.stdout.toString("utf8"),
+    )
+  ) {
+    return { ok: false, error: "git summary screening rejected the patch" };
+  }
+  const check = await git(
+    input.root,
+    ["apply", "--check", "--recount", "--whitespace=nowarn", "-"],
+    retained.diff,
+  );
+  if (check.code !== 0)
+    return {
+      ok: false,
+      error: `git apply --check failed: ${check.stderr.toString("utf8")}`,
+    };
+  const apply = await git(
+    input.root,
+    ["apply", "--recount", "--whitespace=nowarn", "-"],
+    retained.diff,
+  );
+  if (apply.code !== 0)
+    return {
+      ok: false,
+      error: `git apply failed: ${apply.stderr.toString("utf8")}`,
+    };
+  input.store.discard(input.id);
+  return { ok: true, targets, checkExitCode: 0, applyExitCode: 0 };
+}

package/src/result-store.ts

@@ -0,0 +1,40 @@
+import { randomUUID } from "node:crypto";
+import type { Bound } from "./file-snapshot.ts";
+import { snapshotFiles } from "./file-snapshot.ts";
+
+export interface RetainedResult {
+  id: string;
+  diff: Buffer;
+  writeSet: string[];
+  root: string;
+  snapshot: Bound;
+}
+
+export class ResultStore {
+  private readonly results = new Map<string, RetainedResult>();
+
+  retain(input: { diff: string; writeSet: string[]; root: string }): string {
+    const id = randomUUID();
+    this.results.set(id, {
+      id,
+      diff: Buffer.from(input.diff, "utf8"),
+      writeSet: [...new Set(input.writeSet)],
+      root: input.root,
+      snapshot: snapshotFiles(input.root, input.writeSet),
+    });
+    return id;
+  }
+
+  get(id: string): RetainedResult | undefined {
+    return this.results.get(id);
+  }
+  discard(id: string): boolean {
+    return this.results.delete(id);
+  }
+  clear(): void {
+    this.results.clear();
+  }
+  get size(): number {
+    return this.results.size;
+  }
+}