@abelxiaoxing/cadence 1.0.0 → 1.0.1

package/src/runtime.ts

@@ -14,6 +14,7 @@ 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 { Scheduler } from "./scheduler.ts";
 import {
   contractOf,
   sameContract,
@@ -23,6 +24,51 @@ import {
 
 const SHA256_HEX = /^[0-9a-f]{64}$/;
 
+function cancellationError(signal: AbortSignal): { ok: false; error: string } {
+  const reason = signal.reason;
+  return {
+    ok: false,
+    error:
+      reason instanceof Error
+        ? reason.message
+        : typeof reason === "string"
+          ? reason
+          : "child phase cancelled",
+  };
+}
+
+export type RunFailureKind = "failed" | "cancelled" | "timed-out";
+export type RuntimeFailureReason =
+  | "subagent failed"
+  | "subagent cancelled"
+  | "phase timed out";
+export type RuntimeActivityState =
+  | "queued"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "timed-out";
+
+export interface RuntimeActivityEvent {
+  state: RuntimeActivityState;
+  requestId: string;
+  role: string;
+  phase: string;
+  objective: string;
+  sequence: number;
+  failureReason?: RuntimeFailureReason;
+}
+
+export type RuntimeActivityObserver = (
+  event: RuntimeActivityEvent,
+) => void | Promise<void>;
+
+interface ScheduledRunResult {
+  dispatch: DispatchResult;
+  failureKind?: RunFailureKind;
+}
+
 function isSafeBound(snapshot: unknown): snapshot is Bound {
   if (
     typeof snapshot !== "object" ||
@@ -92,22 +138,53 @@ export interface RuntimeOptions {
 
 type RunContext = Pick<ExtensionContext, "cwd" | "model" | "modelRegistry">;
 
+interface StoredRunContext {
+  ctx: RunContext;
+  observer?: RuntimeActivityObserver;
+  sequence: number;
+  runningEmitted: boolean;
+  terminalEmitted: boolean;
+}
+
 export class Runtime {
   readonly activation: Activation;
   readonly limits = LIMITS;
   readonly results = new ResultStore();
   private applyTail: Promise<void> = Promise.resolve();
   private applySeq = 0;
+  private batchSeq = 0;
   private readonly registry = new WorkerRegistry();
+  private readonly runContexts = new WeakMap<
+    RequestEnvelope,
+    StoredRunContext
+  >();
+  private readonly scheduler: Scheduler<ScheduledRunResult>;
 
   constructor(opts: RuntimeOptions = {}) {
     this.activation = opts.activation ?? new Activation();
+    this.scheduler = new Scheduler({
+      limit: LIMITS.maxActiveChildSessions,
+      execute: async (request, signal) => {
+        const context = this.runContexts.get(request);
+        if (!context) throw new Error("scheduled run context is unavailable");
+        this.notify(request, context, "running");
+        const result = await this.runScheduled(request, context.ctx, signal);
+        return {
+          dispatch: result,
+          ...(result.failureKind === undefined
+            ? {}
+            : { failureKind: result.failureKind }),
+        };
+      },
+    });
   }
 
   async execute(
     action: string,
     params: { request?: unknown; resultId?: string },
     ctx?: RunContext,
+    signal?: AbortSignal,
+    observer?: RuntimeActivityObserver,
   ): Promise<DispatchResult> {
     if (!(ACTIONS as readonly string[]).includes(action)) {
       return { ok: false, error: `unknown action: ${String(action)}` };
@@ -115,7 +192,8 @@ export class Runtime {
     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 === "run")
+      return this.run(params.request, ctx, signal, observer);
     if (action === "apply") {
       if (!ctx || !params.resultId)
         return { ok: false, error: "apply requires context and resultId" };
@@ -128,12 +206,11 @@ export class Runtime {
         ? { 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,
-    });
+    if (action === "cancel") {
+      await this.scheduler.cancelAll();
+      return { ok: true, action };
+    }
+    await this.drain();
     return { ok: true, action: "finish" };
   }
 
@@ -160,13 +237,30 @@ export class Runtime {
     agent: { role: string; content: string },
     envelope: RequestEnvelope,
     ctx: RunContext,
-  ): Promise<DispatchResult> {
+    signal: AbortSignal,
+  ): Promise<DispatchResult & { failureKind?: RunFailureKind }> {
+    if (signal.aborted)
+      return {
+        ...cancellationError(signal),
+        failureKind: "cancelled",
+      };
     let phase: Awaited<ReturnType<typeof runtimeFromContext>>;
     try {
-      phase = await runtimeFromContext(ctx);
+      phase = await runtimeFromContext(ctx, signal);
     } catch (error) {
-      return { ok: false, error: (error as Error).message };
+      return {
+        ok: false,
+        error: signal.aborted
+          ? cancellationError(signal).error
+          : (error as Error).message,
+        failureKind: signal.aborted ? "cancelled" : "failed",
+      };
     }
+    if (signal.aborted)
+      return {
+        ...cancellationError(signal),
+        failureKind: "cancelled",
+      };
     const roots = envelope.roots.map(
       (root) => new URL(root, `file://${ctx.cwd}/`).pathname,
     );
@@ -187,8 +281,14 @@ export class Runtime {
       output: envelope.output as "evidence" | "diff",
       roots,
       timeoutMs: LIMITS.phaseTimeoutMs,
+      signal,
     });
-    if (!child.ok) return child;
+    if (signal.aborted)
+      return {
+        ...cancellationError(signal),
+        failureKind: "cancelled",
+      };
+    if (!child.ok) return { ...child, failureKind: child.failureKind };
     if (envelope.output === "evidence") {
       return {
         ok: true,
@@ -221,17 +321,140 @@ export class Runtime {
   private async run(
     request: unknown,
     ctx?: RunContext,
+    signal?: AbortSignal,
+    observer?: RuntimeActivityObserver,
   ): Promise<DispatchResult> {
     if (!ctx) return { ok: false, error: "run requires extension context" };
+    if (signal?.aborted) return cancellationError(signal);
     const validation = validateRequestEnvelope(request);
     if (!validation.ok) return { ok: false, error: validation.reason };
-    const envelope = validation.value;
+    const envelope: RequestEnvelope = {
+      ...validation.value,
+      roots: [...validation.value.roots],
+      context: { ...validation.value.context },
+      declared: {
+        ...validation.value.declared,
+        read: [...validation.value.declared.read],
+        write: [...validation.value.declared.write],
+        conflicts: [...validation.value.declared.conflicts],
+        resources: [...validation.value.declared.resources],
+      },
+    };
+    const context: StoredRunContext = {
+      ctx,
+      observer,
+      sequence: ++this.batchSeq,
+      runningEmitted: false,
+      terminalEmitted: false,
+    };
+    this.runContexts.set(envelope, context);
+    this.notify(envelope, context, "queued");
+    const batchId = `runtime-${context.sequence}`;
+    const batch = this.scheduler.schedule(batchId, [
+      { request: envelope, prerequisites: [] },
+    ]);
+    const cancelBatch = () =>
+      this.scheduler.cancel(
+        batchId,
+        signal?.reason ?? new Error("tool call cancelled"),
+      );
+    if (signal?.aborted) cancelBatch();
+    else signal?.addEventListener("abort", cancelBatch, { once: true });
+    try {
+      const outcome = await batch.result(envelope.id);
+      if (outcome.status === "succeeded" && outcome.value) {
+        const internalResult = outcome.value.dispatch as DispatchResult & {
+          failureKind?: RunFailureKind;
+        };
+        const { failureKind, ...publicResult } = internalResult;
+        if (publicResult.ok) {
+          this.notify(envelope, context, "completed");
+          return publicResult;
+        }
+        const state: RuntimeActivityState = failureKind ?? "failed";
+        this.notify(envelope, context, state);
+        return publicResult;
+      }
+      const state: RuntimeActivityState =
+        outcome.status === "cancelled" ? "cancelled" : "failed";
+      const terminal = {
+        ok: false as const,
+        error: outcome.error ?? `scheduled run ${outcome.status}`,
+      };
+      this.notify(envelope, context, state);
+      return terminal;
+    } finally {
+      signal?.removeEventListener("abort", cancelBatch);
+      this.runContexts.delete(envelope);
+    }
+  }
+
+  private notify(
+    envelope: RequestEnvelope,
+    context: StoredRunContext,
+    state: RuntimeActivityState,
+  ): void {
+    if (!context.observer || context.terminalEmitted) return;
+    if (state === "running") {
+      if (context.runningEmitted) return;
+      context.runningEmitted = true;
+    }
+    if (
+      state === "completed" ||
+      state === "failed" ||
+      state === "cancelled" ||
+      state === "timed-out"
+    ) {
+      context.terminalEmitted = true;
+    }
+    const event: RuntimeActivityEvent = {
+      state,
+      requestId: envelope.id,
+      role: envelope.role,
+      phase: envelope.phase,
+      objective: envelope.objective,
+      sequence: context.sequence,
+      ...(state === "cancelled"
+        ? { failureReason: "subagent cancelled" as const }
+        : state === "timed-out"
+          ? { failureReason: "phase timed out" as const }
+          : state === "failed"
+            ? { failureReason: "subagent failed" as const }
+            : {}),
+    };
+    try {
+      const result = context.observer(event);
+      if (result instanceof Promise) void result.catch(() => undefined);
+    } catch {
+      // Presentation observers cannot affect orchestration.
+    }
+  }
+
+  private async runScheduled(
+    envelope: RequestEnvelope,
+    ctx: RunContext,
+    signal: AbortSignal,
+  ): Promise<DispatchResult & { failureKind?: RunFailureKind }> {
+    if (signal.aborted)
+      return {
+        ...cancellationError(signal),
+        failureKind: "cancelled",
+      };
     const agent = loadAgentDefinitions().find(
       (item) => item.role === envelope.role,
     );
-    if (!agent) return { ok: false, error: "package Agent role not found" };
+    if (!agent)
+      return {
+        ok: false,
+        error: "package Agent role not found",
+        failureKind: "failed",
+      };
     if (!ctx.model)
-      return { ok: false, error: "run requires a model identity" };
+      return {
+        ok: false,
+        error: "run requires a model identity",
+        failureKind: "failed",
+      };
     const identity = workerIdentity(ctx.model);
     const contract = contractOf(envelope);
     const existing = this.registry.get(envelope.id);
@@ -241,6 +464,7 @@ export class Runtime {
           ok: false,
           error:
             "blocked: logical Worker pinned provider/model identity differs",
+          failureKind: "failed",
         };
       }
       if (!sameContract(existing.contract, contract)) {
@@ -248,19 +472,26 @@ export class Runtime {
           ok: false,
           error:
             "blocked: logical Worker contract changed for a recovery scope",
+          failureKind: "failed",
         };
       }
       if (existing.redispatchUsed) {
         return {
           ok: false,
           error: "blocked: mechanical redispatch is already exhausted",
+          failureKind: "failed",
         };
       }
     } else {
       this.registry.pin(contract, identity);
     }
     const pinned = this.registry.get(envelope.id);
-    const first = await this.dispatchChild(agent, envelope, ctx);
+    const first = await this.dispatchChild(agent, envelope, ctx, signal);
+    if (signal.aborted)
+      return {
+        ...cancellationError(signal),
+        failureKind: "cancelled",
+      };
     if (first.ok) {
       if (pinned) pinned.redispatchUsed = false;
       return first;
@@ -269,17 +500,28 @@ export class Runtime {
       return {
         ok: false,
         error: "blocked: mechanical redispatch failed and is exhausted",
+        failureKind: first.failureKind ?? "failed",
       };
     }
     if (!pinned) {
-      return { ok: false, error: "blocked: logical Worker is not pinned" };
+      return {
+        ok: false,
+        error: "blocked: logical Worker is not pinned",
+        failureKind: "failed",
+      };
     }
     pinned.redispatchUsed = true;
-    const second = await this.dispatchChild(agent, envelope, ctx);
+    const second = await this.dispatchChild(agent, envelope, ctx, signal);
+    if (signal.aborted)
+      return {
+        ...cancellationError(signal),
+        failureKind: "cancelled",
+      };
     if (!second.ok) {
       return {
         ok: false,
         error: "blocked: identical mechanical redispatch failed again",
+        failureKind: second.failureKind ?? first.failureKind ?? "failed",
       };
     }
     return second;
@@ -291,12 +533,14 @@ export class Runtime {
     return validateRequestEnvelope(envelope);
   }
 
-  drain(): void {
+  async drain(): Promise<void> {
+    const settled = this.scheduler.cancelAll();
     drainStage({
       results: this.results,
       registry: this.registry,
       activation: this.activation,
     });
+    await settled;
   }
 
   get state(): ActivationState {

package/src/scheduler.ts

@@ -43,6 +43,7 @@ interface Entry<T> {
   state: EntryState;
   attempts: number;
   cancelRequested: boolean;
+  cancelReason: unknown;
   controller: AbortController | null;
   resolve(outcome: ScheduledOutcome<T>): void;
   promise: Promise<ScheduledOutcome<T>>;
@@ -106,6 +107,7 @@ class Batch<T> {
         state: "queued",
         attempts: 0,
         cancelRequested: false,
+        cancelReason: undefined,
         controller: null,
         resolve,
         promise,
@@ -150,6 +152,8 @@ export class Scheduler<T> {
       }
     }
     this.pump();
+    const done = Promise.all(batch.entries.map((entry) => entry.promise));
+    void done.then(() => this.removeBatch(batch));
     return {
       batchId,
       result: (id: string) => {
@@ -157,22 +161,54 @@ export class Scheduler<T> {
         if (!entry) throw new Error(`unknown scheduled request: ${id}`);
         return entry.promise;
       },
-      done: Promise.all(batch.entries.map((entry) => entry.promise)),
+      done,
     };
   }
 
-  cancel(batchId: string): void {
+  private removeBatch(batch: Batch<T>): void {
+    const index = this.batches.indexOf(batch);
+    if (index >= 0) this.batches.splice(index, 1);
+  }
+
+  cancel(
+    batchId: string,
+    reason: unknown = new Error("batch cancelled"),
+  ): void {
     const batch = this.batches.find(
       (candidate) => candidate.batchId === batchId,
     );
-    if (!batch) return;
+    if (batch) this.cancelBatch(batch, reason);
+  }
+
+  async cancelAll(
+    reason: unknown = new Error("batch cancelled"),
+  ): Promise<void> {
+    const batches = [...this.batches];
+    for (const batch of batches) this.requestCancellation(batch, reason);
+    for (const batch of batches) this.settleQueuedCancellation(batch);
+    await Promise.all(
+      batches.flatMap((batch) => batch.entries.map((entry) => entry.promise)),
+    );
+  }
+
+  private cancelBatch(batch: Batch<T>, reason: unknown): void {
+    this.requestCancellation(batch, reason);
+    this.settleQueuedCancellation(batch);
+  }
+
+  private requestCancellation(batch: Batch<T>, reason: unknown): void {
+    for (const entry of batch.entries) {
+      if (entry.state !== "queued" && entry.state !== "running") continue;
+      if (!entry.cancelRequested) entry.cancelReason = reason;
+      entry.cancelRequested = true;
+      if (entry.state === "running") entry.controller?.abort(reason);
+    }
+  }
+
+  private settleQueuedCancellation(batch: Batch<T>): void {
     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();
@@ -182,7 +218,7 @@ export class Scheduler<T> {
     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 (entry.state !== "queued" || entry.cancelRequested) continue;
         if (!this.prerequisitesSucceeded(batch, entry)) continue;
         if (this.hasActiveConflict(entry)) continue;
         this.start(batch, entry);
@@ -207,7 +243,7 @@ export class Scheduler<T> {
 
   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;
+    if (entry.state !== "queued" || entry.cancelRequested) return;
     entry.state = "running";
     entry.attempts += 1;
     entry.controller = new AbortController();
@@ -262,7 +298,7 @@ export class Scheduler<T> {
       id: entry.request.id,
       status: "cancelled",
       attempts: entry.attempts,
-      error: "batch cancelled",
+      error: errorMessage(entry.cancelReason ?? new Error("batch cancelled")),
     };
   }