@tangle-network/agent-interface 0.25.0 → 0.26.0

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

@@ -1,8 +1,7 @@
 import { z } from "zod";
-import { agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
+import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
 import { agentCandidateExecutionPlanEvidenceSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateResolvedModelSchema, } from "./agent-candidate-execution-plan-schema.js";
-import { agentCandidateSpendSchema, } from "./agent-candidate-lineage-schema.js";
-import { agentCandidateBenchmarkResultEvidenceSchema, agentCandidateFixedSpendSchema, agentCandidateModelSettlementEvidenceSchema, agentCandidateTaskOutcomeEvidenceSchema, sameFixedSpend, } from "./agent-candidate-outcome-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";
 const entrypointReceiptSchema = z
@@ -45,12 +44,6 @@ export const agentCandidateTraceEvidenceSchema = z
         });
     }
 });
-export const agentCandidateModelUsageSchema = z
-    .object({
-    resolved: agentCandidateResolvedModelSchema,
-    usage: agentCandidateSpendSchema,
-})
-    .strict();
 export const agentCandidateMemoryReceiptSchema = z.discriminatedUnion("mode", [
     z.object({ mode: z.literal("disabled") }).strict(),
     z
@@ -82,7 +75,7 @@ export const agentCandidateTerminationSchema = z.discriminatedUnion("kind", [
 ]);
 export const agentCandidateMaterializationReceiptSchema = z
     .object({
-    schemaVersion: z.literal(1),
+    schemaVersion: z.literal(2),
     kind: z.literal("agent-candidate-materialization"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     bundleDigest: sha256DigestSchema,
@@ -216,62 +209,16 @@ export const agentCandidateMaterializationReceiptSchema = z
 });
 export const agentCandidateRunReceiptSchema = z
     .object({
-    schemaVersion: z.literal(1),
+    schemaVersion: z.literal(3),
     kind: z.literal("agent-candidate-run"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     bundleDigest: sha256DigestSchema,
     materializationReceiptDigest: sha256DigestSchema,
     executionPlanDigest: sha256DigestSchema,
     memory: agentCandidateMemoryReceiptSchema,
-    usage: agentCandidateSpendSchema,
-    modelUsage: agentCandidateModelUsageSchema,
     trace: agentCandidateTraceEvidenceSchema,
     termination: agentCandidateTerminationSchema,
-    digest: sha256DigestSchema,
-})
-    .strict()
-    .superRefine((receipt, ctx) => {
-    const usageMatchesModel = receipt.usage.costUsd === receipt.modelUsage.usage.costUsd &&
-        receipt.usage.inputTokens === receipt.modelUsage.usage.inputTokens &&
-        receipt.usage.outputTokens === receipt.modelUsage.usage.outputTokens &&
-        receipt.usage.cachedInputTokens ===
-            receipt.modelUsage.usage.cachedInputTokens &&
-        receipt.usage.modelCalls === receipt.modelUsage.usage.modelCalls;
-    if (!usageMatchesModel) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["modelUsage", "usage"],
-            message: "single-model usage must equal aggregate protected usage",
-        });
-    }
-    if (receipt.trace.modelCallCount !== receipt.modelUsage.usage.modelCalls) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["trace", "modelCallCount"],
-            message: "trace model-call count must match protected single-model usage",
-        });
-    }
-    if (!isCanonicalJsonValue(receipt)) {
-        ctx.addIssue({
-            code: "custom",
-            message: "run receipt must contain only RFC 8785 JSON values",
-        });
-    }
-});
-export const agentCandidateRunReceiptV2Schema = z
-    .object({
-    schemaVersion: z.literal(2),
-    kind: z.literal("agent-candidate-run"),
-    digestAlgorithm: z.literal("rfc8785-sha256"),
-    bundleDigest: sha256DigestSchema,
-    materializationReceiptDigest: sha256DigestSchema,
-    executionPlanDigest: sha256DigestSchema,
-    memory: agentCandidateMemoryReceiptSchema,
-    usage: agentCandidateSpendSchema,
-    modelUsage: agentCandidateModelUsageSchema,
-    trace: agentCandidateTraceEvidenceSchema,
-    termination: agentCandidateTerminationSchema,
-    fixedUsage: agentCandidateFixedSpendSchema,
+    executorCapture: agentCandidateArtifactRefSchema,
     modelSettlement: agentCandidateModelSettlementEvidenceSchema,
     taskOutcome: agentCandidateTaskOutcomeEvidenceSchema,
     benchmarkResult: agentCandidateBenchmarkResultEvidenceSchema,
@@ -279,41 +226,6 @@ export const agentCandidateRunReceiptV2Schema = z
 })
     .strict()
     .superRefine((receipt, ctx) => {
-    const legacyUsageMatchesModel = receipt.usage.costUsd === receipt.modelUsage.usage.costUsd &&
-        receipt.usage.inputTokens === receipt.modelUsage.usage.inputTokens &&
-        receipt.usage.outputTokens === receipt.modelUsage.usage.outputTokens &&
-        receipt.usage.cachedInputTokens ===
-            receipt.modelUsage.usage.cachedInputTokens &&
-        receipt.usage.modelCalls === receipt.modelUsage.usage.modelCalls;
-    if (!legacyUsageMatchesModel) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["modelUsage", "usage"],
-            message: "single-model usage must equal aggregate protected usage",
-        });
-    }
-    if (!legacyUsageMatchesFixed(receipt.usage, receipt.fixedUsage)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["fixedUsage"],
-            message: "fixed usage must exactly preserve the legacy usage totals",
-        });
-    }
-    if (!sameFixedSpend(receipt.fixedUsage, receipt.modelSettlement.material.usage)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["modelSettlement", "material", "usage"],
-            message: "model settlement aggregate must equal fixed run usage",
-        });
-    }
-    if (JSON.stringify(receipt.modelUsage.resolved) !==
-        JSON.stringify(receipt.modelSettlement.material.resolved)) {
-        ctx.addIssue({
-            code: "custom",
-            path: ["modelSettlement", "material", "resolved"],
-            message: "model settlement must bind the run's resolved model",
-        });
-    }
     if (receipt.modelSettlement.material.executionPlanDigest !==
         receipt.executionPlanDigest) {
         ctx.addIssue({
@@ -322,7 +234,8 @@ export const agentCandidateRunReceiptV2Schema = z
             message: "model settlement must bind the executed plan",
         });
     }
-    if (receipt.trace.modelCallCount !== receipt.fixedUsage.modelCalls) {
+    if (receipt.trace.modelCallCount !==
+        receipt.modelSettlement.material.usage.modelCalls) {
         ctx.addIssue({
             code: "custom",
             path: ["trace", "modelCallCount"],
@@ -360,29 +273,7 @@ export const agentCandidateRunReceiptV2Schema = z
         });
     }
 });
-/** Explicit V1 alias; the original schema export remains unchanged. */
-export const agentCandidateRunReceiptV1Schema = agentCandidateRunReceiptSchema;
-/** Parses both receipt generations without changing the original V1 export. */
-export const agentCandidateRunReceiptAnyVersionSchema = z.union([
-    agentCandidateRunReceiptSchema,
-    agentCandidateRunReceiptV2Schema,
-]);
-function legacyUsageMatchesFixed(legacy, fixed) {
-    return (legacy.costUsd === fixed.costUsdNanos / 1_000_000_000 &&
-        legacy.inputTokens === fixed.inputTokens &&
-        legacy.outputTokens === fixed.outputTokens &&
-        (legacy.cachedInputTokens ?? 0) === fixed.cachedInputTokens &&
-        legacy.modelCalls === fixed.modelCalls);
-}
 const _materializationReceiptSchemaMatchesType = true;
 const _runReceiptSchemaMatchesType = true;
-const _anyRunReceiptSchemaMatchesType = true;
-const _runReceiptV1SchemaMatchesType = true;
-const _runReceiptV2SchemaMatchesType = true;
-const _v2MustNotSatisfyOriginalReceipt = true;
 void _materializationReceiptSchemaMatchesType;
 void _runReceiptSchemaMatchesType;
-void _anyRunReceiptSchemaMatchesType;
-void _runReceiptV1SchemaMatchesType;
-void _runReceiptV2SchemaMatchesType;
-void _v2MustNotSatisfyOriginalReceipt;

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

@@ -4,6 +4,8 @@ export declare const sha256DigestSchema: z.ZodType<Sha256Digest>;
 export declare const gitObjectSchema: z.ZodString;
 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 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

@@ -1,8 +1,10 @@
+import { sha256 } from "@noble/hashes/sha256";
 import { z } from "zod";
 const sha256Pattern = /^sha256:[a-f0-9]{64}$/;
 const gitObjectPattern = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const environmentNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const headerNamePattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const mediaTypePattern = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/;
 const githubComponentPattern = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
 const secretNamePattern = /(?:^|[_-])(?:api[_-]?key|access[_-]?key|private[_-]?key|token|secret|password|credentials?|authorization|cookie|database[_-]?url|dsn|pat)(?:[_-]|$)/i;
 const obviousSecretValuePattern = /(?:\b(?:sk|gh[pousr]|github_pat|AKIA)[-_A-Za-z0-9]{12,}\b|-----BEGIN [A-Z ]*PRIVATE KEY-----|\bBearer\s+\S+)/;
@@ -29,6 +31,12 @@ export const sha256DigestSchema = z
 export const gitObjectSchema = z.string().regex(gitObjectPattern);
 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));
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `sha256:${hex}`;
+}
 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,7 @@ import { z } from "zod";
  * compares lowercase `sha256:<hex>` identities before materialization.
  */
 export declare const agentCandidateBundleSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
+    schemaVersion: z.ZodLiteral<2>;
     kind: z.ZodLiteral<"agent-candidate-bundle">;
     digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
     profile: z.ZodObject<{
@@ -359,15 +359,15 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             kind: z.ZodLiteral<"evaluator-task-container">;
         }, z.core.$strict>], "kind">;
         workspace: z.ZodOptional<z.ZodObject<{
-            schemaVersion: z.ZodLiteral<1>;
+            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<1>;
+                schemaVersion: z.ZodLiteral<2>;
                 kind: z.ZodLiteral<"agent-candidate-workspace-manifest">;
                 files: z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
-                    mode: z.ZodUnion<readonly [z.ZodLiteral<420>, z.ZodLiteral<493>]>;
+                    mode: z.ZodNumber;
                     sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
                     byteLength: z.ZodNumber;
                 }, z.core.$strict>>;
@@ -418,8 +418,71 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>;
     knowledge: z.ZodOptional<z.ZodObject<{
-        snapshotId: z.ZodString;
-        manifest: z.ZodObject<{
+        candidate: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            kind: z.ZodLiteral<"knowledge-improvement-candidate">;
+            runId: z.ZodString;
+            candidateId: z.ZodString;
+            goalHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            baseHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            candidateHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            evidenceHash: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            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;
+                    mode: z.ZodNumber;
+                    sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                    byteLength: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            manifest: z.ZodUnion<readonly [z.ZodObject<{
+                locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"s3">;
+                    bucket: z.ZodString;
+                    key: z.ZodString;
+                    region: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"ipfs">;
+                    cid: z.ZodString;
+                    path: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>], "kind">;
+                sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                byteLength: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                encoding: z.ZodLiteral<"base64">;
+                content: z.ZodString;
+                sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                byteLength: z.ZodNumber;
+            }, z.core.$strict>]>;
+            archive: z.ZodUnion<readonly [z.ZodObject<{
+                locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"s3">;
+                    bucket: z.ZodString;
+                    key: z.ZodString;
+                    region: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"ipfs">;
+                    cid: z.ZodString;
+                    path: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>], "kind">;
+                sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                byteLength: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                encoding: z.ZodLiteral<"base64">;
+                content: z.ZodString;
+                sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                byteLength: z.ZodNumber;
+            }, z.core.$strict>]>;
+        }, z.core.$strict>;
+        retrievalConfig: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 kind: z.ZodLiteral<"s3">;
                 bucket: z.ZodString;
@@ -432,7 +495,31 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             }, z.core.$strict>], "kind">;
             sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
             byteLength: z.ZodNumber;
-        }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            encoding: z.ZodLiteral<"base64">;
+            content: z.ZodString;
+            sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>]>>;
+        evaluation: z.ZodUnion<readonly [z.ZodObject<{
+            locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"s3">;
+                bucket: z.ZodString;
+                key: z.ZodString;
+                region: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"ipfs">;
+                cid: z.ZodString;
+                path: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>], "kind">;
+            sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            encoding: z.ZodLiteral<"base64">;
+            content: z.ZodString;
+            sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            byteLength: z.ZodNumber;
+        }, z.core.$strict>]>;
     }, z.core.$strict>>;
     memory: z.ZodDiscriminatedUnion<[z.ZodObject<{
         mode: z.ZodLiteral<"disabled">;

package/dist/agent-candidate-schema.js

@@ -14,7 +14,7 @@ import { canonicalizeHarness } from "./harness.js";
  */
 export const agentCandidateBundleSchema = z
     .object({
-    schemaVersion: z.literal(1),
+    schemaVersion: z.literal(2),
     kind: z.literal("agent-candidate-bundle"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     profile: agentCandidateProfileSchema,