@tangle-network/agent-interface 0.22.0 → 0.24.0

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

@@ -1,4 +1,10 @@
 import { z } from "zod";
+export declare const agentCandidateModelAccessNetworkSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    mode: z.ZodLiteral<"disabled">;
+}, z.core.$strict>, z.ZodObject<{
+    mode: z.ZodLiteral<"gateway-only">;
+    domains: z.ZodArray<z.ZodString>;
+}, z.core.$strict>], "mode">;
 export declare const agentCandidateResolvedModelSchema: z.ZodObject<{
     requested: z.ZodString;
     provider: z.ZodString;
@@ -359,6 +365,12 @@ export declare const agentCandidateExecutionPlanMaterialSchema: z.ZodObject<{
         access: z.ZodObject<{
             kind: z.ZodLiteral<"evaluator-mediated">;
             grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            network: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                mode: z.ZodLiteral<"disabled">;
+            }, z.core.$strict>, z.ZodObject<{
+                mode: z.ZodLiteral<"gateway-only">;
+                domains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>], "mode">;
         }, z.core.$strict>;
         routes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"primary">;
@@ -684,6 +696,12 @@ export declare const agentCandidateExecutionPlanEvidenceSchema: z.ZodObject<{
             access: {
                 kind: "evaluator-mediated";
                 grantDigest: `sha256:${string}`;
+                network: {
+                    mode: "disabled";
+                } | {
+                    mode: "gateway-only";
+                    domains: string[];
+                };
             };
             routes: ({
                 kind: "primary";
@@ -989,6 +1007,12 @@ export declare const agentCandidateExecutionPlanEvidenceSchema: z.ZodObject<{
             access: {
                 kind: "evaluator-mediated";
                 grantDigest: `sha256:${string}`;
+                network: {
+                    mode: "disabled";
+                } | {
+                    mode: "gateway-only";
+                    domains: string[];
+                };
             };
             routes: ({
                 kind: "primary";

package/dist/agent-candidate-execution-plan-schema.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
 import { agentCandidateContainerSchema, agentCandidateInstructionDeliverySchema, agentCandidateWorkingDirectorySchema, } from "./agent-candidate-code-schema.js";
-import { addDuplicateIssues, agentCandidateConfigValueSchema, environmentConfigSchema, gitObjectSchema, isCanonicalJsonValue, isSafeExecutable, isSafeRelativePath, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
+import { addDuplicateIssues, agentCandidateConfigValueSchema, environmentConfigSchema, gitObjectSchema, isCanonicalJsonValue, isObviouslyPrivateHostname, isSafeExecutable, isSafeRelativePath, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
 const reasoningEffortSchema = z.enum([
     "none",
@@ -21,6 +21,34 @@ function isCanonicalAbsolutePath(value) {
 function pathsOverlap(left, right) {
     return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
 }
+function isExactPublicGatewayDomain(value) {
+    if (value.length > 253 ||
+        value !== value.toLowerCase() ||
+        value.endsWith(".") ||
+        value.includes(":") ||
+        isObviouslyPrivateHostname(value)) {
+        return false;
+    }
+    const labels = value.split(".");
+    return (labels.length >= 2 &&
+        labels.every((label) => label.length >= 1 &&
+            label.length <= 63 &&
+            /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)) &&
+        /[a-z]/.test(labels.at(-1) ?? ""));
+}
+export const agentCandidateModelAccessNetworkSchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("disabled") }).strict(),
+    z
+        .object({
+        mode: z.literal("gateway-only"),
+        domains: z
+            .array(z
+            .string()
+            .refine(isExactPublicGatewayDomain, "model gateway must be an exact lowercase public DNS name"))
+            .min(1),
+    })
+        .strict(),
+]);
 export const agentCandidateResolvedModelSchema = z
     .object({
     requested: z.string().min(1),
@@ -195,6 +223,7 @@ export const agentCandidateExecutionPlanMaterialSchema = z
             .object({
             kind: z.literal("evaluator-mediated"),
             grantDigest: sha256DigestSchema,
+            network: agentCandidateModelAccessNetworkSchema,
         })
             .strict(),
         routes: z
@@ -300,6 +329,33 @@ export const agentCandidateExecutionPlanMaterialSchema = z
             });
         }
     }
+    const modelNetwork = material.model.access.network;
+    if (material.limits.maxModelCalls === 0 && modelNetwork.mode !== "disabled") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["model", "access", "network"],
+            message: "zero-call plans cannot expose a model gateway",
+        });
+    }
+    if (material.limits.maxModelCalls > 0 && modelNetwork.mode !== "gateway-only") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["model", "access", "network"],
+            message: "model-calling plans require one frozen gateway allowlist",
+        });
+    }
+    if (modelNetwork.mode === "gateway-only") {
+        addDuplicateIssues(modelNetwork.domains, ["model", "access", "network", "domains"], ctx);
+        for (let index = 1; index < modelNetwork.domains.length; index++) {
+            if ((modelNetwork.domains[index - 1] ?? "") >= (modelNetwork.domains[index] ?? "")) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["model", "access", "network", "domains", index],
+                    message: "model gateway domains must be lexicographically sorted",
+                });
+            }
+        }
+    }
     const activeCode = material.codeKind !== "disabled";
     if (activeCode !== (material.candidateWorkspace !== undefined)) {
         ctx.addIssue({

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

@@ -18,8 +18,34 @@ export declare const agentCandidateModelSettlementCallSchema: z.ZodObject<{
     reasoningTokens: z.ZodNumber;
     costUsdNanos: z.ZodNumber;
 }, z.core.$strict>;
-export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
+export declare const agentCandidateModelSettlementCallV2Schema: z.ZodObject<{
+    callId: z.ZodString;
+    generationId: z.ZodString;
+    traceSpanId: z.ZodString;
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        failed: "failed";
+    }>;
+    model: z.ZodString;
+    startedAtMs: z.ZodNumber;
+    endedAtMs: z.ZodNumber;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cachedInputTokens: z.ZodNumber;
+    reasoningTokens: z.ZodNumber;
+    costUsdNanos: z.ZodNumber;
+}, z.core.$strict>;
+export declare const agentCandidateModelSettlementMaterialV1Schema: z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        callId: z.ZodString;
+        traceSpanId: z.ZodString;
+        model: z.ZodString;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>>;
     kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
     executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     preparationId: z.ZodString;
@@ -40,16 +66,54 @@ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
             ultracode: "ultracode";
         }>;
     }, z.core.$strict>;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        modelCalls: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export declare const agentCandidateModelSettlementMaterialV2Schema: z.ZodObject<{
     calls: z.ZodArray<z.ZodObject<{
         callId: z.ZodString;
+        generationId: z.ZodString;
         traceSpanId: z.ZodString;
+        status: z.ZodEnum<{
+            succeeded: "succeeded";
+            failed: "failed";
+        }>;
         model: z.ZodString;
+        startedAtMs: z.ZodNumber;
+        endedAtMs: z.ZodNumber;
         inputTokens: z.ZodNumber;
         outputTokens: z.ZodNumber;
         cachedInputTokens: z.ZodNumber;
         reasoningTokens: z.ZodNumber;
         costUsdNanos: z.ZodNumber;
     }, z.core.$strict>>;
+    kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
+    executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    preparationId: z.ZodString;
+    grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    closed: z.ZodLiteral<true>;
+    resolved: z.ZodObject<{
+        requested: z.ZodString;
+        provider: z.ZodString;
+        model: z.ZodString;
+        snapshot: z.ZodString;
+        reasoningEffort: z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            ultracode: "ultracode";
+        }>;
+    }, z.core.$strict>;
     usage: z.ZodObject<{
         inputTokens: z.ZodNumber;
         outputTokens: z.ZodNumber;
@@ -58,13 +122,111 @@ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
         modelCalls: z.ZodNumber;
         costUsdNanos: z.ZodNumber;
     }, z.core.$strict>;
+    schemaVersion: z.ZodLiteral<2>;
 }, z.core.$strict>;
+export declare const agentCandidateModelSettlementMaterialSchema: z.ZodUnion<readonly [z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        callId: z.ZodString;
+        traceSpanId: z.ZodString;
+        model: z.ZodString;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>>;
+    kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
+    executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    preparationId: z.ZodString;
+    grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    closed: z.ZodLiteral<true>;
+    resolved: z.ZodObject<{
+        requested: z.ZodString;
+        provider: z.ZodString;
+        model: z.ZodString;
+        snapshot: z.ZodString;
+        reasoningEffort: z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            ultracode: "ultracode";
+        }>;
+    }, z.core.$strict>;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        modelCalls: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strict>, z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        callId: z.ZodString;
+        generationId: z.ZodString;
+        traceSpanId: z.ZodString;
+        status: z.ZodEnum<{
+            succeeded: "succeeded";
+            failed: "failed";
+        }>;
+        model: z.ZodString;
+        startedAtMs: z.ZodNumber;
+        endedAtMs: z.ZodNumber;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>>;
+    kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
+    executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    preparationId: z.ZodString;
+    grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    closed: z.ZodLiteral<true>;
+    resolved: z.ZodObject<{
+        requested: z.ZodString;
+        provider: z.ZodString;
+        model: z.ZodString;
+        snapshot: z.ZodString;
+        reasoningEffort: z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            ultracode: "ultracode";
+        }>;
+    }, z.core.$strict>;
+    usage: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cachedInputTokens: z.ZodNumber;
+        reasoningTokens: z.ZodNumber;
+        modelCalls: z.ZodNumber;
+        costUsdNanos: z.ZodNumber;
+    }, z.core.$strict>;
+    schemaVersion: z.ZodLiteral<2>;
+}, z.core.$strict>]>;
 export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     kind: z.ZodLiteral<"agent-candidate-model-settlement">;
     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     material: z.ZodType<{
-        schemaVersion: 1;
+        calls: {
+            callId: string;
+            traceSpanId: string;
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            cachedInputTokens: number;
+            reasoningTokens: number;
+            costUsdNanos: number;
+        }[];
         kind: "agent-candidate-model-settlement-material";
         executionPlanDigest: `sha256:${string}`;
         preparationId: string;
@@ -77,16 +239,42 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
             snapshot: string;
             reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
         };
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            cachedInputTokens: number;
+            reasoningTokens: number;
+            modelCalls: number;
+            costUsdNanos: number;
+        };
+        schemaVersion: 1;
+    } | {
         calls: {
             callId: string;
+            generationId: string;
             traceSpanId: string;
+            status: "succeeded" | "failed";
             model: string;
+            startedAtMs: number;
+            endedAtMs: number;
             inputTokens: number;
             outputTokens: number;
             cachedInputTokens: number;
             reasoningTokens: number;
             costUsdNanos: number;
         }[];
+        kind: "agent-candidate-model-settlement-material";
+        executionPlanDigest: `sha256:${string}`;
+        preparationId: string;
+        grantDigest: `sha256:${string}`;
+        closed: true;
+        resolved: {
+            requested: string;
+            provider: string;
+            model: string;
+            snapshot: string;
+            reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
+        };
         usage: {
             inputTokens: number;
             outputTokens: number;
@@ -95,8 +283,18 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
             modelCalls: number;
             costUsdNanos: number;
         };
+        schemaVersion: 2;
     }, unknown, z.core.$ZodTypeInternals<{
-        schemaVersion: 1;
+        calls: {
+            callId: string;
+            traceSpanId: string;
+            model: string;
+            inputTokens: number;
+            outputTokens: number;
+            cachedInputTokens: number;
+            reasoningTokens: number;
+            costUsdNanos: number;
+        }[];
         kind: "agent-candidate-model-settlement-material";
         executionPlanDigest: `sha256:${string}`;
         preparationId: string;
@@ -109,16 +307,42 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
             snapshot: string;
             reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
         };
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            cachedInputTokens: number;
+            reasoningTokens: number;
+            modelCalls: number;
+            costUsdNanos: number;
+        };
+        schemaVersion: 1;
+    } | {
         calls: {
             callId: string;
+            generationId: string;
             traceSpanId: string;
+            status: "succeeded" | "failed";
             model: string;
+            startedAtMs: number;
+            endedAtMs: number;
             inputTokens: number;
             outputTokens: number;
             cachedInputTokens: number;
             reasoningTokens: number;
             costUsdNanos: number;
         }[];
+        kind: "agent-candidate-model-settlement-material";
+        executionPlanDigest: `sha256:${string}`;
+        preparationId: string;
+        grantDigest: `sha256:${string}`;
+        closed: true;
+        resolved: {
+            requested: string;
+            provider: string;
+            model: string;
+            snapshot: string;
+            reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
+        };
         usage: {
             inputTokens: number;
             outputTokens: number;
@@ -127,6 +351,7 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
             modelCalls: number;
             costUsdNanos: number;
         };
+        schemaVersion: 2;
     }, unknown>>;
     artifact: z.ZodUnion<readonly [z.ZodObject<{
         locator: z.ZodDiscriminatedUnion<[z.ZodObject<{

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

@@ -8,6 +8,7 @@ const safeCountSchema = z
     .nonnegative()
     .refine(Number.isSafeInteger, "value must be a nonnegative safe integer");
 const boundedIdentifierSchema = z.string().min(1).max(256);
+const positiveTimestampSchema = safeCountSchema.positive();
 const normalizedDimensionNameSchema = z
     .string()
     .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/, "dimension names must be normalized lowercase identifiers");
@@ -34,22 +35,71 @@ export const agentCandidateModelSettlementCallSchema = z
     costUsdNanos: safeCountSchema,
 })
     .strict();
-export const agentCandidateModelSettlementMaterialSchema = z
+export const agentCandidateModelSettlementCallV2Schema = z
     .object({
-    schemaVersion: z.literal(1),
+    callId: boundedIdentifierSchema,
+    generationId: boundedIdentifierSchema,
+    traceSpanId: boundedIdentifierSchema,
+    status: z.enum(["succeeded", "failed"]),
+    model: boundedIdentifierSchema,
+    startedAtMs: positiveTimestampSchema,
+    endedAtMs: positiveTimestampSchema,
+    inputTokens: safeCountSchema,
+    outputTokens: safeCountSchema,
+    cachedInputTokens: safeCountSchema,
+    reasoningTokens: safeCountSchema,
+    costUsdNanos: safeCountSchema,
+})
+    .strict()
+    .superRefine((call, ctx) => {
+    if (call.traceSpanId !== call.generationId) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["traceSpanId"],
+            message: "model settlement trace span id must equal the router generation id",
+        });
+    }
+    if (call.endedAtMs < call.startedAtMs) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["endedAtMs"],
+            message: "model settlement call cannot end before it starts",
+        });
+    }
+});
+const modelSettlementMaterialShape = {
     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,
+};
+export const agentCandidateModelSettlementMaterialV1Schema = z
+    .object({
+    schemaVersion: z.literal(1),
+    ...modelSettlementMaterialShape,
+    calls: z.array(agentCandidateModelSettlementCallSchema),
 })
     .strict()
-    .superRefine((material, ctx) => {
+    .superRefine(refineModelSettlementMaterial);
+export const agentCandidateModelSettlementMaterialV2Schema = z
+    .object({
+    schemaVersion: z.literal(2),
+    ...modelSettlementMaterialShape,
+    calls: z.array(agentCandidateModelSettlementCallV2Schema),
+})
+    .strict()
+    .superRefine(refineModelSettlementMaterial);
+export const agentCandidateModelSettlementMaterialSchema = z.union([
+    agentCandidateModelSettlementMaterialV1Schema,
+    agentCandidateModelSettlementMaterialV2Schema,
+]);
+function refineModelSettlementMaterial(material, ctx) {
     const callIds = new Set();
     const traceSpanIds = new Set();
+    const generationIds = new Set();
     const totals = {
         inputTokens: 0,
         outputTokens: 0,
@@ -75,6 +125,19 @@ export const agentCandidateModelSettlementMaterialSchema = z
             });
         }
         traceSpanIds.add(call.traceSpanId);
+        const generationId = "generationId" in call && typeof call.generationId === "string"
+            ? call.generationId
+            : undefined;
+        if (generationId !== undefined) {
+            if (generationIds.has(generationId)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["calls", index, "generationId"],
+                    message: "model settlement generation ids must be unique",
+                });
+            }
+            generationIds.add(generationId);
+        }
         if (call.model !== material.resolved.model) {
             ctx.addIssue({
                 code: "custom",
@@ -115,7 +178,7 @@ export const agentCandidateModelSettlementMaterialSchema = z
             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({

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

@@ -319,6 +319,12 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
                 access: {
                     kind: "evaluator-mediated";
                     grantDigest: `sha256:${string}`;
+                    network: {
+                        mode: "disabled";
+                    } | {
+                        mode: "gateway-only";
+                        domains: string[];
+                    };
                 };
                 routes: ({
                     kind: "primary";
@@ -624,6 +630,12 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
                 access: {
                     kind: "evaluator-mediated";
                     grantDigest: `sha256:${string}`;
+                    network: {
+                        mode: "disabled";
+                    } | {
+                        mode: "gateway-only";
+                        domains: string[];
+                    };
                 };
                 routes: ({
                     kind: "primary";
@@ -1228,7 +1240,16 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
         kind: z.ZodLiteral<"agent-candidate-model-settlement">;
         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         material: z.ZodType<{
-            schemaVersion: 1;
+            calls: {
+                callId: string;
+                traceSpanId: string;
+                model: string;
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                costUsdNanos: number;
+            }[];
             kind: "agent-candidate-model-settlement-material";
             executionPlanDigest: `sha256:${string}`;
             preparationId: string;
@@ -1241,16 +1262,42 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
                 snapshot: string;
                 reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
             };
+            usage: {
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                modelCalls: number;
+                costUsdNanos: number;
+            };
+            schemaVersion: 1;
+        } | {
             calls: {
                 callId: string;
+                generationId: string;
                 traceSpanId: string;
+                status: "succeeded" | "failed";
                 model: string;
+                startedAtMs: number;
+                endedAtMs: number;
                 inputTokens: number;
                 outputTokens: number;
                 cachedInputTokens: number;
                 reasoningTokens: number;
                 costUsdNanos: number;
             }[];
+            kind: "agent-candidate-model-settlement-material";
+            executionPlanDigest: `sha256:${string}`;
+            preparationId: string;
+            grantDigest: `sha256:${string}`;
+            closed: true;
+            resolved: {
+                requested: string;
+                provider: string;
+                model: string;
+                snapshot: string;
+                reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
+            };
             usage: {
                 inputTokens: number;
                 outputTokens: number;
@@ -1259,8 +1306,18 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
                 modelCalls: number;
                 costUsdNanos: number;
             };
+            schemaVersion: 2;
         }, unknown, z.core.$ZodTypeInternals<{
-            schemaVersion: 1;
+            calls: {
+                callId: string;
+                traceSpanId: string;
+                model: string;
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                costUsdNanos: number;
+            }[];
             kind: "agent-candidate-model-settlement-material";
             executionPlanDigest: `sha256:${string}`;
             preparationId: string;
@@ -1273,16 +1330,42 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
                 snapshot: string;
                 reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
             };
+            usage: {
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                modelCalls: number;
+                costUsdNanos: number;
+            };
+            schemaVersion: 1;
+        } | {
             calls: {
                 callId: string;
+                generationId: string;
                 traceSpanId: string;
+                status: "succeeded" | "failed";
                 model: string;
+                startedAtMs: number;
+                endedAtMs: number;
                 inputTokens: number;
                 outputTokens: number;
                 cachedInputTokens: number;
                 reasoningTokens: number;
                 costUsdNanos: number;
             }[];
+            kind: "agent-candidate-model-settlement-material";
+            executionPlanDigest: `sha256:${string}`;
+            preparationId: string;
+            grantDigest: `sha256:${string}`;
+            closed: true;
+            resolved: {
+                requested: string;
+                provider: string;
+                model: string;
+                snapshot: string;
+                reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
+            };
             usage: {
                 inputTokens: number;
                 outputTokens: number;
@@ -1291,6 +1374,7 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
                 modelCalls: number;
                 costUsdNanos: number;
             };
+            schemaVersion: 2;
         }, unknown>>;
         artifact: z.ZodUnion<readonly [z.ZodObject<{
             locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -2060,7 +2144,16 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
         kind: z.ZodLiteral<"agent-candidate-model-settlement">;
         digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
         material: z.ZodType<{
-            schemaVersion: 1;
+            calls: {
+                callId: string;
+                traceSpanId: string;
+                model: string;
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                costUsdNanos: number;
+            }[];
             kind: "agent-candidate-model-settlement-material";
             executionPlanDigest: `sha256:${string}`;
             preparationId: string;
@@ -2073,16 +2166,42 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
                 snapshot: string;
                 reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
             };
+            usage: {
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                modelCalls: number;
+                costUsdNanos: number;
+            };
+            schemaVersion: 1;
+        } | {
             calls: {
                 callId: string;
+                generationId: string;
                 traceSpanId: string;
+                status: "succeeded" | "failed";
                 model: string;
+                startedAtMs: number;
+                endedAtMs: number;
                 inputTokens: number;
                 outputTokens: number;
                 cachedInputTokens: number;
                 reasoningTokens: number;
                 costUsdNanos: number;
             }[];
+            kind: "agent-candidate-model-settlement-material";
+            executionPlanDigest: `sha256:${string}`;
+            preparationId: string;
+            grantDigest: `sha256:${string}`;
+            closed: true;
+            resolved: {
+                requested: string;
+                provider: string;
+                model: string;
+                snapshot: string;
+                reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
+            };
             usage: {
                 inputTokens: number;
                 outputTokens: number;
@@ -2091,8 +2210,18 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
                 modelCalls: number;
                 costUsdNanos: number;
             };
+            schemaVersion: 2;
         }, unknown, z.core.$ZodTypeInternals<{
-            schemaVersion: 1;
+            calls: {
+                callId: string;
+                traceSpanId: string;
+                model: string;
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                costUsdNanos: number;
+            }[];
             kind: "agent-candidate-model-settlement-material";
             executionPlanDigest: `sha256:${string}`;
             preparationId: string;
@@ -2105,16 +2234,42 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
                 snapshot: string;
                 reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
             };
+            usage: {
+                inputTokens: number;
+                outputTokens: number;
+                cachedInputTokens: number;
+                reasoningTokens: number;
+                modelCalls: number;
+                costUsdNanos: number;
+            };
+            schemaVersion: 1;
+        } | {
             calls: {
                 callId: string;
+                generationId: string;
                 traceSpanId: string;
+                status: "succeeded" | "failed";
                 model: string;
+                startedAtMs: number;
+                endedAtMs: number;
                 inputTokens: number;
                 outputTokens: number;
                 cachedInputTokens: number;
                 reasoningTokens: number;
                 costUsdNanos: number;
             }[];
+            kind: "agent-candidate-model-settlement-material";
+            executionPlanDigest: `sha256:${string}`;
+            preparationId: string;
+            grantDigest: `sha256:${string}`;
+            closed: true;
+            resolved: {
+                requested: string;
+                provider: string;
+                model: string;
+                snapshot: string;
+                reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
+            };
             usage: {
                 inputTokens: number;
                 outputTokens: number;
@@ -2123,6 +2278,7 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
                 modelCalls: number;
                 costUsdNanos: number;
             };
+            schemaVersion: 2;
         }, unknown>>;
         artifact: z.ZodUnion<readonly [z.ZodObject<{
             locator: z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/agent-candidate.d.ts

@@ -352,6 +352,13 @@ export interface AgentCandidateProfileApplication {
     targetWorkspace: AgentCandidateWorkingDirectory["workspace"];
     mountPaths: string[];
 }
+/** Evaluator-owned network exception for the one frozen model gateway. */
+export type AgentCandidateModelAccessNetwork = {
+    mode: "disabled";
+} | {
+    mode: "gateway-only";
+    domains: string[];
+};
 /**
  * Canonical, digest-free per-task execution identity document.
  *
@@ -405,6 +412,7 @@ export interface AgentCandidateExecutionPlanMaterialV1 {
         access: {
             kind: "evaluator-mediated";
             grantDigest: Sha256Digest;
+            network: AgentCandidateModelAccessNetwork;
         };
         routes: Array<{
             kind: "primary";
@@ -534,6 +542,13 @@ export interface AgentCandidateModelSettlementCall {
     reasoningTokens: number;
     costUsdNanos: number;
 }
+/** Router-authored call identity, timing, and terminal status. */
+export interface AgentCandidateModelSettlementCallV2 extends AgentCandidateModelSettlementCall {
+    generationId: string;
+    status: "succeeded" | "failed";
+    startedAtMs: number;
+    endedAtMs: number;
+}
 /** Canonical model-access ledger after the evaluator has revoked the grant. */
 export interface AgentCandidateModelSettlementMaterialV1 {
     schemaVersion: 1;
@@ -546,11 +561,24 @@ export interface AgentCandidateModelSettlementMaterialV1 {
     calls: AgentCandidateModelSettlementCall[];
     usage: AgentCandidateFixedSpend;
 }
+/** Canonical ledger whose LLM spans can be reproduced only from router facts. */
+export interface AgentCandidateModelSettlementMaterialV2 {
+    schemaVersion: 2;
+    kind: "agent-candidate-model-settlement-material";
+    executionPlanDigest: Sha256Digest;
+    preparationId: string;
+    grantDigest: Sha256Digest;
+    closed: true;
+    resolved: AgentCandidateResolvedModel;
+    calls: AgentCandidateModelSettlementCallV2[];
+    usage: AgentCandidateFixedSpend;
+}
+export type AgentCandidateModelSettlementMaterial = AgentCandidateModelSettlementMaterialV1 | AgentCandidateModelSettlementMaterialV2;
 export interface AgentCandidateModelSettlementEvidence {
     schemaVersion: 1;
     kind: "agent-candidate-model-settlement";
     digest: Sha256Digest;
-    material: AgentCandidateModelSettlementMaterialV1;
+    material: AgentCandidateModelSettlementMaterial;
     artifact: AgentCandidateCapturedArtifact;
 }
 /** Git identity before or after a task execution. */

package/package.json

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