@abelxiaoxing/cadence 1.0.0

package/src/runtime.ts

@@ -0,0 +1,305 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Activation, type ActivationState } from "./activation.ts";
+import { loadAgentDefinitions } from "./agent-registry.ts";
+import { runChildSession } from "./child-session.ts";
+import {
+  ACTIONS,
+  type DiffResult,
+  LIMITS,
+  type RequestEnvelope,
+  validateRequestEnvelope,
+} from "./contracts.ts";
+import { drainStage } from "./drain.ts";
+import { type Bound, mergeBounds } from "./file-snapshot.ts";
+import { runtimeFromContext } from "./parent-provider.ts";
+import { applyRetainedPatch } from "./patch.ts";
+import { ResultStore } from "./result-store.ts";
+import {
+  contractOf,
+  sameContract,
+  WorkerRegistry,
+  workerIdentity,
+} from "./worker.ts";
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+function isSafeBound(snapshot: unknown): snapshot is Bound {
+  if (
+    typeof snapshot !== "object" ||
+    snapshot === null ||
+    Array.isArray(snapshot)
+  )
+    return false;
+  for (const [path, value] of Object.entries(
+    snapshot as Record<string, unknown>,
+  )) {
+    if (
+      !path ||
+      path.startsWith("/") ||
+      path === "." ||
+      path === ".." ||
+      path.includes("/../") ||
+      path.endsWith("/..") ||
+      path.includes("\\")
+    )
+      return false;
+    if (typeof value !== "object" || value === null) return false;
+    const entry = value as Record<string, unknown>;
+    if (entry.kind === "file") {
+      if (
+        typeof entry.sha256 !== "string" ||
+        !SHA256_HEX.test(entry.sha256) ||
+        typeof entry.bytes !== "number" ||
+        !Number.isSafeInteger(entry.bytes) ||
+        entry.bytes < 0
+      )
+        return false;
+    } else if (entry.kind === "dir") {
+      if (
+        typeof entry.manifest !== "string" ||
+        !SHA256_HEX.test(entry.manifest)
+      )
+        return false;
+    } else if (entry.kind === "absent") {
+      if (entry.absent !== true) return false;
+    } else {
+      return false;
+    }
+  }
+  return true;
+}
+
+export type DispatchResult =
+  | {
+      ok: true;
+      action: string;
+      result?: unknown;
+      resultId?: string;
+      usage?: unknown;
+    }
+  | { ok: false; notReady?: true; error: string };
+
+export interface ApplyResult {
+  targets: string[];
+  checkExitCode: 0;
+  applyExitCode: 0;
+  sequence?: number;
+}
+
+export interface RuntimeOptions {
+  activation?: Activation;
+}
+
+type RunContext = Pick<ExtensionContext, "cwd" | "model" | "modelRegistry">;
+
+export class Runtime {
+  readonly activation: Activation;
+  readonly limits = LIMITS;
+  readonly results = new ResultStore();
+  private applyTail: Promise<void> = Promise.resolve();
+  private applySeq = 0;
+  private readonly registry = new WorkerRegistry();
+
+  constructor(opts: RuntimeOptions = {}) {
+    this.activation = opts.activation ?? new Activation();
+  }
+
+  async execute(
+    action: string,
+    params: { request?: unknown; resultId?: string },
+    ctx?: RunContext,
+  ): Promise<DispatchResult> {
+    if (!(ACTIONS as readonly string[]).includes(action)) {
+      return { ok: false, error: `unknown action: ${String(action)}` };
+    }
+    if (!this.activation.isActive()) {
+      return { ok: false, notReady: true, error: "dispatcher is not active" };
+    }
+    if (action === "run") return this.run(params.request, ctx);
+    if (action === "apply") {
+      if (!ctx || !params.resultId)
+        return { ok: false, error: "apply requires context and resultId" };
+      return this.enqueueApply(ctx.cwd, params.resultId);
+    }
+    if (action === "discard") {
+      if (!params.resultId)
+        return { ok: false, error: "discard requires resultId" };
+      return this.results.discard(params.resultId)
+        ? { ok: true, action }
+        : { ok: false, error: "retained result not found" };
+    }
+    if (action === "cancel") return { ok: true, action };
+    drainStage({
+      results: this.results,
+      registry: this.registry,
+      activation: this.activation,
+    });
+    return { ok: true, action: "finish" };
+  }
+
+  private enqueueApply(root: string, id: string): Promise<DispatchResult> {
+    const run = this.applyTail.then(
+      () => applyRetainedPatch({ root, id, store: this.results }),
+      () => applyRetainedPatch({ root, id, store: this.results }),
+    );
+    this.applyTail = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    const seq = ++this.applySeq;
+    return run.then(
+      (result) =>
+        result.ok
+          ? { ok: true, action: "apply", result: { ...result, sequence: seq } }
+          : result,
+      (error) => ({ ok: false, error: (error as Error).message }),
+    );
+  }
+
+  private async dispatchChild(
+    agent: { role: string; content: string },
+    envelope: RequestEnvelope,
+    ctx: RunContext,
+  ): Promise<DispatchResult> {
+    let phase: Awaited<ReturnType<typeof runtimeFromContext>>;
+    try {
+      phase = await runtimeFromContext(ctx);
+    } catch (error) {
+      return { ok: false, error: (error as Error).message };
+    }
+    const roots = envelope.roots.map(
+      (root) => new URL(root, `file://${ctx.cwd}/`).pathname,
+    );
+    const systemPrompt = [
+      agent.content,
+      envelope.objective,
+      envelope.context.agents,
+      envelope.context.contract,
+    ].join("\n\n");
+    const child = await runChildSession({
+      cwd: ctx.cwd,
+      modelRuntime: phase.modelRuntime,
+      model: phase.model,
+      systemPrompt,
+      requestId: envelope.id,
+      role: envelope.role,
+      phase: envelope.phase,
+      output: envelope.output as "evidence" | "diff",
+      roots,
+      timeoutMs: LIMITS.phaseTimeoutMs,
+    });
+    if (!child.ok) return child;
+    if (envelope.output === "evidence") {
+      return {
+        ok: true,
+        action: "run",
+        result: child.result,
+        usage: child.usage,
+      };
+    }
+    const diff = child.result as DiffResult;
+    const resultId = this.results.retain({
+      diff: diff.diff,
+      writeSet: envelope.declared.write,
+      root: ctx.cwd,
+    });
+    if (isSafeBound(envelope.snapshot)) {
+      const retained = this.results.get(resultId);
+      if (retained) {
+        retained.snapshot = mergeBounds(retained.snapshot, envelope.snapshot);
+      }
+    }
+    return {
+      ok: true,
+      action: "run",
+      result: diff,
+      resultId,
+      usage: child.usage,
+    };
+  }
+
+  private async run(
+    request: unknown,
+    ctx?: RunContext,
+  ): Promise<DispatchResult> {
+    if (!ctx) return { ok: false, error: "run requires extension context" };
+    const validation = validateRequestEnvelope(request);
+    if (!validation.ok) return { ok: false, error: validation.reason };
+    const envelope = validation.value;
+    const agent = loadAgentDefinitions().find(
+      (item) => item.role === envelope.role,
+    );
+    if (!agent) return { ok: false, error: "package Agent role not found" };
+    if (!ctx.model)
+      return { ok: false, error: "run requires a model identity" };
+    const identity = workerIdentity(ctx.model);
+    const contract = contractOf(envelope);
+    const existing = this.registry.get(envelope.id);
+    if (existing) {
+      if (existing.identity !== identity) {
+        return {
+          ok: false,
+          error:
+            "blocked: logical Worker pinned provider/model identity differs",
+        };
+      }
+      if (!sameContract(existing.contract, contract)) {
+        return {
+          ok: false,
+          error:
+            "blocked: logical Worker contract changed for a recovery scope",
+        };
+      }
+      if (existing.redispatchUsed) {
+        return {
+          ok: false,
+          error: "blocked: mechanical redispatch is already exhausted",
+        };
+      }
+    } else {
+      this.registry.pin(contract, identity);
+    }
+    const pinned = this.registry.get(envelope.id);
+    const first = await this.dispatchChild(agent, envelope, ctx);
+    if (first.ok) {
+      if (pinned) pinned.redispatchUsed = false;
+      return first;
+    }
+    if (pinned?.redispatchUsed) {
+      return {
+        ok: false,
+        error: "blocked: mechanical redispatch failed and is exhausted",
+      };
+    }
+    if (!pinned) {
+      return { ok: false, error: "blocked: logical Worker is not pinned" };
+    }
+    pinned.redispatchUsed = true;
+    const second = await this.dispatchChild(agent, envelope, ctx);
+    if (!second.ok) {
+      return {
+        ok: false,
+        error: "blocked: identical mechanical redispatch failed again",
+      };
+    }
+    return second;
+  }
+
+  validateRequest(
+    envelope: unknown,
+  ): { ok: true; value: RequestEnvelope } | { ok: false; reason: string } {
+    return validateRequestEnvelope(envelope);
+  }
+
+  drain(): void {
+    drainStage({
+      results: this.results,
+      registry: this.registry,
+      activation: this.activation,
+    });
+  }
+
+  get state(): ActivationState {
+    return this.activation.state;
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,304 @@
+// Minimal in-memory scheduler for the private orchestration kernel.
+// FIFO DAG-ready admission with one global active limit, declared-set
+// declared serialization, batch cancellation, and at most one mechanical redispatch.
+import { LIMITS, type RequestEnvelope } from "./contracts.ts";
+
+export type TerminalStatus = "succeeded" | "failed" | "cancelled";
+
+export interface ScheduledRequest {
+  request: RequestEnvelope;
+  prerequisites: string[];
+  mechanicalRedispatch?: boolean;
+}
+
+export interface ScheduledOutcome<T = unknown> {
+  id: string;
+  status: TerminalStatus;
+  attempts: number;
+  value?: T;
+  error?: string;
+}
+
+export interface BatchHandle<T = unknown> {
+  batchId: string;
+  result(id: string): Promise<ScheduledOutcome<T>>;
+  done: Promise<ScheduledOutcome<T>[]>;
+}
+
+export interface SchedulerOptions<T = unknown> {
+  limit: number;
+  execute(
+    request: RequestEnvelope,
+    signal: AbortSignal,
+    attempt: number,
+  ): Promise<T>;
+}
+
+type EntryState = "queued" | "running" | TerminalStatus;
+
+interface Entry<T> {
+  request: RequestEnvelope;
+  prerequisites: string[];
+  mechanicalRedispatch: boolean;
+  state: EntryState;
+  attempts: number;
+  cancelRequested: boolean;
+  controller: AbortController | null;
+  resolve(outcome: ScheduledOutcome<T>): void;
+  promise: Promise<ScheduledOutcome<T>>;
+}
+
+function intersects(left: string[], right: string[]): boolean {
+  return left.some((path) => right.includes(path));
+}
+
+function conflictEdgeMatches(
+  conflicts: string[],
+  other: RequestEnvelope,
+): boolean {
+  return conflicts.some(
+    (edge) =>
+      edge === other.id ||
+      other.declared.read.includes(edge) ||
+      other.declared.write.includes(edge),
+  );
+}
+
+/** True when two declared envelopes cannot be active at the same time. */
+export function declarationsConflict(
+  left: RequestEnvelope,
+  right: RequestEnvelope,
+): boolean {
+  const a = left.declared;
+  const b = right.declared;
+  if (intersects(a.write, b.write)) return true;
+  if (intersects(a.write, b.read) || intersects(a.read, b.write)) return true;
+  if (conflictEdgeMatches(a.conflicts, right)) return true;
+  if (conflictEdgeMatches(b.conflicts, left)) return true;
+  if (intersects(a.resources, b.resources)) return true;
+  return (
+    a.verificationLock !== undefined &&
+    a.verificationLock === b.verificationLock
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+class Batch<T> {
+  readonly entries: Entry<T>[] = [];
+  readonly byId = new Map<string, Entry<T>>();
+
+  constructor(
+    readonly batchId: string,
+    requests: ScheduledRequest[],
+  ) {
+    for (const scheduled of requests) {
+      let resolve: (outcome: ScheduledOutcome<T>) => void = () => {};
+      const promise = new Promise<ScheduledOutcome<T>>((accept) => {
+        resolve = accept;
+      });
+      const entry: Entry<T> = {
+        request: scheduled.request,
+        prerequisites: [...scheduled.prerequisites],
+        mechanicalRedispatch: scheduled.mechanicalRedispatch === true,
+        state: "queued",
+        attempts: 0,
+        cancelRequested: false,
+        controller: null,
+        resolve,
+        promise,
+      };
+      this.entries.push(entry);
+      this.byId.set(entry.request.id, entry);
+    }
+  }
+}
+
+export class Scheduler<T> {
+  private readonly limit: number;
+  private readonly execute: SchedulerOptions<T>["execute"];
+  private readonly batches: Batch<T>[] = [];
+  private readonly active = new Set<Entry<T>>();
+
+  constructor(options: SchedulerOptions<T>) {
+    this.limit = Math.max(
+      1,
+      Math.min(options.limit, LIMITS.maxActiveChildSessions),
+    );
+    this.execute = options.execute;
+  }
+
+  schedule(batchId: string, requests: ScheduledRequest[]): BatchHandle<T> {
+    if (requests.length > LIMITS.maxRequestsPerBatch) {
+      throw new Error(
+        `batch ${batchId} exceeds ${LIMITS.maxRequestsPerBatch} requests`,
+      );
+    }
+    const batch = new Batch<T>(batchId, requests);
+    this.batches.push(batch);
+    for (const entry of batch.entries) {
+      const missing = entry.prerequisites.find((id) => !batch.byId.has(id));
+      if (missing !== undefined) {
+        this.settle(batch, entry, {
+          id: entry.request.id,
+          status: "cancelled",
+          attempts: 0,
+          error: `unknown prerequisite: ${missing}`,
+        });
+      }
+    }
+    this.pump();
+    return {
+      batchId,
+      result: (id: string) => {
+        const entry = batch.byId.get(id);
+        if (!entry) throw new Error(`unknown scheduled request: ${id}`);
+        return entry.promise;
+      },
+      done: Promise.all(batch.entries.map((entry) => entry.promise)),
+    };
+  }
+
+  cancel(batchId: string): void {
+    const batch = this.batches.find(
+      (candidate) => candidate.batchId === batchId,
+    );
+    if (!batch) return;
+    for (const entry of batch.entries) {
+      if (entry.state === "queued") {
+        entry.cancelRequested = true;
+        this.settle(batch, entry, this.cancelOutcome(entry));
+      } else if (entry.state === "running") {
+        entry.cancelRequested = true;
+        entry.controller?.abort();
+      }
+    }
+    this.pump();
+  }
+
+  private pump(): void {
+    for (const batch of this.batches) {
+      for (const entry of batch.entries) {
+        if (this.active.size >= this.limit) return;
+        if (entry.state !== "queued") continue;
+        if (!this.prerequisitesSucceeded(batch, entry)) continue;
+        if (this.hasActiveConflict(entry)) continue;
+        this.start(batch, entry);
+      }
+    }
+  }
+
+  private prerequisitesSucceeded(batch: Batch<T>, entry: Entry<T>): boolean {
+    return entry.prerequisites.every(
+      (id) => batch.byId.get(id)?.state === "succeeded",
+    );
+  }
+
+  private hasActiveConflict(entry: Entry<T>): boolean {
+    for (const activeEntry of this.active) {
+      if (declarationsConflict(entry.request, activeEntry.request)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private start(batch: Batch<T>, entry: Entry<T>): void {
+    // Guarded start: a cancelled or settled queued closure never runs later.
+    if (entry.state !== "queued") return;
+    entry.state = "running";
+    entry.attempts += 1;
+    entry.controller = new AbortController();
+    this.active.add(entry);
+    const attempt = entry.attempts;
+    this.execute(entry.request, entry.controller.signal, attempt).then(
+      (value) => {
+        if (entry.cancelRequested) {
+          this.settleCancelled(batch, entry);
+          return;
+        }
+        this.settle(batch, entry, {
+          id: entry.request.id,
+          status: "succeeded",
+          attempts: entry.attempts,
+          value,
+        });
+      },
+      (error) => {
+        if (entry.cancelRequested) {
+          this.settleCancelled(batch, entry);
+          return;
+        }
+        if (entry.mechanicalRedispatch && attempt === 1) {
+          this.redispatch(batch, entry);
+          return;
+        }
+        this.settle(batch, entry, {
+          id: entry.request.id,
+          status: "failed",
+          attempts: entry.attempts,
+          error: errorMessage(error),
+        });
+      },
+    );
+  }
+
+  private redispatch(batch: Batch<T>, entry: Entry<T>): void {
+    // One identical mechanical redispatch in the retained active slot; the
+    // attempt becomes 2 and a further failure settles, so no third attempt.
+    entry.state = "queued";
+    entry.controller = null;
+    this.start(batch, entry);
+  }
+
+  private settleCancelled(batch: Batch<T>, entry: Entry<T>): void {
+    this.settle(batch, entry, this.cancelOutcome(entry));
+  }
+
+  private cancelOutcome(entry: Entry<T>): ScheduledOutcome<T> {
+    return {
+      id: entry.request.id,
+      status: "cancelled",
+      attempts: entry.attempts,
+      error: "batch cancelled",
+    };
+  }
+
+  private settle(
+    batch: Batch<T>,
+    entry: Entry<T>,
+    outcome: ScheduledOutcome<T>,
+  ): void {
+    // Every scheduled request reaches exactly one terminal state.
+    if (entry.state !== "queued" && entry.state !== "running") return;
+    entry.state = outcome.status;
+    this.active.delete(entry);
+    entry.controller = null;
+    entry.resolve(outcome);
+    if (outcome.status !== "succeeded") {
+      this.blockDependents(batch, entry.request.id, outcome.status);
+    }
+    this.pump();
+  }
+
+  private blockDependents(
+    batch: Batch<T>,
+    prerequisiteId: string,
+    status: TerminalStatus,
+  ): void {
+    // A dependent can never start after a prerequisite failure or cancel;
+    // independent siblings keep their own outcomes.
+    for (const dependent of batch.entries) {
+      if (dependent.state !== "queued") continue;
+      if (!dependent.prerequisites.includes(prerequisiteId)) continue;
+      this.settle(batch, dependent, {
+        id: dependent.request.id,
+        status: "cancelled",
+        attempts: dependent.attempts,
+        error: `blocked: prerequisite ${prerequisiteId} ${status}`,
+      });
+    }
+  }
+}