niceeval 0.13.1 → 0.13.2

package/dist/runner/types.d.cts

@@ -39,6 +39,8 @@ export interface ExperimentRunInfo {
     sandboxPlansByEval: globalThis.Record<string, JsonValue>;
     /** Sandbox 是否在同一次 Run 内复用。 */
     sandboxReuse?: boolean;
+    /** 跨 Invocation 共享外部状态的互斥声明；只记录稳定、非凭据 key。 */
+    sharedState?: SharedStateConfig;
     /** 解析后的 Judge 执行身份；只记录凭据选择器名，不记录凭据。 */
     judge?: Pick<JudgeConfig, "model" | "baseUrl" | "apiKeyEnv" | "timeoutMs">;
     /**
@@ -639,10 +641,10 @@ export interface EvalAuthorFields {
     tags?: string[];
     /**
      * 这道题贡献的 Sandbox 声明层。省略等价于空 command-only layer，不提供隐式 template。
-     * 每个实际 Eval x Experiment 配对必须恰好一方提供 template-bearing layer。
+     * 每个实际评估用例 × Experiment 配对必须恰好一方提供 template-bearing layer。
      */
     sandbox?: SandboxLayer;
-    /** Explicit, immutable Eval Plugin occurrences; no directory inheritance exists. */
+    /** 显式且不可变的评估用例 Plugin occurrence；不存在目录继承。 */
     plugins?: readonly PluginInstance<"eval">[];
     /** 声明 Judge capability；true 继承 Experiment/Config，对象同时声明并覆盖它们。 */
     judge?: JudgeDeclaration;
@@ -788,6 +790,13 @@ export interface ExperimentHookContext extends ScopedFeedback {
 }
 /** Shared lifecycle callback shape for author and Experiment Plugin hooks. */
 export type ExperimentHook = (ctx: ExperimentHookContext) => void | Promise<void>;
+/**
+ * 保护同一项目内共享的外部可变状态的互斥声明。它只提供跨 Invocation 的独占，不存储
+ * 状态、不提供事务，也不协调不同机器；`key` 必须稳定且不含凭据，并进入配置身份。
+ */
+export interface SharedStateConfig {
+    readonly key: string;
+}
 /** Experiment 作者自行选择的字段；不包含路径 id 与 factory 品牌。 */
 export interface ExperimentAuthorFields {
     /** 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。 */
@@ -845,17 +854,27 @@ export interface ExperimentAuthorFields {
     /** 同一 Run 内复用沙箱；这种运行与历史携带双向隔离。 */
     sandboxReuse?: boolean;
     /**
-     * 本实验的花费上限(USD)。调度器按「已完成 attempt 的实测花费」累计,到顶后跳过这个实验
-     * 剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`(已在飞的 attempt 仍会跑完)。
+     * 声明本 Experiment 需要独占的共享外部状态。相同 key 的 Invocation 在同一项目
+     * Coordination 域内从 Experiment/Sandbox setup 前一直互斥到 Sandbox teardown、
+     * provider finalizer 与 Experiment teardown 全部完成；等待者不会先创建 Sandbox，
+     * 取得租约后继续自己的 plan。它不是状态存储、事务或跨机器锁。
+     */
+    sharedState?: SharedStateConfig;
+    /**
+     * 本实验的估算花费上限(USD)。调度器累计已完成 attempt 的 `estimatedCostUSD`；该值由
+     * model、token usage 与 runtime/config pricing table 计算，与 Provider / Adapter 回报的
+     * observed `usage.costUSD` 独立，后者不驱动 budget。估算到顶后跳过这个实验剩下未起飞的
+     * attempt 并上报一次 `run:budgetExceeded`（已在飞的 attempt 仍会跑完）。
      */
     budget?: number;
     /**
-     * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
+     * 本 Invocation 内本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
      * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
      * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
      * 或给撞 provider 限额的实验单独降速。名额与 attempt 同生命周期:从沙箱创建前一直握到
      * teardown 与沙箱销毁完成才归还,中途任何等待(含 turn 重试退避)都不松手——
      * `maxConcurrency: 1` 因此是严格的临界区,不会被同实验的下一个 attempt 提前闯入。
+     * 它不跨 Invocation；跨 Invocation 的共享外部状态请声明 `sharedState`。
      */
     maxConcurrency?: number;
     /**
@@ -907,6 +926,7 @@ export interface ExperimentDefinition {
     readonly sandbox?: SandboxLayer;
     readonly plugins: readonly PluginInstance<"experiment">[];
     readonly sandboxReuse: boolean;
+    readonly sharedState?: SharedStateConfig;
     readonly budget?: number;
     readonly maxConcurrency?: number;
     readonly classifyFailure?: AttemptFailureClassifier;
@@ -1040,6 +1060,8 @@ export interface AgentRun {
     /** Canonical, credential-free Experiment Plugin behavior projection. */
     readonly pluginBehavior?: JsonValue;
     readonly sandboxReuse?: boolean;
+    /** 跨 Invocation 共享外部状态的互斥声明；值进入 configHash。 */
+    readonly sharedState?: SharedStateConfig;
     /** Experiment 声明的 judge 覆盖；与 Eval/Config 的逐字段解析在 pair 规划期完成。 */
     readonly judge?: JudgeConfig;
     /**
@@ -1115,6 +1137,8 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     onCurrentRecordReusePlan?: (input: {
         readonly reused: number;
         readonly reusedFailures: readonly FailureDetail[];
+        /** Draft identities become Human-visible only if the final receipt confirms publication. */
+        readonly runIds: ReadonlyMap<string, string>;
     }) => Effect.Effect<void, never>;
     /**
      * 已注册的 reporter,携带 name/required 元数据(见 `ReporterRegistration`)。这是内部编排
@@ -1370,6 +1394,8 @@ export interface InvocationCompletion {
  * 断言一次)。
  */
 export interface RunFeedbackState {
+    /** Draft 期的 Experiment → Run 映射；Human 只在 receipt 确认对应 Run 已发布后使用。 */
+    runIdsByExperiment: ReadonlyMap<string, string>;
     total: number;
     reused: number;
     running: number;

package/dist/runner/types.d.mts

@@ -39,6 +39,8 @@ export interface ExperimentRunInfo {
     sandboxPlansByEval: globalThis.Record<string, JsonValue>;
     /** Sandbox 是否在同一次 Run 内复用。 */
     sandboxReuse?: boolean;
+    /** 跨 Invocation 共享外部状态的互斥声明；只记录稳定、非凭据 key。 */
+    sharedState?: SharedStateConfig;
     /** 解析后的 Judge 执行身份；只记录凭据选择器名，不记录凭据。 */
     judge?: Pick<JudgeConfig, "model" | "baseUrl" | "apiKeyEnv" | "timeoutMs">;
     /**
@@ -639,10 +641,10 @@ export interface EvalAuthorFields {
     tags?: string[];
     /**
      * 这道题贡献的 Sandbox 声明层。省略等价于空 command-only layer，不提供隐式 template。
-     * 每个实际 Eval x Experiment 配对必须恰好一方提供 template-bearing layer。
+     * 每个实际评估用例 × Experiment 配对必须恰好一方提供 template-bearing layer。
      */
     sandbox?: SandboxLayer;
-    /** Explicit, immutable Eval Plugin occurrences; no directory inheritance exists. */
+    /** 显式且不可变的评估用例 Plugin occurrence；不存在目录继承。 */
     plugins?: readonly PluginInstance<"eval">[];
     /** 声明 Judge capability；true 继承 Experiment/Config，对象同时声明并覆盖它们。 */
     judge?: JudgeDeclaration;
@@ -788,6 +790,13 @@ export interface ExperimentHookContext extends ScopedFeedback {
 }
 /** Shared lifecycle callback shape for author and Experiment Plugin hooks. */
 export type ExperimentHook = (ctx: ExperimentHookContext) => void | Promise<void>;
+/**
+ * 保护同一项目内共享的外部可变状态的互斥声明。它只提供跨 Invocation 的独占，不存储
+ * 状态、不提供事务，也不协调不同机器；`key` 必须稳定且不含凭据，并进入配置身份。
+ */
+export interface SharedStateConfig {
+    readonly key: string;
+}
 /** Experiment 作者自行选择的字段；不包含路径 id 与 factory 品牌。 */
 export interface ExperimentAuthorFields {
     /** 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。 */
@@ -845,17 +854,27 @@ export interface ExperimentAuthorFields {
     /** 同一 Run 内复用沙箱；这种运行与历史携带双向隔离。 */
     sandboxReuse?: boolean;
     /**
-     * 本实验的花费上限(USD)。调度器按「已完成 attempt 的实测花费」累计,到顶后跳过这个实验
-     * 剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`(已在飞的 attempt 仍会跑完)。
+     * 声明本 Experiment 需要独占的共享外部状态。相同 key 的 Invocation 在同一项目
+     * Coordination 域内从 Experiment/Sandbox setup 前一直互斥到 Sandbox teardown、
+     * provider finalizer 与 Experiment teardown 全部完成；等待者不会先创建 Sandbox，
+     * 取得租约后继续自己的 plan。它不是状态存储、事务或跨机器锁。
+     */
+    sharedState?: SharedStateConfig;
+    /**
+     * 本实验的估算花费上限(USD)。调度器累计已完成 attempt 的 `estimatedCostUSD`；该值由
+     * model、token usage 与 runtime/config pricing table 计算，与 Provider / Adapter 回报的
+     * observed `usage.costUSD` 独立，后者不驱动 budget。估算到顶后跳过这个实验剩下未起飞的
+     * attempt 并上报一次 `run:budgetExceeded`（已在飞的 attempt 仍会跑完）。
      */
     budget?: number;
     /**
-     * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
+     * 本 Invocation 内本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
      * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
      * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
      * 或给撞 provider 限额的实验单独降速。名额与 attempt 同生命周期:从沙箱创建前一直握到
      * teardown 与沙箱销毁完成才归还,中途任何等待(含 turn 重试退避)都不松手——
      * `maxConcurrency: 1` 因此是严格的临界区,不会被同实验的下一个 attempt 提前闯入。
+     * 它不跨 Invocation；跨 Invocation 的共享外部状态请声明 `sharedState`。
      */
     maxConcurrency?: number;
     /**
@@ -907,6 +926,7 @@ export interface ExperimentDefinition {
     readonly sandbox?: SandboxLayer;
     readonly plugins: readonly PluginInstance<"experiment">[];
     readonly sandboxReuse: boolean;
+    readonly sharedState?: SharedStateConfig;
     readonly budget?: number;
     readonly maxConcurrency?: number;
     readonly classifyFailure?: AttemptFailureClassifier;
@@ -1040,6 +1060,8 @@ export interface AgentRun {
     /** Canonical, credential-free Experiment Plugin behavior projection. */
     readonly pluginBehavior?: JsonValue;
     readonly sandboxReuse?: boolean;
+    /** 跨 Invocation 共享外部状态的互斥声明；值进入 configHash。 */
+    readonly sharedState?: SharedStateConfig;
     /** Experiment 声明的 judge 覆盖；与 Eval/Config 的逐字段解析在 pair 规划期完成。 */
     readonly judge?: JudgeConfig;
     /**
@@ -1115,6 +1137,8 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     onCurrentRecordReusePlan?: (input: {
         readonly reused: number;
         readonly reusedFailures: readonly FailureDetail[];
+        /** Draft identities become Human-visible only if the final receipt confirms publication. */
+        readonly runIds: ReadonlyMap<string, string>;
     }) => Effect.Effect<void, never>;
     /**
      * 已注册的 reporter,携带 name/required 元数据(见 `ReporterRegistration`)。这是内部编排
@@ -1370,6 +1394,8 @@ export interface InvocationCompletion {
  * 断言一次)。
  */
 export interface RunFeedbackState {
+    /** Draft 期的 Experiment → Run 映射；Human 只在 receipt 确认对应 Run 已发布后使用。 */
+    runIdsByExperiment: ReadonlyMap<string, string>;
     total: number;
     reused: number;
     running: number;

package/dist/runner/types.d.ts

@@ -39,6 +39,8 @@ export interface ExperimentRunInfo {
     sandboxPlansByEval: globalThis.Record<string, JsonValue>;
     /** Sandbox 是否在同一次 Run 内复用。 */
     sandboxReuse?: boolean;
+    /** 跨 Invocation 共享外部状态的互斥声明；只记录稳定、非凭据 key。 */
+    sharedState?: SharedStateConfig;
     /** 解析后的 Judge 执行身份；只记录凭据选择器名，不记录凭据。 */
     judge?: Pick<JudgeConfig, "model" | "baseUrl" | "apiKeyEnv" | "timeoutMs">;
     /**
@@ -639,10 +641,10 @@ export interface EvalAuthorFields {
     tags?: string[];
     /**
      * 这道题贡献的 Sandbox 声明层。省略等价于空 command-only layer，不提供隐式 template。
-     * 每个实际 Eval x Experiment 配对必须恰好一方提供 template-bearing layer。
+     * 每个实际评估用例 × Experiment 配对必须恰好一方提供 template-bearing layer。
      */
     sandbox?: SandboxLayer;
-    /** Explicit, immutable Eval Plugin occurrences; no directory inheritance exists. */
+    /** 显式且不可变的评估用例 Plugin occurrence；不存在目录继承。 */
     plugins?: readonly PluginInstance<"eval">[];
     /** 声明 Judge capability；true 继承 Experiment/Config，对象同时声明并覆盖它们。 */
     judge?: JudgeDeclaration;
@@ -788,6 +790,13 @@ export interface ExperimentHookContext extends ScopedFeedback {
 }
 /** Shared lifecycle callback shape for author and Experiment Plugin hooks. */
 export type ExperimentHook = (ctx: ExperimentHookContext) => void | Promise<void>;
+/**
+ * 保护同一项目内共享的外部可变状态的互斥声明。它只提供跨 Invocation 的独占，不存储
+ * 状态、不提供事务，也不协调不同机器；`key` 必须稳定且不含凭据，并进入配置身份。
+ */
+export interface SharedStateConfig {
+    readonly key: string;
+}
 /** Experiment 作者自行选择的字段；不包含路径 id 与 factory 品牌。 */
 export interface ExperimentAuthorFields {
     /** 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。 */
@@ -845,17 +854,27 @@ export interface ExperimentAuthorFields {
     /** 同一 Run 内复用沙箱；这种运行与历史携带双向隔离。 */
     sandboxReuse?: boolean;
     /**
-     * 本实验的花费上限(USD)。调度器按「已完成 attempt 的实测花费」累计,到顶后跳过这个实验
-     * 剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`(已在飞的 attempt 仍会跑完)。
+     * 声明本 Experiment 需要独占的共享外部状态。相同 key 的 Invocation 在同一项目
+     * Coordination 域内从 Experiment/Sandbox setup 前一直互斥到 Sandbox teardown、
+     * provider finalizer 与 Experiment teardown 全部完成；等待者不会先创建 Sandbox，
+     * 取得租约后继续自己的 plan。它不是状态存储、事务或跨机器锁。
+     */
+    sharedState?: SharedStateConfig;
+    /**
+     * 本实验的估算花费上限(USD)。调度器累计已完成 attempt 的 `estimatedCostUSD`；该值由
+     * model、token usage 与 runtime/config pricing table 计算，与 Provider / Adapter 回报的
+     * observed `usage.costUSD` 独立，后者不驱动 budget。估算到顶后跳过这个实验剩下未起飞的
+     * attempt 并上报一次 `run:budgetExceeded`（已在飞的 attempt 仍会跑完）。
      */
     budget?: number;
     /**
-     * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
+     * 本 Invocation 内本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
      * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
      * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
      * 或给撞 provider 限额的实验单独降速。名额与 attempt 同生命周期:从沙箱创建前一直握到
      * teardown 与沙箱销毁完成才归还,中途任何等待(含 turn 重试退避)都不松手——
      * `maxConcurrency: 1` 因此是严格的临界区,不会被同实验的下一个 attempt 提前闯入。
+     * 它不跨 Invocation；跨 Invocation 的共享外部状态请声明 `sharedState`。
      */
     maxConcurrency?: number;
     /**
@@ -907,6 +926,7 @@ export interface ExperimentDefinition {
     readonly sandbox?: SandboxLayer;
     readonly plugins: readonly PluginInstance<"experiment">[];
     readonly sandboxReuse: boolean;
+    readonly sharedState?: SharedStateConfig;
     readonly budget?: number;
     readonly maxConcurrency?: number;
     readonly classifyFailure?: AttemptFailureClassifier;
@@ -1040,6 +1060,8 @@ export interface AgentRun {
     /** Canonical, credential-free Experiment Plugin behavior projection. */
     readonly pluginBehavior?: JsonValue;
     readonly sandboxReuse?: boolean;
+    /** 跨 Invocation 共享外部状态的互斥声明；值进入 configHash。 */
+    readonly sharedState?: SharedStateConfig;
     /** Experiment 声明的 judge 覆盖；与 Eval/Config 的逐字段解析在 pair 规划期完成。 */
     readonly judge?: JudgeConfig;
     /**
@@ -1115,6 +1137,8 @@ export interface RunOptions<RecordError = never, RecordRequirements = never> {
     onCurrentRecordReusePlan?: (input: {
         readonly reused: number;
         readonly reusedFailures: readonly FailureDetail[];
+        /** Draft identities become Human-visible only if the final receipt confirms publication. */
+        readonly runIds: ReadonlyMap<string, string>;
     }) => Effect.Effect<void, never>;
     /**
      * 已注册的 reporter,携带 name/required 元数据(见 `ReporterRegistration`)。这是内部编排
@@ -1370,6 +1394,8 @@ export interface InvocationCompletion {
  * 断言一次)。
  */
 export interface RunFeedbackState {
+    /** Draft 期的 Experiment → Run 映射；Human 只在 receipt 确认对应 Run 已发布后使用。 */
+    runIdsByExperiment: ReadonlyMap<string, string>;
     total: number;
     reused: number;
     running: number;