@abelxiaoxing/cadence 1.0.0

package/src/child-session.ts

@@ -0,0 +1,253 @@
+import type { Model, Usage } from "@earendil-works/pi-ai";
+import {
+  createAgentSession,
+  defineTool,
+  type ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { DiffResult, EvidenceResult } from "./contracts.ts";
+import { EmptyResourceLoader } from "./empty-resource-loader.ts";
+import { createScopedTools } from "./scoped-tools.ts";
+import {
+  createSubmitTool,
+  type FinalCategory,
+  type SubmitClassification,
+} from "./submit-tool.ts";
+
+const ZERO_USAGE: Usage = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+
+export class UsageAggregator {
+  private readonly ids = new Set<string>();
+  private usage: Usage = structuredClone(ZERO_USAGE);
+  add(id: string, value: Usage): boolean {
+    if (this.ids.has(id)) return false;
+    this.ids.add(id);
+    this.usage = {
+      input: this.usage.input + value.input,
+      output: this.usage.output + value.output,
+      cacheRead: this.usage.cacheRead + value.cacheRead,
+      cacheWrite: this.usage.cacheWrite + value.cacheWrite,
+      totalTokens: this.usage.totalTokens + value.totalTokens,
+      cost: {
+        input: this.usage.cost.input + value.cost.input,
+        output: this.usage.cost.output + value.cost.output,
+        cacheRead: this.usage.cost.cacheRead + value.cost.cacheRead,
+        cacheWrite: this.usage.cost.cacheWrite + value.cost.cacheWrite,
+        total: this.usage.cost.total + value.cost.total,
+      },
+    };
+    return true;
+  }
+  total(): Usage {
+    return structuredClone(this.usage);
+  }
+}
+
+function wrapScopedTools(roots: string[]) {
+  const order = ["read", "grep", "find", "ls"];
+  return createScopedTools({ roots })
+    .sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name))
+    .map((scoped) =>
+      defineTool({
+        name: scoped.name,
+        label: scoped.name,
+        description: scoped.description,
+        parameters:
+          scoped.name === "grep"
+            ? Type.Object({ path: Type.String(), pattern: Type.String() })
+            : Type.Object({ path: Type.String() }),
+        async execute(_id, params) {
+          const result = await scoped.execute(
+            params as Record<string, unknown>,
+          );
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(result) }],
+            details: result,
+          };
+        },
+      }),
+    );
+}
+
+export async function runChildSession(input: {
+  cwd: string;
+  modelRuntime: ModelRuntime;
+  model: Model<string>;
+  systemPrompt: string;
+  requestId: string;
+  role: string;
+  phase?: string;
+  output: "evidence" | "diff";
+  roots: string[];
+  timeoutMs: number;
+}): Promise<
+  | {
+      ok: true;
+      result: EvidenceResult | DiffResult;
+      toolNames: string[];
+      submitCount: number;
+      disposeCount: number;
+      usage: Usage;
+      classification: SubmitClassification;
+    }
+  | {
+      ok: false;
+      error: string;
+      disposeCount: number;
+      classification: SubmitClassification;
+    }
+> {
+  const submit = createSubmitTool({
+    requestId: input.requestId,
+    role: input.role,
+    phase: input.phase ?? "red",
+    output: input.output,
+  });
+  const readTools = wrapScopedTools(input.roots);
+  const customTools = [...readTools, submit.tool];
+  const toolNames = customTools.map((tool) => tool.name);
+  let disposeCount = 0;
+  const usage = new UsageAggregator();
+  const abort = new AbortController();
+  const timer = setTimeout(
+    () => abort.abort(new Error("child phase timeout")),
+    input.timeoutMs,
+  );
+  let session:
+    | Awaited<ReturnType<typeof createAgentSession>>["session"]
+    | undefined;
+  let unsubscribe: (() => void) | undefined;
+  const disposeOnce = () => {
+    if (session) {
+      session.dispose();
+      disposeCount++;
+      session = undefined;
+    }
+  };
+  const classifySession = (): SubmitClassification => {
+    const assistants =
+      session?.messages.filter((m) => m.role === "assistant") ?? [];
+    const last = assistants.at(-1);
+    let finalCategory: FinalCategory;
+    if (!last) {
+      finalCategory = "no-final-assistant";
+    } else if (
+      last.content.length === 1 &&
+      last.content[0].type === "toolCall" &&
+      last.content[0].name === "abel_submit_result"
+    ) {
+      finalCategory =
+        submit.getAttempts() > 1 ? "multiple-submit" : "single-submit-only";
+    } else if (last.content.length === 1 && last.content[0].type === "text") {
+      finalCategory = "text-only";
+    } else {
+      finalCategory = "mixed";
+    }
+    return {
+      finalCategory,
+      attempts: submit.getAttempts(),
+      schema: submit.getSchema(),
+      identity: submit.getIdentity(),
+    };
+  };
+  try {
+    ({ session } = await createAgentSession({
+      cwd: input.cwd,
+      modelRuntime: input.modelRuntime,
+      model: input.model,
+      thinkingLevel: "off",
+      tools: toolNames,
+      customTools,
+      resourceLoader: new EmptyResourceLoader(input.systemPrompt),
+      sessionManager: SessionManager.inMemory(input.cwd),
+      settingsManager: SettingsManager.inMemory({
+        compaction: { enabled: false },
+        retry: { enabled: false, maxRetries: 0, provider: { maxRetries: 0 } },
+      }),
+    }));
+    unsubscribe = session.subscribe((event) => {
+      if (event.type === "message_end" && event.message.role === "assistant") {
+        usage.add(
+          `${event.message.provider}:${event.message.model}:${event.message.timestamp}`,
+          event.message.usage,
+        );
+      }
+    });
+    const onAbort = () => void session?.abort();
+    abort.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+      await Promise.race([
+        session.prompt(input.systemPrompt, { expandPromptTemplates: false }),
+        new Promise<never>((_, reject) =>
+          abort.signal.addEventListener(
+            "abort",
+            () => reject(abort.signal.reason),
+            { once: true },
+          ),
+        ),
+      ]);
+    } finally {
+      abort.signal.removeEventListener("abort", onAbort);
+    }
+    const result = submit.getResult();
+    const attempts = submit.getAttempts();
+    const classification = classifySession();
+    if (!result || attempts !== 1) {
+      disposeOnce();
+      return {
+        ok: false,
+        error: "child did not retain exactly one structural submission",
+        disposeCount,
+        classification,
+      };
+    }
+    const assistants = session.messages.filter((m) => m.role === "assistant");
+    const final = assistants.at(-1);
+    if (
+      !final ||
+      final.role !== "assistant" ||
+      final.content.length !== 1 ||
+      final.content[0]?.type !== "toolCall" ||
+      final.content[0]?.name !== "abel_submit_result"
+    ) {
+      disposeOnce();
+      return {
+        ok: false,
+        error: "final assistant message is not one structural submit",
+        disposeCount,
+        classification,
+      };
+    }
+    disposeOnce();
+    return {
+      ok: true,
+      result,
+      toolNames,
+      submitCount: attempts,
+      disposeCount,
+      usage: usage.total(),
+      classification,
+    };
+  } catch (error) {
+    disposeOnce();
+    return {
+      ok: false,
+      error: (error as Error).message,
+      disposeCount,
+      classification: classifySession(),
+    };
+  } finally {
+    clearTimeout(timer);
+    unsubscribe?.();
+    disposeOnce();
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,375 @@
+// Strict request/result contracts for the private orchestration kernel.
+// Structural validation only; no runtime dependency on a schema library.
+export const STAGES = [
+  "abel-design",
+  "abel-implement",
+  "abel-diagnose",
+] as const;
+export const ROLES = [
+  "design-explorer",
+  "contract-reviewer",
+  "implementation-worker",
+  "diagnosis-worker",
+] as const;
+export const ACTIONS = ["run", "apply", "discard", "cancel", "finish"] as const;
+export const OUTPUT_KINDS = ["evidence", "diff"] as const;
+export const PHASES = [
+  "evidence",
+  "red",
+  "green",
+  "refactor",
+  "review",
+] as const;
+
+export const LIMITS = {
+  maxActiveChildSessions: 4,
+  maxRequestsPerBatch: 8,
+  maxEnvelopeBytes: 64 * 1024,
+  phaseTimeoutMs: 20 * 60 * 1000,
+  maxCompleteResultBytes: 64 * 1024,
+} as const;
+
+const NONCANONICAL = /(^|\/)\.\.(\/|$)|(^|\/)\/|^\//;
+
+export interface RequestEnvelope {
+  stage: string;
+  role: string;
+  id: string;
+  phase: string;
+  objective: string;
+  roots: string[];
+  context: { agents: string; contract: string };
+  declared: {
+    read: string[];
+    write: string[];
+    conflicts: string[];
+    resources: string[];
+    verificationLock?: string;
+  };
+  output: string;
+  snapshot?: unknown;
+}
+
+export function isValidRelativePath(p: unknown): p is string {
+  return (
+    typeof p === "string" &&
+    p.length > 0 &&
+    p.length <= 512 &&
+    !NONCANONICAL.test(p) &&
+    !p.startsWith("/") &&
+    !p.includes("..") &&
+    !p.includes("\\") &&
+    !p.includes("\u0000")
+  );
+}
+
+export function validateRequestEnvelope(
+  value: unknown,
+): { ok: true; value: RequestEnvelope } | { ok: false; reason: string } {
+  if (value === null || typeof value !== "object") {
+    return { ok: false, reason: "missing request envelope" };
+  }
+  const env = value as Record<string, unknown>;
+  for (const field of [
+    "stage",
+    "role",
+    "id",
+    "phase",
+    "objective",
+    "roots",
+    "context",
+    "declared",
+    "output",
+  ]) {
+    if (env[field] === undefined) {
+      return { ok: false, reason: `missing required field: ${field}` };
+    }
+  }
+  if (!(STAGES as readonly string[]).includes(env.stage as string)) {
+    return { ok: false, reason: `unknown stage: ${String(env.stage)}` };
+  }
+  if (!(ROLES as readonly string[]).includes(env.role as string)) {
+    return { ok: false, reason: `unknown role: ${String(env.role)}` };
+  }
+  if (
+    typeof env.id !== "string" ||
+    env.id.length === 0 ||
+    env.id.length > 128
+  ) {
+    return { ok: false, reason: "invalid request id" };
+  }
+  if (
+    typeof env.phase !== "string" ||
+    !(PHASES as readonly string[]).includes(env.phase)
+  ) {
+    return { ok: false, reason: `invalid phase: ${String(env.phase)}` };
+  }
+  const serialized = JSON.stringify(env);
+  if (serialized.length > LIMITS.maxEnvelopeBytes) {
+    return {
+      ok: false,
+      reason: `request envelope exceeds ${LIMITS.maxEnvelopeBytes / 1024} KiB`,
+    };
+  }
+  if (
+    typeof env.objective !== "string" ||
+    env.objective.length === 0 ||
+    env.objective.length > 4096
+  ) {
+    return { ok: false, reason: "invalid objective" };
+  }
+  if (
+    !Array.isArray(env.roots) ||
+    env.roots.length === 0 ||
+    !env.roots.every(isValidRelativePath)
+  ) {
+    return { ok: false, reason: "invalid path roots" };
+  }
+  const ctx = env.context as Record<string, unknown>;
+  if (
+    ctx === null ||
+    typeof ctx !== "object" ||
+    typeof ctx.agents !== "string" ||
+    typeof ctx.contract !== "string"
+  ) {
+    return { ok: false, reason: "invalid context" };
+  }
+  const decl = env.declared as Record<string, unknown>;
+  if (decl === null || typeof decl !== "object") {
+    return { ok: false, reason: "invalid declared sets" };
+  }
+  for (const key of ["read", "write", "conflicts", "resources"]) {
+    if (
+      !Array.isArray(decl[key]) ||
+      !(decl[key] as unknown[]).every(isValidRelativePath)
+    ) {
+      return { ok: false, reason: `invalid declared ${key} set` };
+    }
+  }
+  if (
+    decl.verificationLock !== undefined &&
+    !isValidRelativePath(decl.verificationLock)
+  ) {
+    return { ok: false, reason: "invalid verification lock" };
+  }
+  if (!(OUTPUT_KINDS as readonly string[]).includes(env.output as string)) {
+    return { ok: false, reason: `invalid output kind: ${String(env.output)}` };
+  }
+  if (
+    env.snapshot !== undefined &&
+    (env.snapshot === null || typeof env.snapshot !== "object")
+  ) {
+    return { ok: false, reason: "invalid snapshot" };
+  }
+  return { ok: true, value: env as unknown as RequestEnvelope };
+}
+
+/** Extract proposed write paths from ordinary unified diff header pairs. */
+export function diffWritePaths(diffText: string): {
+  paths: string[];
+  kind: 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;
+  for (const line of lines) {
+    if (/^old mode /.test(line) || /^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}`);
+      }
+      continue;
+    }
+    if (line.startsWith("--- ") && !line.startsWith("--- /dev/null")) {
+      pendingOld = parseHeaderPath(line.slice(4));
+      continue;
+    }
+    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");
+        }
+      }
+      pendingOld = null;
+      if (paths.includes(target)) throw new Error("duplicate diff targets");
+      paths.push(target);
+      sawHeader = true;
+    }
+  }
+  if (!sawHeader || paths.length === 0) {
+    throw new Error("diff has no ordinary text headers");
+  }
+  return { paths, kind: "text" };
+}
+
+function parseHeaderPath(header: string): 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}`);
+  }
+  return path;
+}
+
+export interface EvidenceResult {
+  id: string;
+  role: string;
+  kind: "evidence";
+  conclusions: string[];
+  citations: { path: string; lines: string }[];
+  constraints: string[];
+  dependencies: string[];
+  risks: string[];
+  blockingQuestions: string[];
+  hints: { writeSet: string[]; verification: string; agentsImpact: string };
+}
+
+export interface DiffResult {
+  id: string;
+  role: string;
+  kind: "diff";
+  taskId: string;
+  phase: string;
+  summary: string;
+  diff: string;
+  expectedVerification: string;
+  risks: string[];
+  nextStep: string;
+  contractCompliant: boolean;
+}
+
+export function validateEvidenceResult(value: unknown): {
+  ok: boolean;
+  reason?: string;
+} {
+  if (value === null || typeof value !== "object")
+    return { ok: false, reason: "missing result" };
+  const r = value as Record<string, unknown>;
+  if (r.kind !== "evidence") return { ok: false, reason: "wrong result kind" };
+  for (const field of [
+    "id",
+    "role",
+    "conclusions",
+    "citations",
+    "blockingQuestions",
+  ]) {
+    if (r[field] === undefined)
+      return { ok: false, reason: `missing field: ${field}` };
+  }
+  if (typeof r.id !== "string" || typeof r.role !== "string")
+    return { ok: false, reason: "invalid identity" };
+  if (!(ROLES as readonly string[]).includes(r.role))
+    return { ok: false, reason: "unknown role" };
+  const serialized = JSON.stringify(r);
+  if (serialized.length > LIMITS.maxCompleteResultBytes) {
+    return {
+      ok: false,
+      reason: `result exceeds ${LIMITS.maxCompleteResultBytes} bytes`,
+    };
+  }
+  return { ok: true };
+}
+
+export function validateDiffResult(value: unknown): {
+  ok: boolean;
+  reason?: string;
+  paths?: string[];
+} {
+  if (value === null || typeof value !== "object")
+    return { ok: false, reason: "missing result" };
+  const r = value as Record<string, unknown>;
+  if (r.kind !== "diff") return { ok: false, reason: "wrong result kind" };
+  for (const field of [
+    "id",
+    "role",
+    "taskId",
+    "phase",
+    "summary",
+    "diff",
+    "expectedVerification",
+    "risks",
+    "nextStep",
+    "contractCompliant",
+  ]) {
+    if (r[field] === undefined)
+      return { ok: false, reason: `missing field: ${field}` };
+  }
+  if (
+    typeof r.id !== "string" ||
+    r.id.length === 0 ||
+    r.id.length > 128 ||
+    typeof r.role !== "string" ||
+    r.role.length === 0 ||
+    typeof r.taskId !== "string" ||
+    r.taskId.length === 0
+  ) {
+    return { ok: false, reason: "invalid identity" };
+  }
+  if (!(ROLES as readonly string[]).includes(r.role))
+    return { ok: false, reason: "unknown role" };
+  if (
+    typeof r.phase !== "string" ||
+    !(PHASES as readonly string[]).includes(r.phase)
+  ) {
+    return { ok: false, reason: "invalid phase" };
+  }
+  if (
+    typeof r.summary !== "string" ||
+    r.summary.length === 0 ||
+    typeof r.expectedVerification !== "string" ||
+    r.expectedVerification.length === 0 ||
+    typeof r.nextStep !== "string" ||
+    r.nextStep.length === 0
+  ) {
+    return { ok: false, reason: "invalid diff result text" };
+  }
+  if (
+    !Array.isArray(r.risks) ||
+    !(r.risks as unknown[]).every((x) => typeof x === "string")
+  ) {
+    return { ok: false, reason: "invalid risks" };
+  }
+  if (r.contractCompliant !== true)
+    return { ok: false, reason: "contract compliance not affirmed" };
+  let paths: string[];
+  try {
+    paths = diffWritePaths(r.diff as string).paths;
+  } catch (err) {
+    return { ok: false, reason: `invalid diff: ${(err as Error).message}` };
+  }
+  const serialized = JSON.stringify(r);
+  if (serialized.length > LIMITS.maxCompleteResultBytes) {
+    return {
+      ok: false,
+      reason: `result exceeds ${LIMITS.maxCompleteResultBytes} bytes`,
+    };
+  }
+  return { ok: true, paths };
+}

package/src/drain.ts

@@ -0,0 +1,20 @@
+// Unified idempotent drain (P-006). One drain step closes admission, erases
+// retained diffs and Worker metadata, and removes only the dispatcher
+// activation. No private files are created; child usage is returned exactly
+// once by the child-session dispose path.
+import type { Activation } from "./activation.ts";
+import type { ResultStore } from "./result-store.ts";
+import type { WorkerRegistry } from "./worker.ts";
+
+export interface DrainTargets {
+  results: ResultStore;
+  registry: WorkerRegistry;
+  activation: Activation;
+}
+
+/** Close admission, erase retained diffs and Worker metadata, deactivate. */
+export function drainStage(targets: DrainTargets): void {
+  targets.results.clear();
+  targets.registry.clear();
+  targets.activation.drain();
+}

package/src/empty-resource-loader.ts

@@ -0,0 +1,38 @@
+import {
+  createExtensionRuntime,
+  type ResourceLoader,
+} from "@earendil-works/pi-coding-agent";
+
+/** ResourceLoader that discovers nothing and supplies only the approved prompt. */
+export class EmptyResourceLoader implements ResourceLoader {
+  constructor(private readonly systemPrompt?: string) {}
+  getExtensions() {
+    return { extensions: [], errors: [], runtime: createExtensionRuntime() };
+  }
+  getSkills() {
+    return { skills: [], diagnostics: [] };
+  }
+  getPrompts() {
+    return { prompts: [], diagnostics: [] };
+  }
+  getThemes() {
+    return { themes: [], diagnostics: [] };
+  }
+  getAgentsFiles() {
+    return { agentsFiles: [] };
+  }
+  getSystemPrompt() {
+    return this.systemPrompt;
+  }
+  getSystemPromptSource() {
+    return undefined;
+  }
+  getAppendSystemPrompt() {
+    return [];
+  }
+  getAppendSystemPromptSources() {
+    return [];
+  }
+  extendResources() {}
+  async reload() {}
+}