@abelxiaoxing/cadence 1.0.1 → 1.0.2

package/src/file-snapshot.ts

@@ -1,10 +1,17 @@
 // File-level snapshots: content hashes for observed files, deterministic
-// directory-entry manifests for observed directories, and explicit absent
+// recursive content 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";
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  statSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
 
 export interface FileBound {
   kind: "file";
@@ -37,7 +44,57 @@ export function snapshotFile(root: string, relPath: string): FileBound | null {
   return { sha256: sha256(bytes), bytes: bytes.length, kind: "file" };
 }
 
-/** Deterministic directory-entry manifest: hash of sorted name/type entries. */
+function updateManifest(
+  hash: ReturnType<typeof createHash>,
+  ...fields: Array<string | Buffer>
+): void {
+  for (const field of fields) {
+    const bytes = typeof field === "string" ? Buffer.from(field) : field;
+    hash.update(`${bytes.length}:`);
+    hash.update(bytes);
+  }
+}
+
+function recursiveDirectoryManifest(abs: string): string {
+  const hash = createHash("sha256");
+  updateManifest(hash, "cadence-directory-manifest-v2");
+  const visit = (directory: string, prefix: string): void => {
+    const names = readdirSync(directory).sort();
+    for (const name of names) {
+      const relative = prefix ? `${prefix}/${name}` : name;
+      const current = join(directory, name);
+      const stat = lstatSync(current);
+      if (stat.isDirectory()) {
+        updateManifest(hash, "dir", relative, String(stat.mode & 0o777));
+        visit(current, relative);
+      } else if (stat.isFile()) {
+        const bytes = readFileSync(current);
+        updateManifest(
+          hash,
+          "file",
+          relative,
+          String(stat.mode & 0o777),
+          String(bytes.length),
+          sha256(bytes),
+        );
+      } else if (stat.isSymbolicLink()) {
+        updateManifest(hash, "symlink", relative, readlinkSync(current));
+      } else {
+        updateManifest(
+          hash,
+          "special",
+          relative,
+          String(stat.mode),
+          String(stat.size),
+        );
+      }
+    }
+  };
+  visit(abs, "");
+  return hash.digest("hex");
+}
+
+/** Deterministic recursive directory manifest bound to installed content. */
 export function snapshotDirManifest(
   root: string,
   relDir: string,
@@ -45,10 +102,7 @@ export function snapshotDirManifest(
   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" };
+  return { manifest: recursiveDirectoryManifest(abs), kind: "dir" };
 }
 
 /** Build a bound map for the given file paths, observed directories, and absent markers. */

package/src/index.ts

@@ -15,6 +15,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { type Activation, activateTool, deactivateTool } from "./activation.ts";
 import { ACTIONS } from "./contracts.ts";
+import { ParentPayloadBridge } from "./parent-payload-bridge.ts";
 import { Runtime } from "./runtime.ts";
 import {
   ACTIVITY_DETAILS_KEY,
@@ -68,20 +69,27 @@ function hasExpandedPromptMarker(
   );
 }
 
+function isVerifiedStageInvocation(
+  pi: ExtensionAPI,
+  activation: Activation,
+  name: EligiblePrompt,
+  prompt: string,
+): boolean {
+  return (
+    hasPackageProvenance(pi, name) &&
+    hasExpandedPromptMarker(prompt, name) &&
+    (activation.isActive() || activation.state === "inactive")
+  );
+}
+
 function activateDispatcher(
   pi: ExtensionAPI,
   activation: Activation,
   name: EligiblePrompt,
   prompt: string,
 ): void {
-  if (
-    !hasPackageProvenance(pi, name) ||
-    !hasExpandedPromptMarker(prompt, name)
-  ) {
-    return;
-  }
+  if (!isVerifiedStageInvocation(pi, activation, name, prompt)) return;
   if (!activation.isActive()) {
-    if (activation.state !== "inactive") return;
     activation.request();
     activation.activate();
   }
@@ -92,7 +100,8 @@ function activateDispatcher(
 }
 
 export default function register(pi: ExtensionAPI): void {
-  const runtime = new Runtime();
+  const parentPayloadBridge = new ParentPayloadBridge();
+  const runtime = new Runtime({ parentPayloadBridge });
   const activity = new ActivityController();
 
   pi.registerTool({
@@ -152,7 +161,7 @@ export default function register(pi: ExtensionAPI): void {
         };
       }
       return {
-        content: [{ type: "text", text: result.error }],
+        content: [{ type: "text", text: JSON.stringify(result) }],
         details,
         isError: true,
       };
@@ -177,14 +186,37 @@ export default function register(pi: ExtensionAPI): void {
     return { action: "continue" };
   });
 
-  pi.on("before_agent_start", (event) => {
+  pi.on("before_agent_start", (event, ctx) => {
     const prompt = pendingPrompt;
     pendingPrompt = undefined;
+    if (
+      prompt &&
+      isVerifiedStageInvocation(pi, runtime.activation, prompt, event.prompt)
+    ) {
+      const sessionId = ctx.sessionManager?.getSessionId?.();
+      if (typeof sessionId === "string") {
+        parentPayloadBridge.beginSession(sessionId);
+      } else {
+        parentPayloadBridge.clear();
+      }
+    }
+    if (ctx.model) {
+      parentPayloadBridge.install(ctx.model, ctx.modelRegistry);
+    }
     if (prompt)
       activateDispatcher(pi, runtime.activation, prompt, event.prompt);
   });
 
   pi.on("session_start", (_event, ctx) => {
+    const sessionId = ctx.sessionManager?.getSessionId?.();
+    if (typeof sessionId === "string") {
+      parentPayloadBridge.beginSession(sessionId);
+      if (ctx.model) {
+        parentPayloadBridge.install(ctx.model, ctx.modelRegistry);
+      }
+    } else {
+      parentPayloadBridge.clear();
+    }
     pendingPrompt = undefined;
     activity.detach();
     if (ctx.mode === "tui") activity.attach(ctx.ui);
@@ -196,6 +228,19 @@ export default function register(pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("model_select", (event, ctx) => {
+    const sessionId = ctx.sessionManager?.getSessionId?.();
+    if (typeof sessionId !== "string") {
+      parentPayloadBridge.clear();
+      return;
+    }
+    parentPayloadBridge.beginSession(sessionId);
+    const model = event.model ?? ctx.model;
+    if (model) {
+      parentPayloadBridge.install(model, ctx.modelRegistry);
+    }
+  });
+
   pi.on("session_shutdown", async () => {
     activity.detach();
     await runtime.drain();

package/src/parent-payload-bridge.ts

@@ -0,0 +1,442 @@
+import {
+  type AssistantMessage,
+  type AssistantMessageEventStream,
+  type Context,
+  createAssistantMessageEventStream,
+  type Model,
+  type Provider,
+} from "@earendil-works/pi-ai";
+
+export type ParentPayloadCallback = (
+  payload: unknown,
+  model: Model<string>,
+) => unknown | undefined | Promise<unknown | undefined>;
+
+export interface ParentModelKey {
+  provider: string;
+  id: string;
+  api: string;
+  baseUrl: string;
+}
+
+export interface ParentPayloadCapture {
+  readonly generation: number;
+  readonly sessionId: string;
+  readonly modelKey: Readonly<ParentModelKey>;
+  readonly delegate: Provider;
+  readonly onPayload: ParentPayloadCallback;
+}
+
+export interface ParentProviderRegistry {
+  getProvider(provider: string): Provider | undefined;
+  registerProvider(provider: Provider): void;
+}
+
+interface GenerationState {
+  readonly generation: number;
+  readonly sessionId: string;
+  active: boolean;
+  readonly ready: Map<string, ParentPayloadCapture>;
+  readonly installed: Map<string, Provider>;
+  tail: Promise<void>;
+}
+
+interface ProvisionalCapture {
+  readonly state: GenerationState;
+  readonly modelKey: ParentModelKey;
+  readonly delegate: Provider;
+  readonly onPayload: ParentPayloadCallback;
+}
+
+const PROVIDER_WRAPPER = Symbol("cadence-parent-payload-provider");
+
+function streamFailure(model: Model<string>): AssistantMessage {
+  return {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        total: 0,
+      },
+    },
+    stopReason: "error",
+    errorMessage: "parent provider stream failed",
+    timestamp: Date.now(),
+  };
+}
+
+function abortable<T>(
+  value: T | PromiseLike<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  if (!signal) return Promise.resolve(value);
+  signal.throwIfAborted();
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      callback();
+    };
+    const onAbort = () => {
+      try {
+        signal.throwIfAborted();
+      } catch (error) {
+        finish(() => reject(error));
+      }
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+    Promise.resolve(value).then(
+      (result) => finish(() => resolve(result)),
+      (error) => finish(() => reject(error)),
+    );
+  });
+}
+
+function modelKeyFor(model: Model<string>): ParentModelKey {
+  return {
+    provider: model.provider,
+    id: model.id,
+    api: model.api,
+    baseUrl: model.baseUrl,
+  };
+}
+
+function modelKeyId(modelKey: Readonly<ParentModelKey>): string {
+  return JSON.stringify([
+    modelKey.provider,
+    modelKey.id,
+    modelKey.api,
+    modelKey.baseUrl,
+  ]);
+}
+
+function sameModelKey(
+  left: Readonly<ParentModelKey>,
+  right: Readonly<ParentModelKey>,
+): boolean {
+  return (
+    left.provider === right.provider &&
+    left.id === right.id &&
+    left.api === right.api &&
+    left.baseUrl === right.baseUrl
+  );
+}
+
+function requireSafePayload(
+  payload: unknown,
+): asserts payload is Record<string, unknown> {
+  if (
+    typeof payload !== "object" ||
+    payload === null ||
+    Array.isArray(payload)
+  ) {
+    throw new Error("parent payload bridge produced an unsafe payload");
+  }
+}
+
+export class ParentPayloadBridge {
+  private nextGeneration = 0;
+  private state: GenerationState | undefined;
+  private readonly captureStates = new WeakMap<
+    ParentPayloadCapture,
+    GenerationState
+  >();
+
+  beginSession(sessionId: string): number {
+    this.invalidate();
+    const state: GenerationState = {
+      generation: ++this.nextGeneration,
+      sessionId,
+      active: true,
+      ready: new Map(),
+      installed: new Map(),
+      tail: Promise.resolve(),
+    };
+    this.state = state;
+    return state.generation;
+  }
+
+  clear(): void {
+    this.invalidate();
+    this.nextGeneration++;
+    this.state = undefined;
+  }
+
+  install(
+    model: Model<string>,
+    registry: ParentProviderRegistry,
+  ): Provider | undefined {
+    const current = registry.getProvider(model.provider);
+    if (!current) return undefined;
+    const delegate = this.unwrapProvider(current);
+    const state = this.state;
+    if (state?.active) {
+      const key = modelKeyId(modelKeyFor(model));
+      state.installed.set(key, delegate);
+      const ready = state.ready.get(key);
+      if (ready && ready.delegate !== delegate) {
+        state.ready.delete(key);
+      }
+    }
+    const wrapped = this.wrapProvider(delegate);
+    registry.registerProvider(wrapped);
+    return wrapped;
+  }
+
+  capture(
+    modelKey: ParentModelKey,
+    registry?: Pick<ParentProviderRegistry, "getProvider">,
+  ): ParentPayloadCapture | undefined {
+    const state = this.state;
+    if (!state?.active) return undefined;
+    const capture = state.ready.get(modelKeyId(modelKey));
+    if (!capture || !sameModelKey(capture.modelKey, modelKey)) {
+      return undefined;
+    }
+    if (registry) {
+      const current = registry.getProvider(modelKey.provider);
+      if (!current || this.unwrapProvider(current) !== capture.delegate) {
+        return undefined;
+      }
+    }
+    return capture;
+  }
+
+  wrapProvider(delegate: Provider): Provider {
+    const original = this.unwrapProvider(delegate);
+    const stream = (
+      model: Model<string>,
+      context: Context,
+      options?: unknown,
+    ) => this.forwardProvider(original, "stream", model, context, options);
+    const streamSimple = (
+      model: Model<string>,
+      context: Context,
+      options?: unknown,
+    ) =>
+      this.forwardProvider(original, "streamSimple", model, context, options);
+    const boundMethods = new Map<
+      PropertyKey,
+      {
+        source: (...args: never[]) => unknown;
+        bound: (...args: never[]) => unknown;
+      }
+    >();
+
+    return new Proxy(original, {
+      get(target, property) {
+        if (property === PROVIDER_WRAPPER) return original;
+        if (property === "stream") return stream;
+        if (property === "streamSimple") return streamSimple;
+        const value = Reflect.get(target, property, target) as unknown;
+        if (typeof value !== "function") return value;
+        const current = boundMethods.get(property);
+        if (current?.source === value) return current.bound;
+        const source = value as (...args: never[]) => unknown;
+        const bound = source.bind(target);
+        boundMethods.set(property, { source, bound });
+        return bound;
+      },
+      set(target, property, value) {
+        return Reflect.set(target, property, value, target);
+      },
+    });
+  }
+
+  async composePayload(
+    capture: ParentPayloadCapture | undefined,
+    payload: unknown,
+    model: Model<string>,
+    childOnPayload?: ParentPayloadCallback,
+    signal?: AbortSignal,
+  ): Promise<Record<string, unknown>> {
+    if (!capture) throw new Error("parent payload bridge is unavailable");
+    const requestedKey = modelKeyFor(model);
+    const state = this.requireCurrentCapture(capture, requestedKey);
+    signal?.throwIfAborted();
+
+    let current = payload;
+    if (childOnPayload) {
+      const childResult = await abortable(
+        childOnPayload(current, model),
+        signal,
+      );
+      if (childResult !== undefined) current = childResult;
+    }
+    requireSafePayload(current);
+    signal?.throwIfAborted();
+    this.requireCurrentCapture(capture, requestedKey);
+
+    const predecessor = state.tail;
+    let release = () => {};
+    const completed = new Promise<void>((resolve) => {
+      release = () => resolve();
+    });
+    state.tail = predecessor.then(
+      () => completed,
+      () => completed,
+    );
+    let parentSettlement: Promise<void> | undefined;
+
+    try {
+      await abortable(predecessor, signal);
+      signal?.throwIfAborted();
+      this.requireCurrentCapture(capture, requestedKey);
+
+      const parentCall = Promise.resolve(capture.onPayload(current, model));
+      parentSettlement = parentCall.then(
+        () => undefined,
+        () => undefined,
+      );
+      const parentResult = await abortable(parentCall, signal);
+      if (parentResult !== undefined) current = parentResult;
+      requireSafePayload(current);
+
+      let finalPayload: Record<string, unknown> = current;
+      if (model.api === "openai-responses") {
+        finalPayload = { ...current };
+        delete finalPayload.max_output_tokens;
+      }
+
+      signal?.throwIfAborted();
+      this.requireCurrentCapture(capture, requestedKey);
+      return finalPayload;
+    } finally {
+      if (parentSettlement) void parentSettlement.then(release);
+      else release();
+    }
+  }
+
+  private forwardProvider(
+    delegate: Provider,
+    method: "stream" | "streamSimple",
+    model: Model<string>,
+    context: Context,
+    options?: unknown,
+  ): AssistantMessageEventStream {
+    const state = this.state;
+    const candidate = (options as { onPayload?: unknown } | null | undefined)
+      ?.onPayload;
+    const onPayload =
+      typeof candidate === "function"
+        ? (candidate as ParentPayloadCallback)
+        : undefined;
+    const provisional: ProvisionalCapture | undefined =
+      state?.active && onPayload
+        ? {
+            state,
+            modelKey: modelKeyFor(model),
+            delegate,
+            onPayload,
+          }
+        : undefined;
+    const source =
+      method === "stream"
+        ? delegate.stream(model, context, options as never)
+        : delegate.streamSimple(model, context, options as never);
+    const output = createAssistantMessageEventStream();
+    void this.mirrorStream(source, output, model, provisional);
+    return output;
+  }
+
+  private async mirrorStream(
+    source: AssistantMessageEventStream,
+    output: AssistantMessageEventStream,
+    model: Model<string>,
+    provisional: ProvisionalCapture | undefined,
+  ): Promise<void> {
+    let successful = false;
+    try {
+      for await (const event of source) {
+        if (event.type === "done") successful = true;
+        output.push(event);
+      }
+      if (successful && provisional) this.commitCapture(provisional);
+    } catch {
+      const error = streamFailure(model);
+      output.push({ type: "error", reason: "error", error });
+    } finally {
+      output.end();
+    }
+  }
+
+  private commitCapture(provisional: ProvisionalCapture): void {
+    const { state } = provisional;
+    if (!state.active || this.state !== state) return;
+    const key = modelKeyId(provisional.modelKey);
+    if (
+      state.installed.has(key) &&
+      state.installed.get(key) !== provisional.delegate
+    ) {
+      return;
+    }
+    const capture: ParentPayloadCapture = Object.freeze({
+      generation: state.generation,
+      sessionId: state.sessionId,
+      modelKey: Object.freeze({ ...provisional.modelKey }),
+      delegate: provisional.delegate,
+      onPayload: provisional.onPayload,
+    });
+    state.ready.set(key, capture);
+    this.captureStates.set(capture, state);
+  }
+
+  private requireCurrentCapture(
+    capture: ParentPayloadCapture | undefined,
+    modelKey: ParentModelKey,
+  ): GenerationState {
+    const state = this.state;
+    if (
+      !capture ||
+      !state?.active ||
+      this.captureStates.get(capture) !== state ||
+      capture.generation !== state.generation ||
+      capture.sessionId !== state.sessionId ||
+      !sameModelKey(capture.modelKey, modelKey) ||
+      state.ready.get(modelKeyId(modelKey)) !== capture
+    ) {
+      throw new Error("parent payload bridge is unavailable");
+    }
+    return state;
+  }
+
+  private unwrapProvider(provider: Provider): Provider {
+    let current = provider;
+    const seen = new Set<Provider>();
+    while (!seen.has(current)) {
+      seen.add(current);
+      const candidate = Reflect.get(current, PROVIDER_WRAPPER) as unknown;
+      if (
+        typeof candidate !== "object" ||
+        candidate === null ||
+        seen.has(candidate as Provider)
+      ) {
+        return current;
+      }
+      current = candidate as Provider;
+    }
+    return current;
+  }
+
+  private invalidate(): void {
+    if (!this.state) return;
+    this.state.active = false;
+    this.state.ready.clear();
+    this.state.installed.clear();
+  }
+}