@tangle-network/agent-interface 0.35.0 → 0.37.0

package/dist/agent-profile-improvement-schema.d.ts

@@ -178,6 +178,11 @@ export declare const agentProfileImprovementSuiteInputsSchema: z.ZodObject<{
 export declare const agentProfileImprovementArmSchema: z.ZodObject<{
     stateDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
 }, z.core.$strict>;
+export declare const agentProfileImprovementExecutionRefSchema: z.ZodObject<{
+    identity: z.ZodString;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+}, z.core.$strict>;
 /**
  * The first product path changes only prompt and skills, but it uses the
  * shared profile-diff language so execution and activation apply identical
@@ -190,9 +195,36 @@ export declare const agentProfileImprovementExperimentSchema: z.ZodObject<{
     digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
     source: z.ZodObject<{
         kind: z.ZodString;
-        sourceIdentity: z.ZodString;
+        sourceIdentity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
         sourceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
-        sourceRevision: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        sourceRevision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+        license: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"spdx">;
+            expression: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"custom">;
+            name: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+            reference: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+            termsDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], "kind">>;
+        attribution: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        transformations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                normalization: "normalization";
+                transformation: "transformation";
+            }>;
+            identity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+            revision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+            procedureDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            inputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            outputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    executionRef: z.ZodObject<{
+        identity: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
     }, z.core.$strict>;
     baseline: z.ZodObject<{
         stateDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -360,6 +392,11 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
     kind: z.ZodLiteral<"agent-profile-improvement-run">;
     digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
     executionId: z.ZodString;
+    executionRef: z.ZodObject<{
+        identity: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+    }, z.core.$strict>;
     runCell: z.ZodObject<{
         kind: z.ZodLiteral<"agent-profile-improvement-run-cell">;
         experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -426,6 +463,10 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
         reasoningTokens: z.ZodNumber;
         modelCalls: z.ZodNumber;
         costUsdNanos: z.ZodNumber;
+        costProvenance: z.ZodEnum<{
+            observed: "observed";
+            estimated: "estimated";
+        }>;
     }, z.core.$strict>;
     trace: z.ZodObject<{
         evidence: z.ZodObject<{
@@ -485,6 +526,10 @@ export declare const agentProfileImprovementRunReceiptSchema: z.ZodObject<{
             reasoningTokens: z.ZodNumber;
             modelCalls: z.ZodNumber;
             costUsdNanos: z.ZodNumber;
+            costProvenance: z.ZodEnum<{
+                observed: "observed";
+                estimated: "estimated";
+            }>;
         }, z.core.$strict>;
         score: z.ZodNumber;
         passed: z.ZodBoolean;
@@ -640,12 +685,37 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
     diff: z.ZodString;
     evaluation: z.ZodObject<{
         generationsExplored: z.ZodNumber;
-        searchDurationMs: z.ZodNumber;
-        executionDurationMs: z.ZodNumber;
-        durationMs: z.ZodNumber;
-        searchCostUsd: z.ZodNumber;
-        executionCostUsd: z.ZodNumber;
-        totalCostUsd: z.ZodNumber;
+        preparation: z.ZodObject<{
+            wallDurationMs: z.ZodNumber;
+            cost: z.ZodObject<{
+                usd: z.ZodNumber;
+                provenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        measurement: z.ZodObject<{
+            wallDurationMs: z.ZodNumber;
+            workDurationMs: z.ZodNumber;
+            cost: z.ZodObject<{
+                usd: z.ZodNumber;
+                provenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        total: z.ZodObject<{
+            wallDurationMs: z.ZodNumber;
+            cost: z.ZodObject<{
+                usd: z.ZodNumber;
+                provenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
     }, z.core.$strict>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<import("./agent-candidate.js").AgentCandidateJsonValue, import("./agent-candidate.js").AgentCandidateJsonValue>>>;
     kind: z.ZodLiteral<"agent-profile-improvement-measured-comparison">;
@@ -654,9 +724,36 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
         digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
         source: z.ZodObject<{
             kind: z.ZodString;
-            sourceIdentity: z.ZodString;
+            sourceIdentity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
             sourceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
-            sourceRevision: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            sourceRevision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+            license: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"spdx">;
+                expression: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"custom">;
+                name: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+                reference: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+                termsDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>], "kind">>;
+            attribution: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            transformations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    normalization: "normalization";
+                    transformation: "transformation";
+                }>;
+                identity: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+                revision: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, z.ZodNumber]>;
+                procedureDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                inputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                outputDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>;
+        executionRef: z.ZodObject<{
+            identity: z.ZodString;
+            digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
         }, z.core.$strict>;
         baseline: z.ZodObject<{
             stateDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -809,6 +906,11 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
             kind: z.ZodLiteral<"agent-profile-improvement-run">;
             digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
             executionId: z.ZodString;
+            executionRef: z.ZodObject<{
+                identity: z.ZodString;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+            }, z.core.$strict>;
             runCell: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-profile-improvement-run-cell">;
                 experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -875,6 +977,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                 reasoningTokens: z.ZodNumber;
                 modelCalls: z.ZodNumber;
                 costUsdNanos: z.ZodNumber;
+                costProvenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
             }, z.core.$strict>;
             trace: z.ZodObject<{
                 evidence: z.ZodObject<{
@@ -934,6 +1040,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                     reasoningTokens: z.ZodNumber;
                     modelCalls: z.ZodNumber;
                     costUsdNanos: z.ZodNumber;
+                    costProvenance: z.ZodEnum<{
+                        observed: "observed";
+                        estimated: "estimated";
+                    }>;
                 }, z.core.$strict>;
                 score: z.ZodNumber;
                 passed: z.ZodBoolean;
@@ -948,6 +1058,11 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
             kind: z.ZodLiteral<"agent-profile-improvement-run">;
             digestAlgorithm: z.ZodLiteral<"rfc8785-sha256">;
             executionId: z.ZodString;
+            executionRef: z.ZodObject<{
+                identity: z.ZodString;
+                digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+                kind: z.ZodLiteral<"agent-profile-improvement-execution-ref">;
+            }, z.core.$strict>;
             runCell: z.ZodObject<{
                 kind: z.ZodLiteral<"agent-profile-improvement-run-cell">;
                 experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -1014,6 +1129,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                 reasoningTokens: z.ZodNumber;
                 modelCalls: z.ZodNumber;
                 costUsdNanos: z.ZodNumber;
+                costProvenance: z.ZodEnum<{
+                    observed: "observed";
+                    estimated: "estimated";
+                }>;
             }, z.core.$strict>;
             trace: z.ZodObject<{
                 evidence: z.ZodObject<{
@@ -1073,6 +1192,10 @@ export declare const agentProfileImprovementMeasuredComparisonSchema: z.ZodObjec
                     reasoningTokens: z.ZodNumber;
                     modelCalls: z.ZodNumber;
                     costUsdNanos: z.ZodNumber;
+                    costProvenance: z.ZodEnum<{
+                        observed: "observed";
+                        estimated: "estimated";
+                    }>;
                 }, z.core.$strict>;
                 score: z.ZodNumber;
                 passed: z.ZodBoolean;

package/dist/agent-profile-improvement-schema.js

@@ -98,6 +98,11 @@ export const agentProfileImprovementArmSchema = z
     stateDigest: sha256DigestSchema,
 })
     .strict();
+export const agentProfileImprovementExecutionRefSchema = profileImprovementEvidenceSchema
+    .extend({
+    kind: z.literal("agent-profile-improvement-execution-ref"),
+})
+    .strict();
 /**
  * The first product path changes only prompt and skills, but it uses the
  * shared profile-diff language so execution and activation apply identical
@@ -176,6 +181,7 @@ export const agentProfileImprovementExperimentSchema = z
     kind: z.literal("agent-profile-improvement-experiment"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     source: agentImprovementSourceSchema,
+    executionRef: agentProfileImprovementExecutionRefSchema,
     baseline: agentProfileImprovementArmSchema,
     candidate: agentProfileImprovementArmSchema,
     change: agentProfileImprovementChangeSchema,
@@ -305,6 +311,7 @@ export const agentProfileImprovementRunReceiptSchema = z
     kind: z.literal("agent-profile-improvement-run"),
     digestAlgorithm: z.literal("rfc8785-sha256"),
     executionId: z.string().min(1).max(500),
+    executionRef: agentProfileImprovementExecutionRefSchema,
     runCell: agentProfileImprovementRunCellSchema,
     runRecord: profileImprovementEvidenceSchema,
     billing: z
@@ -362,7 +369,7 @@ export const agentProfileImprovementRunReceiptSchema = z
     refineAgentExecutionWithinLimits(receipt.limits, {
         durationMs: receipt.timing.durationMs,
         steps: receipt.steps,
-        usage: receipt.usage,
+        usage: combinedProfileUsage(receipt.usage, receipt.grading.usage),
     }, ctx);
     const billing = receipt.billing.map(evidenceKey);
     if (new Set(billing).size !== billing.length) {
@@ -380,6 +387,19 @@ export const agentProfileImprovementRunReceiptSchema = z
         });
     }
 });
+function combinedProfileUsage(execution, grading) {
+    return {
+        inputTokens: execution.inputTokens + grading.inputTokens,
+        outputTokens: execution.outputTokens + grading.outputTokens,
+        cachedInputTokens: execution.cachedInputTokens + grading.cachedInputTokens,
+        reasoningTokens: execution.reasoningTokens + grading.reasoningTokens,
+        modelCalls: execution.modelCalls + grading.modelCalls,
+        costUsdNanos: execution.costUsdNanos + grading.costUsdNanos,
+        costProvenance: execution.costProvenance === "observed" && grading.costProvenance === "observed"
+            ? "observed"
+            : "estimated",
+    };
+}
 const agentProfileImprovementMeasurementSchema = z
     .object({
     baseline: agentProfileImprovementRunReceiptSchema,
@@ -455,6 +475,11 @@ function refineProfileImprovementComparison(comparison, ctx) {
                         [...armPath, "runCell", "experimentDigest"],
                         "profile run receipt must bind the measured experiment",
                     ],
+                    [
+                        JSON.stringify(receipt.executionRef) === JSON.stringify(comparison.experiment.executionRef),
+                        [...armPath, "executionRef"],
+                        "profile run receipt must bind the measured executor",
+                    ],
                     [
                         cell.arm === arm,
                         [...armPath, "runCell", "arm"],
@@ -537,6 +562,7 @@ function refineProfileImprovementComparison(comparison, ctx) {
         score: (receipt) => receipt.grading.score,
         dimension: (receipt, name) => receipt.grading.dimensions.find((dimension) => dimension.name === name)?.score,
         cost: profileImprovementExecutionCostUsd,
+        costProvenance: profileImprovementExecutionCostProvenance,
         latency: profileImprovementExecutionLatencyMs,
     }, ctx);
     if (!isCanonicalJsonValue(comparison)) {
@@ -555,6 +581,12 @@ function evidenceKey(evidence) {
 function profileImprovementExecutionCostUsd(receipt) {
     return (receipt.usage.costUsdNanos + receipt.grading.usage.costUsdNanos) / 1_000_000_000;
 }
+function profileImprovementExecutionCostProvenance(receipt) {
+    return receipt.usage.costProvenance === "observed" &&
+        receipt.grading.usage.costProvenance === "observed"
+        ? "observed"
+        : "estimated";
+}
 function profileImprovementExecutionLatencyMs(receipt) {
     return receipt.timing.durationMs + receipt.grading.timing.durationMs;
 }

package/dist/agent-profile-improvement.d.ts

@@ -44,6 +44,10 @@ export interface AgentProfileImprovementSuiteInputs {
 export interface AgentProfileImprovementArm {
     stateDigest: Sha256Digest;
 }
+/** Exact non-secret identity of the runner that measured and can activate a profile change. */
+export interface AgentProfileImprovementExecutionRef extends AgentProfileImprovementEvidence {
+    kind: "agent-profile-improvement-execution-ref";
+}
 /**
  * Ordered portable profile patches retained for review and activation.
  *
@@ -58,6 +62,7 @@ export interface AgentProfileImprovementExperimentMaterial {
     kind: "agent-profile-improvement-experiment";
     digestAlgorithm: AgentCandidateDigestAlgorithm;
     source: AgentImprovementSource;
+    executionRef: AgentProfileImprovementExecutionRef;
     baseline: AgentProfileImprovementArm;
     candidate: AgentProfileImprovementArm;
     change: AgentProfileImprovementChange;
@@ -89,6 +94,7 @@ export interface AgentProfileImprovementRunReceipt {
     kind: "agent-profile-improvement-run";
     digestAlgorithm: AgentCandidateDigestAlgorithm;
     executionId: string;
+    executionRef: AgentProfileImprovementExecutionRef;
     runCell: AgentProfileImprovementRunCell;
     runRecord: AgentProfileImprovementEvidence;
     billing: [AgentProfileImprovementEvidence, ...AgentProfileImprovementEvidence[]];

package/dist/index.d.ts

@@ -615,6 +615,7 @@ export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";
 export type { Sha256Digest } from "./agent-candidate.js";
 export { canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, sha256Bytes, sha256DigestSchema, sha256Utf8, } from "./agent-candidate-schema-common.js";
+export { numbersApproximatelyEqual } from "./number-validation.js";
 export * from "./agent-candidate-promotion-schema.js";
 export { agentCandidateEvaluationPolicySchema } from "./agent-improvement-measurement-schema.js";
 export * from "./agent-improvement-source.js";

package/dist/index.js

@@ -127,6 +127,7 @@ export * from "./interaction.js";
 export * from "./agent-candidate.js";
 export * from "./agent-candidate-schema.js";
 export { canonicalCandidateBytes, canonicalCandidateDigest, canonicalCandidateJson, sha256Bytes, sha256DigestSchema, sha256Utf8, } from "./agent-candidate-schema-common.js";
+export { numbersApproximatelyEqual } from "./number-validation.js";
 export * from "./agent-candidate-promotion-schema.js";
 export { agentCandidateEvaluationPolicySchema } from "./agent-improvement-measurement-schema.js";
 export * from "./agent-improvement-source.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -34,10 +34,12 @@
   ],
   "dependencies": {
     "@noble/hashes": "1.8.0",
+    "spdx-expression-parse": "5.0.0",
     "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "25.6.0",
+    "@types/spdx-expression-parse": "4.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },