@abelxiaoxing/cadence 1.0.14 → 1.1.0

package/src/submit-tool.ts

@@ -1,14 +1,17 @@
+import { createHash } from "node:crypto";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
   type CandidateFailure,
   type DiffResult,
   type EvidenceResult,
+  isValidRelativePath,
   type SubmitFinalCategory,
   type SubmitSchemaState,
   validateDiffResult,
   validateEvidenceResult,
 } from "./contracts.ts";
+import type { BeginCandidateInput, TaskLedger } from "./task-ledger.ts";
 
 const compactEvidenceSchema = Type.Object({
   id: Type.String(),
@@ -76,6 +79,277 @@ const diffSchema = Type.Object({
   contractCompliant: Type.Literal(true),
 });
 
+function candidateArtifactSchema(candidateId: string) {
+  return Type.Union([
+    Type.Object(
+      {
+        kind: Type.Literal("candidate-segment"),
+        candidateId: Type.Literal(candidateId),
+        sequence: Type.Integer({ minimum: 0 }),
+        text: Type.String({ minLength: 1 }),
+      },
+      { additionalProperties: false },
+    ),
+    Type.Object(
+      {
+        kind: Type.Literal("candidate-seal"),
+        candidateId: Type.Literal(candidateId),
+      },
+      { additionalProperties: false },
+    ),
+    Type.Object(
+      {
+        kind: Type.Literal("context-request"),
+        candidateId: Type.Literal(candidateId),
+        code: Type.Union([
+          Type.Literal("approved-context-needed"),
+          Type.Literal("task-split-needed"),
+          Type.Literal("boundary-review-needed"),
+        ]),
+        refs: Type.Array(Type.String(), { maxItems: 32 }),
+      },
+      { additionalProperties: false },
+    ),
+  ]);
+}
+
+export type CandidateArtifactSubmissionResult =
+  | {
+      kind: "sealed-candidate";
+      candidateId: string;
+      state: "sealed";
+      artifactHash: string;
+      bytes: number;
+      paths: string[];
+      replayed?: true;
+    }
+  | {
+      kind: "context-request";
+      candidateId: string;
+      code:
+        | "approved-context-needed"
+        | "task-split-needed"
+        | "boundary-review-needed";
+      refs: string[];
+    };
+
+export type CandidateContextRequest = Extract<
+  CandidateArtifactSubmissionResult,
+  { kind: "context-request" }
+>;
+
+export interface ClassifiedCandidateContextRequest {
+  kind: "paused" | "approval-needed";
+  code:
+    | "approved-context-needed"
+    | "task-split-needed"
+    | "boundary-review-needed";
+  contextRequest: {
+    code: CandidateContextRequest["code"];
+    refs: string[];
+  };
+}
+
+function contextRefWithinBoundary(relative: string, approved: string): boolean {
+  return (
+    approved === "." ||
+    relative === approved ||
+    relative.startsWith(`${approved}/`)
+  );
+}
+
+export function classifyCandidateContextRequest(
+  request: CandidateContextRequest,
+  approvedPaths: readonly string[],
+): ClassifiedCandidateContextRequest {
+  const refs = [...request.refs];
+  const inBoundary =
+    refs.length > 0 &&
+    refs.every((relative) =>
+      approvedPaths.some((approved) =>
+        contextRefWithinBoundary(relative, approved),
+      ),
+    );
+  const approvalNeeded =
+    !inBoundary || request.code === "boundary-review-needed";
+  return {
+    kind: approvalNeeded ? "approval-needed" : "paused",
+    code: inBoundary ? request.code : "boundary-review-needed",
+    contextRequest: {
+      code: request.code,
+      refs,
+    },
+  };
+}
+
+export interface CandidateArtifactSubmission {
+  ledger: Pick<
+    TaskLedger,
+    "beginCandidate" | "appendCandidateSegment" | "sealCandidate"
+  >;
+  identity: BeginCandidateInput;
+}
+
+export function createCandidateArtifactTool(
+  input: CandidateArtifactSubmission,
+) {
+  input.ledger.beginCandidate(input.identity);
+  const parameters = candidateArtifactSchema(input.identity.candidateId);
+  let result: CandidateArtifactSubmissionResult | undefined;
+  let failure: CandidateFailure | undefined;
+  let attempts = 0;
+  let schema: SubmitSchemaState = "not-submitted";
+  let segmentCount = 0;
+  let totalBytes = 0;
+  const candidateHash = createHash("sha256");
+  const identity: IdentityOutcome = {
+    request: true,
+    role: true,
+    task: true,
+    phase: true,
+  };
+  const tool = defineTool<typeof parameters, unknown>({
+    name: "abel_submit_result",
+    label: "Submit Abel Candidate Artifact",
+    description:
+      "Submit ordered raw-text candidate segments, atomically seal the complete candidate, or request bounded approved context. Encoding and hashes are computed by this trusted tool.",
+    executionMode: "sequential",
+    parameters,
+    async execute(_toolCallId, params) {
+      if (result !== undefined) {
+        throw new Error("candidate terminal result already submitted");
+      }
+      attempts++;
+      const value = params as unknown as Record<string, unknown>;
+      if (value.candidateId !== input.identity.candidateId) {
+        identity.request = false;
+        schema = "invalid";
+        failure = {
+          kind: "artifact",
+          code: "structural-identity-mismatch",
+          stage: "structural-submit",
+        };
+        throw new Error("candidate identity mismatch");
+      }
+      schema = "valid";
+      if (value.kind === "candidate-segment") {
+        const bytes = Buffer.from(value.text as string, "utf8");
+        const segmentHash = createHash("sha256").update(bytes).digest("hex");
+        let accepted: ReturnType<
+          CandidateArtifactSubmission["ledger"]["appendCandidateSegment"]
+        >;
+        try {
+          accepted = input.ledger.appendCandidateSegment({
+            ...input.identity,
+            sequence: value.sequence as number,
+            bytes,
+            segmentHash,
+          });
+        } catch (error) {
+          schema = "invalid";
+          failure = {
+            kind: "artifact",
+            code: "invalid-diff",
+            stage: "candidate-diff",
+          };
+          throw error;
+        }
+        if (!accepted.ok) {
+          failure = {
+            kind: "result-limit",
+            limitBytes: accepted.limitBytes,
+          };
+        } else {
+          candidateHash.update(bytes);
+          segmentCount = accepted.nextSequence;
+          totalBytes = accepted.totalBytes;
+        }
+        return {
+          content: [
+            { type: "text" as const, text: "Candidate segment accepted." },
+          ],
+          details: accepted,
+          ...(!accepted.ok ? { terminate: true } : {}),
+        };
+      }
+      if (value.kind === "candidate-seal") {
+        let sealed: ReturnType<
+          CandidateArtifactSubmission["ledger"]["sealCandidate"]
+        >;
+        try {
+          sealed = input.ledger.sealCandidate({
+            ...input.identity,
+            segmentCount,
+            totalBytes,
+            candidateHash: candidateHash.digest("hex"),
+          });
+        } catch (error) {
+          schema = "invalid";
+          const mismatch =
+            error instanceof Error &&
+            error.message === "candidate-write-set-mismatch";
+          failure = {
+            kind: "artifact",
+            code: mismatch ? "write-set-mismatch" : "invalid-diff",
+            stage: "candidate-diff",
+          };
+          throw error;
+        }
+        if (!sealed.ok) return { content: [], details: sealed };
+        result = {
+          kind: "sealed-candidate",
+          candidateId: input.identity.candidateId,
+          state: "sealed",
+          artifactHash: sealed.artifactHash,
+          bytes: sealed.bytes,
+          paths: [...sealed.paths],
+          ...(sealed.replayed ? { replayed: true } : {}),
+        };
+        return {
+          content: [
+            { type: "text" as const, text: "Candidate artifact sealed." },
+          ],
+          details: sealed,
+          terminate: true,
+        };
+      }
+      const refs = value.refs as string[];
+      if (
+        refs.some((relative) => !isValidRelativePath(relative)) ||
+        new Set(refs).size !== refs.length
+      ) {
+        throw new Error("context request refs are invalid");
+      }
+      result = {
+        kind: "context-request",
+        candidateId: input.identity.candidateId,
+        code: value.code as Extract<
+          CandidateArtifactSubmissionResult,
+          { kind: "context-request" }
+        >["code"],
+        refs: [...refs],
+      };
+      return {
+        content: [
+          { type: "text" as const, text: "Bounded context request accepted." },
+        ],
+        details: result,
+        terminate: true,
+      };
+    },
+  });
+  return {
+    tool,
+    getResult: () =>
+      result === undefined ? undefined : structuredClone(result),
+    getAttempts: () => attempts,
+    getSchema: () => schema,
+    getIdentity: () => ({ ...identity }),
+    getFailure: () =>
+      failure === undefined ? undefined : structuredClone(failure),
+  };
+}
+
 export type FinalCategory = SubmitFinalCategory;
 
 export interface IdentityOutcome {