@hue-run/sdk 0.6.0 → 0.8.0

package/dist/environment/types.d.ts

@@ -275,6 +275,80 @@ export interface Effect {
     /** Changed field names. */
     fields: string[];
 }
+/** Lifecycle of a world the simulation gateway serves. */
+export type WorldLifecycle = "pending" | "live" | "completing" | "sealed";
+/** Advisory flags on a world's status read. */
+export type WorldFlag = "no_calls" | "fingerprint_differs";
+/** One pinned provider surface of one provider instance, as the mirror URL an official client
+ * is pointed at. `alias` stays null until the provider's alias hosts are served. */
+export interface WorldSurface {
+    /** Provider identity, such as `google.gmail`. */
+    provider: string;
+    /** Surface identity, such as `google.gmail/mcp` or `google.gmail/rest`. */
+    surface: string;
+    /** The provider instance of the environment version this surface belongs to. */
+    providerInstanceKey: string;
+    /** Mirror URL in the path form. */
+    url: string;
+    /** Alias-host URL, or null while unavailable. */
+    alias: string | null;
+}
+/** The headers an MCP client sends the mirror. */
+export interface WorldMcpHeaders {
+    /** `Bearer <world token>`. */
+    Authorization: string;
+}
+/** One MCP server entry of the common `mcpServers` configuration shape. */
+export interface WorldMcpServer {
+    /** Transport; the mirrors serve Streamable HTTP. */
+    type: "http";
+    /** Mirror URL of the MCP surface. */
+    url: string;
+    /** The world token as a bearer. */
+    headers: WorldMcpHeaders;
+}
+/** The `{ url, token, expiresAt }` shape the retired `hue_sim_` capability had. */
+export interface LegacyMcpCapability {
+    /** MCP endpoint: the world's first MCP mirror. */
+    url: string;
+    /** The world token. */
+    token: string;
+    /** The world deadline as an ISO timestamp. */
+    expiresAt: string;
+}
+/** The common `mcpServers` shape, one server per MCP surface of each provider instance. */
+export interface WorldMcpConfig {
+    /** Servers keyed by provider instance (suffixed by surface when an instance has several). */
+    mcpServers: Record<string, WorldMcpServer>;
+}
+/**
+ * What the World API hands an agent for one world: the world token in the provider's own
+ * credential slot, the mirror URLs, the environment carriers and the MCP configuration.
+ * Minted per response and never stored by Hue; keep it out of logs and checkpoints.
+ */
+export interface WorldHandoff {
+    /** World identity (the environment-run ID). */
+    id: string;
+    /** The `hue_world_…` credential; lives exactly as long as the world. */
+    token: string;
+    /** World deadline; the token outlives it by the 5 s completion grace. */
+    expiresAt: string;
+    /** Current lifecycle. */
+    lifecycle: WorldLifecycle;
+    /** Grace deadline while completing, else null. */
+    completingUntil: string | null;
+    /** The caller's trace context, echoed for the agent; null when none was supplied. */
+    traceparent: string | null;
+    /** `hue-world=<id>`, the OpenTelemetry baggage carrier value. */
+    baggage: string;
+    /** Mirror surfaces of every provider instance the environment version binds. */
+    surfaces: WorldSurface[];
+    /** `HUE_WORLD_ID`, `HUE_WORLD_TOKEN`, `BAGGAGE`, `TRACEPARENT` and one
+     * `HUE_SIM_<SURFACE ID>_URL` per surface. */
+    env: Record<string, string>;
+    /** The `mcpServers` configuration for the MCP surfaces. */
+    mcpConfig: WorldMcpConfig;
+}
 /** Newly created isolated world and its action catalog. */
 export interface EnvironmentRun {
     /** Environment-run identity. */
@@ -291,6 +365,26 @@ export interface EnvironmentRun {
     expiresAt: string;
     /** Closed generated action catalog. */
     actions: ActionDefinition[];
+    /** World identity; present for a world the simulation gateway serves. */
+    worldId?: string;
+    /** World token; present for a world the simulation gateway serves. */
+    token?: string;
+    /** Lifecycle; present for a world the simulation gateway serves. */
+    lifecycle?: WorldLifecycle;
+    /** Grace deadline while completing. */
+    completingUntil?: string | null;
+    /** Baggage carrier value. */
+    baggage?: string;
+    /** The stored caller trace context, or null. */
+    traceparent?: string | null;
+    /** Mirror surfaces. */
+    surfaces?: WorldSurface[];
+    /** Environment carriers. */
+    env?: Record<string, string>;
+    /** MCP configuration. */
+    mcpConfig?: WorldMcpConfig;
+    /** Reserved for connection keys; null today. */
+    connection?: null;
 }
 /** Result of invoking one environment action. */
 export interface ActionResult {
@@ -382,6 +476,20 @@ export interface RunState extends EnvironmentCoverage {
     stateDigest: string;
     /** Final state, available after sealing. */
     finalState?: JsonValue;
+    /** World identity; present for a world the simulation gateway serves. */
+    worldId?: string;
+    /** Lifecycle; present for a world the simulation gateway serves. */
+    lifecycle?: WorldLifecycle;
+    /** Grace deadline while completing. */
+    completingUntil?: string | null;
+    /** The trace the linked execution declared, or null. */
+    traceExternalId?: string | null;
+    /** Mirror surfaces. */
+    surfaces?: WorldSurface[];
+    /** Advisory flags. A status read never returns the token. */
+    flags?: WorldFlag[];
+    /** Reserved for connection keys; null today. */
+    connection?: null;
 }
 /** One immutable journal entry. */
 export interface Step {
@@ -423,9 +531,25 @@ export interface SealedRun {
     stepCount: number;
     /** Final state digest. */
     stateDigest: string;
-    /** Seal timestamp. */
-    sealedAt: string;
+    /** Seal timestamp; null while a gateway world is `completing` (its seal follows the grace). */
+    sealedAt: string | null;
+    /** Lifecycle after finish, for a world the simulation gateway serves. */
+    lifecycle?: "completing" | "sealed";
+    /** Grace deadline while completing. */
+    completingUntil?: string | null;
+}
+/** One section of a sealed world's evidence, or everything. */
+export type WorldEvidenceSection = "all" | "start" | "end" | "diff" | "ledger";
+/** Options for reading a sealed world's evaluator-only evidence. */
+export interface WorldEvidenceOptions {
+    /** One section, or everything (default). */
+    section?: WorldEvidenceSection;
+    /** Include ledger request and response bodies (default true). */
+    bodies?: boolean;
 }
+/** The evaluator-only evidence of a sealed world: start and end state, the diff, the call ledger,
+ * coverage and the fingerprint. Hue's shape is the authority; this client does not narrow it. */
+export type WorldEvidence = Record<string, JsonValue>;
 /** Options for creating one fresh isolated world. */
 export interface CreateRunInput {
     /** Stable idempotency key for recovering creation acknowledgement. */
@@ -440,6 +564,11 @@ export interface CreateRunInput {
     maxSteps?: number;
     /** Optional lease in seconds. */
     ttlSeconds?: number;
+    /** The case span's W3C context (`00-<trace id>-<span id>-<flags>`); its trace ID must equal
+     * the trace the execution declared at start. The world span is parented on it. */
+    traceparent?: string;
+    /** The agent revision under test, 1 to 256 characters; part of the world's fingerprint. */
+    agentRevision?: string;
 }
 /** Request to invoke one action. */
 export interface ActionInput {

package/dist/environment/world.d.ts

@@ -0,0 +1,50 @@
+import type { EnvironmentRun, LegacyMcpCapability, WorldHandoff } from "./types.js";
+/**
+ * The world an agent acts on through provider mirrors, read from a create or replay response.
+ * Null for a world created while the gateway was off: that world has Hue-native tools and no
+ * mirror URLs. The handoff carries the world token; keep it out of logs and checkpoints.
+ */
+export declare function worldHandoff(run: EnvironmentRun): WorldHandoff | null;
+/** Variables that authenticate against Hue's control plane rather than a simulated provider. */
+export declare const HUE_CONTROL_PLANE_VARIABLES: readonly string[];
+/** True for a control-plane variable by name, or for any variable holding a Hue credential. */
+export declare function isHueControlPlaneCredential(name: string, value: string | undefined): boolean;
+/** The parent's variables without Hue control-plane credentials; `undefined` values are dropped. */
+export declare function stripHueControlPlaneCredentials(parent: Record<string, string | undefined>): Record<string, string>;
+/** Options for {@link agentEnvironment}. */
+export interface AgentEnvironmentOptions {
+    /** The environment to start from; defaults to this process's. */
+    parent?: Record<string, string | undefined>;
+    /** Keep Hue control-plane credentials in the child. Off by default: the agent gets world
+     * tokens only (plan section 10.3) and the project key stays with the runner. */
+    includeHueCredentials?: boolean;
+    /** Also set `HUE_MCP_URL`, `HUE_MCP_TOKEN` and `HUE_MCP_EXPIRES_AT` from the world's first
+     * MCP mirror, the names the `hue_sim_` bridge used, for one compatibility release. On by
+     * default; the canonical carriers are the world's own `env`. */
+    legacyMcpVariables?: boolean;
+}
+/**
+ * The environment for an agent child process running one case (the coordination briefs'
+ * recommended policy): the parent's variables minus Hue control-plane credentials, then the
+ * world's carriers, which win over anything the parent set. Nothing here is logged.
+ */
+export declare function agentEnvironment(world: WorldHandoff, options?: AgentEnvironmentOptions): Record<string, string>;
+/** The `{ url, token, expiresAt }` shape the `hue_sim_` capability had, projected from the
+ * world's first MCP mirror so an adapter written for the bridge keeps working through the
+ * compatibility release. Undefined for a world without an MCP surface. */
+export declare function legacyMcpCapability(world: WorldHandoff): LegacyMcpCapability | undefined;
+/** The owner-only `mcpServers` file {@link writeMcpConfig} wrote. */
+export interface McpConfigFile {
+    /** The owner-only file; pass its path to the harness and dispose after the run. */
+    path: string;
+    /** Removes the file and its private directory; safe to call twice. */
+    dispose(): Promise<void>;
+}
+/**
+ * Writes the world's `mcpConfig` as an owner-only file in a private directory (plan section
+ * 4.9): the file carries the world token, so it is created with mode 0600 inside a 0700
+ * directory, is never logged, and `dispose` removes the directory after the run.
+ */
+export declare function writeMcpConfig(world: WorldHandoff, options?: {
+    directory?: string;
+}): Promise<McpConfigFile>;

package/dist/environment/world.js

@@ -0,0 +1,105 @@
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * The world an agent acts on through provider mirrors, read from a create or replay response.
+ * Null for a world created while the gateway was off: that world has Hue-native tools and no
+ * mirror URLs. The handoff carries the world token; keep it out of logs and checkpoints.
+ */
+export function worldHandoff(run) {
+    if (!run.token || !run.env || !run.mcpConfig || !run.surfaces)
+        return null;
+    const id = run.worldId ?? run.id;
+    return {
+        id,
+        token: run.token,
+        expiresAt: run.expiresAt,
+        lifecycle: run.lifecycle ?? "live",
+        completingUntil: run.completingUntil ?? null,
+        traceparent: run.traceparent ?? null,
+        baggage: run.baggage ?? `hue-world=${id}`,
+        surfaces: run.surfaces.map((surface) => ({ ...surface })),
+        env: { ...run.env },
+        mcpConfig: {
+            mcpServers: Object.fromEntries(Object.entries(run.mcpConfig.mcpServers).map(([name, server]) => [
+                name,
+                { type: server.type, url: server.url, headers: { ...server.headers } },
+            ])),
+        },
+    };
+}
+/** Variables that authenticate against Hue's control plane rather than a simulated provider. */
+export const HUE_CONTROL_PLANE_VARIABLES = [
+    "HUE_API_KEY",
+    "HUE_MCP_KEY",
+    "HUE_PROJECT_KEY",
+    "HUE_SERVICE_KEY",
+];
+/** Hue's own credential shapes: project keys, attempt grants and the project MCP key. */
+const HUE_CREDENTIAL_SHAPE = /^hue_(sk|attempt|mcp)_/;
+/** True for a control-plane variable by name, or for any variable holding a Hue credential. */
+export function isHueControlPlaneCredential(name, value) {
+    if (HUE_CONTROL_PLANE_VARIABLES.includes(name))
+        return true;
+    return typeof value === "string" && HUE_CREDENTIAL_SHAPE.test(value.trim());
+}
+/** The parent's variables without Hue control-plane credentials; `undefined` values are dropped. */
+export function stripHueControlPlaneCredentials(parent) {
+    const child = {};
+    for (const [name, value] of Object.entries(parent)) {
+        if (value === undefined || isHueControlPlaneCredential(name, value))
+            continue;
+        child[name] = value;
+    }
+    return child;
+}
+/**
+ * The environment for an agent child process running one case (the coordination briefs'
+ * recommended policy): the parent's variables minus Hue control-plane credentials, then the
+ * world's carriers, which win over anything the parent set. Nothing here is logged.
+ */
+export function agentEnvironment(world, options = {}) {
+    const parent = options.parent ?? process.env;
+    const child = options.includeHueCredentials
+        ? Object.fromEntries(Object.entries(parent).filter((entry) => entry[1] !== undefined))
+        : stripHueControlPlaneCredentials(parent);
+    Object.assign(child, world.env);
+    if (options.legacyMcpVariables ?? true) {
+        const legacy = legacyMcpCapability(world);
+        if (legacy) {
+            child.HUE_MCP_URL = legacy.url;
+            child.HUE_MCP_TOKEN = legacy.token;
+            child.HUE_MCP_EXPIRES_AT = legacy.expiresAt;
+        }
+    }
+    return child;
+}
+/** The `{ url, token, expiresAt }` shape the `hue_sim_` capability had, projected from the
+ * world's first MCP mirror so an adapter written for the bridge keeps working through the
+ * compatibility release. Undefined for a world without an MCP surface. */
+export function legacyMcpCapability(world) {
+    const server = Object.values(world.mcpConfig.mcpServers)[0];
+    if (!server)
+        return undefined;
+    return { url: server.url, token: world.token, expiresAt: world.expiresAt };
+}
+/**
+ * Writes the world's `mcpConfig` as an owner-only file in a private directory (plan section
+ * 4.9): the file carries the world token, so it is created with mode 0600 inside a 0700
+ * directory, is never logged, and `dispose` removes the directory after the run.
+ */
+export async function writeMcpConfig(world, options = {}) {
+    const directory = await mkdtemp(join(options.directory ?? tmpdir(), "hue-world-"));
+    const dispose = () => rm(directory, { recursive: true, force: true });
+    try {
+        await chmod(directory, 0o700);
+        const path = join(directory, "mcp.json");
+        await writeFile(path, `${JSON.stringify(world.mcpConfig, null, 2)}\n`, { mode: 0o600 });
+        return { path, dispose };
+    }
+    catch (error) {
+        // A half-written file would hold the token; never leave it behind.
+        await dispose();
+        throw error;
+    }
+}

package/dist/environment.d.ts

@@ -3,3 +3,5 @@ export type { EnvironmentClientOptions } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
 export type { BindEnvironmentToolsOptions, EnvironmentTool } from "./environment/tools.js";
 export type * from "./environment/types.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, writeMcpConfig, } from "./environment/world.js";
+export type { AgentEnvironmentOptions, McpConfigFile } from "./environment/world.js";

package/dist/environment.js

@@ -1,2 +1,3 @@
 export { createEnvironmentClient, EnvironmentClient, HueEnvironmentError, } from "./environment/client.js";
 export { bindEnvironmentTools } from "./environment/tools.js";
+export { agentEnvironment, HUE_CONTROL_PLANE_VARIABLES, isHueControlPlaneCredential, legacyMcpCapability, stripHueControlPlaneCredentials, worldHandoff, writeMcpConfig, } from "./environment/world.js";

package/dist/evals/environment-target.d.ts

@@ -1,6 +1,7 @@
 import type { HueClient } from "../client.js";
-import type { EnvironmentClient } from "../environment/client.js";
+import { type EnvironmentClient } from "../environment/client.js";
 import { type EnvironmentTool } from "../environment/tools.js";
+import type { EnvironmentRun, WorldHandoff } from "../environment/types.js";
 import type { HueSpan } from "../types.js";
 import { type ActualAgentManifestInputV2, type AttemptBaselineV2, type AttemptConnectionBundleV2, type RequestedAttemptProviderV2, type SurfaceBindingV2 } from "./attempt.js";
 import type { EvaluationClient } from "./client.js";
@@ -52,8 +53,16 @@ export interface EnvironmentTargetContext {
         traceId: string;
         spanId: string;
     };
+    /** Hue-native tools of a world created while the gateway was off; empty for a gateway
+     * world, whose calls go to the provider mirrors in `world`. */
     tools: Record<string, EnvironmentTool>;
-    mcp: SimulationMcpCapability;
+    /** The mirror URLs, world token, environment carriers and MCP configuration of a gateway
+     * world. Absent for a world created while the gateway was off. */
+    world?: WorldHandoff;
+    /** One MCP endpoint and bearer: for a gateway world, its first MCP mirror with the world
+     * token; otherwise the deprecated execution-scoped `hue_sim_` capability. Absent when a
+     * gateway world has no MCP surface. */
+    mcp?: SimulationMcpCapability;
     connectionBundle?: AttemptConnectionBundleV2;
     signal?: AbortSignal;
 }
@@ -72,10 +81,52 @@ export interface RunEnvironmentTargetOptions {
     requested?: PinnedAttemptV2;
     maxSteps?: number;
     ttlSeconds?: number;
+    /** The agent revision under test, sent on create for the world's fingerprint. */
+    agentRevision?: string;
+    /** Emit a one-time `DeprecationWarning` when a legacy path (Hue-native tools, the `hue_sim_`
+     * capability, the provider facade) is used; on by default. A harness that adapts to whatever
+     * the deployment serves, such as `hue eval`, turns it off. */
+    deprecationWarnings?: boolean;
     signal?: AbortSignal;
     onProgress?(event: EnvironmentTargetProgress): void | Promise<void>;
     target(inputs: JsonValue, context: EnvironmentTargetContext): JsonValue | undefined | Promise<JsonValue | undefined>;
 }
+/** The W3C context of the case span, sent on create so the world span parents on it. The
+ * flags are the span's own: an unsampled case span is not exported, and the World API must not
+ * be told otherwise. */
+export declare function caseTraceparent(span: {
+    traceId: string;
+    spanId: string;
+    span?: {
+        spanContext?(): {
+            traceFlags?: number;
+        };
+    };
+}): string;
+/** What a deployment's credential-free gateway health said: `on` (200 with
+ * `gateway: "simulation"`), `off` (the empty 404 the disabled handler answers, with no
+ * `x-hue-diagnostic`), or `unknown` for anything else. */
+export type GatewayState = "on" | "off" | "unknown";
+/**
+ * Whether the deployment serves the simulation gateway, from its credential-free health
+ * endpoint: 200 with `gateway: "simulation"` is on, the disabled handler's empty 404 (no
+ * `x-hue-diagnostic`) is off, and anything else (a network failure, a timeout, a redirect, a
+ * refusal carrying a diagnostic, another status or body) is unknown. Probed only after a create
+ * was refused; on and off are remembered per origin, unknown is probed again next time.
+ */
+export declare function gatewayState(baseUrl: string, fetchImpl?: (url: string, init?: RequestInit) => Promise<Response>): Promise<GatewayState>;
+/**
+ * Creates the world with the World API fields. An older deployment whose simulation gateway is
+ * off refuses them on the legacy create (400); when the deployment's health says the gateway is
+ * off, the create is repeated once without them and the world is the legacy kind. A 400 from a
+ * deployment with the gateway on is a real refusal (a trace context that does not match the
+ * execution, for one) and is raised as it is, and so is a 400 whose deployment's health is
+ * unknown (unreachable, a timeout): the fields are never dropped on a guess. The stable
+ * idempotency key makes a repeat a replay, never a second world.
+ */
+export declare function createWorldForExecution(client: Pick<EnvironmentClient, "createRun" | "baseUrl">, input: Parameters<EnvironmentClient["createRun"]>[0], options?: {
+    gatewayState?: (baseUrl: string) => Promise<GatewayState>;
+}): Promise<EnvironmentRun>;
 /** One authoritative environment/provider lifecycle shared by direct simulations and
  * outbound local workers. Credential-bearing connections stay in this call frame and
  * are never returned to either runner's checkpoint state.

package/dist/evals/environment-target.js

@@ -1,5 +1,7 @@
 import { randomUUID } from "node:crypto";
+import { HueEnvironmentError } from "../environment/client.js";
 import { bindEnvironmentTools } from "../environment/tools.js";
+import { legacyMcpCapability, worldHandoff } from "../environment/world.js";
 import { actualAgentManifestV2, attemptBaselineV2, projectMcpConnectionV2, requestedAttemptProvidersV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
 import { TargetCancelledError, TargetOutcomeUncertainError } from "./runner.js";
 export function requestedAttemptV2(options) {
@@ -49,11 +51,91 @@ async function seal(client, runId, executionId, status) {
         });
     }
     catch (error) {
+        // A gateway world answers 409 once it is completing, sealed or expired: each is the
+        // outcome the caller wanted or the one it can no longer change.
         const recovered = await client.getRun(runId).catch(() => undefined);
-        if (recovered?.status !== status && recovered?.status !== "expired")
+        if (recovered?.status !== status &&
+            recovered?.status !== "expired" &&
+            !(recovered?.status === "open" && recovered.lifecycle === "completing"))
             throw new TargetOutcomeUncertainError(executionId, { cause: error });
     }
 }
+const deprecations = new Set();
+/** One warning per process per legacy path. */
+function warnDeprecated(code, message) {
+    if (deprecations.has(code))
+        return;
+    deprecations.add(code);
+    process.emitWarning(message, { type: "DeprecationWarning", code });
+}
+/** The W3C context of the case span, sent on create so the world span parents on it. The
+ * flags are the span's own: an unsampled case span is not exported, and the World API must not
+ * be told otherwise. */
+export function caseTraceparent(span) {
+    let flags = 1;
+    try {
+        const context = span.span?.spanContext?.();
+        if (context && typeof context.traceFlags === "number")
+            flags = context.traceFlags;
+    }
+    catch {
+        // A span that cannot report its context is treated as sampled, as before.
+    }
+    return `00-${span.traceId}-${span.spanId}-${(flags & 0xff).toString(16).padStart(2, "0")}`;
+}
+const gatewayStates = new Map();
+/**
+ * Whether the deployment serves the simulation gateway, from its credential-free health
+ * endpoint: 200 with `gateway: "simulation"` is on, the disabled handler's empty 404 (no
+ * `x-hue-diagnostic`) is off, and anything else (a network failure, a timeout, a redirect, a
+ * refusal carrying a diagnostic, another status or body) is unknown. Probed only after a create
+ * was refused; on and off are remembered per origin, unknown is probed again next time.
+ */
+export function gatewayState(baseUrl, fetchImpl = fetch) {
+    const origin = new URL(baseUrl).origin;
+    const remembered = gatewayStates.get(origin);
+    if (remembered)
+        return remembered;
+    const probe = fetchImpl(`${origin}/api/sim/gmailmcp.googleapis.com/_hue/health`, { redirect: "error", signal: AbortSignal.timeout(5_000) })
+        .then(async (response) => {
+        if (response.status === 404)
+            return response.headers.has("x-hue-diagnostic") ? "unknown" : "off";
+        if (!response.ok)
+            return "unknown";
+        const body = (await response.json());
+        return body.gateway === "simulation" ? "on" : "unknown";
+    })
+        .catch(() => "unknown");
+    gatewayStates.set(origin, probe);
+    void probe.then((state) => {
+        if (state === "unknown" && gatewayStates.get(origin) === probe)
+            gatewayStates.delete(origin);
+    });
+    return probe;
+}
+/**
+ * Creates the world with the World API fields. An older deployment whose simulation gateway is
+ * off refuses them on the legacy create (400); when the deployment's health says the gateway is
+ * off, the create is repeated once without them and the world is the legacy kind. A 400 from a
+ * deployment with the gateway on is a real refusal (a trace context that does not match the
+ * execution, for one) and is raised as it is, and so is a 400 whose deployment's health is
+ * unknown (unreachable, a timeout): the fields are never dropped on a guess. The stable
+ * idempotency key makes a repeat a replay, never a second world.
+ */
+export async function createWorldForExecution(client, input, options = {}) {
+    try {
+        return await client.createRun(input);
+    }
+    catch (error) {
+        const { traceparent, agentRevision, ...legacy } = input;
+        if (!(error instanceof HueEnvironmentError) ||
+            error.status !== 400 ||
+            (traceparent === undefined && agentRevision === undefined) ||
+            (await (options.gatewayState ?? gatewayState)(client.baseUrl)) !== "off")
+            throw error;
+        return client.createRun(legacy);
+    }
+}
 /** One authoritative environment/provider lifecycle shared by direct simulations and
  * outbound local workers. Credential-bearing connections stay in this call frame and
  * are never returned to either runner's checkpoint state.
@@ -63,28 +145,42 @@ export async function runEnvironmentTarget(options) {
     const environmentVersionId = context.item.environmentVersionId;
     if (!environmentVersionId)
         throw new Error("The simulation case has no pinned environment version");
-    const run = await options.environmentClient.createRun({
+    // One stable idempotency key per case attempt: a replay after a lost acknowledgement gets
+    // the same world and the same token.
+    const run = await createWorldForExecution(options.environmentClient, {
         idempotencyKey: `execution:${context.executionId}`,
         environmentVersionId,
         executionId: context.executionId,
         maxSteps: options.maxSteps,
         ttlSeconds: options.ttlSeconds,
+        traceparent: caseTraceparent(context.span),
+        agentRevision: options.agentRevision,
     });
+    const world = worldHandoff(run);
     const progress = (event) => options.onProgress?.(event);
     let finalized = false;
     try {
         await progress({ type: "world_created", environmentRunId: run.id });
         if (options.signal?.aborted)
             throw new TargetCancelledError();
-        const tools = bindEnvironmentTools({
-            hue: options.hue,
-            client: options.environmentClient,
-            run,
-            parentContext: context.span.context,
-        });
+        // A gateway world refuses Hue-native actions (409 simulation_world); its agent reaches
+        // the provider mirrors in `world` instead.
+        const tools = world
+            ? {}
+            : bindEnvironmentTools({
+                hue: options.hue,
+                client: options.environmentClient,
+                run,
+                parentContext: context.span.context,
+            });
+        const warn = options.deprecationWarnings ?? true;
+        if (!world && warn)
+            warnDeprecated("HUE_NATIVE_SIMULATION_TOOLS", "Hue-native simulation tools and the hue_sim_ MCP capability are deprecated; worlds created through the simulation gateway hand the agent provider mirrors and a world token (context.world).");
         let connectionBundle;
         let mcp;
-        if (options.requested) {
+        if (options.requested && !world) {
+            if (warn)
+                warnDeprecated("HUE_PROVIDER_FACADE", "The provider facade (prepareAttempt) is deprecated; worlds created through the simulation gateway hand the agent provider mirrors and a world token (context.world).");
             const actualManifest = actualAgentManifestV2.parse(typeof options.requested.actualAgentManifest === "function"
                 ? await options.requested.actualAgentManifest({
                     config: structuredClone(context.config),
@@ -134,6 +230,13 @@ export async function runEnvironmentTarget(options) {
                 throw new TypeError("The prepared attempt has no selected MCP surface");
             mcp = projected;
         }
+        else if (world) {
+            // A gateway world is served by the provider mirrors; the facade's attempt preflight
+            // belongs to the legacy transport and is not run for it.
+            if (options.requested && warn)
+                warnDeprecated("HUE_PROVIDER_FACADE_IGNORED", "Provider-profile options (requestedProviders, mcpSurface, actualAgentManifest) are ignored for a world the simulation gateway serves; the agent receives the provider mirrors in context.world.");
+            mcp = legacyMcpCapability(world);
+        }
         else {
             mcp = await options.client.createSimulationMcpCapability({
                 runId: run.id,
@@ -150,7 +253,8 @@ export async function runEnvironmentTarget(options) {
             environmentRunId: run.id,
             trace: { traceId: context.span.traceId, spanId: context.span.spanId },
             tools,
-            mcp,
+            ...(world ? { world } : {}),
+            ...(mcp ? { mcp } : {}),
             ...(connectionBundle ? { connectionBundle } : {}),
             signal: options.signal,
         });

package/dist/evals/local-worker.d.ts

@@ -1,6 +1,7 @@
 import type { HueClient } from "../client.js";
 import type { EnvironmentClient } from "../environment/client.js";
 import type { EnvironmentTool } from "../environment/tools.js";
+import type { WorldHandoff } from "../environment/types.js";
 import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
 import type { EvaluationClient } from "./client.js";
 import { type RunExperimentTargetContext, type RunnerReport } from "./runner.js";
@@ -30,13 +31,17 @@ export interface LocalAgentTargetContext {
         /** Root execution span identifier. */
         spanId: string;
     };
-    /** Short-lived, execution-scoped hosted tools for model providers that execute MCP remotely. */
-    mcp: {
-        /** Execution-scoped MCP endpoint. */
+    /** The mirror URLs, world token, environment carriers and MCP configuration of a gateway
+     * world; absent for a world created while the gateway was off. */
+    world?: WorldHandoff;
+    /** One MCP endpoint and bearer: the gateway world's first MCP mirror with the world token,
+     * or the deprecated execution-scoped `hue_sim_` capability of a legacy world. */
+    mcp?: {
+        /** MCP endpoint. */
         url: string;
-        /** Short-lived bearer, never the project service key. */
+        /** Bearer for that endpoint, never the project service key. */
         token: string;
-        /** Capability expiry as an ISO timestamp. */
+        /** Expiry as an ISO timestamp. */
         expiresAt: string;
     };
     /** Credential-bearing provider connections for this callback only. Hue never
@@ -89,6 +94,8 @@ export interface RunLocalAgentOptions {
     signal?: AbortSignal;
     /** Useful for one-shot jobs and deterministic acceptance. Omit to keep polling. */
     maxRuns?: number;
+    /** Emit a one-time `DeprecationWarning` when the deployment serves a legacy world; on by default. */
+    deprecationWarnings?: boolean;
     /** Opt into the experiment's immutable V2 provider profile. These three values are
      * validated together before the worker polls; no endpoint or credential is supplied here. */
     actualAgentManifest?: ActualAgentManifestInputV2 | ((context: {

package/dist/evals/local-worker.js

@@ -31,11 +31,16 @@ function localAgentTargetContext(context) {
         executionId: context.executionId,
         environmentRunId: context.environmentRunId,
         trace: { traceId: context.trace.traceId, spanId: context.trace.spanId },
-        mcp: {
-            url: context.mcp.url,
-            token: context.mcp.token,
-            expiresAt: context.mcp.expiresAt,
-        },
+        ...(context.world ? { world: structuredClone(context.world) } : {}),
+        ...(context.mcp
+            ? {
+                mcp: {
+                    url: context.mcp.url,
+                    token: context.mcp.token,
+                    expiresAt: context.mcp.expiresAt,
+                },
+            }
+            : {}),
         ...(context.connectionBundle
             ? { connectionBundle: structuredClone(context.connectionBundle) }
             : {}),
@@ -178,6 +183,9 @@ export async function runLocalAgent(options) {
                             inputs,
                             context,
                             requested,
+                            // The registered revision is the agent revision under test.
+                            agentRevision: options.agent.revision,
+                            deprecationWarnings: options.deprecationWarnings,
                             signal: options.signal,
                             target: (targetInputs, targetContext) => target(structuredClone(targetInputs), targetContext.tools, localAgentTargetContext(targetContext)),
                         });