@hue-run/sdk 0.4.1 → 0.4.2

package/CLI.md

@@ -42,8 +42,8 @@ project manifest are refused because managers can update ancestor locks; Python
 The generated `hue.setup.mjs` or `hue_setup.py` always selects `captureContent: false` /
 `capture_content=False`. For a supported application, setup installs the dependency and adds the
 managed import and middleware registration to the existing entrypoint; an unreferenced helper is
-not a completed integration. TypeScript uses `@hue-run/sdk@0.4.1`, `@opentelemetry/api@1.9.1` and
-`@opentelemetry/context-async-hooks@2.11.0`; Python uses `hue-run==0.2.2`.
+not a completed integration. TypeScript uses `@hue-run/sdk@0.4.2`, `@opentelemetry/api@1.9.1` and
+`@opentelemetry/context-async-hooks@2.11.0`; Python uses published `hue-run==0.2.2`.
 Content capture requires an ordinary account-managed key and a later explicit application decision.
 
 The generated bootstrap supplies standard active SERVER-span context across asynchronous/streaming
@@ -172,7 +172,7 @@ capability `setup_telemetry_write`.
 Normal project credentials and unknown token shapes are refused in setup responses and private
 managed state. These credentials authorize metadata-only OTLP at `/api/v1/otlp/v1/traces` and exact
 content-free receipt verification at `/api/v1/setup/traces/{traceId}/receipt`. They do not authorize
-generic project, receipt, evaluation, log or browsing APIs. Python `0.2.2` can export with the setup
+generic project, receipt, evaluation, log or browsing APIs. Published Python `0.2.2` can export with the setup
 credential; the CLI verifies the dedicated setup receipt instead of Python's generic receipt helper.
 
 Each command uses bounded timeouts and retries. Provisioning records at most five attempts per local
@@ -241,7 +241,7 @@ node packages/sdk-typescript/scripts/verify-package.mjs --artifacts-dir .artifac
 # Set project to an existing supported fixture; use the same directory on resume.
 project=/absolute/path/to/supported-fixture
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.4.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.4.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command setup \
   --evidence .context/setup-staging-before-claim.json
@@ -252,7 +252,7 @@ the private local handoff and finish the real browser claim, then reconcile the
 
 ```sh
 node packages/sdk-typescript/scripts/verify-setup-live.mjs \
-  --archive .artifacts/typescript/hue-run-sdk-0.4.1.tgz \
+  --archive .artifacts/typescript/hue-run-sdk-0.4.2.tgz \
   --origin https://STAGING_ORIGIN \
   --project "$project" --command claim \
   --evidence .context/setup-staging-after-claim.json

package/ENVIRONMENTS.md

@@ -30,7 +30,7 @@ try {
     environmentClient: createEnvironmentClient(connection),
     hue,
     checkpointDirectory: ".hue-checkpoints/refund-scenario",
-    scenario: { kind: "experiment", experimentId: process.env.HUE_EXPERIMENT_ID! },
+    definition: { kind: "experiment", experimentId: process.env.HUE_EXPERIMENT_ID! },
     persistResultContent: true,
     traceEvidence: { mode: "required" },
     target: (inputs, { tools, mcp, config, signal }) =>

package/dist/evals/simulation.d.ts

@@ -22,8 +22,8 @@ export interface RepositorySimulationCase {
     /** Optional caller-owned case metadata. */
     metadata?: Record<string, JsonValue>;
 }
-/** Immutable app-authored experiment reference or repository-authored scenario definition. */
-export type SimulationScenario = {
+/** Immutable app-authored experiment reference or repository-authored simulation definition. */
+export type SimulationDefinition = {
     /** Select an existing app-authored immutable experiment template. */
     kind: "experiment";
     /** Experiment to clone into a fresh attempt. */
@@ -118,8 +118,12 @@ export interface RunSimulationOptions {
     hue: HueClient;
     /** Dedicated private directory for resumable checkpoints. */
     checkpointDirectory: string;
-    /** App-authored reference or repository-authored scenario. */
-    scenario: SimulationScenario;
+    /** App-authored reference or repository-authored definition. */
+    definition?: SimulationDefinition;
+    /**
+     * @deprecated Use `definition`.
+     */
+    scenario?: SimulationDefinition;
     /** Required privacy decision for saved target/scorer content. */
     persistResultContent: boolean;
     /** Required trace receipt policy for every target attempt. */
@@ -178,6 +182,10 @@ export interface SimulationReport extends RunnerReport {
     /** Browser URL joining task, trace, world evidence and scoring. */
     runUrl: string;
 }
+/**
+ * @deprecated Use {@link SimulationDefinition}.
+ */
+export type SimulationScenario = SimulationDefinition;
 /** Run an existing agent callback against one fresh hosted world per case. The helper
  * owns immutable resolution, execution linkage, finalization, scoring and resumable uploads.
  */

package/dist/evals/simulation.js

@@ -46,24 +46,24 @@ function normalizedEnvironmentDefinition(definition) {
         metadata: definition.metadata ?? {},
     }, aggregateBounds(240_000));
 }
-function scenarioIdentity(scenario) {
-    if (scenario.kind === "experiment")
-        return scenario;
+function definitionIdentity(definition) {
+    if (definition.kind === "experiment")
+        return definition;
     return json({
-        kind: scenario.kind,
-        name: scenario.name,
-        slug: scenario.slug,
-        description: scenario.description ?? "",
+        kind: definition.kind,
+        name: definition.name,
+        slug: definition.slug,
+        description: definition.description ?? "",
         environment: {
-            ...scenario.environment,
-            definition: normalizedEnvironmentDefinition(scenario.environment.definition),
+            ...definition.environment,
+            definition: normalizedEnvironmentDefinition(definition.environment.definition),
         },
-        cases: scenario.cases,
-        scorers: scenario.scorers.map(({ scorer, ...identity }) => ({
+        cases: definition.cases,
+        scorers: definition.scorers.map(({ scorer, ...identity }) => ({
             ...identity,
             definition: normalizeScorerDefinitionForPublication("definition" in scorer ? scorer.definition : scorer),
         })),
-        config: scenario.config ?? {},
+        config: definition.config ?? {},
     }, aggregateBounds(8 * 1024 * 1024));
 }
 async function findBySlug(page, slug) {
@@ -283,9 +283,9 @@ async function allCases(client, versionId) {
         after = page.nextCursor;
     }
 }
-async function resolveExperiment(options, idempotencyKey) {
-    if (options.scenario.kind === "experiment") {
-        const source = await options.client.getExperiment(options.scenario.experimentId);
+async function resolveExperiment(options, definition, idempotencyKey) {
+    if (definition.kind === "experiment") {
+        const source = await options.client.getExperiment(definition.experimentId);
         const created = await options.client.createExperiment({
             idempotencyKey,
             name: options.runName ?? source.name,
@@ -295,25 +295,35 @@ async function resolveExperiment(options, idempotencyKey) {
         });
         return { experimentId: created.id, bindings: options.localScorers ?? [] };
     }
-    const environmentVersionId = await resolveEnvironment(options.environmentClient, options.scenario.environment);
-    const datasetVersionId = await resolveDataset(options.client, options.scenario, environmentVersionId);
-    const scorers = await resolveScorers(options.client, options.scenario.scorers);
+    const environmentVersionId = await resolveEnvironment(options.environmentClient, definition.environment);
+    const datasetVersionId = await resolveDataset(options.client, definition, environmentVersionId);
+    const scorers = await resolveScorers(options.client, definition.scorers);
     const created = await options.client.createExperiment({
         idempotencyKey,
-        name: options.runName ?? options.scenario.name,
+        name: options.runName ?? definition.name,
         datasetVersionId,
         scorerVersionIds: scorers.versionIds,
-        config: options.scenario.config ?? {},
+        config: definition.config ?? {},
     });
     return {
         experimentId: created.id,
         bindings: [...scorers.bindings, ...(options.localScorers ?? [])],
     };
 }
+let scenarioDeprecationWarned = false;
 /** Run an existing agent callback against one fresh hosted world per case. The helper
  * owns immutable resolution, execution linkage, finalization, scoring and resumable uploads.
  */
 export async function runSimulation(options) {
+    const definition = options.definition ?? options.scenario;
+    if (!definition)
+        throw new TypeError("runSimulation requires a definition");
+    if (options.definition && options.scenario && options.definition !== options.scenario)
+        throw new TypeError("Pass either definition or scenario, not both");
+    if (!options.definition && !scenarioDeprecationWarned) {
+        scenarioDeprecationWarned = true;
+        process.emitWarning("runSimulation option scenario is deprecated; use definition", "DeprecationWarning");
+    }
     const requestedConfiguration = requestedAttemptV2(options);
     if (options.maxSteps !== undefined &&
         (!Number.isInteger(options.maxSteps) ||
@@ -332,7 +342,7 @@ export async function runSimulation(options) {
         baseUrl: options.client.baseUrl,
     });
     try {
-        const scenarioDigest = digest(scenarioIdentity(options.scenario));
+        const scenarioDigest = digest(definitionIdentity(definition));
         let attempt = await store.read("active-attempt");
         if (attempt && attempt.stage !== "completed" && attempt.scenarioDigest !== scenarioDigest)
             throw new Error("Recover the unfinished simulation before running a changed scenario");
@@ -346,15 +356,15 @@ export async function runSimulation(options) {
         }
         let bindings = options.localScorers ?? [];
         if (!attempt.experimentId) {
-            const resolved = await resolveExperiment(options, attempt.idempotencyKey);
+            const resolved = await resolveExperiment(options, definition, attempt.idempotencyKey);
             attempt.experimentId = resolved.experimentId;
             bindings = resolved.bindings;
             attempt.stage = "running";
             await store.write("active-attempt", attempt);
         }
-        else if (options.scenario.kind === "repository") {
+        else if (definition.kind === "repository") {
             bindings = [
-                ...options.scenario.scorers
+                ...definition.scorers
                     .filter((item) => "definition" in item.scorer)
                     .map((item) => item.scorer),
                 ...(options.localScorers ?? []),

package/dist/evals.d.ts

@@ -3,7 +3,7 @@ export type { EvaluationClientOptions } from "./evals/client.js";
 export { runExperiment, rescore, UncertainExecutionError, OutcomeSerializationError, TargetCancelledError, TargetOutcomeUncertainError, } from "./evals/runner.js";
 export type { RunExperimentOptions, RescoreOptions, RunnerReport } from "./evals/runner.js";
 export { runSimulation } from "./evals/simulation.js";
-export type { RepositorySimulationCase, RepositorySimulationScorer, RunSimulationOptions, SimulationProgress, SimulationReport, SimulationScenario, SimulationTargetContext, } from "./evals/simulation.js";
+export type { RepositorySimulationCase, RepositorySimulationScorer, RunSimulationOptions, SimulationDefinition, SimulationProgress, SimulationReport, SimulationScenario, SimulationTargetContext, } from "./evals/simulation.js";
 export { actualAgentManifestV2, agentManifestDigestV2, attemptBaselineV2, attemptBindingRead, attemptConnectionBundleV2, attemptIdentityV2, dependencyManifestV2, dependencyProviderV2, expectedAgentManifestV2, executionManifestDigestV2, parityEvidenceV2, preflightFindingV2, preflightReportV2, prepareAttemptInputV2, projectMcpConnectionV2, secretFreeBindingV2, surfaceBindingV2, } from "./evals/attempt.js";
 export type { ActualAgentManifestInputV2, ActualAgentManifestV2, AttemptBaselineV2, AttemptBindingRead, AttemptConnectionBundleV2, AttemptIdentityV2, DependencyManifestV2, DependencyProviderV2, ExpectedAgentManifestV2, ParityEvidenceV2, PreflightFindingV2, PreflightReportV2, PrepareAttemptIncompleteV2, PrepareAttemptInputV2, PrepareAttemptReadyV2, PrepareAttemptRequestV2, PrepareAttemptResultV2, RefreshAttemptResultV2, RequestedAttemptProviderV2, RevokeAttemptResult, SurfaceBindingV2, } from "./evals/attempt.js";
 export { builtins, defineLocalScorer, scoreLocally } from "./evals/scorers.js";

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.4.1";
+export declare const sdkVersion = "0.4.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.4.1";
+export const sdkVersion = "0.4.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": false,
   "license": "MIT",
   "publishConfig": {