@abelxiaoxing/cadence 1.8.4 → 2.0.1

package/src/native-build.ts

@@ -0,0 +1,6 @@
+// Generated by scripts/build-service.mjs; do not edit.
+export const nativeBuild = {
+  kind: "native",
+  contractHash:
+    "e7e5248f8273a373827ac70d2d8be1d5aaea1e329379e59e4947fc10f82be818",
+} as const;

package/src/native-client.ts

@@ -0,0 +1,103 @@
+/** Native attachment only. No SDK/auth resolution, worker or storage mutation. */
+
+import { Agent } from "undici";
+import { nativeBuild } from "./native-build.ts";
+import { ServiceCoordination } from "./service/coordination.ts";
+import { ServiceClient } from "./service-client.ts";
+import {
+  ContractError,
+  compatibleBuild,
+  type SessionBootstrap,
+} from "./service-contract.ts";
+import { HttpServiceTransport } from "./service-http-client.ts";
+
+export const MANAGEMENT_GUIDANCE =
+  "Cadence owner absent, unavailable or incompatible. Explicitly run cadence-service status --workspace <path>, cadence-service diagnose --workspace <path>, or cadence-service start --workspace <path>. Stop older Cadence sessions first. For retained fences use cadence-service recover inspect; resolve requires a local terminal and separate process, credential and storage acknowledgments. Never treat unavailable/quarantined as stopped. No service was started and no embedded executor is available.";
+
+export class NativeConnection {
+  private transport?: HttpServiceTransport;
+  private network?: Agent;
+  private networkClose?: Promise<void>;
+  private closing?: Promise<void>;
+  private allocating?: Promise<void>;
+  client?: ServiceClient;
+  session?: SessionBootstrap;
+  private epoch?: string;
+
+  async attach(cwd: string): Promise<ServiceClient> {
+    // Failed detach keeps its exact transport/slot. Explicit re-entry may retry
+    // detach, but never forget it and allocate a replacement on uncertainty.
+    await this.detach();
+    const access = new ServiceCoordination(cwd).localAccess();
+    this.epoch = access.epoch;
+    const network = new Agent();
+    this.network = network;
+    this.transport = new HttpServiceTransport({
+      origin: access.endpoint,
+      localCapability: access.capability,
+      build: nativeBuild,
+      // Bound finite requests, not the entire streaming archive. Export keeps
+      // caller cancellation and the owner's download-idle policy, like WebUI.
+      requestTimeoutMs: 10000,
+      // Local capability MUST stay on direct numeric loopback even when the Pi
+      // process routes provider auth through a proxy. Public per-request Node
+      // dispatcher only: never replace/restore the parent's global dispatcher.
+      fetch: (url, init) =>
+        globalThis.fetch(url, Object.assign({}, init, { dispatcher: network })),
+    });
+    const client = new ServiceClient(this.transport);
+    this.client = client;
+    const allocation = (async () => {
+      await this.refresh();
+    })();
+    this.allocating = allocation;
+    try {
+      await allocation;
+    } finally {
+      if (this.allocating === allocation) this.allocating = undefined;
+    }
+    return client;
+  }
+  async refresh(): Promise<SessionBootstrap> {
+    if (!this.client) throw new ContractError("unavailable");
+    const reply = await this.client.session();
+    if (reply.kind === "error") throw new ContractError(reply.error.code);
+    if (reply.value.authority !== "local" || reply.value.epoch !== this.epoch)
+      throw new ContractError("stale");
+    this.session = reply.value;
+    return reply.value;
+  }
+  compatible(safety = false): boolean {
+    return compatibleBuild(this.session?.build, nativeBuild, safety);
+  }
+  detach(): Promise<void> {
+    if (this.closing) return this.closing;
+    const transport = this.transport;
+    const network = this.network;
+    if (!transport && !network) return Promise.resolve();
+    const allocation = this.allocating;
+    const closing = (async () => {
+      // Track late allocations; a caller's departure isn't evidence of release.
+      await allocation?.catch(() => {});
+      await transport?.detach();
+      if (network) {
+        this.networkClose ??= Promise.resolve().then(() => network.close());
+        await this.networkClose; // original close; failure retains this exact resource
+      }
+      if (this.transport === transport && this.network === network) {
+        this.network = undefined;
+        this.networkClose = undefined;
+        this.transport = undefined;
+        this.client = undefined;
+        this.session = undefined;
+      }
+    })();
+    this.closing = closing;
+    void closing
+      .finally(() => {
+        if (this.closing === closing) this.closing = undefined;
+      })
+      .catch(() => {});
+    return closing;
+  }
+}

package/src/native-export.ts

@@ -0,0 +1,58 @@
+/** Explicit user-selected native export. Exclusive destination, verified stream, no overwrite. */
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import type { ServiceClient } from "./service-client.ts";
+import {
+  ContractError,
+  type ExportRequest,
+  encodeExportFrame,
+} from "./service-contract.ts";
+
+export async function exportNative(
+  client: ServiceClient,
+  request: ExportRequest,
+  destination: string,
+  signal: AbortSignal,
+): Promise<"complete" | "incomplete"> {
+  // Preserve operational path bytes, including spaces; refuse aliases, not trim.
+  if (!isAbsolute(destination) || resolve(destination) !== destination)
+    throw new ContractError("invalid");
+  for (let at = dirname(destination); ; at = dirname(at)) {
+    const stat = await lstat(at);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+      throw new ContractError("forbidden");
+    if (dirname(at) === at) break;
+  }
+  if (signal.aborted) throw new ContractError("unavailable");
+  const file = await open(
+    destination,
+    constants.O_WRONLY |
+      constants.O_CREAT |
+      constants.O_EXCL |
+      (constants.O_NOFOLLOW ?? 0),
+    0o600,
+  );
+  const digest = createHash("sha256");
+  let completed: "complete" | "incomplete" | undefined;
+  try {
+    // ServiceClient checks counts/sequence/scope and withholds trailer until EOF.
+    for await (const frame of client.export(request, signal)) {
+      const encoded = encodeExportFrame(frame, request.format);
+      if (frame.event.kind === "trailer") {
+        if (digest.digest("hex") !== frame.event.sha256)
+          throw new ContractError("conflict");
+        completed = frame.event.complete ? "complete" : "incomplete";
+      } else digest.update(encoded);
+      await file.writeFile(encoded, "utf8");
+    }
+    if (!completed || signal.aborted) throw new ContractError("unavailable");
+    await file.sync();
+    return completed;
+  } finally {
+    // On any error the partial destination is retained, never removed/replaced or
+    // relabelled complete. The caller reports its exact path as unverified.
+    await file.close();
+  }
+}

package/src/native-history.ts

@@ -0,0 +1,359 @@
+/** Native retained readers: one human-paced request per page/proof continuation. */
+
+import { exportNative } from "./native-export.ts";
+import type { ServiceClient } from "./service-client.ts";
+import {
+  type ContentRef,
+  ContractError,
+  type DetailReadResult,
+  type ExportRequest,
+  type GraphReadRequest,
+  type HistoryRecord,
+  type ListRequest,
+  type ReadCursor,
+  type ReaderKind,
+  type Reply,
+  type Scope,
+  type Snapshot,
+} from "./service-contract.ts";
+import { diagnosticText } from "./verification-diagnostics.ts";
+
+export function value<T>(reply: Reply<T>): T {
+  if (reply.kind === "error") throw new ContractError(reply.error.code);
+  return reply.value;
+}
+export const pretty = (data: unknown) => JSON.stringify(data, null, 2);
+export interface NativeViews {
+  select(title: string, choices: string[]): Promise<string | undefined>;
+  input(title: string, prefill?: string): Promise<string | undefined>;
+  show(text: string): Promise<void>;
+  confirm(title: string, text: string): Promise<boolean>;
+  notify(text: string): void;
+  current(): void;
+  signal: AbortSignal;
+}
+export class NativeHistory {
+  constructor(
+    readonly client: ServiceClient,
+    readonly storeId: string,
+    readonly ui: NativeViews,
+  ) {}
+  async detail(seed: ReadCursor): Promise<void> {
+    let cursor: ReadCursor | null = seed;
+    const previous: ReadCursor[] = [];
+    while (cursor) {
+      const page: DetailReadResult = value(
+        await this.client.detail(cursor, this.ui.signal),
+      );
+      this.ui.current();
+      await this.ui.show(
+        "kind" in page
+          ? `Detail proof progress — no content yet\n${pretty(page.coverage)}`
+          : `${page.content.field} • ${page.content.recordId} v${page.content.version}\nUTF-8 bytes ${pretty(page.range)} / ${page.content.bytes}\nCoverage ${pretty(page.coverage)}\n\n${page.text}`,
+      );
+      const action = await this.ui.select("Retained detail (not a preview)", [
+        ...(page.next ? ["Next detail page / proof"] : []),
+        ...(previous.length ? ["Previous detail page"] : []),
+        "Return",
+      ]);
+      if (action === "Next detail page / proof" && page.next) {
+        previous.push(cursor);
+        cursor = page.next;
+      } else if (action === "Previous detail page")
+        cursor = previous.pop() ?? null;
+      else return;
+    }
+  }
+  async graph(seed: GraphReadRequest) {
+    let request = seed;
+    for (;;) {
+      const page = value(await this.client.graph(request, this.ui.signal));
+      this.ui.current();
+      if (!("kind" in page)) return page.graph;
+      if (
+        (await this.ui.select(
+          `Graph proof progress • ${pretty(page.coverage)}`,
+          ["Continue graph proof", "Return"],
+        )) !== "Continue graph proof"
+      )
+        return;
+      request = page.next;
+    }
+  }
+  private cursor(scope: Scope, seq: string, ref: ContentRef): ReadCursor {
+    return {
+      storeId: this.storeId,
+      scope,
+      snapshotSeq: seq,
+      query: null,
+      recordId: ref.recordId,
+      recordVersion: ref.version,
+      field: ref.field,
+      offset: 0,
+    };
+  }
+  async record(record: HistoryRecord, request: ListRequest): Promise<void> {
+    await this.ui.show(pretty(record));
+    if (request.scope.kind === "workspace" || !request.snapshotSeq) return;
+    const scope = request.scope,
+      refs: ContentRef[] = [];
+    switch (record.kind) {
+      case "task":
+        if (record.plan) refs.push(record.plan);
+        break;
+      case "message":
+        if (record.finalText) refs.push(record.finalText);
+        break;
+      case "content":
+        refs.push(record.content);
+        break;
+      case "owner-fact": {
+        const fact = record.fact;
+        if (fact.kind === "changes" || fact.kind === "review")
+          refs.push(fact.content);
+        if (fact.kind === "check-settled" && fact.output)
+          refs.push(fact.output);
+        break;
+      }
+      case "run": {
+        const r = record.projection;
+        await this.scope({
+          kind: r.childRunId ? "child" : "run",
+          id: r.childRunId ?? r.runId,
+        });
+        return;
+      }
+    }
+    for (;;) {
+      const options = refs.map(
+        (r) => `${r.field} • ${r.recordId} v${r.version} • ${r.bytes} bytes`,
+      );
+      const selected = await this.ui.select(
+        "Recorded fields • full arguments/results are in Retained content",
+        [...options, "Retained content", "Return"],
+      );
+      if (selected === "Retained content")
+        await this.pages("contents", scope, request.snapshotSeq);
+      else if (selected && options.includes(selected))
+        await this.detail(
+          this.cursor(
+            scope,
+            request.snapshotSeq,
+            refs[options.indexOf(selected)],
+          ),
+        );
+      else return;
+    }
+  }
+  async pages(
+    reader: ReaderKind,
+    scope: ListRequest["scope"],
+    snapshotSeq: string | null = null,
+    chooseTask = false,
+  ): Promise<string | undefined> {
+    let request: ListRequest = {
+      reader,
+      storeId: this.storeId,
+      scope,
+      snapshotSeq,
+      after: null,
+      limit: 50,
+    };
+    const previous: ListRequest[] = [];
+    for (;;) {
+      const page = value(await this.client[reader](request, this.ui.signal));
+      this.ui.current();
+      // A first data page can select the committed snapshot too. Pin its exact
+      // request before inspecting a record or going Back; never repeat a null
+      // seed and silently rebase an already displayed list.
+      if (page.request.snapshotSeq !== null) request = page.request;
+      const records = "kind" in page ? [] : page.records;
+      const labels = records.map((r, i) => `${i + 1}. ${recordLabel(r)}`);
+      const action = await this.ui.select(
+        `${reader} • snapshot ${page.request.snapshotSeq ?? "selecting"} • ${"kind" in page ? page.kind : "retained page"} • coverage ${pretty(page.coverage)}`,
+        [
+          ...labels,
+          ...(page.next ? ["Next page / proof"] : []),
+          ...(previous.length ? ["Previous page"] : []),
+          "Return",
+        ],
+      );
+      if (action === "Next page / proof" && page.next) {
+        if (request.snapshotSeq !== null) previous.push(request);
+        request = page.next;
+      } else if (action === "Previous page")
+        request = previous.pop() ?? request;
+      else if (action && labels.includes(action)) {
+        const record = records[labels.indexOf(action)];
+        if (chooseTask && record.kind === "task") return record.owner.taskId;
+        await this.record(record, page.request);
+      } else return;
+    }
+  }
+  async search(scope: Scope, snapshotSeq: string): Promise<void> {
+    const query = await this.ui.input(
+      "Literal case-sensitive search (1–1024 UTF-8 bytes)",
+    );
+    if (!query) return;
+    let cursor: ReadCursor = {
+      storeId: this.storeId,
+      scope,
+      snapshotSeq,
+      query,
+      recordId: null,
+      recordVersion: null,
+      field: null,
+      offset: 0,
+    };
+    const previous: ReadCursor[] = [];
+    for (;;) {
+      const page = value(await this.client.search(cursor, this.ui.signal));
+      this.ui.current();
+      const labels = page.hits.map(
+        (hit, i) =>
+          `${i + 1}. ${hit.content.recordId} v${hit.content.version} ${hit.content.field} bytes ${hit.range.start}–${hit.range.end} • ${diagnosticText(hit.preview, 160)}`,
+      );
+      const selected = await this.ui.select(
+        `Search ${JSON.stringify(query)} • ${page.next ? "more retained ranges remain (zero hits is not completion)" : "retained scan ended"} • ${pretty(page.coverage)}`,
+        [
+          ...labels,
+          ...(page.next ? ["Next search page / proof"] : []),
+          ...(previous.length ? ["Previous search page"] : []),
+          "Return",
+        ],
+      );
+      if (selected === "Next search page / proof" && page.next) {
+        previous.push(cursor);
+        cursor = page.next;
+      } else if (selected === "Previous search page")
+        cursor = previous.pop() ?? cursor;
+      else if (selected && labels.includes(selected)) {
+        const hit = page.hits[labels.indexOf(selected)];
+        await this.ui.show(
+          `Exact hit (UTF-8 range, not character indexes)\n${pretty(hit)}`,
+        );
+        await this.detail(hit.cursor);
+      } else return;
+    }
+  }
+  async export(scope: Scope, snapshotSeq: string): Promise<void> {
+    const format = await this.ui.select(
+      "Full retained export • credentials/private auth are excluded",
+      ["ndjson", "markdown"],
+    );
+    if (format !== "ndjson" && format !== "markdown") return;
+    const destination = await this.ui.input(
+      "Absolute NEW export file path (no overwrite; partial files preserved)",
+    );
+    if (!destination) return;
+    if (
+      !(await this.ui.confirm(
+        "Write full verified export?",
+        `${JSON.stringify(destination)}\n${pretty(scope)} at ${snapshotSeq}\nInterrupted or incomplete output is not a complete archive.`,
+      ))
+    )
+      return;
+    const request: ExportRequest = {
+      storeId: this.storeId,
+      scope,
+      snapshotSeq,
+      format,
+    };
+    try {
+      const result = await exportNative(
+        this.client,
+        request,
+        destination,
+        this.ui.signal,
+      );
+      this.ui.current();
+      this.ui.notify(
+        `Export ${result}: count/digest/trailer/EOF verified; ${JSON.stringify(destination)}. Coverage is independent of original-source completeness.`,
+      );
+    } catch {
+      this.ui.notify(
+        `Export unverified/incomplete or destination refused: ${JSON.stringify(destination)}. Any partial file is preserved; no overwrite or cleanup.`,
+      );
+    }
+  }
+  async scope(scope: Scope): Promise<void> {
+    for (;;) {
+      const snapshot: Snapshot = value(
+        await this.client.snapshot(scope, this.ui.signal),
+      );
+      this.ui.current();
+      const selected = await this.ui.select(
+        `${scope.kind} ${scope.id} • committed ${snapshot.committedSeq} (observation only)`,
+        [
+          "Status / graph",
+          "Runs / children",
+          "Messages",
+          "Tools",
+          "Retained content",
+          "Timeline",
+          "Checks history",
+          "Changes history",
+          "Human review history",
+          "Search",
+          "Export",
+          "Return",
+        ],
+      );
+      if (selected === "Status / graph") {
+        await this.ui.show(pretty(snapshot));
+        for (const r of snapshot.runs) {
+          if (
+            !r.childRunId &&
+            r.admission.graph &&
+            (await this.ui.confirm("Read recorded graph?", r.runId))
+          ) {
+            const graph = await this.graph({
+              storeId: this.storeId,
+              scope,
+              snapshotSeq: snapshot.committedSeq,
+              graph: r.admission.graph,
+            });
+            if (graph) await this.ui.show(pretty(graph));
+          }
+        }
+      } else if (selected === "Search")
+        await this.search(scope, snapshot.committedSeq);
+      else if (selected === "Export")
+        await this.export(scope, snapshot.committedSeq);
+      else {
+        const readers: Record<string, ReaderKind> = {
+          "Runs / children": "runs",
+          Messages: "messages",
+          Tools: "tools",
+          "Retained content": "contents",
+          Timeline: "events",
+          "Checks history": "checks",
+          "Changes history": "changes",
+          "Human review history": "reviews",
+        };
+        if (!selected || !readers[selected]) return;
+        await this.pages(readers[selected], scope, snapshot.committedSeq);
+      }
+    }
+  }
+}
+export function recordLabel(r: HistoryRecord): string {
+  switch (r.kind) {
+    case "task":
+      return `${r.owner.taskId} • ${diagnosticText(r.goal, 160)}`;
+    case "run":
+      return `${r.projection.childRunId ?? r.projection.runId} • ${r.projection.assignmentId ?? "parent"} • ${r.projection.lifecycle} / ${r.projection.outcome ?? "unsettled"}`;
+    case "message":
+      return `${r.owner.entity.id} • ${r.role} • ${r.state}`;
+    case "tool":
+      return `${r.owner.entity.id} • ${diagnosticText(r.name)} • SDK error ${r.result?.isError ?? "unavailable"} (not a parent check)`;
+    case "content":
+      return `${r.content.recordId} v${r.content.version} • ${r.content.field} • ${r.content.bytes} retained bytes`;
+    case "omitted":
+      return `${r.owner.entity.id} • omitted`;
+    case "owner-fact":
+      return `seq ${r.committedSeq} • observed ${r.observedMs}ms • ${r.fact.kind}`;
+    case "capture-fact":
+      return `seq ${r.committedSeq} • ${r.capture.event.kind} • child ${r.link.childRunId}`;
+  }
+}