@tangle-network/agent-interface 0.21.0 → 0.23.0

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

@@ -0,0 +1,293 @@
+import { z } from "zod";
+import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
+import { agentCandidateResolvedModelSchema } from "./agent-candidate-execution-plan-schema.js";
+import { gitObjectSchema, isCanonicalJsonValue, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+const safeCountSchema = z
+    .number()
+    .int()
+    .nonnegative()
+    .refine(Number.isSafeInteger, "value must be a nonnegative safe integer");
+const boundedIdentifierSchema = z.string().min(1).max(256);
+const normalizedDimensionNameSchema = z
+    .string()
+    .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/, "dimension names must be normalized lowercase identifiers");
+const normalizedScoreSchema = z.number().finite().min(0).max(1);
+export const agentCandidateFixedSpendSchema = z
+    .object({
+    inputTokens: safeCountSchema,
+    outputTokens: safeCountSchema,
+    cachedInputTokens: safeCountSchema,
+    reasoningTokens: safeCountSchema,
+    modelCalls: safeCountSchema,
+    costUsdNanos: safeCountSchema,
+})
+    .strict();
+export const agentCandidateModelSettlementCallSchema = z
+    .object({
+    callId: boundedIdentifierSchema,
+    traceSpanId: boundedIdentifierSchema,
+    model: boundedIdentifierSchema,
+    inputTokens: safeCountSchema,
+    outputTokens: safeCountSchema,
+    cachedInputTokens: safeCountSchema,
+    reasoningTokens: safeCountSchema,
+    costUsdNanos: safeCountSchema,
+})
+    .strict();
+export const agentCandidateModelSettlementMaterialSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-model-settlement-material"),
+    executionPlanDigest: sha256DigestSchema,
+    preparationId: boundedIdentifierSchema,
+    grantDigest: sha256DigestSchema,
+    closed: z.literal(true),
+    resolved: agentCandidateResolvedModelSchema,
+    calls: z.array(agentCandidateModelSettlementCallSchema),
+    usage: agentCandidateFixedSpendSchema,
+})
+    .strict()
+    .superRefine((material, ctx) => {
+    const callIds = new Set();
+    const traceSpanIds = new Set();
+    const totals = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedInputTokens: 0,
+        reasoningTokens: 0,
+        modelCalls: material.calls.length,
+        costUsdNanos: 0,
+    };
+    for (const [index, call] of material.calls.entries()) {
+        if (callIds.has(call.callId)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["calls", index, "callId"],
+                message: "model settlement call ids must be unique",
+            });
+        }
+        callIds.add(call.callId);
+        if (traceSpanIds.has(call.traceSpanId)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["calls", index, "traceSpanId"],
+                message: "model settlement trace span ids must be unique",
+            });
+        }
+        traceSpanIds.add(call.traceSpanId);
+        if (call.model !== material.resolved.model) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["calls", index, "model"],
+                message: "settled call model must match the resolved single model",
+            });
+        }
+        for (const field of [
+            "inputTokens",
+            "outputTokens",
+            "cachedInputTokens",
+            "reasoningTokens",
+            "costUsdNanos",
+        ]) {
+            const sum = totals[field] + call[field];
+            if (!Number.isSafeInteger(sum)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["calls", index, field],
+                    message: `model settlement ${field} total exceeds safe integer range`,
+                });
+            }
+            else {
+                totals[field] = sum;
+            }
+        }
+    }
+    if (!sameFixedSpend(totals, material.usage)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["usage"],
+            message: "model settlement usage must equal the exact per-call aggregate",
+        });
+    }
+    if (!isCanonicalJsonValue(material)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "model settlement material must contain only RFC 8785 JSON values",
+        });
+    }
+});
+export const agentCandidateModelSettlementEvidenceSchema = evidenceSchema("agent-candidate-model-settlement", agentCandidateModelSettlementMaterialSchema, "model settlement");
+export const agentCandidateRepositoryStateSchema = z
+    .object({
+    identity: z.string().min(1),
+    rootIdentity: z.string().min(1),
+    commit: gitObjectSchema,
+    tree: gitObjectSchema,
+})
+    .strict()
+    .superRefine((state, ctx) => {
+    if (!sameGitObjectFormat(state.commit, state.tree)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["tree"],
+            message: "repository commit and tree must use the same Git object format",
+        });
+    }
+});
+export const agentCandidateTaskOutcomeMaterialSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-task-outcome-material"),
+    executionPlanDigest: sha256DigestSchema,
+    baseRepository: agentCandidateRepositoryStateSchema,
+    resultRepository: agentCandidateRepositoryStateSchema,
+    afterState: agentCandidateWorkspaceSnapshotEvidenceSchema,
+    gitDiff: z
+        .object({
+        format: z.literal("git-diff-binary"),
+        artifact: agentCandidateArtifactRefSchema,
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((material, ctx) => {
+    if (material.baseRepository.identity !== material.resultRepository.identity) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["resultRepository", "identity"],
+            message: "base and result repository identities must match",
+        });
+    }
+    if (material.baseRepository.rootIdentity !==
+        material.resultRepository.rootIdentity) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["resultRepository", "rootIdentity"],
+            message: "base and result repository roots must match",
+        });
+    }
+    if (!sameGitObjectFormat(material.baseRepository.commit, material.resultRepository.commit) ||
+        !sameGitObjectFormat(material.baseRepository.tree, material.resultRepository.tree)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["resultRepository"],
+            message: "base and result repositories must use one Git object format",
+        });
+    }
+    if (!isCanonicalJsonValue(material)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "task outcome material must contain only RFC 8785 JSON values",
+        });
+    }
+});
+export const agentCandidateTaskOutcomeEvidenceSchema = evidenceSchema("agent-candidate-task-outcome", agentCandidateTaskOutcomeMaterialSchema, "task outcome");
+export const agentCandidateBenchmarkDimensionSchema = z
+    .object({
+    name: normalizedDimensionNameSchema,
+    score: normalizedScoreSchema,
+})
+    .strict();
+export const agentCandidateBenchmarkResultMaterialSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-candidate-benchmark-result-material"),
+    executionPlanDigest: sha256DigestSchema,
+    taskOutcomeDigest: sha256DigestSchema,
+    benchmark: z
+        .object({
+        name: z.string().min(1),
+        version: z.string().min(1),
+        taskId: z.string().min(1),
+        splitDigest: sha256DigestSchema,
+    })
+        .strict(),
+    grader: z
+        .object({
+        name: z.string().min(1),
+        version: z.string().min(1),
+        artifact: agentCandidateArtifactRefSchema,
+    })
+        .strict(),
+    evidence: agentCandidateArtifactRefSchema,
+    score: normalizedScoreSchema,
+    passed: z.boolean(),
+    dimensions: z.array(agentCandidateBenchmarkDimensionSchema),
+})
+    .strict()
+    .superRefine((material, ctx) => {
+    if (material.grader.artifact.byteLength === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["grader", "artifact", "byteLength"],
+            message: "pinned grader artifact must contain executable grader bytes",
+        });
+    }
+    if (material.evidence.byteLength === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["evidence", "byteLength"],
+            message: "benchmark result must contain non-empty durable grading evidence",
+        });
+    }
+    if (material.evidence.sha256 === material.grader.artifact.sha256) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["evidence", "sha256"],
+            message: "grading evidence must be distinct from the grader implementation",
+        });
+    }
+    for (let index = 1; index < material.dimensions.length; index++) {
+        const previous = material.dimensions[index - 1]?.name ?? "";
+        const current = material.dimensions[index]?.name ?? "";
+        if (previous >= current) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["dimensions", index, "name"],
+                message: "benchmark dimensions must be unique and lexicographically sorted",
+            });
+        }
+    }
+    if (!isCanonicalJsonValue(material)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "benchmark result material must contain only RFC 8785 JSON values",
+        });
+    }
+});
+export const agentCandidateBenchmarkResultEvidenceSchema = evidenceSchema("agent-candidate-benchmark-result", agentCandidateBenchmarkResultMaterialSchema, "benchmark result");
+export function sameFixedSpend(left, right) {
+    return (left.inputTokens === right.inputTokens &&
+        left.outputTokens === right.outputTokens &&
+        left.cachedInputTokens === right.cachedInputTokens &&
+        left.reasoningTokens === right.reasoningTokens &&
+        left.modelCalls === right.modelCalls &&
+        left.costUsdNanos === right.costUsdNanos);
+}
+function evidenceSchema(kind, material, label) {
+    return z
+        .object({
+        schemaVersion: z.literal(1),
+        kind: z.literal(kind),
+        digest: sha256DigestSchema,
+        material,
+        artifact: agentCandidateCapturedArtifactSchema,
+    })
+        .strict()
+        .superRefine((evidence, ctx) => {
+        if (evidence.artifact.sha256 !== evidence.digest) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["artifact", "sha256"],
+                message: `${label} artifact hash must equal its canonical material digest`,
+            });
+        }
+        if (evidence.artifact.byteLength === 0) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["artifact", "byteLength"],
+                message: `${label} artifact must contain canonical material bytes`,
+            });
+        }
+    });
+}