@abelxiaoxing/cadence 1.0.13 → 1.1.0

package/src/artifact-store.ts

@@ -0,0 +1,204 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+const SHA256 = /^[a-f0-9]{64}$/u;
+
+export interface ArtifactIdentity {
+  hash: string;
+  bytes: number;
+}
+
+function digest(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function requireHash(hash: string): void {
+  if (!SHA256.test(hash)) throw new Error("artifact-hash-invalid");
+}
+
+function ensureDirectory(directory: string): void {
+  const stat = lstatSync(directory, { throwIfNoEntry: false });
+  if (stat) {
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error("artifact-store-path-unsafe");
+    }
+    chmodSync(directory, 0o700);
+    return;
+  }
+  let cursor = path.dirname(directory);
+  while (cursor !== path.dirname(cursor)) {
+    const ancestor = lstatSync(cursor, { throwIfNoEntry: false });
+    if (ancestor) {
+      if (ancestor.isSymbolicLink() || !ancestor.isDirectory()) {
+        throw new Error("artifact-store-path-unsafe");
+      }
+      break;
+    }
+    cursor = path.dirname(cursor);
+  }
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const created = lstatSync(directory);
+  if (created.isSymbolicLink() || !created.isDirectory()) {
+    throw new Error("artifact-store-path-unsafe");
+  }
+  chmodSync(directory, 0o700);
+}
+
+function syncDirectory(directory: string): void {
+  const descriptor = openSync(directory, constants.O_RDONLY);
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function writeAtomic(target: string, bytes: Uint8Array): void {
+  const directory = path.dirname(target);
+  ensureDirectory(directory);
+  const temporary = path.join(
+    directory,
+    `.${path.basename(target)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  const descriptor = openSync(
+    temporary,
+    constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+    0o600,
+  );
+  try {
+    writeFileSync(descriptor, bytes);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  try {
+    renameSync(temporary, target);
+    chmodSync(target, 0o600);
+    syncDirectory(directory);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // The rename may already have consumed the temporary file.
+    }
+    throw error;
+  }
+}
+
+/** Durable content-addressed bytes used by workspace revisions and sealed results. */
+export class ArtifactStore {
+  readonly root: string;
+  readonly #blobs: string;
+  readonly #references: string;
+
+  constructor(root: string) {
+    if (!path.isAbsolute(root)) throw new Error("artifact-store-root-invalid");
+    this.root = path.resolve(root);
+    this.#blobs = path.join(this.root, "blobs");
+    this.#references = path.join(this.root, "references");
+    ensureDirectory(this.root);
+    ensureDirectory(this.#blobs);
+    ensureDirectory(this.#references);
+  }
+
+  #blobPath(hash: string): string {
+    requireHash(hash);
+    return path.join(this.#blobs, hash.slice(0, 2), hash);
+  }
+
+  #referencePath(hash: string): string {
+    requireHash(hash);
+    return path.join(this.#references, hash.slice(0, 2), `${hash}.ref`);
+  }
+
+  put(input: Uint8Array): ArtifactIdentity {
+    if (!(input instanceof Uint8Array))
+      throw new Error("artifact-bytes-invalid");
+    const bytes = Buffer.from(input);
+    const hash = digest(bytes);
+    const target = this.#blobPath(hash);
+    const existing = lstatSync(target, { throwIfNoEntry: false });
+    if (existing) {
+      if (existing.isSymbolicLink() || !existing.isFile()) {
+        throw new Error("artifact-store-path-unsafe");
+      }
+      const current = readFileSync(target);
+      if (current.length !== bytes.length || digest(current) !== hash) {
+        throw new Error("artifact-integrity-invalid");
+      }
+    } else {
+      writeAtomic(target, bytes);
+      const stored = readFileSync(target);
+      if (stored.length !== bytes.length || digest(stored) !== hash) {
+        throw new Error("artifact-integrity-invalid");
+      }
+    }
+    return Object.freeze({ hash, bytes: bytes.length });
+  }
+
+  read(hash: string): Uint8Array {
+    const target = this.#blobPath(hash);
+    const stat = lstatSync(target, { throwIfNoEntry: false });
+    if (!stat?.isFile() || stat.isSymbolicLink()) {
+      throw new Error("artifact-unavailable");
+    }
+    const bytes = readFileSync(target);
+    if (digest(bytes) !== hash) throw new Error("artifact-integrity-invalid");
+    return Buffer.from(bytes);
+  }
+
+  referenceCount(hash: string): number {
+    requireHash(hash);
+    const referencePath = this.#referencePath(hash);
+    const stat = lstatSync(referencePath, { throwIfNoEntry: false });
+    if (!stat) return 0;
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error("artifact-reference-invalid");
+    }
+    const raw = readFileSync(referencePath, "utf8");
+    if (!/^(?:0|[1-9][0-9]*)\n$/u.test(raw)) {
+      throw new Error("artifact-reference-invalid");
+    }
+    const count = Number(raw.trim());
+    if (!Number.isSafeInteger(count))
+      throw new Error("artifact-reference-invalid");
+    return count;
+  }
+
+  #setReferenceCount(hash: string, count: number): number {
+    if (!Number.isSafeInteger(count) || count < 0) {
+      throw new Error("artifact-reference-invalid");
+    }
+    writeAtomic(this.#referencePath(hash), Buffer.from(`${count}\n`));
+    return count;
+  }
+
+  retain(hash: string): number {
+    this.read(hash);
+    const current = this.referenceCount(hash);
+    if (current === Number.MAX_SAFE_INTEGER) {
+      throw new Error("artifact-reference-overflow");
+    }
+    return this.#setReferenceCount(hash, current + 1);
+  }
+
+  release(hash: string): number {
+    this.read(hash);
+    const current = this.referenceCount(hash);
+    if (current === 0) throw new Error("artifact-reference-underflow");
+    return this.#setReferenceCount(hash, current - 1);
+  }
+}

package/src/child-session.ts

@@ -16,12 +16,21 @@ import type {
   SafeFailureDetails,
 } from "./contracts.ts";
 import { EmptyResourceLoader } from "./empty-resource-loader.ts";
-import { createScopedTools, TOOL_LIMITS } from "./scoped-tools.ts";
 import {
+  createScopedTools,
+  type Observation,
+  ScopedObservationCollector,
+  TOOL_LIMITS,
+} from "./scoped-tools.ts";
+import {
+  type CandidateArtifactSubmission,
+  type CandidateArtifactSubmissionResult,
+  createCandidateArtifactTool,
   createSubmitTool,
   type FinalCategory,
   type SubmitClassification,
 } from "./submit-tool.ts";
+import { serializeTaskLedgerProjection } from "./task-ledger.ts";
 
 function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
   signal.throwIfAborted();
@@ -106,6 +115,7 @@ function wrapScopedTools(
   roots: string[],
   cwd: string,
   allowedPaths?: string[],
+  observer?: (observation: Observation) => void,
 ) {
   const order = ["read", "grep", "find", "ls"];
   return createScopedTools({
@@ -117,6 +127,7 @@ function wrapScopedTools(
           ),
         }
       : {}),
+    ...(observer ? { observer } : {}),
   })
     .sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name))
     .map((scoped) =>
@@ -175,6 +186,20 @@ function finalDeliveryContent(message: AssistantMessage | undefined) {
   );
 }
 
+function hasStructuralSubmit(message: AssistantMessage | undefined) {
+  return finalDeliveryContent(message).some(
+    (content) =>
+      content.type === "toolCall" && content.name === "abel_submit_result",
+  );
+}
+
+function structuralSubmitCount(message: AssistantMessage | undefined) {
+  return finalDeliveryContent(message).filter(
+    (content) =>
+      content.type === "toolCall" && content.name === "abel_submit_result",
+  ).length;
+}
+
 function isSingleStructuralSubmit(message: AssistantMessage | undefined) {
   const content = finalDeliveryContent(message);
   return (
@@ -251,12 +276,13 @@ function withSubmitDetails(
 export type ChildSessionResult =
   | {
       ok: true;
-      result: EvidenceResult | DiffResult;
+      result: EvidenceResult | DiffResult | CandidateArtifactSubmissionResult;
       toolNames: string[];
       submitCount: number;
       disposeCount: number;
       usage: Usage;
       classification: SubmitClassification;
+      observations?: { observations: Observation[]; truncated: boolean };
     }
   | {
       ok: false;
@@ -267,6 +293,7 @@ export type ChildSessionResult =
       disposeCount: number;
       usage: Usage;
       classification: SubmitClassification;
+      observations?: { observations: Observation[]; truncated: boolean };
     };
 
 export async function runChildSession(input: {
@@ -284,19 +311,49 @@ export async function runChildSession(input: {
   timeoutMs: number;
   signal?: AbortSignal;
   failureOverride?: () => ChildFailure | undefined;
+  ledgerProjection?: unknown;
+  captureObservations?: boolean;
+  candidateArtifact?: CandidateArtifactSubmission;
+  onStreamStart?: () => void;
+  onStreamProgress?: () => void;
 }): Promise<ChildSessionResult> {
-  const submit = createSubmitTool({
-    requestId: input.requestId,
-    taskId: input.taskId,
-    role: input.role,
-    phase: input.phase ?? "red",
-    output: input.output,
-  });
-  const readTools = wrapScopedTools(input.roots, input.cwd, input.allowedPaths);
+  const segmentedCandidate = input.candidateArtifact !== undefined;
+  const submit = input.candidateArtifact
+    ? createCandidateArtifactTool(input.candidateArtifact)
+    : createSubmitTool({
+        requestId: input.requestId,
+        taskId: input.taskId,
+        role: input.role,
+        phase: input.phase ?? "red",
+        output: input.output,
+      });
+  const observationCollector = input.captureObservations
+    ? new ScopedObservationCollector()
+    : undefined;
+  const readTools = wrapScopedTools(
+    input.roots,
+    input.cwd,
+    input.allowedPaths,
+    observationCollector?.observe,
+  );
   const customTools = [...readTools, submit.tool];
   const toolNames = customTools.map((tool) => tool.name);
   let disposeCount = 0;
   const usage = new UsageAggregator();
+  const effectivePrompt =
+    input.ledgerProjection === undefined
+      ? input.systemPrompt
+      : [
+          input.systemPrompt,
+          "",
+          "<abel-task-ledger-projection>",
+          serializeTaskLedgerProjection(input.ledgerProjection),
+          "</abel-task-ledger-projection>",
+        ].join("\n");
+  const observationMetadata = () =>
+    observationCollector
+      ? { observations: observationCollector.projection() }
+      : {};
   const abort = new AbortController();
   const forwardCancellation = () =>
     abort.abort(input.signal?.reason ?? new Error("child phase cancelled"));
@@ -316,6 +373,24 @@ export async function runChildSession(input: {
   let unsubscribe: (() => void) | undefined;
   let abortSettlement: Promise<void> | undefined;
   let assistantSequence = 0;
+  let streamStarted = false;
+  const notifyStreamStart = () => {
+    if (streamStarted) return;
+    streamStarted = true;
+    try {
+      input.onStreamStart?.();
+    } catch {
+      // Stream observation cannot influence child execution.
+    }
+  };
+  const notifyStreamProgress = () => {
+    notifyStreamStart();
+    try {
+      input.onStreamProgress?.();
+    } catch {
+      // Stream observation cannot influence child execution.
+    }
+  };
   const disposeOnce = () => {
     if (session) {
       session.dispose();
@@ -332,7 +407,9 @@ export async function runChildSession(input: {
       finalCategory = "no-final-assistant";
     } else if (isSingleStructuralSubmit(last)) {
       finalCategory =
-        submit.getAttempts() > 1 ? "multiple-submit" : "single-submit-only";
+        !segmentedCandidate && submit.getAttempts() > 1
+          ? "multiple-submit"
+          : "single-submit-only";
     } else {
       const content = finalDeliveryContent(last);
       finalCategory =
@@ -383,8 +460,11 @@ export async function runChildSession(input: {
     }
     return undefined;
   };
-  const noStructuralSubmit = (): ChildFailure =>
-    submit.getAttempts() === 0
+  const noStructuralSubmit = (): ChildFailure => {
+    const final = session?.messages
+      .filter((message) => message.role === "assistant")
+      .at(-1);
+    return submit.getAttempts() === 0 && !hasStructuralSubmit(final)
       ? {
           kind: "artifact",
           code: "child-no-structural-submit",
@@ -395,6 +475,7 @@ export async function runChildSession(input: {
           code: "invalid-structural-result",
           stage: "structural-submit",
         };
+  };
   try {
     abort.signal.throwIfAborted();
     const creation = createAgentSession({
@@ -404,7 +485,7 @@ export async function runChildSession(input: {
       thinkingLevel: "off",
       tools: toolNames,
       customTools,
-      resourceLoader: new EmptyResourceLoader(input.systemPrompt),
+      resourceLoader: new EmptyResourceLoader(effectivePrompt),
       sessionManager: SessionManager.inMemory(input.cwd),
       settingsManager: SettingsManager.inMemory({
         compaction: { enabled: false },
@@ -419,7 +500,33 @@ export async function runChildSession(input: {
         .catch(() => undefined);
       throw error;
     }
+    const childAgent = session.agent;
+    if (childAgent) {
+      const previousShouldStopAfterTurn = childAgent.shouldStopAfterTurn;
+      childAgent.shouldStopAfterTurn = async (turn, signal) => {
+        if (
+          segmentedCandidate
+            ? submit.getResult() !== undefined
+            : hasStructuralSubmit(turn.message)
+        ) {
+          return true;
+        }
+        return (await previousShouldStopAfterTurn?.(turn, signal)) ?? false;
+      };
+    }
     unsubscribe = session.subscribe((event) => {
+      if (
+        event.type === "message_start" &&
+        event.message.role === "assistant"
+      ) {
+        notifyStreamStart();
+      }
+      if (
+        event.type === "message_update" &&
+        event.message.role === "assistant"
+      ) {
+        notifyStreamProgress();
+      }
       if (event.type === "message_end" && event.message.role === "assistant") {
         usage.add(`assistant:${assistantSequence++}`, event.message.usage);
       }
@@ -438,7 +545,7 @@ export async function runChildSession(input: {
         throw abort.signal.reason;
       }
       await Promise.race([
-        session.prompt(input.systemPrompt, { expandPromptTemplates: false }),
+        session.prompt(effectivePrompt, { expandPromptTemplates: false }),
         new Promise<never>((_, reject) =>
           abort.signal.addEventListener(
             "abort",
@@ -453,7 +560,11 @@ export async function runChildSession(input: {
     const result = submit.getResult();
     const attempts = submit.getAttempts();
     const classification = classifySession();
-    if (!result || attempts !== 1) {
+    const segmentedComplete =
+      segmentedCandidate &&
+      result !== undefined &&
+      (result.kind === "sealed-candidate" || result.kind === "context-request");
+    if (!result || (segmentedCandidate ? !segmentedComplete : attempts !== 1)) {
       const failure = withSubmitDetails(
         submit.getFailure() ??
           input.failureOverride?.() ??
@@ -472,11 +583,16 @@ export async function runChildSession(input: {
         disposeCount,
         usage: usage.total(),
         classification,
+        ...observationMetadata(),
       };
     }
     const assistants = session.messages.filter((m) => m.role === "assistant");
     const final = assistants.at(-1);
-    if (!isSingleStructuralSubmit(final)) {
+    if (
+      !(segmentedCandidate
+        ? segmentedComplete && structuralSubmitCount(final) === 1
+        : isSingleStructuralSubmit(final))
+    ) {
       const failure = {
         kind: "artifact",
         code: "invalid-structural-result",
@@ -493,6 +609,7 @@ export async function runChildSession(input: {
         disposeCount,
         usage: usage.total(),
         classification,
+        ...observationMetadata(),
       };
     }
     disposeOnce();
@@ -504,6 +621,7 @@ export async function runChildSession(input: {
       disposeCount,
       usage: usage.total(),
       classification,
+      ...observationMetadata(),
     };
   } catch (error) {
     if (abort.signal.aborted && session) {
@@ -553,6 +671,7 @@ export async function runChildSession(input: {
       disposeCount,
       usage: usage.total(),
       classification,
+      ...observationMetadata(),
     };
   } finally {
     clearTimeout(timer);