niceeval 0.17.0 → 0.17.1

package/dist/expect/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AAC9E,mDAAqD;AAA5C,uGAAA,WAAW,OAAA;AAEpB,mDAAwY;AAA/X,+FAAA,GAAG,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,wGAAA,YAAY,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,+FAAA,GAAG,OAAA;AAAE,8FAAA,EAAE,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,qGAAA,SAAS,OAAA;AAEtW,mEAAoH;AAA3G,8GAAA,UAAU,OAAA;AAAE,gHAAA,YAAY,OAAA;AAAE,wHAAA,oBAAoB,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAE3E,mEAAyF;AAAhF,uHAAA,mBAAmB,OAAA;AAAE,sHAAA,kBAAkB,OAAA","sourcesContent":["// niceeval/expect：只导出纯 Match factories。Fact、verdict 与 score use 由 context 负责。\nexport { defineJudge } from \"../assertions/judge.ts\";\nexport type { JudgeAnchor, JudgeDefinition, JudgeOptions } from \"../assertions/judge.ts\";\nexport { and, atLeast, atMost, commandMatch, commandSucceeded, countWhere, defineScoreMatch, defineValueMatch, equals, eventMatch, excludes, filterWhere, greaterThan, includes, includesUrl, inOrder, isDefined, isFalse, isTrue, jsonMatch, hasSections, lessThan, matches, mapEach, mapValue, not, or, pattern, referencesAnyPath, satisfies, similarity, toolMatch, } from \"../assertions/match.ts\";\nexport type { BooleanMatch, CollectionMatch, CollectionValue, CommandMatchOptions, EventMatch, EventOccurrenceMatch, EventOccurrenceQuantifiers, EventOccurrenceView, EventSequenceMatch, EventUpperBoundOccurrenceMatch, EventOptionsByType, LogicalCommandOccurrence, ManagedToolCalls, ManagedEventOccurrences, Match, MatchDomain, NumericComparisonMatch, TextMatchOptions, ToolMatch, ToolOccurrenceMatch, ToolSequenceMatch, ToolUpperBoundOccurrenceMatch, ToolMatchOptions, ToolOccurrenceQuantifiers, ToolOccurrenceView, ToolStatus, ValueMatch, ManagedScoreMatchOptions, ScoreMatch, ScoreMatchContext, ScoreMatchLlmFailure, ScoreMatchResult, ScoreMatchAnchor, } from \"../assertions/match.ts\";\nexport { factuality, faithfulness, instructionFollowing, pairwisePreference } from \"../assertions/judge-presets.ts\";\nexport type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, InstructionFollowingMaterial, PairwisePreferenceMaterial } from \"../assertions/judge-presets.ts\";\nexport { defineMaterialMatch, defineContextMatch } from \"../assertions/context-match.ts\";\nexport type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from \"../assertions/context-match.ts\";\nexport type { NumericMaterial } from \"../assertions/match.ts\";\nexport type { EvalUsage } from \"../o11y/eval-usage.ts\";\nexport type { CacheReadReport, CacheReadSummary } from \"../o11y/cache-read.ts\";\nexport type { AgentMatchContext } from \"../context/assert-first.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,8EAA8E;AAC9E,mDAAqD;AAA5C,uGAAA,WAAW,OAAA;AAEpB,mDAAwY;AAA/X,+FAAA,GAAG,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,wGAAA,YAAY,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,kGAAA,MAAM,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,+FAAA,GAAG,OAAA;AAAE,8FAAA,EAAE,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAAE,qGAAA,SAAS,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,qGAAA,SAAS,OAAA;AAEtW,mEAAoH;AAA3G,8GAAA,UAAU,OAAA;AAAE,gHAAA,YAAY,OAAA;AAAE,wHAAA,oBAAoB,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAE3E,mEAAyF;AAAhF,uHAAA,mBAAmB,OAAA;AAAE,sHAAA,kBAAkB,OAAA","sourcesContent":["// niceeval/expect：只导出纯 Match factories。Fact、verdict 与 score use 由 context 负责。\nexport { defineJudge } from \"../assertions/judge.ts\";\nexport type { JudgeAnchor, JudgeDefinition, JudgeOptions } from \"../assertions/judge.ts\";\nexport { and, atLeast, atMost, commandMatch, commandSucceeded, countWhere, defineScoreMatch, defineValueMatch, equals, eventMatch, excludes, filterWhere, greaterThan, includes, includesUrl, inOrder, isDefined, isFalse, isTrue, jsonMatch, hasSections, lessThan, matches, mapEach, mapValue, not, or, pattern, referencesAnyPath, satisfies, similarity, toolMatch, } from \"../assertions/match.ts\";\nexport type { BooleanMatch, CollectionMatch, CollectionValue, CommandMatchOptions, EventMatch, EventOccurrenceMatch, EventOccurrenceQuantifiers, EventOccurrenceView, EventSequenceMatch, EventUpperBoundOccurrenceMatch, EventOptionsByType, LogicalCommandOccurrence, ManagedToolCalls, ManagedEventOccurrences, Match, MatchDomain, NumericComparisonMatch, TextMatchOptions, ToolMatch, ToolOccurrenceMatch, ToolSequenceMatch, ToolUpperBoundOccurrenceMatch, ToolMatchOptions, ToolOccurrenceQuantifiers, ToolOccurrenceView, ToolStatus, ValueMatch, ManagedScoreMatchOptions, ScoreMatch, ScoreMatchContext, ScoreMatchLlmFailure, ScoreMatchResult, ScoreMatchAnchor, } from \"../assertions/match.ts\";\nexport { factuality, faithfulness, instructionFollowing, pairwisePreference } from \"../assertions/judge-presets.ts\";\nexport type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, InstructionFollowingMaterial, PairwisePreferenceMaterial } from \"../assertions/judge-presets.ts\";\nexport { defineMaterialMatch, defineContextMatch } from \"../assertions/context-match.ts\";\nexport type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from \"../assertions/context-match.ts\";\nexport type { NumericMaterial } from \"../assertions/match.ts\";\nexport type { EvalUsage, EvalCacheRead } from \"../o11y/eval-usage.ts\";\nexport type { CacheReadReport, CacheReadSummary } from \"../o11y/cache-read.ts\";\nexport type { AgentMatchContext } from \"../context/assert-first.ts\";\n"]}

package/dist/expect/index.d.cts

@@ -7,6 +7,6 @@ export type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, Inst
 export { defineMaterialMatch, defineContextMatch } from "../assertions/context-match.cjs";
 export type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from "../assertions/context-match.cjs";
 export type { NumericMaterial } from "../assertions/match.cjs";
-export type { EvalUsage } from "../o11y/eval-usage.cjs";
+export type { EvalUsage, EvalCacheRead } from "../o11y/eval-usage.cjs";
 export type { CacheReadReport, CacheReadSummary } from "../o11y/cache-read.cjs";
 export type { AgentMatchContext } from "../context/assert-first.cjs";

package/dist/expect/index.d.mts

@@ -7,6 +7,6 @@ export type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, Inst
 export { defineMaterialMatch, defineContextMatch } from "../assertions/context-match.mjs";
 export type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from "../assertions/context-match.mjs";
 export type { NumericMaterial } from "../assertions/match.mjs";
-export type { EvalUsage } from "../o11y/eval-usage.mjs";
+export type { EvalUsage, EvalCacheRead } from "../o11y/eval-usage.mjs";
 export type { CacheReadReport, CacheReadSummary } from "../o11y/cache-read.mjs";
 export type { AgentMatchContext } from "../context/assert-first.mjs";

package/dist/expect/index.d.ts

@@ -7,6 +7,6 @@ export type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, Inst
 export { defineMaterialMatch, defineContextMatch } from "../assertions/context-match.js";
 export type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from "../assertions/context-match.js";
 export type { NumericMaterial } from "../assertions/match.js";
-export type { EvalUsage } from "../o11y/eval-usage.js";
+export type { EvalUsage, EvalCacheRead } from "../o11y/eval-usage.js";
 export type { CacheReadReport, CacheReadSummary } from "../o11y/cache-read.js";
 export type { AgentMatchContext } from "../context/assert-first.js";

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,+CAA+C;AAC/C,uEAAuE;AACvE,yCAA2G;AAAlG,uGAAA,UAAU,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AACrF,2CAAoE;AAA3D,2GAAA,aAAa,OAAA;AAAE,mHAAA,qBAAqB,OAAA;AAC7C,kDAAoD;AAA3C,uGAAA,WAAW,OAAA;AAEpB,kDAAyD;AAAhD,4GAAA,gBAAgB,OAAA;AAGzB,0EAAuN;AAA9M,2HAAA,mBAAmB,OAAA;AAG5B,qCAA8D;AAArD,qGAAA,UAAU,OAAA;AAAE,iGAAA,MAAM,OAAA;AAAE,wGAAA,aAAa,OAAA;AAC1C,6CAA6C;AAC7C,6EAA6E;AAC7E,8DAAiG;AAAxF,wHAAA,oBAAoB,OAAA;AAAE,kHAAA,cAAc,OAAA;AAAE,kHAAA,cAAc,OAAA;AAK7D,kEAAmH;AAA1G,8GAAA,UAAU,OAAA;AAAE,gHAAA,YAAY,OAAA;AAAE,wHAAA,oBAAoB,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAG3E,wDAAiH;AAAxG,kHAAA,sBAAsB,OAAA;AAI/B,kEAAwF;AAA/E,uHAAA,mBAAmB,OAAA;AAAE,sHAAA,kBAAkB,OAAA","sourcesContent":["// niceeval 公开导出(import { … } from \"niceeval\")。\n// Agent/Adapter 相关见 \"niceeval/adapter\";Sandbox 相关见 \"niceeval/sandbox\"。\nexport { defineEval, defineScoreEval, defineEvalGroup, defineConfig, defineExperiment } from \"./define.ts\";\nexport { defineAdapter, defineAdapterContract } from \"./adapter.ts\";\nexport { defineJudge } from \"./assertions/judge.ts\";\nexport type { JudgeAnchor, JudgeDefinition, JudgeOptions } from \"./assertions/judge.ts\";\nexport { defineScoreMatch } from \"./assertions/match.ts\";\nexport type { ManagedScoreMatchOptions, ScoreMatch, ScoreMatchAnchor, ScoreMatchContext, ScoreMatchLlmFailure, ScoreMatchResult } from \"./assertions/match.ts\";\nexport type { AssertionEntryId } from \"./assertions/identity.ts\";\nexport { readScoreMatchAudit, type ScoreMatchAudit, type ScoreMatchAuditV3, type ScoreMatchAuditImageContent, type ScoreMatchAuditEnvelope, type ScoreMatchAuditReadResult, } from \"./assertions/score-match-audit.ts\";\nexport type { AgentSendWindowIdentity, AgentWorkspaceDiffEndpoint, AgentWorkspaceDiffHunks, AgentWorkspaceDiffPolicy, AgentWorkspaceDiff, AgentWorkspaceDiffWindow, AgentWorkspaceDiffWindowChange, } from \"./assertions/workspace-diff.ts\";\nexport type { AssertionCheck, ScoreFunction, PolymorphicBooleanAssertionHandle, PolymorphicMeasurementAssertionHandle, PostRunBooleanAssertionHandle, } from \"./assertions/api.ts\";\nexport { requireEnv, getEnv, stripComments } from \"./util.ts\";\n// 执行失败分类:抛出点糖衣类(声明死因波及多远)+ 结构守卫。判据、分类链与止损语义见\n// docs/feature/error-classification/README.md;`niceeval/adapter` 复导出同一份词表类型。\nexport { ExperimentFatalError, EvalFatalError, failureClassOf } from \"./shared/failure-class.ts\";\n// 类型(eval 作者会用到;跑哪个 agent / 用哪个 sandbox 见对应子路径)\nexport type { StreamEvent, ToolName, JsonValue, FlagValue, ExperimentFlags, JsonMatch, Usage, Turn, EvidenceCoverageStatus, EvidenceCoverageEntry, EvidenceCoverage, TurnEvidenceCoverage, TurnInput, InputFile, AnswerValue, InputResponse, RespondAnswer, TurnHandle, SessionHandle, TestContext, ScoreTestContext, Verdict, EvalAuthorFields, EvalInput, ScoreEvalInput, EvalDefinition, AnyEvalDefinition, EvalGroupMember, EvalGroupInput, EvalGroupDefinition, EvaluationKind, EvalDescriptor, ExperimentAuthorFields, SharedStateConfig, ExperimentInput, ExperimentDefinition, ExperimentHook, ExperimentHookContext, Config, LocalizedText, Reporter, ReporterEvent, EvalResult, AcceptedDifference, AcceptedResult, RetryAttemptRecord, InvocationSummary, InvocationShape, DiagnosticRecord, ExperimentRunInfo, SandboxRunInfo, ScriptResult, CommandResult, InputRequest, InputRequestFilter, O11ySummary, TraceSpan, SpanKind, DerivedFacts, FailureClass, FailureScope, AttemptFailureInfo, AttemptFailureClassifier, ExternalCause, ExternalCauseFact, ExternalCauseLink, ExternalCauseScalar, } from \"./types.ts\";\nexport type { Adapter, AdapterAssertionsFactory, AdapterAssertionsFactoryContext, AdapterCleanupContext, AttemptCancellation, AttemptSignal, AdapterContract, AdapterCreateContext, AdapterDefinition, AdapterEvalDefinition, AdapterEvalInput, AdapterIdentity, AdapterImplementation, AdapterImplementationInput, AdapterRuntimeDefinition, AdapterScoreEvalInput, EvalContext, ReservedAdapterContextKey, } from \"./adapter.ts\";\nexport type { ParsedTranscript } from \"./o11y/parsers/index.ts\";\nexport { factuality, faithfulness, instructionFollowing, pairwisePreference } from \"./assertions/judge-presets.ts\";\nexport type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, InstructionFollowingMaterial, PairwisePreferenceMaterial } from \"./assertions/judge-presets.ts\";\nexport type { JudgeProvider, JudgeSelection } from \"./judge/index.ts\";\nexport { MigrationRequiredError, type MigrationOccurrence, type ErrorSource } from \"./error-assistance/index.ts\";\nexport type { AdapterUsageInput, AdapterUsageSeal } from \"./adapter-usage.ts\";\nexport type { AdapterAttachmentInput, AdapterAttachmentReceipt } from \"./adapter-attachments.ts\";\nexport type { ExecutionDisplayBlock, ExecutionTraceActor, ExecutionTraceEvent, ExecutionTraceEvidence, ExecutionTraceInput, ExecutionTraceLimitation, ExecutionTraceLink, ExecutionTraceReceipt, ExecutionTraceScope, ExecutionTraceScopeMembership, ExecutionTraceSource, ExecutionTraceTime, TraceJson, } from \"./adapter-execution-trace.ts\";\nexport { defineMaterialMatch, defineContextMatch } from \"./assertions/context-match.ts\";\nexport type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from \"./assertions/context-match.ts\";\nexport type { AttemptUsageSnapshot, AdapterAttemptUsageSnapshot } from \"./o11y/adapter-usage-projection.ts\";\nexport type { EvalUsage } from \"./o11y/eval-usage.ts\";\nexport type { AgentMatchContext } from \"./context/assert-first.ts\";\nexport type { ModelSlotSelection, ResolvedModelSlot, ResolvedModelSlots } from \"./model-slots.ts\";\nexport type { CacheReadReport, CacheReadSummary } from \"./o11y/cache-read.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,+CAA+C;AAC/C,uEAAuE;AACvE,yCAA2G;AAAlG,uGAAA,UAAU,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,4GAAA,eAAe,OAAA;AAAE,yGAAA,YAAY,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AACrF,2CAAoE;AAA3D,2GAAA,aAAa,OAAA;AAAE,mHAAA,qBAAqB,OAAA;AAC7C,kDAAoD;AAA3C,uGAAA,WAAW,OAAA;AAEpB,kDAAyD;AAAhD,4GAAA,gBAAgB,OAAA;AAGzB,0EAAuN;AAA9M,2HAAA,mBAAmB,OAAA;AAG5B,qCAA8D;AAArD,qGAAA,UAAU,OAAA;AAAE,iGAAA,MAAM,OAAA;AAAE,wGAAA,aAAa,OAAA;AAC1C,6CAA6C;AAC7C,6EAA6E;AAC7E,8DAAiG;AAAxF,wHAAA,oBAAoB,OAAA;AAAE,kHAAA,cAAc,OAAA;AAAE,kHAAA,cAAc,OAAA;AAK7D,kEAAmH;AAA1G,8GAAA,UAAU,OAAA;AAAE,gHAAA,YAAY,OAAA;AAAE,wHAAA,oBAAoB,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAG3E,wDAAiH;AAAxG,kHAAA,sBAAsB,OAAA;AAI/B,kEAAwF;AAA/E,uHAAA,mBAAmB,OAAA;AAAE,sHAAA,kBAAkB,OAAA","sourcesContent":["// niceeval 公开导出(import { … } from \"niceeval\")。\n// Agent/Adapter 相关见 \"niceeval/adapter\";Sandbox 相关见 \"niceeval/sandbox\"。\nexport { defineEval, defineScoreEval, defineEvalGroup, defineConfig, defineExperiment } from \"./define.ts\";\nexport { defineAdapter, defineAdapterContract } from \"./adapter.ts\";\nexport { defineJudge } from \"./assertions/judge.ts\";\nexport type { JudgeAnchor, JudgeDefinition, JudgeOptions } from \"./assertions/judge.ts\";\nexport { defineScoreMatch } from \"./assertions/match.ts\";\nexport type { ManagedScoreMatchOptions, ScoreMatch, ScoreMatchAnchor, ScoreMatchContext, ScoreMatchLlmFailure, ScoreMatchResult } from \"./assertions/match.ts\";\nexport type { AssertionEntryId } from \"./assertions/identity.ts\";\nexport { readScoreMatchAudit, type ScoreMatchAudit, type ScoreMatchAuditV3, type ScoreMatchAuditImageContent, type ScoreMatchAuditEnvelope, type ScoreMatchAuditReadResult, } from \"./assertions/score-match-audit.ts\";\nexport type { AgentSendWindowIdentity, AgentWorkspaceDiffEndpoint, AgentWorkspaceDiffHunks, AgentWorkspaceDiffPolicy, AgentWorkspaceDiff, AgentWorkspaceDiffWindow, AgentWorkspaceDiffWindowChange, } from \"./assertions/workspace-diff.ts\";\nexport type { AssertionCheck, ScoreFunction, PolymorphicBooleanAssertionHandle, PolymorphicMeasurementAssertionHandle, PostRunBooleanAssertionHandle, } from \"./assertions/api.ts\";\nexport { requireEnv, getEnv, stripComments } from \"./util.ts\";\n// 执行失败分类:抛出点糖衣类(声明死因波及多远)+ 结构守卫。判据、分类链与止损语义见\n// docs/feature/error-classification/README.md;`niceeval/adapter` 复导出同一份词表类型。\nexport { ExperimentFatalError, EvalFatalError, failureClassOf } from \"./shared/failure-class.ts\";\n// 类型(eval 作者会用到;跑哪个 agent / 用哪个 sandbox 见对应子路径)\nexport type { StreamEvent, ToolName, JsonValue, FlagValue, ExperimentFlags, JsonMatch, Usage, Turn, EvidenceCoverageStatus, EvidenceCoverageEntry, EvidenceCoverage, TurnEvidenceCoverage, TurnInput, InputFile, AnswerValue, InputResponse, RespondAnswer, TurnHandle, SessionHandle, TestContext, ScoreTestContext, Verdict, EvalAuthorFields, EvalInput, ScoreEvalInput, EvalDefinition, AnyEvalDefinition, EvalGroupMember, EvalGroupInput, EvalGroupDefinition, EvaluationKind, EvalDescriptor, ExperimentAuthorFields, SharedStateConfig, ExperimentInput, ExperimentDefinition, ExperimentHook, ExperimentHookContext, Config, LocalizedText, Reporter, ReporterEvent, EvalResult, AcceptedDifference, AcceptedResult, RetryAttemptRecord, InvocationSummary, InvocationShape, DiagnosticRecord, ExperimentRunInfo, SandboxRunInfo, ScriptResult, CommandResult, InputRequest, InputRequestFilter, O11ySummary, TraceSpan, SpanKind, DerivedFacts, FailureClass, FailureScope, AttemptFailureInfo, AttemptFailureClassifier, ExternalCause, ExternalCauseFact, ExternalCauseLink, ExternalCauseScalar, } from \"./types.ts\";\nexport type { Adapter, AdapterAssertionsFactory, AdapterAssertionsFactoryContext, AdapterCleanupContext, AttemptCancellation, AttemptSignal, AdapterContract, AdapterCreateContext, AdapterDefinition, AdapterEvalDefinition, AdapterEvalInput, AdapterIdentity, AdapterImplementation, AdapterImplementationInput, AdapterRuntimeDefinition, AdapterScoreEvalInput, EvalContext, ReservedAdapterContextKey, } from \"./adapter.ts\";\nexport type { ParsedTranscript } from \"./o11y/parsers/index.ts\";\nexport { factuality, faithfulness, instructionFollowing, pairwisePreference } from \"./assertions/judge-presets.ts\";\nexport type { JudgePresetOptions, FactualityMaterial, FaithfulnessMaterial, InstructionFollowingMaterial, PairwisePreferenceMaterial } from \"./assertions/judge-presets.ts\";\nexport type { JudgeProvider, JudgeSelection } from \"./judge/index.ts\";\nexport { MigrationRequiredError, type MigrationOccurrence, type ErrorSource } from \"./error-assistance/index.ts\";\nexport type { AdapterUsageInput, AdapterUsageSeal } from \"./adapter-usage.ts\";\nexport type { AdapterAttachmentInput, AdapterAttachmentReceipt } from \"./adapter-attachments.ts\";\nexport type { ExecutionDisplayBlock, ExecutionTraceActor, ExecutionTraceEvent, ExecutionTraceEvidence, ExecutionTraceInput, ExecutionTraceLimitation, ExecutionTraceLink, ExecutionTraceReceipt, ExecutionTraceScope, ExecutionTraceScopeMembership, ExecutionTraceSource, ExecutionTraceTime, TraceJson, } from \"./adapter-execution-trace.ts\";\nexport { defineMaterialMatch, defineContextMatch } from \"./assertions/context-match.ts\";\nexport type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from \"./assertions/context-match.ts\";\nexport type { AttemptUsageSnapshot, AdapterAttemptUsageSnapshot } from \"./o11y/adapter-usage-projection.ts\";\nexport type { EvalUsage, EvalCacheRead } from \"./o11y/eval-usage.ts\";\nexport type { AgentMatchContext } from \"./context/assert-first.ts\";\nexport type { ModelSlotSelection, ResolvedModelSlot, ResolvedModelSlots } from \"./model-slots.ts\";\nexport type { CacheReadReport, CacheReadSummary } from \"./o11y/cache-read.ts\";\n"]}

package/dist/index.d.cts

@@ -23,7 +23,7 @@ export type { ExecutionDisplayBlock, ExecutionTraceActor, ExecutionTraceEvent, E
 export { defineMaterialMatch, defineContextMatch } from "./assertions/context-match.cjs";
 export type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from "./assertions/context-match.cjs";
 export type { AttemptUsageSnapshot, AdapterAttemptUsageSnapshot } from "./o11y/adapter-usage-projection.cjs";
-export type { EvalUsage } from "./o11y/eval-usage.cjs";
+export type { EvalUsage, EvalCacheRead } from "./o11y/eval-usage.cjs";
 export type { AgentMatchContext } from "./context/assert-first.cjs";
 export type { ModelSlotSelection, ResolvedModelSlot, ResolvedModelSlots } from "./model-slots.cjs";
 export type { CacheReadReport, CacheReadSummary } from "./o11y/cache-read.cjs";

package/dist/index.d.mts

@@ -23,7 +23,7 @@ export type { ExecutionDisplayBlock, ExecutionTraceActor, ExecutionTraceEvent, E
 export { defineMaterialMatch, defineContextMatch } from "./assertions/context-match.mjs";
 export type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from "./assertions/context-match.mjs";
 export type { AttemptUsageSnapshot, AdapterAttemptUsageSnapshot } from "./o11y/adapter-usage-projection.mjs";
-export type { EvalUsage } from "./o11y/eval-usage.mjs";
+export type { EvalUsage, EvalCacheRead } from "./o11y/eval-usage.mjs";
 export type { AgentMatchContext } from "./context/assert-first.mjs";
 export type { ModelSlotSelection, ResolvedModelSlot, ResolvedModelSlots } from "./model-slots.mjs";
 export type { CacheReadReport, CacheReadSummary } from "./o11y/cache-read.mjs";

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { ExecutionDisplayBlock, ExecutionTraceActor, ExecutionTraceEvent, E
 export { defineMaterialMatch, defineContextMatch } from "./assertions/context-match.js";
 export type { MaterialMatch, ContextBooleanMatch, ContextScoreMatch, MatchContext, ReadonlyMaterial, MatchFact, MaterialCollection, MaterialItem, MaterialCaptureBudget, FactCaptureBudget } from "./assertions/context-match.js";
 export type { AttemptUsageSnapshot, AdapterAttemptUsageSnapshot } from "./o11y/adapter-usage-projection.js";
-export type { EvalUsage } from "./o11y/eval-usage.js";
+export type { EvalUsage, EvalCacheRead } from "./o11y/eval-usage.js";
 export type { AgentMatchContext } from "./context/assert-first.js";
 export type { ModelSlotSelection, ResolvedModelSlot, ResolvedModelSlots } from "./model-slots.js";
 export type { CacheReadReport, CacheReadSummary } from "./o11y/cache-read.js";

package/dist/o11y/eval-usage.cjs

@@ -5,6 +5,24 @@ exports.projectAgentEvalUsage = projectAgentEvalUsage;
 const cache_read_ts_1 = require("./cache-read.cjs");
 const pricing_ts_1 = require("../record/family/adapter-usage/pricing.cjs");
 const adapter_usage_projection_ts_1 = require("./adapter-usage-projection.cjs");
+function authorCacheRead(report, models) {
+    const declared = new Set(Object.keys(models ?? {}));
+    const rates = new Map(report.modelSlots.map((group) => [group.modelSlot, group.rate]));
+    return Object.freeze({
+        ...report,
+        rate: (modelSlot) => {
+            if (modelSlot === undefined)
+                return report.total.rate;
+            if (!declared.has(modelSlot)) {
+                throw new TypeError(`Undeclared model slot ${JSON.stringify(modelSlot)}; declared slots: ${[...declared].join(", ") || "(none)"}.`);
+            }
+            const rate = rates.get(modelSlot);
+            if (rate !== undefined && !(rate.state === "unavailable" && rate.reason === "no-calls"))
+                return rate;
+            return Object.freeze({ state: "unavailable", reason: "slot-has-no-calls" });
+        },
+    });
+}
 function contributionCosts(calls, complete) {
     const totals = (0, adapter_usage_projection_ts_1.effectiveCostTotals)(calls, complete ? "complete" : "partial");
     return Object.freeze({
@@ -26,7 +44,7 @@ function projectAdapterEvalUsage(usage, models) {
         scope: "attempt",
         basis: "recorded-calls",
         cut: "call-time",
-        cacheRead: (0, cache_read_ts_1.projectCacheRead)(usage, models, true),
+        cacheRead: authorCacheRead((0, cache_read_ts_1.projectCacheRead)(usage, models, true), models),
         inputTokens: (0, adapter_usage_projection_ts_1.adapterTokenMaterial)(usage, "inputTokens"),
         inputTotalTokens: (0, adapter_usage_projection_ts_1.adapterTokenMaterial)(usage, "inputTotalTokens"),
         outputTokens: (0, adapter_usage_projection_ts_1.adapterTokenMaterial)(usage, "outputTokens"),
@@ -137,7 +155,7 @@ function projectAgentEvalUsage(input) {
         scope: input.scope,
         basis: "reported-sends",
         cut: "call-time",
-        cacheRead: (0, cache_read_ts_1.projectCacheRead)(null, undefined, false, "adapter-usage-required"),
+        cacheRead: authorCacheRead((0, cache_read_ts_1.projectCacheRead)(null, undefined, false, "adapter-usage-required")),
         inputTokens: agentTokenMaterial(input.contributions, "inputTokens", input.scope),
         inputTotalTokens: agentTokenMaterial(input.contributions, "inputTotalTokens", input.scope),
         outputTokens: agentTokenMaterial(input.contributions, "outputTokens", input.scope),

package/dist/o11y/eval-usage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"eval-usage.js","sourceRoot":"","sources":["eval-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import { projectCacheRead, type CacheReadReport } from \"./cache-read.ts\";\nimport type { ResolvedModelSlots } from \"../model-slots.ts\";\nimport type { NumericMaterial } from \"../assertions/match.ts\";\nimport type { ResolvedEvidenceCoverage } from \"../assertions/coverage.ts\";\nimport type { PriceOverride, Usage } from \"../types.ts\";\nimport type { ReadableAdapterUsageAttachment } from \"../record/family/adapter-usage/schema.ts\";\nimport { addCanonicalDecimals, canonicalDecimalFromNumber, multiplyCanonicalDecimalPerMillion, } from \"../record/family/adapter-usage/pricing.ts\";\nimport { adapterTokenMaterial, effectiveCostTotals, effectiveUsageCalls, type EffectiveCallCost, } from \"./adapter-usage-projection.ts\";\n/** Internal source-owned shape; package-root exposure belongs to the author facade. */\nexport interface EvalUsage {\n    readonly source: \"agent\" | \"adapter\" | \"unavailable\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly basis: \"reported-sends\" | \"recorded-calls\" | \"unbound\";\n    readonly cut: \"call-time\";\n    readonly cacheRead: CacheReadReport;\n    readonly inputTokens: NumericMaterial;\n    readonly inputTotalTokens: NumericMaterial;\n    readonly outputTokens: NumericMaterial;\n    readonly cacheReadTokens: NumericMaterial;\n    readonly cacheWriteTokens: NumericMaterial;\n    readonly totalTokens: NumericMaterial;\n    readonly costs: {\n        readonly state: \"complete\" | \"partial\" | \"unavailable\";\n        readonly values: readonly {\n            readonly currency: string;\n            readonly value: string;\n            readonly source: \"reported\" | \"estimated\" | \"mixed\";\n            readonly coveredContributions: number;\n            readonly reportedContributions: number;\n            readonly estimatedContributions: number;\n        }[];\n        readonly totalContributions: number;\n    };\n}\nexport interface AgentUsageContribution {\n    readonly sessionScopeId: string;\n    readonly turnId: string;\n    readonly sendAttempt: number;\n    readonly state: \"pending\" | \"terminal\";\n    readonly outcome: \"completed\" | \"failed\" | \"interrupted\" | null;\n    readonly model: string | null;\n    readonly usage: Readonly<Usage> | null;\n    readonly coverage: ResolvedEvidenceCoverage[\"usage\"];\n}\ntype TokenMetric = \"inputTokens\" | \"inputTotalTokens\" | \"outputTokens\" | \"cacheReadTokens\" | \"cacheWriteTokens\" | \"totalTokens\";\nfunction contributionCosts(calls: readonly {\n    readonly effectiveCost: EffectiveCallCost | null;\n}[], complete: boolean): EvalUsage[\"costs\"] {\n    const totals = effectiveCostTotals(calls, complete ? \"complete\" : \"partial\");\n    return Object.freeze({\n        state: totals.state,\n        values: Object.freeze(totals.values.map((value) => Object.freeze({\n            currency: value.currency,\n            value: value.value,\n            source: value.source,\n            coveredContributions: value.coveredCalls,\n            reportedContributions: value.reportedCalls,\n            estimatedContributions: value.estimatedCalls,\n        }))),\n        totalContributions: totals.totalCalls,\n    });\n}\nexport function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment, models?: ResolvedModelSlots): EvalUsage {\n    return Object.freeze({\n        source: \"adapter\",\n        scope: \"attempt\",\n        basis: \"recorded-calls\",\n        cut: \"call-time\",\n        cacheRead: projectCacheRead(usage, models, true),\n        inputTokens: adapterTokenMaterial(usage, \"inputTokens\"),\n        inputTotalTokens: adapterTokenMaterial(usage, \"inputTotalTokens\"),\n        outputTokens: adapterTokenMaterial(usage, \"outputTokens\"),\n        cacheReadTokens: adapterTokenMaterial(usage, \"cacheReadTokens\"),\n        cacheWriteTokens: adapterTokenMaterial(usage, \"cacheWriteTokens\"),\n        totalTokens: adapterTokenMaterial(usage, \"totalTokens\"),\n        costs: contributionCosts(effectiveUsageCalls(usage), usage.collection.state === \"complete\"),\n    });\n}\nfunction tokenBuckets(contribution: AgentUsageContribution, metric: TokenMetric): readonly (number | undefined)[] {\n    // Some producers have an independent total. Missing totals retain the mutually exclusive bucket fallback.\n    const usage: (Readonly<Usage> & {\n        readonly inputTotalTokens?: number;\n    }) | null = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return [undefined];\n    const input = usage.inputTotalTokens !== undefined\n        ? [usage.inputTotalTokens]\n        : [usage.inputTokens, usage.cacheReadTokens, usage.cacheCreationTokens];\n    switch (metric) {\n        case \"inputTotalTokens\": return input;\n        case \"totalTokens\": return [...input, usage.outputTokens];\n        case \"cacheWriteTokens\": return [usage.cacheCreationTokens];\n        default: return [usage[metric]];\n    }\n}\nfunction agentTokenMaterial(contributions: readonly AgentUsageContribution[], metric: TokenMetric, scope: EvalUsage[\"scope\"]): NumericMaterial {\n    const provenance = Object.freeze({ source: \"agent\", scope, unit: \"tokens\", cut: \"call-time\" });\n    let value = 0;\n    let observed = false;\n    let complete = contributions.length > 0;\n    for (const contribution of contributions) {\n        if (contribution.state !== \"terminal\" || contribution.coverage.status !== \"complete\")\n            complete = false;\n        for (const bucket of tokenBuckets(contribution, metric)) {\n            if (bucket === undefined) {\n                complete = false;\n                continue;\n            }\n            if (!Number.isSafeInteger(bucket) || bucket < 0) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-invalid-token-value\", provenance });\n            }\n            value += bucket;\n            observed = true;\n            if (!Number.isSafeInteger(value)) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-exceeds-safe-integer\", provenance });\n            }\n        }\n    }\n    return Object.freeze(!observed\n        ? { state: \"unavailable\", reason: \"usage-not-reported\", provenance }\n        : { state: complete ? \"exact\" : \"lower-bound\", value, provenance });\n}\nfunction agentCost(contribution: AgentUsageContribution, pricing: Record<string, PriceOverride> | undefined): EffectiveCallCost | null {\n    const usage = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return null;\n    const coverageComplete = contribution.coverage.status === \"complete\";\n    if (usage.costUSD !== undefined) {\n        const amount = canonicalDecimalFromNumber(usage.costUSD);\n        return amount === undefined ? null : Object.freeze({\n            amount, currency: \"USD\", source: Object.freeze({ kind: \"reported\", id: \"agent-send\" }),\n            state: coverageComplete ? \"complete\" : \"partial\",\n        });\n    }\n    const model = contribution.model;\n    if (model === null || pricing === undefined)\n        return null;\n    const wildcard = model.includes(\"/\") ? `${model.slice(0, model.indexOf(\"/\"))}/*` : undefined;\n    const profile = Object.hasOwn(pricing, model) ? pricing[model]\n        : wildcard !== undefined && Object.hasOwn(pricing, wildcard) ? pricing[wildcard] : undefined;\n    if (profile === undefined || profile.currency !== undefined && profile.currency !== \"USD\" ||\n        profile.basis !== undefined && profile.basis !== \"catalog-reference\")\n        return null;\n    const buckets = [\n        [usage.inputTokens, profile.inputPerMTok],\n        [usage.outputTokens, profile.outputPerMTok],\n        [usage.cacheReadTokens, profile.cacheReadPerMTok],\n        [usage.cacheCreationTokens, profile.cacheWritePerMTok],\n    ] as const;\n    const charges: string[] = [];\n    let complete = coverageComplete;\n    for (const [tokens, price] of buckets) {\n        if (tokens === undefined || !Number.isSafeInteger(tokens) || tokens < 0) {\n            complete = false;\n            continue;\n        }\n        if (tokens === 0) {\n            charges.push(\"0\");\n            continue;\n        }\n        const rate = price === undefined ? undefined : canonicalDecimalFromNumber(price);\n        if (rate === undefined) {\n            complete = false;\n            continue;\n        }\n        charges.push(multiplyCanonicalDecimalPerMillion(rate, tokens));\n    }\n    return charges.length === 0 ? null : Object.freeze({\n        amount: addCanonicalDecimals(charges),\n        currency: \"USD\",\n        source: Object.freeze({ kind: \"estimated\", id: profile.source?.id ?? \"niceeval.config.pricing\" }),\n        state: complete ? \"complete\" : \"partial\",\n    });\n}\n/** The receiver selects scope membership before calling this pure projection. */\nexport function projectAgentEvalUsage(input: {\n    contributions: readonly AgentUsageContribution[];\n    scope: \"turn\" | \"session\" | \"attempt\";\n    pricing?: Record<string, PriceOverride>;\n}): EvalUsage {\n    return Object.freeze({\n        source: \"agent\",\n        scope: input.scope,\n        basis: \"reported-sends\",\n        cut: \"call-time\",\n        cacheRead: projectCacheRead(null, undefined, false, \"adapter-usage-required\"),\n        inputTokens: agentTokenMaterial(input.contributions, \"inputTokens\", input.scope),\n        inputTotalTokens: agentTokenMaterial(input.contributions, \"inputTotalTokens\", input.scope),\n        outputTokens: agentTokenMaterial(input.contributions, \"outputTokens\", input.scope),\n        cacheReadTokens: agentTokenMaterial(input.contributions, \"cacheReadTokens\", input.scope),\n        cacheWriteTokens: agentTokenMaterial(input.contributions, \"cacheWriteTokens\", input.scope),\n        totalTokens: agentTokenMaterial(input.contributions, \"totalTokens\", input.scope),\n        costs: contributionCosts(input.contributions.map((contribution) => ({\n            effectiveCost: agentCost(contribution, input.pricing),\n        })), input.contributions.every((contribution) => contribution.state === \"terminal\" && contribution.coverage.status === \"complete\")),\n    });\n}\n"]}
+{"version":3,"file":"eval-usage.js","sourceRoot":"","sources":["eval-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import { projectCacheRead, type CacheReadReport } from \"./cache-read.ts\";\nimport type { ResolvedModelSlots } from \"../model-slots.ts\";\nimport type { NumericMaterial } from \"../assertions/match.ts\";\nimport type { ResolvedEvidenceCoverage } from \"../assertions/coverage.ts\";\nimport type { PriceOverride, Usage } from \"../types.ts\";\nimport type { ReadableAdapterUsageAttachment } from \"../record/family/adapter-usage/schema.ts\";\nimport { addCanonicalDecimals, canonicalDecimalFromNumber, multiplyCanonicalDecimalPerMillion, } from \"../record/family/adapter-usage/pricing.ts\";\nimport { adapterTokenMaterial, effectiveCostTotals, effectiveUsageCalls, type EffectiveCallCost, } from \"./adapter-usage-projection.ts\";\n/** Frozen cache report with author-facing selection by Experiment model purpose. */\nexport interface EvalCacheRead extends CacheReadReport {\n    /** Omit the slot for the total. An undeclared slot throws; missing observations remain unavailable. */\n    rate(modelSlot?: string): NumericMaterial;\n}\nfunction authorCacheRead(report: CacheReadReport, models?: ResolvedModelSlots): EvalCacheRead {\n    const declared = new Set(Object.keys(models ?? {}));\n    const rates = new Map(report.modelSlots.map((group) => [group.modelSlot, group.rate]));\n    return Object.freeze({\n        ...report,\n        rate: (modelSlot?: string): NumericMaterial => {\n            if (modelSlot === undefined)\n                return report.total.rate;\n            if (!declared.has(modelSlot)) {\n                throw new TypeError(`Undeclared model slot ${JSON.stringify(modelSlot)}; declared slots: ${[...declared].join(\", \") || \"(none)\"}.`);\n            }\n            const rate = rates.get(modelSlot);\n            if (rate !== undefined && !(rate.state === \"unavailable\" && rate.reason === \"no-calls\"))\n                return rate;\n            return Object.freeze({ state: \"unavailable\", reason: \"slot-has-no-calls\" });\n        },\n    });\n}\n/** Internal source-owned shape; package-root exposure belongs to the author facade. */\nexport interface EvalUsage {\n    readonly source: \"agent\" | \"adapter\" | \"unavailable\";\n    readonly scope: \"turn\" | \"session\" | \"attempt\";\n    readonly basis: \"reported-sends\" | \"recorded-calls\" | \"unbound\";\n    readonly cut: \"call-time\";\n    readonly cacheRead: EvalCacheRead;\n    readonly inputTokens: NumericMaterial;\n    readonly inputTotalTokens: NumericMaterial;\n    readonly outputTokens: NumericMaterial;\n    readonly cacheReadTokens: NumericMaterial;\n    readonly cacheWriteTokens: NumericMaterial;\n    readonly totalTokens: NumericMaterial;\n    readonly costs: {\n        readonly state: \"complete\" | \"partial\" | \"unavailable\";\n        readonly values: readonly {\n            readonly currency: string;\n            readonly value: string;\n            readonly source: \"reported\" | \"estimated\" | \"mixed\";\n            readonly coveredContributions: number;\n            readonly reportedContributions: number;\n            readonly estimatedContributions: number;\n        }[];\n        readonly totalContributions: number;\n    };\n}\nexport interface AgentUsageContribution {\n    readonly sessionScopeId: string;\n    readonly turnId: string;\n    readonly sendAttempt: number;\n    readonly state: \"pending\" | \"terminal\";\n    readonly outcome: \"completed\" | \"failed\" | \"interrupted\" | null;\n    readonly model: string | null;\n    readonly usage: Readonly<Usage> | null;\n    readonly coverage: ResolvedEvidenceCoverage[\"usage\"];\n}\ntype TokenMetric = \"inputTokens\" | \"inputTotalTokens\" | \"outputTokens\" | \"cacheReadTokens\" | \"cacheWriteTokens\" | \"totalTokens\";\nfunction contributionCosts(calls: readonly {\n    readonly effectiveCost: EffectiveCallCost | null;\n}[], complete: boolean): EvalUsage[\"costs\"] {\n    const totals = effectiveCostTotals(calls, complete ? \"complete\" : \"partial\");\n    return Object.freeze({\n        state: totals.state,\n        values: Object.freeze(totals.values.map((value) => Object.freeze({\n            currency: value.currency,\n            value: value.value,\n            source: value.source,\n            coveredContributions: value.coveredCalls,\n            reportedContributions: value.reportedCalls,\n            estimatedContributions: value.estimatedCalls,\n        }))),\n        totalContributions: totals.totalCalls,\n    });\n}\nexport function projectAdapterEvalUsage(usage: ReadableAdapterUsageAttachment, models?: ResolvedModelSlots): EvalUsage {\n    return Object.freeze({\n        source: \"adapter\",\n        scope: \"attempt\",\n        basis: \"recorded-calls\",\n        cut: \"call-time\",\n        cacheRead: authorCacheRead(projectCacheRead(usage, models, true), models),\n        inputTokens: adapterTokenMaterial(usage, \"inputTokens\"),\n        inputTotalTokens: adapterTokenMaterial(usage, \"inputTotalTokens\"),\n        outputTokens: adapterTokenMaterial(usage, \"outputTokens\"),\n        cacheReadTokens: adapterTokenMaterial(usage, \"cacheReadTokens\"),\n        cacheWriteTokens: adapterTokenMaterial(usage, \"cacheWriteTokens\"),\n        totalTokens: adapterTokenMaterial(usage, \"totalTokens\"),\n        costs: contributionCosts(effectiveUsageCalls(usage), usage.collection.state === \"complete\"),\n    });\n}\nfunction tokenBuckets(contribution: AgentUsageContribution, metric: TokenMetric): readonly (number | undefined)[] {\n    // Some producers have an independent total. Missing totals retain the mutually exclusive bucket fallback.\n    const usage: (Readonly<Usage> & {\n        readonly inputTotalTokens?: number;\n    }) | null = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return [undefined];\n    const input = usage.inputTotalTokens !== undefined\n        ? [usage.inputTotalTokens]\n        : [usage.inputTokens, usage.cacheReadTokens, usage.cacheCreationTokens];\n    switch (metric) {\n        case \"inputTotalTokens\": return input;\n        case \"totalTokens\": return [...input, usage.outputTokens];\n        case \"cacheWriteTokens\": return [usage.cacheCreationTokens];\n        default: return [usage[metric]];\n    }\n}\nfunction agentTokenMaterial(contributions: readonly AgentUsageContribution[], metric: TokenMetric, scope: EvalUsage[\"scope\"]): NumericMaterial {\n    const provenance = Object.freeze({ source: \"agent\", scope, unit: \"tokens\", cut: \"call-time\" });\n    let value = 0;\n    let observed = false;\n    let complete = contributions.length > 0;\n    for (const contribution of contributions) {\n        if (contribution.state !== \"terminal\" || contribution.coverage.status !== \"complete\")\n            complete = false;\n        for (const bucket of tokenBuckets(contribution, metric)) {\n            if (bucket === undefined) {\n                complete = false;\n                continue;\n            }\n            if (!Number.isSafeInteger(bucket) || bucket < 0) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-invalid-token-value\", provenance });\n            }\n            value += bucket;\n            observed = true;\n            if (!Number.isSafeInteger(value)) {\n                return Object.freeze({ state: \"unavailable\", reason: \"usage-exceeds-safe-integer\", provenance });\n            }\n        }\n    }\n    return Object.freeze(!observed\n        ? { state: \"unavailable\", reason: \"usage-not-reported\", provenance }\n        : { state: complete ? \"exact\" : \"lower-bound\", value, provenance });\n}\nfunction agentCost(contribution: AgentUsageContribution, pricing: Record<string, PriceOverride> | undefined): EffectiveCallCost | null {\n    const usage = contribution.usage;\n    if (contribution.state === \"pending\" || usage === null)\n        return null;\n    const coverageComplete = contribution.coverage.status === \"complete\";\n    if (usage.costUSD !== undefined) {\n        const amount = canonicalDecimalFromNumber(usage.costUSD);\n        return amount === undefined ? null : Object.freeze({\n            amount, currency: \"USD\", source: Object.freeze({ kind: \"reported\", id: \"agent-send\" }),\n            state: coverageComplete ? \"complete\" : \"partial\",\n        });\n    }\n    const model = contribution.model;\n    if (model === null || pricing === undefined)\n        return null;\n    const wildcard = model.includes(\"/\") ? `${model.slice(0, model.indexOf(\"/\"))}/*` : undefined;\n    const profile = Object.hasOwn(pricing, model) ? pricing[model]\n        : wildcard !== undefined && Object.hasOwn(pricing, wildcard) ? pricing[wildcard] : undefined;\n    if (profile === undefined || profile.currency !== undefined && profile.currency !== \"USD\" ||\n        profile.basis !== undefined && profile.basis !== \"catalog-reference\")\n        return null;\n    const buckets = [\n        [usage.inputTokens, profile.inputPerMTok],\n        [usage.outputTokens, profile.outputPerMTok],\n        [usage.cacheReadTokens, profile.cacheReadPerMTok],\n        [usage.cacheCreationTokens, profile.cacheWritePerMTok],\n    ] as const;\n    const charges: string[] = [];\n    let complete = coverageComplete;\n    for (const [tokens, price] of buckets) {\n        if (tokens === undefined || !Number.isSafeInteger(tokens) || tokens < 0) {\n            complete = false;\n            continue;\n        }\n        if (tokens === 0) {\n            charges.push(\"0\");\n            continue;\n        }\n        const rate = price === undefined ? undefined : canonicalDecimalFromNumber(price);\n        if (rate === undefined) {\n            complete = false;\n            continue;\n        }\n        charges.push(multiplyCanonicalDecimalPerMillion(rate, tokens));\n    }\n    return charges.length === 0 ? null : Object.freeze({\n        amount: addCanonicalDecimals(charges),\n        currency: \"USD\",\n        source: Object.freeze({ kind: \"estimated\", id: profile.source?.id ?? \"niceeval.config.pricing\" }),\n        state: complete ? \"complete\" : \"partial\",\n    });\n}\n/** The receiver selects scope membership before calling this pure projection. */\nexport function projectAgentEvalUsage(input: {\n    contributions: readonly AgentUsageContribution[];\n    scope: \"turn\" | \"session\" | \"attempt\";\n    pricing?: Record<string, PriceOverride>;\n}): EvalUsage {\n    return Object.freeze({\n        source: \"agent\",\n        scope: input.scope,\n        basis: \"reported-sends\",\n        cut: \"call-time\",\n        cacheRead: authorCacheRead(projectCacheRead(null, undefined, false, \"adapter-usage-required\")),\n        inputTokens: agentTokenMaterial(input.contributions, \"inputTokens\", input.scope),\n        inputTotalTokens: agentTokenMaterial(input.contributions, \"inputTotalTokens\", input.scope),\n        outputTokens: agentTokenMaterial(input.contributions, \"outputTokens\", input.scope),\n        cacheReadTokens: agentTokenMaterial(input.contributions, \"cacheReadTokens\", input.scope),\n        cacheWriteTokens: agentTokenMaterial(input.contributions, \"cacheWriteTokens\", input.scope),\n        totalTokens: agentTokenMaterial(input.contributions, \"totalTokens\", input.scope),\n        costs: contributionCosts(input.contributions.map((contribution) => ({\n            effectiveCost: agentCost(contribution, input.pricing),\n        })), input.contributions.every((contribution) => contribution.state === \"terminal\" && contribution.coverage.status === \"complete\")),\n    });\n}\n"]}

package/dist/o11y/eval-usage.d.cts

@@ -4,13 +4,18 @@ import type { NumericMaterial } from "../assertions/match.cjs";
 import type { ResolvedEvidenceCoverage } from "../assertions/coverage.cjs";
 import type { PriceOverride, Usage } from "../types.cjs";
 import type { ReadableAdapterUsageAttachment } from "../record/family/adapter-usage/schema.cjs";
+/** Frozen cache report with author-facing selection by Experiment model purpose. */
+export interface EvalCacheRead extends CacheReadReport {
+    /** Omit the slot for the total. An undeclared slot throws; missing observations remain unavailable. */
+    rate(modelSlot?: string): NumericMaterial;
+}
 /** Internal source-owned shape; package-root exposure belongs to the author facade. */
 export interface EvalUsage {
     readonly source: "agent" | "adapter" | "unavailable";
     readonly scope: "turn" | "session" | "attempt";
     readonly basis: "reported-sends" | "recorded-calls" | "unbound";
     readonly cut: "call-time";
-    readonly cacheRead: CacheReadReport;
+    readonly cacheRead: EvalCacheRead;
     readonly inputTokens: NumericMaterial;
     readonly inputTotalTokens: NumericMaterial;
     readonly outputTokens: NumericMaterial;

package/dist/o11y/eval-usage.d.mts

@@ -4,13 +4,18 @@ import type { NumericMaterial } from "../assertions/match.mjs";
 import type { ResolvedEvidenceCoverage } from "../assertions/coverage.mjs";
 import type { PriceOverride, Usage } from "../types.mjs";
 import type { ReadableAdapterUsageAttachment } from "../record/family/adapter-usage/schema.mjs";
+/** Frozen cache report with author-facing selection by Experiment model purpose. */
+export interface EvalCacheRead extends CacheReadReport {
+    /** Omit the slot for the total. An undeclared slot throws; missing observations remain unavailable. */
+    rate(modelSlot?: string): NumericMaterial;
+}
 /** Internal source-owned shape; package-root exposure belongs to the author facade. */
 export interface EvalUsage {
     readonly source: "agent" | "adapter" | "unavailable";
     readonly scope: "turn" | "session" | "attempt";
     readonly basis: "reported-sends" | "recorded-calls" | "unbound";
     readonly cut: "call-time";
-    readonly cacheRead: CacheReadReport;
+    readonly cacheRead: EvalCacheRead;
     readonly inputTokens: NumericMaterial;
     readonly inputTotalTokens: NumericMaterial;
     readonly outputTokens: NumericMaterial;

package/dist/o11y/eval-usage.d.ts

@@ -4,13 +4,18 @@ import type { NumericMaterial } from "../assertions/match.js";
 import type { ResolvedEvidenceCoverage } from "../assertions/coverage.js";
 import type { PriceOverride, Usage } from "../types.js";
 import type { ReadableAdapterUsageAttachment } from "../record/family/adapter-usage/schema.js";
+/** Frozen cache report with author-facing selection by Experiment model purpose. */
+export interface EvalCacheRead extends CacheReadReport {
+    /** Omit the slot for the total. An undeclared slot throws; missing observations remain unavailable. */
+    rate(modelSlot?: string): NumericMaterial;
+}
 /** Internal source-owned shape; package-root exposure belongs to the author facade. */
 export interface EvalUsage {
     readonly source: "agent" | "adapter" | "unavailable";
     readonly scope: "turn" | "session" | "attempt";
     readonly basis: "reported-sends" | "recorded-calls" | "unbound";
     readonly cut: "call-time";
-    readonly cacheRead: CacheReadReport;
+    readonly cacheRead: EvalCacheRead;
     readonly inputTokens: NumericMaterial;
     readonly inputTotalTokens: NumericMaterial;
     readonly outputTokens: NumericMaterial;

package/docs-site/zh/tutorials/control-run-cost.mdx

@@ -115,11 +115,9 @@ Headless Adapter 使用 `ctx.recordUsage` 登记真实调用，并在采集结
 ```ts
 import { atLeast } from "niceeval/expect";
 
-const planner = t.usage.cacheRead.modelSlots.find(group => group.modelSlot === "planner");
-t.check(
-  planner?.rate ?? { state: "unavailable", reason: "model-slot-not-recorded" },
-  atLeast(0.6),
-).gate();
+t.check(t.usage.cacheRead.rate("planner"), atLeast(0.6)).gate();
+// 不区分用途时，检查所有已登记调用的合计。
+t.check(t.usage.cacheRead.rate(), atLeast(0.6)).gate();
 ```
 
 读取率是同组调用的 **缓存读取 token 总量 / 含缓存输入 token 总量**，包括失败调用与重试。它不是逐次百分比的平均值。每次调用优先使用 `inputTotalTokens`；没有独立总量时，必须同时提供 `inputTokens`、`cacheReadTokens`、`cacheWriteTokens` 三个互斥桶。
@@ -129,3 +127,44 @@ t.check(
 缺失输入、未 seal、partial seal、unknown 调用状态、空组或零分母均返回 `unavailable`，`reasons` 列出原因。缺失不按零处理；完整且有正输入总量的零缓存读取率才是数值 0。旧账本没有明确的生产者完整性声明时，也返回不可判定。
 
 使用 `niceeval show <Attempt locator> --usage` 或 View 查看读取率、覆盖情况与原因；脚本通过 `attempt.usage` 的 `usage.cacheRead` 读取相同报告。已有 `recordUsage` 调用无需改名，但必须登记缓存 token，并在采集完成后诚实 seal。无需迁移历史结果文件。
+
+
+槽位名来自 Experiment 的 `models` 键，不是框架内置名单。`model` 单模型简写对应 `default`。
+传入未声明的槽位会在调用处报错，并列出可用名称。已声明但完整记录中没有调用的槽位返回 `slot-has-no-calls`；采集不完整时仍返回 `collection-incomplete`。
+Eval 可以被多个 Experiment 复用，因此此入口在运行回调里校验槽位，不在定义期检查动态字符串。
+
+### 登记命令行 Agent 的用量
+
+Adapter 应按外部回执记录真实调用，并将 `modelSlot` 设为 Experiment 声明的用途，例如 `mind`。
+同一请求的流式增量和最终回执不能各登记一次；先按请求 ID 合并，收到最终回执后再登记。
+
+```ts
+// 单次 Claude 请求的最终 usage；字段缺失时保留 null。
+ctx.recordUsage({
+  callId: requestId,
+  modelSlot: "mind",
+  provider: observedProvider,
+  model: observedModel,
+  status: observedStatus,
+  inputTokens: usage.input_tokens ?? null,
+  cacheReadTokens: usage.cache_read_input_tokens ?? null,
+  cacheWriteTokens: usage.cache_creation_input_tokens ?? null,
+  outputTokens: usage.output_tokens ?? null,
+});
+```
+
+Claude 的 `input_tokens` 是未命中缓存的输入桶，含缓存总量需加上读取和写入桶，见 [Claude 缓存用量说明](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。
+Codex 的 usage 若提供含缓存的 `input_tokens`，应映射到 `inputTotalTokens`，`cached_input_tokens` 映射到 `cacheReadTokens`，不要再把缓存加进总量。
+不能仅因命令成功退出就认定全部模型调用都已被记录；需核对所用 CLI 版本输出的是逐请求、Turn 还是会话合计。
+
+只有会话总量时，不要把多次物理调用伪装成一次调用，也不要把合计与明细同时登记。
+当前 `recordUsage` 的单位是物理调用；将会话合计保存在统计附件中，并声明 `partial`，缓存判据会诚实地显示不可判定。
+完全没有 usage 时同样声明 `partial`，不要填零或声明完整空账本：
+
+```ts
+ctx.sealUsage({ state: "partial", reason: "usage-not-exposed" });
+// 只提供会话总量、不能证明逐调用完整性时：
+// ctx.sealUsage({ state: "partial", reason: "session-totals-only" });
+```
+
+确实拿到全部物理调用的最终记录后，再调用 `ctx.sealUsage({ state: "complete" })`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",