@tangle-network/agent-interface 0.21.0 → 0.22.0

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { 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 { gitObjectSchema, isCanonicalJsonValue, isSafeRelativePath, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
 const entrypointReceiptSchema = z
@@ -257,7 +258,131 @@ export const agentCandidateRunReceiptSchema = z
         });
     }
 });
+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,
+    modelSettlement: agentCandidateModelSettlementEvidenceSchema,
+    taskOutcome: agentCandidateTaskOutcomeEvidenceSchema,
+    benchmarkResult: agentCandidateBenchmarkResultEvidenceSchema,
+    digest: sha256DigestSchema,
+})
+    .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({
+            code: "custom",
+            path: ["modelSettlement", "material", "executionPlanDigest"],
+            message: "model settlement must bind the executed plan",
+        });
+    }
+    if (receipt.trace.modelCallCount !== receipt.fixedUsage.modelCalls) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["trace", "modelCallCount"],
+            message: "trace model-call count must match fixed run usage",
+        });
+    }
+    if (receipt.taskOutcome.material.executionPlanDigest !==
+        receipt.executionPlanDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["taskOutcome", "material", "executionPlanDigest"],
+            message: "task outcome must bind the executed plan",
+        });
+    }
+    if (receipt.benchmarkResult.material.executionPlanDigest !==
+        receipt.executionPlanDigest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["benchmarkResult", "material", "executionPlanDigest"],
+            message: "benchmark result must bind the executed plan",
+        });
+    }
+    if (receipt.benchmarkResult.material.taskOutcomeDigest !==
+        receipt.taskOutcome.digest) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["benchmarkResult", "material", "taskOutcomeDigest"],
+            message: "benchmark result must bind the exact task outcome",
+        });
+    }
+    if (!isCanonicalJsonValue(receipt)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "run receipt must contain only RFC 8785 JSON values",
+        });
+    }
+});
+/** 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.d.ts

@@ -493,6 +493,7 @@ export * from "./agent-candidate-artifact-schema.js";
 export * from "./agent-candidate-code-schema.js";
 export * from "./agent-candidate-execution-plan-schema.js";
 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";

package/dist/agent-candidate-schema.js

@@ -139,6 +139,7 @@ export * from "./agent-candidate-artifact-schema.js";
 export * from "./agent-candidate-code-schema.js";
 export * from "./agent-candidate-execution-plan-schema.js";
 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";

package/dist/agent-candidate.d.ts

@@ -216,6 +216,16 @@ export interface AgentCandidateSpend {
     cachedInputTokens?: number;
     modelCalls: number;
 }
+/** Lossless evaluator-owned usage totals for one candidate execution. */
+export interface AgentCandidateFixedSpend {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    reasoningTokens: number;
+    modelCalls: number;
+    /** Integer billionths of one US dollar. */
+    costUsdNanos: number;
+}
 /** Evidence and ancestry that produced the immutable candidate. */
 export interface AgentCandidateLineage {
     source: "optimizer" | "human" | "import" | "compound";
@@ -513,6 +523,112 @@ export interface AgentCandidateRunReceiptV1 {
     termination: AgentCandidateTermination;
     digest: Sha256Digest;
 }
+/** One evaluator-mediated model call in a terminal settlement. */
+export interface AgentCandidateModelSettlementCall {
+    callId: string;
+    traceSpanId: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    reasoningTokens: number;
+    costUsdNanos: number;
+}
+/** Canonical model-access ledger after the evaluator has revoked the grant. */
+export interface AgentCandidateModelSettlementMaterialV1 {
+    schemaVersion: 1;
+    kind: "agent-candidate-model-settlement-material";
+    executionPlanDigest: Sha256Digest;
+    preparationId: string;
+    grantDigest: Sha256Digest;
+    closed: true;
+    resolved: AgentCandidateResolvedModel;
+    calls: AgentCandidateModelSettlementCall[];
+    usage: AgentCandidateFixedSpend;
+}
+export interface AgentCandidateModelSettlementEvidence {
+    schemaVersion: 1;
+    kind: "agent-candidate-model-settlement";
+    digest: Sha256Digest;
+    material: AgentCandidateModelSettlementMaterialV1;
+    artifact: AgentCandidateCapturedArtifact;
+}
+/** Git identity before or after a task execution. */
+export interface AgentCandidateRepositoryState {
+    identity: string;
+    rootIdentity: string;
+    commit: string;
+    tree: string;
+}
+/** Canonical repository result produced by the candidate on one task. */
+export interface AgentCandidateTaskOutcomeMaterialV1 {
+    schemaVersion: 1;
+    kind: "agent-candidate-task-outcome-material";
+    executionPlanDigest: Sha256Digest;
+    baseRepository: AgentCandidateRepositoryState;
+    resultRepository: AgentCandidateRepositoryState;
+    afterState: AgentCandidateWorkspaceSnapshotEvidence;
+    gitDiff: {
+        format: "git-diff-binary";
+        artifact: AgentCandidateArtifactRef;
+    };
+}
+export interface AgentCandidateTaskOutcomeEvidence {
+    schemaVersion: 1;
+    kind: "agent-candidate-task-outcome";
+    digest: Sha256Digest;
+    material: AgentCandidateTaskOutcomeMaterialV1;
+    artifact: AgentCandidateCapturedArtifact;
+}
+export interface AgentCandidateBenchmarkDimension {
+    name: string;
+    score: number;
+}
+/** Canonical executable-grade result for one task outcome. */
+export interface AgentCandidateBenchmarkResultMaterialV1 {
+    schemaVersion: 1;
+    kind: "agent-candidate-benchmark-result-material";
+    executionPlanDigest: Sha256Digest;
+    taskOutcomeDigest: Sha256Digest;
+    benchmark: {
+        name: string;
+        version: string;
+        taskId: string;
+        splitDigest: Sha256Digest;
+    };
+    grader: {
+        name: string;
+        version: string;
+        artifact: AgentCandidateArtifactRef;
+    };
+    /** Raw grader output required to independently audit the reported verdict. */
+    evidence: AgentCandidateArtifactRef;
+    score: number;
+    passed: boolean;
+    dimensions: AgentCandidateBenchmarkDimension[];
+}
+export interface AgentCandidateBenchmarkResultEvidence {
+    schemaVersion: 1;
+    kind: "agent-candidate-benchmark-result";
+    digest: Sha256Digest;
+    material: AgentCandidateBenchmarkResultMaterialV1;
+    artifact: AgentCandidateCapturedArtifact;
+}
+/**
+ * Terminal candidate receipt with lossless spend, exact repository output,
+ * and executable benchmark evidence. V1 fields remain present for consumers
+ * that have not yet adopted the stronger evidence surfaces.
+ */
+export interface AgentCandidateRunReceiptV2 extends Omit<AgentCandidateRunReceiptV1, "schemaVersion"> {
+    schemaVersion: 2;
+    fixedUsage: AgentCandidateFixedSpend;
+    modelSettlement: AgentCandidateModelSettlementEvidence;
+    taskOutcome: AgentCandidateTaskOutcomeEvidence;
+    benchmarkResult: AgentCandidateBenchmarkResultEvidence;
+}
+/** Backward-compatible V1 receipt name. */
 export type AgentCandidateRunReceipt = AgentCandidateRunReceiptV1;
+/** Explicit parser target for consumers that accept both receipt generations. */
+export type AgentCandidateRunReceiptAnyVersion = AgentCandidateRunReceiptV1 | AgentCandidateRunReceiptV2;
 /** Declare a candidate bundle while retaining literal inference. */
 export declare function defineAgentCandidateBundle<T extends AgentCandidateBundle>(bundle: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",