@tangle-network/agent-interface 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -388,6 +388,24 @@ export declare const agentCandidateExecutionPlanMaterialSchema: z.ZodObject<{
388
388
  requested: z.ZodString;
389
389
  }, z.core.$strict>], "kind">>;
390
390
  }, z.core.$strict>;
391
+ grader: z.ZodObject<{
392
+ name: z.ZodString;
393
+ version: z.ZodString;
394
+ artifact: z.ZodObject<{
395
+ locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
396
+ kind: z.ZodLiteral<"s3">;
397
+ bucket: z.ZodString;
398
+ key: z.ZodString;
399
+ region: z.ZodOptional<z.ZodString>;
400
+ }, z.core.$strict>, z.ZodObject<{
401
+ kind: z.ZodLiteral<"ipfs">;
402
+ cid: z.ZodString;
403
+ path: z.ZodOptional<z.ZodString>;
404
+ }, z.core.$strict>], "kind">;
405
+ sha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
406
+ byteLength: z.ZodNumber;
407
+ }, z.core.$strict>;
408
+ }, z.core.$strict>;
391
409
  launch: z.ZodObject<{
392
410
  executable: z.ZodString;
393
411
  args: z.ZodArray<z.ZodObject<{
@@ -719,6 +737,24 @@ export declare const agentCandidateExecutionPlanEvidenceSchema: z.ZodObject<{
719
737
  requested: string;
720
738
  })[];
721
739
  };
740
+ grader: {
741
+ name: string;
742
+ version: string;
743
+ artifact: {
744
+ locator: {
745
+ kind: "s3";
746
+ bucket: string;
747
+ key: string;
748
+ region?: string | undefined;
749
+ } | {
750
+ kind: "ipfs";
751
+ cid: string;
752
+ path?: string | undefined;
753
+ };
754
+ sha256: `sha256:${string}`;
755
+ byteLength: number;
756
+ };
757
+ };
722
758
  launch: {
723
759
  executable: string;
724
760
  args: {
@@ -1030,6 +1066,24 @@ export declare const agentCandidateExecutionPlanEvidenceSchema: z.ZodObject<{
1030
1066
  requested: string;
1031
1067
  })[];
1032
1068
  };
1069
+ grader: {
1070
+ name: string;
1071
+ version: string;
1072
+ artifact: {
1073
+ locator: {
1074
+ kind: "s3";
1075
+ bucket: string;
1076
+ key: string;
1077
+ region?: string | undefined;
1078
+ } | {
1079
+ kind: "ipfs";
1080
+ cid: string;
1081
+ path?: string | undefined;
1082
+ };
1083
+ sha256: `sha256:${string}`;
1084
+ byteLength: number;
1085
+ };
1086
+ };
1033
1087
  launch: {
1034
1088
  executable: string;
1035
1089
  args: {
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- import { agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
2
+ import { agentCandidateArtifactRefSchema, agentCandidateCapturedArtifactSchema, agentCandidateWorkspaceSnapshotEvidenceSchema, } from "./agent-candidate-artifact-schema.js";
3
3
  import { agentCandidateContainerSchema, agentCandidateInstructionDeliverySchema, agentCandidateWorkingDirectorySchema, } from "./agent-candidate-code-schema.js";
4
4
  import { addDuplicateIssues, agentCandidateConfigValueSchema, environmentConfigSchema, gitObjectSchema, isCanonicalJsonValue, isObviouslyPrivateHostname, isSafeExecutable, isSafeRelativePath, sameGitObjectFormat, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
5
5
  import { harnessTypeSchema } from "./harness.js";
@@ -258,6 +258,13 @@ export const agentCandidateExecutionPlanMaterialSchema = z
258
258
  .min(1),
259
259
  })
260
260
  .strict(),
261
+ grader: z
262
+ .object({
263
+ name: z.string().min(1),
264
+ version: z.string().min(1),
265
+ artifact: agentCandidateArtifactRefSchema,
266
+ })
267
+ .strict(),
261
268
  launch: z
262
269
  .object({
263
270
  executable: z
@@ -18,8 +18,34 @@ export declare const agentCandidateModelSettlementCallSchema: z.ZodObject<{
18
18
  reasoningTokens: z.ZodNumber;
19
19
  costUsdNanos: z.ZodNumber;
20
20
  }, z.core.$strict>;
21
- export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
22
- schemaVersion: z.ZodLiteral<1>;
21
+ export declare const agentCandidateModelSettlementCallV2Schema: z.ZodObject<{
22
+ callId: z.ZodString;
23
+ generationId: z.ZodString;
24
+ traceSpanId: z.ZodString;
25
+ status: z.ZodEnum<{
26
+ succeeded: "succeeded";
27
+ failed: "failed";
28
+ }>;
29
+ model: z.ZodString;
30
+ startedAtMs: z.ZodNumber;
31
+ endedAtMs: z.ZodNumber;
32
+ inputTokens: z.ZodNumber;
33
+ outputTokens: z.ZodNumber;
34
+ cachedInputTokens: z.ZodNumber;
35
+ reasoningTokens: z.ZodNumber;
36
+ costUsdNanos: z.ZodNumber;
37
+ }, z.core.$strict>;
38
+ export declare const agentCandidateModelSettlementMaterialV1Schema: z.ZodObject<{
39
+ calls: z.ZodArray<z.ZodObject<{
40
+ callId: z.ZodString;
41
+ traceSpanId: z.ZodString;
42
+ model: z.ZodString;
43
+ inputTokens: z.ZodNumber;
44
+ outputTokens: z.ZodNumber;
45
+ cachedInputTokens: z.ZodNumber;
46
+ reasoningTokens: z.ZodNumber;
47
+ costUsdNanos: z.ZodNumber;
48
+ }, z.core.$strict>>;
23
49
  kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
24
50
  executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
25
51
  preparationId: z.ZodString;
@@ -40,16 +66,54 @@ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
40
66
  ultracode: "ultracode";
41
67
  }>;
42
68
  }, z.core.$strict>;
69
+ usage: z.ZodObject<{
70
+ inputTokens: z.ZodNumber;
71
+ outputTokens: z.ZodNumber;
72
+ cachedInputTokens: z.ZodNumber;
73
+ reasoningTokens: z.ZodNumber;
74
+ modelCalls: z.ZodNumber;
75
+ costUsdNanos: z.ZodNumber;
76
+ }, z.core.$strict>;
77
+ schemaVersion: z.ZodLiteral<1>;
78
+ }, z.core.$strict>;
79
+ export declare const agentCandidateModelSettlementMaterialV2Schema: z.ZodObject<{
43
80
  calls: z.ZodArray<z.ZodObject<{
44
81
  callId: z.ZodString;
82
+ generationId: z.ZodString;
45
83
  traceSpanId: z.ZodString;
84
+ status: z.ZodEnum<{
85
+ succeeded: "succeeded";
86
+ failed: "failed";
87
+ }>;
46
88
  model: z.ZodString;
89
+ startedAtMs: z.ZodNumber;
90
+ endedAtMs: z.ZodNumber;
47
91
  inputTokens: z.ZodNumber;
48
92
  outputTokens: z.ZodNumber;
49
93
  cachedInputTokens: z.ZodNumber;
50
94
  reasoningTokens: z.ZodNumber;
51
95
  costUsdNanos: z.ZodNumber;
52
96
  }, z.core.$strict>>;
97
+ kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
98
+ executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
99
+ preparationId: z.ZodString;
100
+ grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
101
+ closed: z.ZodLiteral<true>;
102
+ resolved: z.ZodObject<{
103
+ requested: z.ZodString;
104
+ provider: z.ZodString;
105
+ model: z.ZodString;
106
+ snapshot: z.ZodString;
107
+ reasoningEffort: z.ZodEnum<{
108
+ none: "none";
109
+ minimal: "minimal";
110
+ low: "low";
111
+ medium: "medium";
112
+ high: "high";
113
+ xhigh: "xhigh";
114
+ ultracode: "ultracode";
115
+ }>;
116
+ }, z.core.$strict>;
53
117
  usage: z.ZodObject<{
54
118
  inputTokens: z.ZodNumber;
55
119
  outputTokens: z.ZodNumber;
@@ -58,13 +122,111 @@ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
58
122
  modelCalls: z.ZodNumber;
59
123
  costUsdNanos: z.ZodNumber;
60
124
  }, z.core.$strict>;
125
+ schemaVersion: z.ZodLiteral<2>;
61
126
  }, z.core.$strict>;
127
+ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodUnion<readonly [z.ZodObject<{
128
+ calls: z.ZodArray<z.ZodObject<{
129
+ callId: z.ZodString;
130
+ traceSpanId: z.ZodString;
131
+ model: z.ZodString;
132
+ inputTokens: z.ZodNumber;
133
+ outputTokens: z.ZodNumber;
134
+ cachedInputTokens: z.ZodNumber;
135
+ reasoningTokens: z.ZodNumber;
136
+ costUsdNanos: z.ZodNumber;
137
+ }, z.core.$strict>>;
138
+ kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
139
+ executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
140
+ preparationId: z.ZodString;
141
+ grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
142
+ closed: z.ZodLiteral<true>;
143
+ resolved: z.ZodObject<{
144
+ requested: z.ZodString;
145
+ provider: z.ZodString;
146
+ model: z.ZodString;
147
+ snapshot: z.ZodString;
148
+ reasoningEffort: z.ZodEnum<{
149
+ none: "none";
150
+ minimal: "minimal";
151
+ low: "low";
152
+ medium: "medium";
153
+ high: "high";
154
+ xhigh: "xhigh";
155
+ ultracode: "ultracode";
156
+ }>;
157
+ }, z.core.$strict>;
158
+ usage: z.ZodObject<{
159
+ inputTokens: z.ZodNumber;
160
+ outputTokens: z.ZodNumber;
161
+ cachedInputTokens: z.ZodNumber;
162
+ reasoningTokens: z.ZodNumber;
163
+ modelCalls: z.ZodNumber;
164
+ costUsdNanos: z.ZodNumber;
165
+ }, z.core.$strict>;
166
+ schemaVersion: z.ZodLiteral<1>;
167
+ }, z.core.$strict>, z.ZodObject<{
168
+ calls: z.ZodArray<z.ZodObject<{
169
+ callId: z.ZodString;
170
+ generationId: z.ZodString;
171
+ traceSpanId: z.ZodString;
172
+ status: z.ZodEnum<{
173
+ succeeded: "succeeded";
174
+ failed: "failed";
175
+ }>;
176
+ model: z.ZodString;
177
+ startedAtMs: z.ZodNumber;
178
+ endedAtMs: z.ZodNumber;
179
+ inputTokens: z.ZodNumber;
180
+ outputTokens: z.ZodNumber;
181
+ cachedInputTokens: z.ZodNumber;
182
+ reasoningTokens: z.ZodNumber;
183
+ costUsdNanos: z.ZodNumber;
184
+ }, z.core.$strict>>;
185
+ kind: z.ZodLiteral<"agent-candidate-model-settlement-material">;
186
+ executionPlanDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
187
+ preparationId: z.ZodString;
188
+ grantDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
189
+ closed: z.ZodLiteral<true>;
190
+ resolved: z.ZodObject<{
191
+ requested: z.ZodString;
192
+ provider: z.ZodString;
193
+ model: z.ZodString;
194
+ snapshot: z.ZodString;
195
+ reasoningEffort: z.ZodEnum<{
196
+ none: "none";
197
+ minimal: "minimal";
198
+ low: "low";
199
+ medium: "medium";
200
+ high: "high";
201
+ xhigh: "xhigh";
202
+ ultracode: "ultracode";
203
+ }>;
204
+ }, z.core.$strict>;
205
+ usage: z.ZodObject<{
206
+ inputTokens: z.ZodNumber;
207
+ outputTokens: z.ZodNumber;
208
+ cachedInputTokens: z.ZodNumber;
209
+ reasoningTokens: z.ZodNumber;
210
+ modelCalls: z.ZodNumber;
211
+ costUsdNanos: z.ZodNumber;
212
+ }, z.core.$strict>;
213
+ schemaVersion: z.ZodLiteral<2>;
214
+ }, z.core.$strict>]>;
62
215
  export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
63
216
  schemaVersion: z.ZodLiteral<1>;
64
217
  kind: z.ZodLiteral<"agent-candidate-model-settlement">;
65
218
  digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
66
219
  material: z.ZodType<{
67
- schemaVersion: 1;
220
+ calls: {
221
+ callId: string;
222
+ traceSpanId: string;
223
+ model: string;
224
+ inputTokens: number;
225
+ outputTokens: number;
226
+ cachedInputTokens: number;
227
+ reasoningTokens: number;
228
+ costUsdNanos: number;
229
+ }[];
68
230
  kind: "agent-candidate-model-settlement-material";
69
231
  executionPlanDigest: `sha256:${string}`;
70
232
  preparationId: string;
@@ -77,16 +239,42 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
77
239
  snapshot: string;
78
240
  reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
79
241
  };
242
+ usage: {
243
+ inputTokens: number;
244
+ outputTokens: number;
245
+ cachedInputTokens: number;
246
+ reasoningTokens: number;
247
+ modelCalls: number;
248
+ costUsdNanos: number;
249
+ };
250
+ schemaVersion: 1;
251
+ } | {
80
252
  calls: {
81
253
  callId: string;
254
+ generationId: string;
82
255
  traceSpanId: string;
256
+ status: "succeeded" | "failed";
83
257
  model: string;
258
+ startedAtMs: number;
259
+ endedAtMs: number;
84
260
  inputTokens: number;
85
261
  outputTokens: number;
86
262
  cachedInputTokens: number;
87
263
  reasoningTokens: number;
88
264
  costUsdNanos: number;
89
265
  }[];
266
+ kind: "agent-candidate-model-settlement-material";
267
+ executionPlanDigest: `sha256:${string}`;
268
+ preparationId: string;
269
+ grantDigest: `sha256:${string}`;
270
+ closed: true;
271
+ resolved: {
272
+ requested: string;
273
+ provider: string;
274
+ model: string;
275
+ snapshot: string;
276
+ reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
277
+ };
90
278
  usage: {
91
279
  inputTokens: number;
92
280
  outputTokens: number;
@@ -95,8 +283,18 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
95
283
  modelCalls: number;
96
284
  costUsdNanos: number;
97
285
  };
286
+ schemaVersion: 2;
98
287
  }, unknown, z.core.$ZodTypeInternals<{
99
- schemaVersion: 1;
288
+ calls: {
289
+ callId: string;
290
+ traceSpanId: string;
291
+ model: string;
292
+ inputTokens: number;
293
+ outputTokens: number;
294
+ cachedInputTokens: number;
295
+ reasoningTokens: number;
296
+ costUsdNanos: number;
297
+ }[];
100
298
  kind: "agent-candidate-model-settlement-material";
101
299
  executionPlanDigest: `sha256:${string}`;
102
300
  preparationId: string;
@@ -109,16 +307,42 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
109
307
  snapshot: string;
110
308
  reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
111
309
  };
310
+ usage: {
311
+ inputTokens: number;
312
+ outputTokens: number;
313
+ cachedInputTokens: number;
314
+ reasoningTokens: number;
315
+ modelCalls: number;
316
+ costUsdNanos: number;
317
+ };
318
+ schemaVersion: 1;
319
+ } | {
112
320
  calls: {
113
321
  callId: string;
322
+ generationId: string;
114
323
  traceSpanId: string;
324
+ status: "succeeded" | "failed";
115
325
  model: string;
326
+ startedAtMs: number;
327
+ endedAtMs: number;
116
328
  inputTokens: number;
117
329
  outputTokens: number;
118
330
  cachedInputTokens: number;
119
331
  reasoningTokens: number;
120
332
  costUsdNanos: number;
121
333
  }[];
334
+ kind: "agent-candidate-model-settlement-material";
335
+ executionPlanDigest: `sha256:${string}`;
336
+ preparationId: string;
337
+ grantDigest: `sha256:${string}`;
338
+ closed: true;
339
+ resolved: {
340
+ requested: string;
341
+ provider: string;
342
+ model: string;
343
+ snapshot: string;
344
+ reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
345
+ };
122
346
  usage: {
123
347
  inputTokens: number;
124
348
  outputTokens: number;
@@ -127,6 +351,7 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
127
351
  modelCalls: number;
128
352
  costUsdNanos: number;
129
353
  };
354
+ schemaVersion: 2;
130
355
  }, unknown>>;
131
356
  artifact: z.ZodUnion<readonly [z.ZodObject<{
132
357
  locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -8,6 +8,7 @@ const safeCountSchema = z
8
8
  .nonnegative()
9
9
  .refine(Number.isSafeInteger, "value must be a nonnegative safe integer");
10
10
  const boundedIdentifierSchema = z.string().min(1).max(256);
11
+ const positiveTimestampSchema = safeCountSchema.positive();
11
12
  const normalizedDimensionNameSchema = z
12
13
  .string()
13
14
  .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/, "dimension names must be normalized lowercase identifiers");
@@ -34,22 +35,71 @@ export const agentCandidateModelSettlementCallSchema = z
34
35
  costUsdNanos: safeCountSchema,
35
36
  })
36
37
  .strict();
37
- export const agentCandidateModelSettlementMaterialSchema = z
38
+ export const agentCandidateModelSettlementCallV2Schema = z
38
39
  .object({
39
- schemaVersion: z.literal(1),
40
+ callId: boundedIdentifierSchema,
41
+ generationId: boundedIdentifierSchema,
42
+ traceSpanId: boundedIdentifierSchema,
43
+ status: z.enum(["succeeded", "failed"]),
44
+ model: boundedIdentifierSchema,
45
+ startedAtMs: positiveTimestampSchema,
46
+ endedAtMs: positiveTimestampSchema,
47
+ inputTokens: safeCountSchema,
48
+ outputTokens: safeCountSchema,
49
+ cachedInputTokens: safeCountSchema,
50
+ reasoningTokens: safeCountSchema,
51
+ costUsdNanos: safeCountSchema,
52
+ })
53
+ .strict()
54
+ .superRefine((call, ctx) => {
55
+ if (call.traceSpanId !== call.generationId) {
56
+ ctx.addIssue({
57
+ code: "custom",
58
+ path: ["traceSpanId"],
59
+ message: "model settlement trace span id must equal the router generation id",
60
+ });
61
+ }
62
+ if (call.endedAtMs < call.startedAtMs) {
63
+ ctx.addIssue({
64
+ code: "custom",
65
+ path: ["endedAtMs"],
66
+ message: "model settlement call cannot end before it starts",
67
+ });
68
+ }
69
+ });
70
+ const modelSettlementMaterialShape = {
40
71
  kind: z.literal("agent-candidate-model-settlement-material"),
41
72
  executionPlanDigest: sha256DigestSchema,
42
73
  preparationId: boundedIdentifierSchema,
43
74
  grantDigest: sha256DigestSchema,
44
75
  closed: z.literal(true),
45
76
  resolved: agentCandidateResolvedModelSchema,
46
- calls: z.array(agentCandidateModelSettlementCallSchema),
47
77
  usage: agentCandidateFixedSpendSchema,
78
+ };
79
+ export const agentCandidateModelSettlementMaterialV1Schema = z
80
+ .object({
81
+ schemaVersion: z.literal(1),
82
+ ...modelSettlementMaterialShape,
83
+ calls: z.array(agentCandidateModelSettlementCallSchema),
48
84
  })
49
85
  .strict()
50
- .superRefine((material, ctx) => {
86
+ .superRefine(refineModelSettlementMaterial);
87
+ export const agentCandidateModelSettlementMaterialV2Schema = z
88
+ .object({
89
+ schemaVersion: z.literal(2),
90
+ ...modelSettlementMaterialShape,
91
+ calls: z.array(agentCandidateModelSettlementCallV2Schema),
92
+ })
93
+ .strict()
94
+ .superRefine(refineModelSettlementMaterial);
95
+ export const agentCandidateModelSettlementMaterialSchema = z.union([
96
+ agentCandidateModelSettlementMaterialV1Schema,
97
+ agentCandidateModelSettlementMaterialV2Schema,
98
+ ]);
99
+ function refineModelSettlementMaterial(material, ctx) {
51
100
  const callIds = new Set();
52
101
  const traceSpanIds = new Set();
102
+ const generationIds = new Set();
53
103
  const totals = {
54
104
  inputTokens: 0,
55
105
  outputTokens: 0,
@@ -75,6 +125,19 @@ export const agentCandidateModelSettlementMaterialSchema = z
75
125
  });
76
126
  }
77
127
  traceSpanIds.add(call.traceSpanId);
128
+ const generationId = "generationId" in call && typeof call.generationId === "string"
129
+ ? call.generationId
130
+ : undefined;
131
+ if (generationId !== undefined) {
132
+ if (generationIds.has(generationId)) {
133
+ ctx.addIssue({
134
+ code: "custom",
135
+ path: ["calls", index, "generationId"],
136
+ message: "model settlement generation ids must be unique",
137
+ });
138
+ }
139
+ generationIds.add(generationId);
140
+ }
78
141
  if (call.model !== material.resolved.model) {
79
142
  ctx.addIssue({
80
143
  code: "custom",
@@ -115,7 +178,7 @@ export const agentCandidateModelSettlementMaterialSchema = z
115
178
  message: "model settlement material must contain only RFC 8785 JSON values",
116
179
  });
117
180
  }
118
- });
181
+ }
119
182
  export const agentCandidateModelSettlementEvidenceSchema = evidenceSchema("agent-candidate-model-settlement", agentCandidateModelSettlementMaterialSchema, "model settlement");
120
183
  export const agentCandidateRepositoryStateSchema = z
121
184
  .object({
@@ -342,6 +342,24 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
342
342
  requested: string;
343
343
  })[];
344
344
  };
345
+ grader: {
346
+ name: string;
347
+ version: string;
348
+ artifact: {
349
+ locator: {
350
+ kind: "s3";
351
+ bucket: string;
352
+ key: string;
353
+ region?: string | undefined;
354
+ } | {
355
+ kind: "ipfs";
356
+ cid: string;
357
+ path?: string | undefined;
358
+ };
359
+ sha256: `sha256:${string}`;
360
+ byteLength: number;
361
+ };
362
+ };
345
363
  launch: {
346
364
  executable: string;
347
365
  args: {
@@ -653,6 +671,24 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
653
671
  requested: string;
654
672
  })[];
655
673
  };
674
+ grader: {
675
+ name: string;
676
+ version: string;
677
+ artifact: {
678
+ locator: {
679
+ kind: "s3";
680
+ bucket: string;
681
+ key: string;
682
+ region?: string | undefined;
683
+ } | {
684
+ kind: "ipfs";
685
+ cid: string;
686
+ path?: string | undefined;
687
+ };
688
+ sha256: `sha256:${string}`;
689
+ byteLength: number;
690
+ };
691
+ };
656
692
  launch: {
657
693
  executable: string;
658
694
  args: {
@@ -1240,7 +1276,16 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
1240
1276
  kind: z.ZodLiteral<"agent-candidate-model-settlement">;
1241
1277
  digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
1242
1278
  material: z.ZodType<{
1243
- schemaVersion: 1;
1279
+ calls: {
1280
+ callId: string;
1281
+ traceSpanId: string;
1282
+ model: string;
1283
+ inputTokens: number;
1284
+ outputTokens: number;
1285
+ cachedInputTokens: number;
1286
+ reasoningTokens: number;
1287
+ costUsdNanos: number;
1288
+ }[];
1244
1289
  kind: "agent-candidate-model-settlement-material";
1245
1290
  executionPlanDigest: `sha256:${string}`;
1246
1291
  preparationId: string;
@@ -1253,16 +1298,42 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
1253
1298
  snapshot: string;
1254
1299
  reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
1255
1300
  };
1301
+ usage: {
1302
+ inputTokens: number;
1303
+ outputTokens: number;
1304
+ cachedInputTokens: number;
1305
+ reasoningTokens: number;
1306
+ modelCalls: number;
1307
+ costUsdNanos: number;
1308
+ };
1309
+ schemaVersion: 1;
1310
+ } | {
1256
1311
  calls: {
1257
1312
  callId: string;
1313
+ generationId: string;
1258
1314
  traceSpanId: string;
1315
+ status: "succeeded" | "failed";
1259
1316
  model: string;
1317
+ startedAtMs: number;
1318
+ endedAtMs: number;
1260
1319
  inputTokens: number;
1261
1320
  outputTokens: number;
1262
1321
  cachedInputTokens: number;
1263
1322
  reasoningTokens: number;
1264
1323
  costUsdNanos: number;
1265
1324
  }[];
1325
+ kind: "agent-candidate-model-settlement-material";
1326
+ executionPlanDigest: `sha256:${string}`;
1327
+ preparationId: string;
1328
+ grantDigest: `sha256:${string}`;
1329
+ closed: true;
1330
+ resolved: {
1331
+ requested: string;
1332
+ provider: string;
1333
+ model: string;
1334
+ snapshot: string;
1335
+ reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
1336
+ };
1266
1337
  usage: {
1267
1338
  inputTokens: number;
1268
1339
  outputTokens: number;
@@ -1271,8 +1342,18 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
1271
1342
  modelCalls: number;
1272
1343
  costUsdNanos: number;
1273
1344
  };
1345
+ schemaVersion: 2;
1274
1346
  }, unknown, z.core.$ZodTypeInternals<{
1275
- schemaVersion: 1;
1347
+ calls: {
1348
+ callId: string;
1349
+ traceSpanId: string;
1350
+ model: string;
1351
+ inputTokens: number;
1352
+ outputTokens: number;
1353
+ cachedInputTokens: number;
1354
+ reasoningTokens: number;
1355
+ costUsdNanos: number;
1356
+ }[];
1276
1357
  kind: "agent-candidate-model-settlement-material";
1277
1358
  executionPlanDigest: `sha256:${string}`;
1278
1359
  preparationId: string;
@@ -1285,16 +1366,42 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
1285
1366
  snapshot: string;
1286
1367
  reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
1287
1368
  };
1369
+ usage: {
1370
+ inputTokens: number;
1371
+ outputTokens: number;
1372
+ cachedInputTokens: number;
1373
+ reasoningTokens: number;
1374
+ modelCalls: number;
1375
+ costUsdNanos: number;
1376
+ };
1377
+ schemaVersion: 1;
1378
+ } | {
1288
1379
  calls: {
1289
1380
  callId: string;
1381
+ generationId: string;
1290
1382
  traceSpanId: string;
1383
+ status: "succeeded" | "failed";
1291
1384
  model: string;
1385
+ startedAtMs: number;
1386
+ endedAtMs: number;
1292
1387
  inputTokens: number;
1293
1388
  outputTokens: number;
1294
1389
  cachedInputTokens: number;
1295
1390
  reasoningTokens: number;
1296
1391
  costUsdNanos: number;
1297
1392
  }[];
1393
+ kind: "agent-candidate-model-settlement-material";
1394
+ executionPlanDigest: `sha256:${string}`;
1395
+ preparationId: string;
1396
+ grantDigest: `sha256:${string}`;
1397
+ closed: true;
1398
+ resolved: {
1399
+ requested: string;
1400
+ provider: string;
1401
+ model: string;
1402
+ snapshot: string;
1403
+ reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
1404
+ };
1298
1405
  usage: {
1299
1406
  inputTokens: number;
1300
1407
  outputTokens: number;
@@ -1303,6 +1410,7 @@ export declare const agentCandidateRunReceiptV2Schema: z.ZodObject<{
1303
1410
  modelCalls: number;
1304
1411
  costUsdNanos: number;
1305
1412
  };
1413
+ schemaVersion: 2;
1306
1414
  }, unknown>>;
1307
1415
  artifact: z.ZodUnion<readonly [z.ZodObject<{
1308
1416
  locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -2072,7 +2180,16 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
2072
2180
  kind: z.ZodLiteral<"agent-candidate-model-settlement">;
2073
2181
  digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
2074
2182
  material: z.ZodType<{
2075
- schemaVersion: 1;
2183
+ calls: {
2184
+ callId: string;
2185
+ traceSpanId: string;
2186
+ model: string;
2187
+ inputTokens: number;
2188
+ outputTokens: number;
2189
+ cachedInputTokens: number;
2190
+ reasoningTokens: number;
2191
+ costUsdNanos: number;
2192
+ }[];
2076
2193
  kind: "agent-candidate-model-settlement-material";
2077
2194
  executionPlanDigest: `sha256:${string}`;
2078
2195
  preparationId: string;
@@ -2085,16 +2202,42 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
2085
2202
  snapshot: string;
2086
2203
  reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
2087
2204
  };
2205
+ usage: {
2206
+ inputTokens: number;
2207
+ outputTokens: number;
2208
+ cachedInputTokens: number;
2209
+ reasoningTokens: number;
2210
+ modelCalls: number;
2211
+ costUsdNanos: number;
2212
+ };
2213
+ schemaVersion: 1;
2214
+ } | {
2088
2215
  calls: {
2089
2216
  callId: string;
2217
+ generationId: string;
2090
2218
  traceSpanId: string;
2219
+ status: "succeeded" | "failed";
2091
2220
  model: string;
2221
+ startedAtMs: number;
2222
+ endedAtMs: number;
2092
2223
  inputTokens: number;
2093
2224
  outputTokens: number;
2094
2225
  cachedInputTokens: number;
2095
2226
  reasoningTokens: number;
2096
2227
  costUsdNanos: number;
2097
2228
  }[];
2229
+ kind: "agent-candidate-model-settlement-material";
2230
+ executionPlanDigest: `sha256:${string}`;
2231
+ preparationId: string;
2232
+ grantDigest: `sha256:${string}`;
2233
+ closed: true;
2234
+ resolved: {
2235
+ requested: string;
2236
+ provider: string;
2237
+ model: string;
2238
+ snapshot: string;
2239
+ reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
2240
+ };
2098
2241
  usage: {
2099
2242
  inputTokens: number;
2100
2243
  outputTokens: number;
@@ -2103,8 +2246,18 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
2103
2246
  modelCalls: number;
2104
2247
  costUsdNanos: number;
2105
2248
  };
2249
+ schemaVersion: 2;
2106
2250
  }, unknown, z.core.$ZodTypeInternals<{
2107
- schemaVersion: 1;
2251
+ calls: {
2252
+ callId: string;
2253
+ traceSpanId: string;
2254
+ model: string;
2255
+ inputTokens: number;
2256
+ outputTokens: number;
2257
+ cachedInputTokens: number;
2258
+ reasoningTokens: number;
2259
+ costUsdNanos: number;
2260
+ }[];
2108
2261
  kind: "agent-candidate-model-settlement-material";
2109
2262
  executionPlanDigest: `sha256:${string}`;
2110
2263
  preparationId: string;
@@ -2117,16 +2270,42 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
2117
2270
  snapshot: string;
2118
2271
  reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
2119
2272
  };
2273
+ usage: {
2274
+ inputTokens: number;
2275
+ outputTokens: number;
2276
+ cachedInputTokens: number;
2277
+ reasoningTokens: number;
2278
+ modelCalls: number;
2279
+ costUsdNanos: number;
2280
+ };
2281
+ schemaVersion: 1;
2282
+ } | {
2120
2283
  calls: {
2121
2284
  callId: string;
2285
+ generationId: string;
2122
2286
  traceSpanId: string;
2287
+ status: "succeeded" | "failed";
2123
2288
  model: string;
2289
+ startedAtMs: number;
2290
+ endedAtMs: number;
2124
2291
  inputTokens: number;
2125
2292
  outputTokens: number;
2126
2293
  cachedInputTokens: number;
2127
2294
  reasoningTokens: number;
2128
2295
  costUsdNanos: number;
2129
2296
  }[];
2297
+ kind: "agent-candidate-model-settlement-material";
2298
+ executionPlanDigest: `sha256:${string}`;
2299
+ preparationId: string;
2300
+ grantDigest: `sha256:${string}`;
2301
+ closed: true;
2302
+ resolved: {
2303
+ requested: string;
2304
+ provider: string;
2305
+ model: string;
2306
+ snapshot: string;
2307
+ reasoningEffort: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "ultracode";
2308
+ };
2130
2309
  usage: {
2131
2310
  inputTokens: number;
2132
2311
  outputTokens: number;
@@ -2135,6 +2314,7 @@ export declare const agentCandidateRunReceiptAnyVersionSchema: z.ZodUnion<readon
2135
2314
  modelCalls: number;
2136
2315
  costUsdNanos: number;
2137
2316
  };
2317
+ schemaVersion: 2;
2138
2318
  }, unknown>>;
2139
2319
  artifact: z.ZodUnion<readonly [z.ZodObject<{
2140
2320
  locator: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -430,6 +430,12 @@ export interface AgentCandidateExecutionPlanMaterialV1 {
430
430
  requested: string;
431
431
  }>;
432
432
  };
433
+ /** Exact evaluator grader implementation admitted for this plan. */
434
+ grader: {
435
+ name: string;
436
+ version: string;
437
+ artifact: AgentCandidateArtifactRef;
438
+ };
433
439
  launch: {
434
440
  executable: string;
435
441
  args: AgentCandidateConfigValue[];
@@ -542,6 +548,13 @@ export interface AgentCandidateModelSettlementCall {
542
548
  reasoningTokens: number;
543
549
  costUsdNanos: number;
544
550
  }
551
+ /** Router-authored call identity, timing, and terminal status. */
552
+ export interface AgentCandidateModelSettlementCallV2 extends AgentCandidateModelSettlementCall {
553
+ generationId: string;
554
+ status: "succeeded" | "failed";
555
+ startedAtMs: number;
556
+ endedAtMs: number;
557
+ }
545
558
  /** Canonical model-access ledger after the evaluator has revoked the grant. */
546
559
  export interface AgentCandidateModelSettlementMaterialV1 {
547
560
  schemaVersion: 1;
@@ -554,11 +567,24 @@ export interface AgentCandidateModelSettlementMaterialV1 {
554
567
  calls: AgentCandidateModelSettlementCall[];
555
568
  usage: AgentCandidateFixedSpend;
556
569
  }
570
+ /** Canonical ledger whose LLM spans can be reproduced only from router facts. */
571
+ export interface AgentCandidateModelSettlementMaterialV2 {
572
+ schemaVersion: 2;
573
+ kind: "agent-candidate-model-settlement-material";
574
+ executionPlanDigest: Sha256Digest;
575
+ preparationId: string;
576
+ grantDigest: Sha256Digest;
577
+ closed: true;
578
+ resolved: AgentCandidateResolvedModel;
579
+ calls: AgentCandidateModelSettlementCallV2[];
580
+ usage: AgentCandidateFixedSpend;
581
+ }
582
+ export type AgentCandidateModelSettlementMaterial = AgentCandidateModelSettlementMaterialV1 | AgentCandidateModelSettlementMaterialV2;
557
583
  export interface AgentCandidateModelSettlementEvidence {
558
584
  schemaVersion: 1;
559
585
  kind: "agent-candidate-model-settlement";
560
586
  digest: Sha256Digest;
561
- material: AgentCandidateModelSettlementMaterialV1;
587
+ material: AgentCandidateModelSettlementMaterial;
562
588
  artifact: AgentCandidateCapturedArtifact;
563
589
  }
564
590
  /** Git identity before or after a task execution. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tangle-network/agent-interface",
3
- "version": "0.23.0",
3
+ "version": "0.25.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "main": "./dist/index.js",