@tangle-network/agent-interface 0.27.2 → 0.29.0

package/dist/agent-candidate-receipt-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
-import { agentCandidateExecutionPlanEvidenceSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
+import { agentCandidateExecutionPlanEvidenceSchema, agentCandidateProfileActivationSchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
 import { agentCandidateBenchmarkResultEvidenceSchema, agentCandidateModelSettlementEvidenceSchema, agentCandidateTaskOutcomeEvidenceSchema, } from "./agent-candidate-outcome-schema.js";
 import { gitObjectSchema, isCanonicalJsonValue, isSafeRelativePath, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
@@ -20,9 +20,36 @@ const ociPlatformSchema = z
     variant: z.string().min(1).optional(),
 })
     .strict();
+const benchmarkMaterialEvidenceSchema = z
+    .object({
+    digest: sha256DigestSchema,
+    material: agentCandidateCapturedArtifactSchema,
+})
+    .strict()
+    .superRefine((evidence, ctx) => {
+    if (evidence.material.sha256 !== evidence.digest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["material", "sha256"],
+            message: "benchmark material artifact must match its canonical digest",
+        });
+    }
+    if (evidence.material.byteLength === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["material", "byteLength"],
+            message: "benchmark material artifact must contain canonical bytes",
+        });
+    }
+});
+export const agentCandidateBenchmarkInputEvidenceSchema = z
+    .object({
+    suite: benchmarkMaterialEvidenceSchema,
+    task: benchmarkMaterialEvidenceSchema,
+})
+    .strict();
 export const agentCandidateTraceEvidenceSchema = z
     .object({
-    schemaVersion: z.literal(1),
     artifact: agentCandidateCapturedArtifactSchema,
     eventCount: z.number().int().positive(),
     modelCallCount: z.number().int().nonnegative(),
@@ -75,11 +102,11 @@ export const agentCandidateTerminationSchema = z.discriminatedUnion("kind", [
 ]);
 export const agentCandidateMaterializationReceiptSchema = z
     .object({
-    schemaVersion: z.literal(2),
     kind: z.literal("agent-candidate-materialization"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     bundleDigest: sha256DigestSchema,
-    profilePlan: agentCandidateProfilePlanEvidenceSchema,
+    benchmark: agentCandidateBenchmarkInputEvidenceSchema,
+    profileActivation: agentCandidateProfileActivationSchema,
     executionPlan: agentCandidateExecutionPlanEvidenceSchema,
     candidateWorkspace: agentCandidateWorkspaceSnapshotEvidenceSchema.optional(),
     codeKind: z.enum(["disabled", "no-op", "git-patch"]),
@@ -135,18 +162,28 @@ export const agentCandidateMaterializationReceiptSchema = z
     }
     const checks = [
         [
-            receipt.bundleDigest === plan.bundleDigest,
-            ["executionPlan", "material", "bundleDigest"],
+            receipt.bundleDigest === plan.runCell.bundleDigest,
+            ["executionPlan", "material", "runCell", "bundleDigest"],
             "execution plan must bind the receipt bundle",
         ],
         [
-            receipt.profilePlan.digest === plan.profile.planDigest,
+            receipt.benchmark.suite.digest === plan.runCell.suiteDigest,
+            ["benchmark", "suite", "digest"],
+            "execution plan must bind the captured benchmark suite",
+        ],
+        [
+            receipt.benchmark.task.digest === plan.runCell.taskDigest,
+            ["benchmark", "task", "digest"],
+            "execution plan must bind the captured benchmark task",
+        ],
+        [
+            receipt.profileActivation.profilePlan.digest === plan.profile.planDigest,
             ["executionPlan", "material", "profile", "planDigest"],
             "execution plan must bind the exact profile plan",
         ],
         [
             JSON.stringify(plan.profile.mountPaths) ===
-                JSON.stringify(receipt.profilePlan.material.files.map((file) => file.relPath)),
+                JSON.stringify(receipt.profileActivation.profilePlan.material.files.map((file) => file.relPath)),
             ["executionPlan", "material", "profile", "mountPaths"],
             "execution plan must bind every profile mount path",
         ],
@@ -191,8 +228,8 @@ export const agentCandidateMaterializationReceiptSchema = z
             "execution plan must bind the exact uploaded candidate workspace",
         ],
         [
-            receipt.profilePlan.material.harness === receipt.harness,
-            ["profilePlan", "material", "harness"],
+            receipt.profileActivation.profilePlan.material.harness === receipt.harness,
+            ["profileActivation", "profilePlan", "material", "harness"],
             "profile plan harness must match materialization",
         ],
     ];
@@ -209,12 +246,19 @@ export const agentCandidateMaterializationReceiptSchema = z
 });
 export const agentCandidateRunReceiptSchema = z
     .object({
-    schemaVersion: z.literal(3),
     kind: z.literal("agent-candidate-run"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     bundleDigest: sha256DigestSchema,
+    runCellDigest: sha256DigestSchema,
     materializationReceiptDigest: sha256DigestSchema,
     executionPlanDigest: sha256DigestSchema,
+    timing: z
+        .object({
+        startedAtMs: z.number().int().nonnegative().safe(),
+        endedAtMs: z.number().int().nonnegative().safe(),
+        durationMs: z.number().int().nonnegative().safe(),
+    })
+        .strict(),
     memory: agentCandidateMemoryReceiptSchema,
     trace: agentCandidateTraceEvidenceSchema,
     termination: agentCandidateTerminationSchema,
@@ -226,6 +270,15 @@ export const agentCandidateRunReceiptSchema = z
 })
     .strict()
     .superRefine((receipt, ctx) => {
+    if (receipt.timing.endedAtMs < receipt.timing.startedAtMs ||
+        receipt.timing.durationMs !==
+            receipt.timing.endedAtMs - receipt.timing.startedAtMs) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["timing"],
+            message: "run timing must be ordered and internally consistent",
+        });
+    }
     if (receipt.modelSettlement.material.executionPlanDigest !==
         receipt.executionPlanDigest) {
         ctx.addIssue({
@@ -234,6 +287,24 @@ export const agentCandidateRunReceiptSchema = z
             message: "model settlement must bind the executed plan",
         });
     }
+    for (const [index, call] of receipt.modelSettlement.material.calls.entries()) {
+        if (call.startedAtMs < receipt.timing.startedAtMs ||
+            call.endedAtMs > receipt.timing.endedAtMs) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["modelSettlement", "material", "calls", index],
+                message: "model calls must occur within the recorded run",
+            });
+        }
+    }
+    if (receipt.benchmarkResult.material.grading.timing.startedAtMs <
+        receipt.timing.endedAtMs) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["benchmarkResult", "material", "grading", "timing", "startedAtMs"],
+            message: "grading must start after candidate execution ends",
+        });
+    }
     if (receipt.trace.modelCallCount !==
         receipt.modelSettlement.material.usage.modelCalls) {
         ctx.addIssue({

package/dist/agent-candidate-schema-common.d.ts

@@ -6,6 +6,14 @@ export declare const environmentNameSchema: z.ZodString;
 export declare const headerNameSchema: z.ZodString;
 export declare const agentCandidateMediaTypeSchema: z.ZodString;
 export declare function sha256Utf8(value: string): Sha256Digest;
+export declare function sha256Bytes(value: Uint8Array): Sha256Digest;
+/** RFC 8785 serialization used by every candidate-producing package. */
+export declare function canonicalCandidateJson(value: unknown): string;
+export declare function canonicalCandidateBytes(value: unknown): Uint8Array;
+export declare function canonicalCandidateDigest(value: unknown): Sha256Digest;
+export declare function omitTopLevelDigest<T extends {
+    digest: Sha256Digest;
+}>(value: T): Omit<T, "digest">;
 export declare function isWellFormedUnicode(value: string): boolean;
 export declare function isSafeRelativePath(value: string, allowDot: boolean): boolean;
 export declare function isSafeExecutable(value: string): boolean;

package/dist/agent-candidate-schema-common.js

@@ -33,10 +33,44 @@ export const environmentNameSchema = z.string().regex(environmentNamePattern);
 export const headerNameSchema = z.string().regex(headerNamePattern);
 export const agentCandidateMediaTypeSchema = z.string().regex(mediaTypePattern);
 export function sha256Utf8(value) {
-    const bytes = sha256(new TextEncoder().encode(value));
+    return sha256Bytes(new TextEncoder().encode(value));
+}
+export function sha256Bytes(value) {
+    const bytes = sha256(value);
     const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
     return `sha256:${hex}`;
 }
+/** RFC 8785 serialization used by every candidate-producing package. */
+export function canonicalCandidateJson(value) {
+    if (!isCanonicalJsonValue(value)) {
+        throw new Error("candidate document must be finite, acyclic RFC 8785 JSON");
+    }
+    return serializeCanonicalCandidate(value);
+}
+export function canonicalCandidateBytes(value) {
+    return new TextEncoder().encode(canonicalCandidateJson(value));
+}
+export function canonicalCandidateDigest(value) {
+    return sha256Bytes(canonicalCandidateBytes(value));
+}
+export function omitTopLevelDigest(value) {
+    const { digest: _digest, ...material } = value;
+    return material;
+}
+function serializeCanonicalCandidate(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "number") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(serializeCanonicalCandidate).join(",")}]`;
+    }
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${serializeCanonicalCandidate(value[key])}`)
+        .join(",")}}`;
+}
 export function isWellFormedUnicode(value) {
     for (let index = 0; index < value.length; index++) {
         const code = value.charCodeAt(index);

package/dist/agent-candidate-schema.d.ts

@@ -8,7 +8,6 @@ import { z } from "zod";
  * compares lowercase `sha256:<hex>` identities before materialization.
  */
 export declare const agentCandidateBundleSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<2>;
     kind: z.ZodLiteral<"agent-candidate-bundle">;
     digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
     profile: z.ZodObject<{
@@ -251,10 +250,6 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
     }, z.core.$strict>;
     code: z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"disabled">;
-        reason: z.ZodEnum<{
-            control: "control";
-            "not-applicable": "not-applicable";
-        }>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"no-op">;
         reason: z.ZodLiteral<"proposer-no-change">;
@@ -359,11 +354,9 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             kind: z.ZodLiteral<"evaluator-task-container">;
         }, z.core.$strict>], "kind">;
         workspace: z.ZodOptional<z.ZodObject<{
-            schemaVersion: z.ZodLiteral<2>;
             kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
             digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             material: z.ZodObject<{
-                schemaVersion: z.ZodLiteral<2>;
                 kind: z.ZodLiteral<"agent-candidate-workspace-manifest">;
                 files: z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
@@ -419,7 +412,6 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
     }, z.core.$strict>;
     knowledge: z.ZodOptional<z.ZodObject<{
         candidate: z.ZodObject<{
-            schemaVersion: z.ZodLiteral<1>;
             kind: z.ZodLiteral<"knowledge-improvement-candidate">;
             runId: z.ZodString;
             candidateId: z.ZodString;
@@ -430,11 +422,9 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             promotionPlanHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         }, z.core.$strict>;
         snapshot: z.ZodObject<{
-            schemaVersion: z.ZodLiteral<2>;
             kind: z.ZodLiteral<"agent-candidate-workspace-snapshot">;
             digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             material: z.ZodObject<{
-                schemaVersion: z.ZodLiteral<2>;
                 kind: z.ZodLiteral<"agent-candidate-workspace-manifest">;
                 files: z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
@@ -541,39 +531,6 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             byteLength: z.ZodNumber;
         }, z.core.$strict>>;
     }, z.core.$strict>], "mode">;
-    lineage: z.ZodObject<{
-        source: z.ZodEnum<{
-            optimizer: "optimizer";
-            human: "human";
-            import: "import";
-            compound: "compound";
-        }>;
-        parentDigests: z.ZodOptional<z.ZodArray<z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>>>;
-        runIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        profileDiffIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        modelSnapshots: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        benchmark: z.ZodOptional<z.ZodObject<{
-            name: z.ZodString;
-            version: z.ZodString;
-            splitDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
-        }, z.core.$strict>>;
-        spend: z.ZodOptional<z.ZodObject<{
-            proposal: z.ZodObject<{
-                costUsd: z.ZodNumber;
-                inputTokens: z.ZodNumber;
-                outputTokens: z.ZodNumber;
-                cachedInputTokens: z.ZodOptional<z.ZodNumber>;
-                modelCalls: z.ZodNumber;
-            }, z.core.$strict>;
-            evaluation: z.ZodObject<{
-                costUsd: z.ZodNumber;
-                inputTokens: z.ZodNumber;
-                outputTokens: z.ZodNumber;
-                cachedInputTokens: z.ZodOptional<z.ZodNumber>;
-                modelCalls: z.ZodNumber;
-            }, z.core.$strict>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>;
     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
 }, z.core.$strict>;
 export * from "./agent-candidate-artifact-schema.js";
@@ -583,4 +540,5 @@ export * from "./agent-candidate-lineage-schema.js";
 export * from "./agent-candidate-outcome-schema.js";
 export * from "./agent-candidate-profile-schema.js";
 export * from "./agent-candidate-receipt-schema.js";
-export { sha256DigestSchema } from "./agent-candidate-schema-common.js";
+export * from "./agent-candidate-task-schema.js";
+export { canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, omitTopLevelDigest, sha256Bytes, sha256DigestSchema, sha256Utf8, } from "./agent-candidate-schema-common.js";

package/dist/agent-candidate-schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { agentCandidateCodeSchema, agentCandidateExecutionSchema } from "./agent-candidate-code-schema.js";
 import { agentCandidateProfileSchema } from "./agent-candidate-profile-schema.js";
-import { agentCandidateKnowledgeSchema, agentCandidateLineageSchema, agentCandidateMemoryPolicySchema, } from "./agent-candidate-lineage-schema.js";
+import { agentCandidateKnowledgeSchema, agentCandidateMemoryPolicySchema, } from "./agent-candidate-lineage-schema.js";
 import { isCanonicalJsonValue, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { canonicalizeHarness } from "./harness.js";
 /**
@@ -14,7 +14,6 @@ import { canonicalizeHarness } from "./harness.js";
  */
 export const agentCandidateBundleSchema = z
     .object({
-    schemaVersion: z.literal(2),
     kind: z.literal("agent-candidate-bundle"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     profile: agentCandidateProfileSchema,
@@ -22,7 +21,6 @@ export const agentCandidateBundleSchema = z
     execution: agentCandidateExecutionSchema,
     knowledge: agentCandidateKnowledgeSchema.optional(),
     memory: agentCandidateMemoryPolicySchema,
-    lineage: agentCandidateLineageSchema,
     digest: sha256DigestSchema,
 })
     .strict()
@@ -42,13 +40,6 @@ export const agentCandidateBundleSchema = z
             message: "execution harness must match the candidate profile preference",
         });
     }
-    if (bundle.lineage.parentDigests?.includes(bundle.digest)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["lineage", "parentDigests"],
-            message: "a candidate cannot name itself as a parent",
-        });
-    }
     if (bundle.code.kind === "disabled") {
         if (bundle.execution.cwd.workspace !== "task") {
             ctx.addIssue({
@@ -71,15 +62,6 @@ export const agentCandidateBundleSchema = z
                 message: "disabled code cannot carry a candidate workspace",
             });
         }
-        if (bundle.code.reason === "control" &&
-            (bundle.lineage.source === "optimizer" ||
-                bundle.lineage.source === "compound")) {
-            ctx.addIssue({
-                code: "custom",
-                path: ["lineage", "source"],
-                message: "fixed controls cannot claim proposer lineage",
-            });
-        }
     }
     else {
         const launch = bundle.execution.launch;
@@ -122,15 +104,6 @@ export const agentCandidateBundleSchema = z
                 });
             }
         }
-        if (bundle.code.kind === "no-op" &&
-            bundle.lineage.source !== "optimizer" &&
-            bundle.lineage.source !== "compound") {
-            ctx.addIssue({
-                code: "custom",
-                path: ["lineage", "source"],
-                message: "proposer no-op candidates require optimizer or compound lineage",
-            });
-        }
     }
 });
 const _bundleSchemaMatchesType = true;
@@ -142,4 +115,5 @@ export * from "./agent-candidate-lineage-schema.js";
 export * from "./agent-candidate-outcome-schema.js";
 export * from "./agent-candidate-profile-schema.js";
 export * from "./agent-candidate-receipt-schema.js";
-export { sha256DigestSchema } from "./agent-candidate-schema-common.js";
+export * from "./agent-candidate-task-schema.js";
+export { canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, omitTopLevelDigest, sha256Bytes, sha256DigestSchema, sha256Utf8, } from "./agent-candidate-schema-common.js";