@abelxiaoxing/cadence 1.0.0

package/src/scoped-tools.ts

@@ -0,0 +1,282 @@
+// Scoped read-only filesystem tools: read, grep, find, ls. Repository-relative
+// paths only, no mutation, no process execution, bounded output and scan sizes.
+import {
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  type Stats,
+  statSync,
+} from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+
+export const TOOL_LIMITS = {
+  maxReadBytes: 50 * 1024,
+  maxReadLines: 2000,
+  maxGrepPattern: 1024,
+  maxGrepFiles: 2000,
+  maxGrepMillis: 5000,
+  maxEntries: 20000,
+} as const;
+
+export type Observation =
+  | { kind: "file"; path: string }
+  | { kind: "dir"; path: string };
+
+export interface ScopedToolDef {
+  name: string;
+  description: string;
+  execute(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+interface Options {
+  roots: string[];
+  observer?: (obs: Observation) => void;
+}
+
+type PathResult =
+  | { ok: true; abs: string; rel: string }
+  | { ok: false; error: string };
+
+function resolveScoped(roots: string[], input: unknown): PathResult {
+  if (typeof input !== "string" || input.length === 0) {
+    return { ok: false, error: "missing path" };
+  }
+  if (input.includes("\u0000"))
+    return { ok: false, error: "NUL byte rejected" };
+  if (input.includes("\\")) return { ok: false, error: "backslash rejected" };
+  if (input.startsWith("/") || input.startsWith("~")) {
+    return { ok: false, error: "absolute path rejected" };
+  }
+  if (input.split("/").includes("..")) {
+    return { ok: false, error: "parent traversal rejected" };
+  }
+  if (input.startsWith("./") || input.includes("//") || input.endsWith("/.")) {
+    return { ok: false, error: "noncanonical path rejected" };
+  }
+  for (const root of roots) {
+    const abs = resolve(root, input);
+    const inside =
+      abs === root || abs.startsWith(root.endsWith("/") ? root : `${root}/`);
+    if (!inside) continue;
+    // Hidden directories are rejected unless the root itself is the hidden scope.
+    const hiddenRoot =
+      basename(realpathSync(root)) === ".git" ||
+      basename(realpathSync(root)) === "node_modules";
+    for (const segment of input.split("/").slice(0, -1)) {
+      if ((segment === ".git" || segment === "node_modules") && !hiddenRoot) {
+        return { ok: false, error: "hidden path rejected" };
+      }
+    }
+    // Reject symlinks on any existing component and verify realpath containment.
+    let current = root;
+    for (const segment of input.split("/")) {
+      current = join(current, segment);
+      let st: Stats | undefined;
+      try {
+        st = lstatSync(current);
+      } catch {
+        break; // nonexistent leaf is fine for absent markers
+      }
+      if (st.isSymbolicLink()) return { ok: false, error: "symlink rejected" };
+    }
+    if (existsSync(current)) {
+      const real = realpathSync(current);
+      const realRoot = realpathSync(root);
+      if (real !== realRoot && !real.startsWith(`${realRoot}/`)) {
+        return { ok: false, error: "path escapes the approved root" };
+      }
+    }
+    return { ok: true, abs: abs, rel: relative(root, abs) || "." };
+  }
+  return { ok: false, error: "path is outside every approved root" };
+}
+
+function existsSync(p: string): boolean {
+  try {
+    statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function utf8Text(abs: string): string | null {
+  const buf = readFileSync(abs);
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+export function createScopedTools(opts: Options): ScopedToolDef[] {
+  const roots = opts.roots.map((r) => resolve(r));
+  const observe = opts.observer ?? (() => {});
+
+  const readTool: ScopedToolDef = {
+    name: "read",
+    description:
+      "Read a regular UTF-8 text file within the approved scope (max 2,000 lines / 50 KiB).",
+    async execute(params) {
+      const resolved = resolveScoped(roots, params.path);
+      if (!resolved.ok) return { ok: false, error: resolved.error };
+      let st: Stats | undefined;
+      try {
+        st = statSync(resolved.abs);
+      } catch {
+        return { ok: false, error: "file does not exist" };
+      }
+      if (!st.isFile()) return { ok: false, error: "not a regular file" };
+      const text = utf8Text(resolved.abs);
+      if (text === null) return { ok: false, error: "not valid UTF-8 text" };
+      observe({ kind: "file", path: resolved.rel });
+      const bytes = Buffer.byteLength(text, "utf8");
+      const lines = text.split("\n").length;
+      const truncated =
+        bytes > TOOL_LIMITS.maxReadBytes || lines > TOOL_LIMITS.maxReadLines;
+      let content = text;
+      if (bytes > TOOL_LIMITS.maxReadBytes) {
+        content = Buffer.from(text, "utf8")
+          .subarray(0, TOOL_LIMITS.maxReadBytes)
+          .toString("utf8");
+      }
+      if (content.split("\n").length > TOOL_LIMITS.maxReadLines) {
+        content = content
+          .split("\n")
+          .slice(0, TOOL_LIMITS.maxReadLines)
+          .join("\n");
+      }
+      return { ok: true, content, truncated };
+    },
+  };
+
+  const grepTool: ScopedToolDef = {
+    name: "grep",
+    description:
+      "Search regular text files with a bounded JavaScript regular expression (max 1,024 chars, 2,000 files).",
+    async execute(params) {
+      const pattern = params.pattern;
+      if (typeof pattern !== "string" || pattern.length === 0) {
+        return { ok: false, error: "missing pattern" };
+      }
+      if (pattern.length > TOOL_LIMITS.maxGrepPattern) {
+        return {
+          ok: false,
+          error: `pattern exceeds ${TOOL_LIMITS.maxGrepPattern} characters`,
+        };
+      }
+      const resolved = resolveScoped(roots, params.path ?? ".");
+      if (!resolved.ok) return { ok: false, error: resolved.error };
+      let regex: RegExp;
+      try {
+        regex = new RegExp(pattern, "u");
+      } catch {
+        return { ok: false, error: "invalid regular expression" };
+      }
+      const start = performance.now();
+      const matches: { path: string; line: number; text: string }[] = [];
+      let scanned = 0;
+      const files = collectFiles(resolved.abs, [], TOOL_LIMITS.maxEntries);
+      for (const file of files) {
+        if (scanned >= TOOL_LIMITS.maxGrepFiles) break;
+        if (performance.now() - start > TOOL_LIMITS.maxGrepMillis) break;
+        scanned++;
+        const text = utf8Text(file);
+        if (text === null) continue;
+        observe({ kind: "file", path: relative(roots[0], file) });
+        const lines = text.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          regex.lastIndex = 0;
+          if (regex.test(lines[i])) {
+            matches.push({
+              path: relative(roots[0], file),
+              line: i + 1,
+              text: lines[i].slice(0, 500),
+            });
+          }
+        }
+      }
+      return { ok: true, matches };
+    },
+  };
+
+  const lsTool: ScopedToolDef = {
+    name: "ls",
+    description:
+      "List a directory within the approved scope (max 20,000 entries, stable code-unit order).",
+    async execute(params) {
+      const resolved = resolveScoped(roots, params.path ?? ".");
+      if (!resolved.ok) return { ok: false, error: resolved.error };
+      let st: Stats | undefined;
+      try {
+        st = statSync(resolved.abs);
+      } catch {
+        return { ok: false, error: "directory does not exist" };
+      }
+      if (!st.isDirectory()) return { ok: false, error: "not a directory" };
+      observe({ kind: "dir", path: resolved.rel });
+      const entries = readdirSync(resolved.abs, { withFileTypes: true })
+        .filter((e) => !isHidden(e.name, roots))
+        .slice(0, TOOL_LIMITS.maxEntries)
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+      return {
+        ok: true,
+        entries: entries.map((e) => ({
+          name: e.name,
+          type: e.isDirectory() ? "dir" : "file",
+        })),
+      };
+    },
+  };
+
+  const findTool: ScopedToolDef = {
+    name: "find",
+    description:
+      "Recursively list paths within the approved scope (max 20,000 entries, stable code-unit order).",
+    async execute(params) {
+      const resolved = resolveScoped(roots, params.path ?? ".");
+      if (!resolved.ok) return { ok: false, error: resolved.error };
+      let st: Stats | undefined;
+      try {
+        st = statSync(resolved.abs);
+      } catch {
+        return { ok: false, error: "directory does not exist" };
+      }
+      if (!st.isDirectory()) return { ok: false, error: "not a directory" };
+      observe({ kind: "dir", path: resolved.rel });
+      const out = collectFiles(resolved.abs, [], TOOL_LIMITS.maxEntries);
+      return { ok: true, entries: out.slice(0, TOOL_LIMITS.maxEntries).sort() };
+    },
+  };
+
+  function collectFiles(dir: string, out: string[], limit: number): string[] {
+    if (out.length >= limit) return out;
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const e of entries) {
+      if (out.length >= limit) break;
+      if (isHidden(e.name, roots)) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        collectFiles(full, out, limit);
+      } else if (e.isFile()) {
+        out.push(full);
+      }
+    }
+    return out;
+  }
+
+  function isHidden(name: string, scopes: string[]): boolean {
+    if (name !== ".git" && name !== "node_modules") return false;
+    // Explicit scope: the approved root itself is the hidden directory.
+    for (const scope of scopes) {
+      if (basename(realpathSync(scope)) === name) return false;
+    }
+    return true;
+  }
+
+  return [readTool, grepTool, lsTool, findTool];
+}
+
+export { resolveScoped };

package/src/submit-tool.ts

@@ -0,0 +1,135 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  type DiffResult,
+  type EvidenceResult,
+  validateDiffResult,
+  validateEvidenceResult,
+} from "./contracts.ts";
+
+const evidenceSchema = 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 diffSchema = Type.Object({
+  id: Type.String(),
+  role: Type.String(),
+  kind: Type.Literal("diff"),
+  taskId: Type.String(),
+  phase: Type.String(),
+  summary: Type.String(),
+  diff: Type.String(),
+  expectedVerification: Type.String(),
+  risks: Type.Array(Type.String()),
+  nextStep: Type.String(),
+  contractCompliant: Type.Literal(true),
+});
+
+export type FinalCategory =
+  | "no-final-assistant"
+  | "text-only"
+  | "mixed"
+  | "multiple-submit"
+  | "single-submit-only";
+
+export interface IdentityOutcome {
+  request: boolean;
+  role: boolean;
+  task: boolean;
+  phase: boolean;
+}
+
+export interface SubmitClassification {
+  finalCategory: FinalCategory;
+  attempts: number;
+  schema: "valid" | "invalid";
+  identity: IdentityOutcome;
+}
+
+export function createSubmitTool(input: {
+  requestId: string;
+  role: string;
+  phase: string;
+  output: "evidence" | "diff";
+}) {
+  let submitted: EvidenceResult | DiffResult | undefined;
+  let attempts = 0;
+  let schema: "valid" | "invalid" = "invalid";
+  const identity: IdentityOutcome = {
+    request: true,
+    role: true,
+    task: true,
+    phase: true,
+  };
+
+  const tool = defineTool({
+    name: "abel_submit_result",
+    label: "Submit Abel Result",
+    description:
+      "Submit the one final structured Abel evidence or complete unified-diff result.",
+    executionMode: "sequential",
+    parameters: input.output === "evidence" ? evidenceSchema : diffSchema,
+    async execute(_toolCallId, params) {
+      attempts++;
+      const value = params as unknown as Record<string, unknown>;
+      if (value === null || typeof value !== "object") {
+        identity.request = false;
+        identity.role = false;
+        identity.task = false;
+        identity.phase = false;
+        schema = "invalid";
+        throw new Error("submitted result is not an object");
+      }
+      if (value.id !== input.requestId) identity.request = false;
+      if (value.role !== input.role) identity.role = false;
+      if (input.output === "diff") {
+        if (value.taskId !== input.requestId) identity.task = false;
+        if (value.phase !== input.phase) identity.phase = false;
+      }
+      const validation =
+        input.output === "evidence"
+          ? validateEvidenceResult(value)
+          : validateDiffResult(value);
+      schema = validation.ok ? "valid" : "invalid";
+      const matches =
+        identity.request && identity.role && identity.task && identity.phase;
+      if (!validation.ok || !matches) {
+        throw new Error(
+          validation.reason ?? "submitted result identity does not match",
+        );
+      }
+      if (submitted) throw new Error("duplicate structural submission");
+      submitted = structuredClone(value) as unknown as
+        | EvidenceResult
+        | DiffResult;
+      return {
+        content: [{ type: "text" as const, text: "Abel result accepted." }],
+        details: { accepted: true },
+        terminate: true,
+      };
+    },
+  });
+
+  return {
+    tool,
+    getResult: () => submitted,
+    getAttempts: () => attempts,
+    getSchema: () => schema,
+    getIdentity: () => ({ ...identity }),
+  };
+}

package/src/worker.ts

@@ -0,0 +1,119 @@
+// Process-local logical Worker registry for private orchestration. A Worker
+// is pinned by the first accepted phase: logical ID, stage, role, the
+// provider/model/API/thinking identity, and the approved non-snapshot
+// contract. Later accepted Red/Green/optional Refactor phases receive fresh
+// snapshots and fresh phase-local auth for the SAME pinned identity. A failed
+// phase may be mechanically redispatched exactly once when its canonical
+// request is identical apart from refreshed snapshot hashes; a second failure
+// blocks that branch. No credential, transcript, or retry ledger is retained.
+
+import type { RequestEnvelope } from "./contracts.ts";
+
+export interface WorkerContract {
+  stage: string;
+  role: string;
+  id: string;
+  objective: string;
+  roots: string[];
+  agents: string;
+  contractText: string;
+  read: string[];
+  write: string[];
+  conflicts: string[];
+  resources: string[];
+  verificationLock?: string;
+  output: string;
+}
+
+export interface LogicalWorker {
+  identity: string;
+  contract: WorkerContract;
+  redispatchUsed: boolean;
+}
+
+// Pins the semantic scope of a logical Worker, excluding the phase label so a
+// later Red/Green/Refactor phase is recognized as the same Worker.
+export function contractOf(envelope: RequestEnvelope): WorkerContract {
+  return {
+    stage: envelope.stage,
+    role: envelope.role,
+    id: envelope.id,
+    objective: envelope.objective,
+    roots: [...envelope.roots],
+    agents: envelope.context.agents,
+    contractText: envelope.context.contract,
+    read: [...envelope.declared.read],
+    write: [...envelope.declared.write],
+    conflicts: [...envelope.declared.conflicts],
+    resources: [...envelope.declared.resources],
+    verificationLock: envelope.declared.verificationLock,
+    output: envelope.output,
+  };
+}
+
+export function sameContract(a: WorkerContract, b: WorkerContract): boolean {
+  if (
+    a.stage !== b.stage ||
+    a.role !== b.role ||
+    a.id !== b.id ||
+    a.objective !== b.objective ||
+    a.agents !== b.agents ||
+    a.contractText !== b.contractText ||
+    a.output !== b.output ||
+    a.verificationLock !== b.verificationLock
+  )
+    return false;
+  return (
+    arrayEqual(a.roots, b.roots) &&
+    arrayEqual(a.read, b.read) &&
+    arrayEqual(a.write, b.write) &&
+    arrayEqual(a.conflicts, b.conflicts) &&
+    arrayEqual(a.resources, b.resources)
+  );
+}
+
+function arrayEqual(a: string[], b: string[]): boolean {
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+// Stable provider/model/API/thinking identity fingerprint for a phase. Each
+// child attempt re-derives it while the phase-local auth boundary is called
+// anew, so the identity stays pinned across fresh phases.
+export function workerIdentity(model: {
+  provider?: unknown;
+  baseUrl?: unknown;
+  id?: unknown;
+  name?: unknown;
+}): string {
+  const parts: string[] = [`p:${String(model.provider ?? "")}`];
+  if (model.baseUrl !== undefined) parts.push(`u:${String(model.baseUrl)}`);
+  if (typeof model.id === "string") parts.push(`id:${model.id}`);
+  if (typeof model.name === "string") parts.push(`n:${model.name}`);
+  return parts.join("|");
+}
+
+export class WorkerRegistry {
+  private readonly workers = new Map<string, LogicalWorker>();
+
+  has(id: string): boolean {
+    return this.workers.has(id);
+  }
+
+  get(id: string): LogicalWorker | undefined {
+    return this.workers.get(id);
+  }
+
+  pin(contract: WorkerContract, identity: string): LogicalWorker {
+    const worker: LogicalWorker = {
+      identity,
+      contract,
+      redispatchUsed: false,
+    };
+    this.workers.set(contract.id, worker);
+    return worker;
+  }
+
+  clear(): void {
+    this.workers.clear();
+  }
+}