@hue-run/sdk 0.2.2 → 0.3.0

package/ENVIRONMENTS.md

@@ -1,9 +1,10 @@
 # Simulated environments
 
-Install the optional evaluation runtime-contract peer with the SDK:
+This guide documents the TypeScript `0.3.0` release candidate. Until registry acceptance, use
+the exact reviewed archive rather than requesting `0.3.0` from npm:
 
 ```bash
-npm install @hue-run/sdk zod
+npm install /path/to/reviewed/hue-run-sdk-0.3.0.tgz zod
 ```
 
 Your agent runs in your process while a disposable simulated world runs in Hue. The world is
@@ -77,11 +78,12 @@ them to checkpoints or progress events, and it never mutates global `process.env
 world seal cannot be confirmed, the checkpoint remains uncertain and resume neither reacquires
 credentials nor invokes the callback again.
 
-This is currently a control-plane contract. Hue can issue provider endpoints under
-`/api/v1/provider-facades/{bindingId}/{grantId}`, but a provider data-plane facade call has not
-yet been proven by the released integration. The existing generic Hue MCP capability remains the
-runnable hosted-tool path; do not interpret preparation or local-tool tests as evidence of a
-hosted Gmail or Slack MCP call.
+The SDK consumes the versioned connection contract but does not itself establish provider
+fidelity. Public package acceptance exercises local control-plane responses and connection-bundle
+handling; it does not call the issued facade endpoint. Exact installed-registry-package to hosted-
+facade acceptance remains a post-publication Fern integration gate. No public SDK test calls the
+official Gmail service, and passing these tests is not evidence of universal Gmail or Slack
+parity. A matching Hue deployment and verified provider profile remain required.
 
 ## Repository-authored scenarios
 
@@ -97,6 +99,13 @@ identity-affecting defaults as Hue before resolving versions and rejects unknown
 kinds. In particular, `document_verifier` is not part of this SDK contract and is rejected rather
 than published with a guessed digest.
 
+The extendable `EnvironmentDefinition` name remains the V1 contract and is also exported as
+`EnvironmentDefinitionV1`. Use `EnvironmentDefinitionV2` to add immutable Gmail
+`providerInstances`; `PublishableEnvironmentDefinition` is the publication/repository union.
+Hue canonicalizes valid synthetic-principal UUIDs to lowercase, and repository resolution does
+the same before comparing immutable digests, so casing-only UUID changes reuse the stored
+version without dropping provider bindings.
+
 ```ts
 const scenario = {
   kind: "repository" as const,
@@ -180,3 +189,13 @@ that cannot be confirmed stays uncertain and never causes the agent to be replay
 The hosted MCP connection exposes Hue's bounded native actions; it is not general Gmail or
 Slack HTTP parity and does not proxy arbitrary provider traffic. Forking, in-place reset and
 arbitrary-step diffs are outside this interface.
+
+## Candidate context migration
+
+This candidate-context restriction is part of the `@hue-run/sdk@0.3.0` release candidate.
+
+`runSimulation` now supplies `context.item` as `{ id, externalKey }`. Read candidate inputs
+from the callback's first argument. Expected outcomes, case metadata and environment-version
+pins are available to evaluation and scoring code, and are omitted from the candidate callback.
+Inputs and configuration are cloned before invocation so candidate mutations cannot change
+pinned grading data. The generic `runExperiment` evaluator interface is unchanged.

package/EVALUATIONS.md

@@ -9,6 +9,8 @@ npm install @hue-run/sdk zod
 
 The SDK executes targets and scorers on your machine. Hue stores pinned definitions, experiment progress and results. It does not execute uploaded source code. Follow the [installation guide](https://docs.hue.run/installation) to add `@hue-run/sdk` to your application.
 
+Create a **Tracing and evaluations** project service key under **Settings → Integrations & API keys** and expose it to this server-side process as `HUE_API_KEY`. A **Tracing only** key cannot author datasets or evaluation runs.
+
 ```ts
 import { randomUUID } from "node:crypto";
 import { createHue } from "@hue-run/sdk";
@@ -150,4 +152,66 @@ The runner stops scheduling more cases after an operational failure and waits fo
 
 ## Verification boundaries
 
-`scripts/verify-package.mjs` installs a real packed tarball outside the monorepo and runs HTTP contract tests against a synthetic service plus actual OpenTelemetry exporters. It checks two configurations, rescoring without target invocation, absent/null output, upload resume, uncertain execution, exclusive checkpoints, source/metric contracts, content policy and terminating schema workers. `scripts/verify-evaluation-api.mjs` is a separate opt-in acceptance against a real Hue receiver/API; it creates synthetic datasets/scorers/experiments in the project associated with the supplied development key.
+`scripts/verify-package.mjs` installs a real packed tarball outside the monorepo and runs HTTP contract tests against a synthetic service plus actual OpenTelemetry exporters. It checks two configurations, rescoring without target invocation, absent/null output, upload resume, uncertain execution, exclusive checkpoints, source/metric contracts, content policy and terminating schema workers. It also exercises the local worker's ready, incomplete and uncertain provider-attempt control-plane paths, but does not call an issued provider facade. `scripts/verify-evaluation-api.mjs` is a separate opt-in acceptance against a real Hue receiver/API; it creates synthetic datasets/scorers/experiments in the project associated with the supplied development key.
+
+## Outbound local agent worker
+
+`runLocalAgent` is included in the `@hue-run/sdk@0.3.0` release candidate. Queue registration,
+claims, scoped MCP capabilities and sealed evidence require a supporting Hue server and project
+access; the package version alone does not establish hosted availability. Until registry
+acceptance, install the exact reviewed `hue-run-sdk-0.3.0.tgz` archive with the optional `zod`
+peer. `node packages/sdk-typescript/scripts/verify-package.mjs` creates and verifies that archive;
+do not request `0.3.0` from npm yet.
+
+`runLocalAgent` registers one fixed application callback and polls for queued runs. Hue selects
+the registered key/revision; it does not send executable code or shell commands. Keep the
+checkpoint directory private and durable. The worker persists result content and requires
+acknowledged trace and sealed environment evidence.
+
+```ts
+import { createHue } from "@hue-run/sdk";
+import { createEnvironmentClient } from "@hue-run/sdk/environment";
+import { createEvaluationClient, runLocalAgent } from "@hue-run/sdk/evals";
+import { runMyAgent } from "./agent.js"; // Your existing application entry point.
+
+const connection = { apiKey: process.env.HUE_API_KEY! };
+const hue = createHue({ ...connection, serviceName: "local-worker", captureContent: false });
+try {
+  await runLocalAgent({
+    client: createEvaluationClient(connection),
+    environmentClient: createEnvironmentClient(connection),
+    hue,
+    agent: { key: "support-agent", name: "Support agent", revision: "1" },
+    checkpointDirectory: ".hue-checkpoints/support-agent",
+    target: (inputs, tools, context) => runMyAgent({ inputs, tools, config: context.config }),
+  });
+} finally {
+  await hue.shutdownSafe();
+}
+```
+
+The callback receives cloned inputs, local tools, and an allowlisted context containing
+`config`, `item: {id, externalKey}`, `executionId`, `environmentRunId`,
+`trace: {traceId,spanId}` and a short-lived `mcp` capability. Expected outcomes, case metadata
+and original source pins remain private to grading. Pass the tools or scoped MCP capability into
+the agent's actual tool boundary; their presence does not redirect provider calls. Capabilities
+are not written to checkpoints. `maxRuns` limits completed runs for one-shot workers, while
+`signal` stops polling. A stop signal does not forcibly cancel an already executing callback.
+
+For an experiment with an immutable V2 attempt baseline, also supply `actualAgentManifest`, the
+exact ordered `requestedProviders`, and an `mcpSurface` selected from that request. The worker
+creates the world and prepares once before target code. A ready response exposes the memory-only
+`connectionBundle` and keeps `context.mcp` as its selected MCP projection; it never mints the
+legacy generic capability for that attempt. An incomplete response seals the world as completed
+without invoking the target or scorers. A lost preparation acknowledgement remains uncertain
+and is never recovered through binding reads, credential refresh or target replay. Synthetic
+acceptance does not contact official Gmail or claim universal provider parity.
+
+Completion or result-upload failures keep the run claimed by the durable worker identity.
+Restart with the same checkpoint directory to resume saved uploads without invoking the
+candidate again. A lost world-seal acknowledgement is recovered by reading authoritative world
+state. If the seal or candidate outcome cannot be confirmed, or an outcome cannot be serialized,
+the worker reports `attention` and stops; operator investigation is required. Such runs are not
+automatically reclaimed, and presenting the same uncertain checkpoint again cannot replay the
+candidate. Public package acceptance proves this lifecycle against local fixtures; exact
+installed-registry-package to hosted-facade acceptance remains a post-publication Fern gate.

package/README.md

@@ -395,6 +395,20 @@ published. The chatbot README describes running that external installation.
 
 The optional `@hue-run/sdk/evals` entry point supports dataset/scorer registration, frozen-version experiments, local built-in/custom scoring, upload resume, and historical rescoring. See the [evaluation guide](https://docs.hue.run/evaluations/first-evaluation) for the complete journey, content policy and checkpoint recovery contract.
 
+### App-launched local workers
+
+The TypeScript `0.3.0` release candidate adds `runLocalAgent()` for a fixed local callback that
+claims app-launched simulation work while keeping the agent, provider orchestration and debugger
+in the developer's process. Until registry acceptance, test it only from the exact reviewed
+`hue-run-sdk-0.3.0.tgz` archive rather than requesting `0.3.0` from npm. It shares
+`runSimulation()`'s provider-aware world lifecycle, keeps scoped credentials in callback memory,
+skips target/scorer execution for incomplete environments, and never reacquires or replays after
+an uncertain preparation. See the
+[outbound worker contract](EVALUATIONS.md#outbound-local-agent-worker) and
+[simulated environment guide](ENVIRONMENTS.md). Tests exercise local control-plane fixtures, not
+an issued facade endpoint or the official Gmail service, and do not claim universal provider
+parity.
+
 ## Managed targets
 
 Start a frozen dataset run in Hue while your agent stays in your application. Expose a

package/dist/environment/client.d.ts

@@ -1,4 +1,4 @@
-import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, EnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions } from "./types.js";
+import type { ActionInput, ActionResult, CoverageGapInput, CoverageGapResult, CreateRunInput, Environment, PublishableEnvironmentDefinition, EnvironmentIdentity, EnvironmentPage, EnvironmentPageOptions, EnvironmentRun, EnvironmentSummary, EnvironmentVersion, EnvironmentVersionSummary, FinishRunInput, SealedRun, StepPage, StepPageOptions } from "./types.js";
 /** Connection and retry options for {@link createEnvironmentClient}. */
 export interface EnvironmentClientOptions {
     /** Project service key sent as a bearer token; server-side only. */
@@ -37,7 +37,7 @@ export declare class EnvironmentClient {
     /** Reads one environment and its immutable version summaries. */
     getEnvironment(id: string): Promise<Environment>;
     /** Publishes an immutable definition; this non-idempotent registry write is not retried. */
-    publishVersion(environmentId: string, definition: EnvironmentDefinition): Promise<EnvironmentVersionSummary>;
+    publishVersion(environmentId: string, definition: PublishableEnvironmentDefinition): Promise<EnvironmentVersionSummary>;
     /** Reads a full immutable environment version and generated action catalog. */
     getVersion(id: string): Promise<EnvironmentVersion>;
     /** Creates or recovers one fresh isolated world using a stable idempotency key. */

package/dist/environment/types.d.ts

@@ -170,12 +170,44 @@ export interface EnvironmentDefinition {
     /** Caller-owned immutable metadata. */
     metadata?: Record<string, JsonValue>;
 }
+/** The extendable legacy name remains V1. Publication and runs select their
+ * explicit version; provider context is validated by the authoritative server. */
+export type EnvironmentDefinitionV1 = EnvironmentDefinition;
+/** One synthetic Gmail principal and its world-state collection bindings. */
+export interface GmailProviderInstance {
+    /** Stable instance key referenced by attempt provider selection. */
+    providerInstanceKey: string;
+    /** Provider discriminator for the V2 Gmail slice. */
+    providerId: "google.gmail";
+    /** Synthetic principal UUID, canonicalized to lowercase by Hue. */
+    syntheticPrincipalId: string;
+    /** Versioned mapping from Gmail concepts to authored-world collections. */
+    configuration: {
+        /** Gmail mailbox configuration discriminator. */
+        kind: "gmail_mailbox/v1";
+        /** Collection containing synthetic messages. */
+        messagesCollection: string;
+        /** Collection containing synthetic drafts. */
+        draftsCollection: string;
+        /** Synthetic mailbox address. */
+        mailboxAddress: string;
+    };
+}
+/** V2 authored world with immutable provider-instance bindings. */
+export interface EnvironmentDefinitionV2 extends Omit<EnvironmentDefinition, "schemaVersion"> {
+    /** Definition schema discriminator. */
+    schemaVersion: 2;
+    /** Provider instances available to a strict attempt profile. */
+    providerInstances: GmailProviderInstance[];
+}
+/** Definition accepted by immutable environment publication. */
+export type PublishableEnvironmentDefinition = EnvironmentDefinitionV1 | EnvironmentDefinitionV2;
 /** Full immutable environment version and its generated action catalog. */
 export interface EnvironmentVersion extends EnvironmentVersionSummary {
     /** Owning environment identity. */
     environmentId: string;
     /** Stored, defaulted authored definition. */
-    definition: EnvironmentDefinition;
+    definition: PublishableEnvironmentDefinition;
     /** Generated agent-visible actions. */
     actions: ActionDefinition[];
 }

package/dist/evals/client.d.ts

@@ -1,6 +1,6 @@
 import type { ProjectConnection } from "../types.js";
 import { type AttemptConnectionBundleV2, type PrepareAttemptRequestV2 } from "./attempt.js";
-import type { CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvaluationItem, EvaluationRun, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Identity, JsonValue, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Scorer, ScorerDefinition, ScorerVersion, SimulationMcpCapability, StartExecution, Subject, StoredResult } from "./types.js";
+import type { CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvaluationItem, EvaluationRun, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Identity, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Scorer, ScorerDefinition, ScorerVersion, SimulationMcpCapability, StartExecution, Subject, StoredResult } from "./types.js";
 /** Connection options for {@link createEvaluationClient}. */
 export interface EvaluationClientOptions {
     /** Project service key sent as a Bearer token; server side only. */
@@ -176,6 +176,35 @@ export declare class EvaluationClient {
     }>;
     /** Reads the project's hosted judge budget and admission controls. */
     getJudgeBudget(): Promise<JudgeBudget>;
+    /** Register or refresh the fixed local agent key and revision. */
+    registerLocalAgent(input: LocalAgentRegistration): Promise<RegisteredLocalAgent>;
+    /** Claim a queued run for this agent and durable worker identity. */
+    claimLocalAgentRun(input: {
+        agentId: string;
+        workerId: string;
+    }): Promise<LocalAgentClaim | null>;
+    /** Refresh the lease of a claimed local run. */
+    heartbeatLocalAgentRun(input: {
+        runId: string;
+        workerId: string;
+    }): Promise<{
+        /** Queue-run identity. */
+        runId: string;
+        /** The worker claim remains active. */
+        active: true;
+    }>;
+    /** Report acknowledged completion or an execution requiring attention. */
+    completeLocalAgentRun(input: {
+        runId: string;
+        workerId: string;
+        state: "completed" | "attention";
+        failureType?: string;
+    }): Promise<{
+        /** Queue-run identity. */
+        runId: string;
+        /** Acknowledged terminal queue state. */
+        state: "completed" | "attention";
+    }>;
     /** Creates the legacy execution-scoped generic MCP capability for one world. */
     createSimulationMcpCapability(input: {
         runId: string;

package/dist/evals/client.js

@@ -309,6 +309,22 @@ export class EvaluationClient {
     getJudgeBudget() {
         return this.request("GET", "/judge-budget");
     }
+    /** Register or refresh the fixed local agent key and revision. */
+    registerLocalAgent(input) {
+        return this.request("POST", "/local-agent-worker/register", input);
+    }
+    /** Claim a queued run for this agent and durable worker identity. */
+    claimLocalAgentRun(input) {
+        return this.request("POST", "/local-agent-worker/claim", input);
+    }
+    /** Refresh the lease of a claimed local run. */
+    heartbeatLocalAgentRun(input) {
+        return this.request("POST", "/local-agent-worker/runs/heartbeat", input);
+    }
+    /** Report acknowledged completion or an execution requiring attention. */
+    completeLocalAgentRun(input) {
+        return this.request("POST", "/local-agent-worker/runs/complete", input);
+    }
     /** Creates the legacy execution-scoped generic MCP capability for one world. */
     createSimulationMcpCapability(input) {
         return this.request("POST", "/local-agent-worker/mcp-capability", input);

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

@@ -0,0 +1,84 @@
+import type { HueClient } from "../client.js";
+import type { EnvironmentClient } from "../environment/client.js";
+import { type EnvironmentTool } from "../environment/tools.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";
+import type { ExperimentCase, JsonValue, SimulationMcpCapability } from "./types.js";
+export type McpSurfaceKeyV2 = Extract<SurfaceBindingV2["surfaceKey"], `${string}/mcp`>;
+export type ActualAgentManifestResolverV2 = ActualAgentManifestInputV2 | ((context: {
+    config: JsonValue;
+    item: ExperimentCase;
+    signal?: AbortSignal;
+}) => ActualAgentManifestInputV2 | Promise<ActualAgentManifestInputV2>);
+export interface ProviderAttemptOptionsV2 {
+    actualAgentManifest?: ActualAgentManifestResolverV2;
+    requestedProviders?: RequestedAttemptProviderV2[];
+    mcpSurface?: {
+        providerInstanceKey: string;
+        surfaceKey: McpSurfaceKeyV2;
+    };
+}
+export type RequestedAttemptV2 = {
+    actualAgentManifest: ActualAgentManifestResolverV2;
+    requestedProviders: RequestedAttemptProviderV2[];
+    mcpSurface: {
+        providerInstanceKey: string;
+        surfaceKey: McpSurfaceKeyV2;
+    };
+};
+export type PinnedAttemptV2 = RequestedAttemptV2 & {
+    expectedAgentManifestDigest: AttemptBaselineV2["expectedAgentManifestDigest"];
+};
+export declare function requestedAttemptV2(options: ProviderAttemptOptionsV2): RequestedAttemptV2 | undefined;
+export declare function pinRequestedAttemptV2(requested: RequestedAttemptV2, config: JsonValue): PinnedAttemptV2;
+export type EnvironmentTargetProgress = {
+    type: "world_created" | "target_started" | "world_sealed";
+    environmentRunId: string;
+} | {
+    type: "attempt_prepared";
+    environmentRunId: string;
+    bindingId: string;
+    status: "ready" | "environment_incomplete";
+    findingCodes: string[];
+    executionManifestDigest?: AttemptConnectionBundleV2["parity"]["executionManifestDigest"];
+};
+export interface EnvironmentTargetContext {
+    config: JsonValue;
+    item: ExperimentCase;
+    executionId: string;
+    environmentRunId: string;
+    trace: {
+        traceId: string;
+        spanId: string;
+    };
+    tools: Record<string, EnvironmentTool>;
+    mcp: SimulationMcpCapability;
+    connectionBundle?: AttemptConnectionBundleV2;
+    signal?: AbortSignal;
+}
+interface RunnerTargetContext {
+    config: JsonValue;
+    item: ExperimentCase;
+    executionId: string;
+    span: HueSpan;
+}
+export interface RunEnvironmentTargetOptions {
+    client: EvaluationClient;
+    environmentClient: EnvironmentClient;
+    hue: HueClient;
+    inputs: JsonValue;
+    context: RunnerTargetContext;
+    requested?: PinnedAttemptV2;
+    maxSteps?: number;
+    ttlSeconds?: number;
+    signal?: AbortSignal;
+    onProgress?(event: EnvironmentTargetProgress): void | Promise<void>;
+    target(inputs: JsonValue, context: EnvironmentTargetContext): JsonValue | undefined | Promise<JsonValue | undefined>;
+}
+/** 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.
+ */
+export declare function runEnvironmentTarget(options: RunEnvironmentTargetOptions): Promise<JsonValue | undefined>;
+export {};

package/dist/evals/environment-target.js

@@ -0,0 +1,201 @@
+import { randomUUID } from "node:crypto";
+import { bindEnvironmentTools } from "../environment/tools.js";
+import { actualAgentManifestV2, attemptBaselineV2, projectMcpConnectionV2, requestedAttemptProvidersV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
+import { TargetCancelledError, TargetOutcomeUncertainError } from "./runner.js";
+export function requestedAttemptV2(options) {
+    const requested = options.requestedProviders !== undefined;
+    const selected = options.mcpSurface !== undefined;
+    if (!requested && !selected) {
+        if (options.actualAgentManifest !== undefined)
+            throw new TypeError("actualAgentManifest requires requestedProviders and mcpSurface");
+        return undefined;
+    }
+    if (!requested || !selected)
+        throw new TypeError("requestedProviders and mcpSurface must be supplied together");
+    const requestedProviders = requestedAttemptProvidersV2.parse(options.requestedProviders);
+    const mcpSurface = options.mcpSurface;
+    const provider = requestedProviders.find((candidate) => candidate.providerInstanceKey === mcpSurface.providerInstanceKey);
+    if (!provider?.surfaceKeys.includes(mcpSurface.surfaceKey))
+        throw new TypeError("mcpSurface must identify an exactly requested MCP surface");
+    const actualAgentManifest = typeof options.actualAgentManifest === "function"
+        ? options.actualAgentManifest
+        : actualAgentManifestV2.parse(options.actualAgentManifest);
+    return {
+        actualAgentManifest,
+        requestedProviders,
+        mcpSurface: { ...mcpSurface },
+    };
+}
+export function pinRequestedAttemptV2(requested, config) {
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        throw new TypeError("Provider-profile simulations require an immutable V2 attempt baseline");
+    const source = config;
+    const baseline = attemptBaselineV2.safeParse(source.attemptBaselineV2);
+    if (!baseline.success) {
+        if (source.attemptBaselineV2 === undefined && source.attemptBaselineV1 !== undefined)
+            throw new TypeError("Legacy V1 attempts require a fresh experiment with a V2 baseline");
+        if (source.attemptBaselineV2 !== undefined)
+            throw new TypeError("The immutable V2 attempt baseline is invalid");
+        throw new TypeError("Provider-profile simulations require an immutable V2 attempt baseline");
+    }
+    return { ...requested, expectedAgentManifestDigest: baseline.data.expectedAgentManifestDigest };
+}
+/** Confirm a seal from the authoritative run after a lost acknowledgement. */
+async function seal(client, runId, executionId, status) {
+    try {
+        await client.finishRun(runId, {
+            idempotencyKey: `execution:${executionId}:${status}`,
+            status,
+        });
+    }
+    catch (error) {
+        const recovered = await client.getRun(runId).catch(() => undefined);
+        if (recovered?.status !== status)
+            throw new TargetOutcomeUncertainError(executionId, { cause: error });
+    }
+}
+/** 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.
+ */
+export async function runEnvironmentTarget(options) {
+    const { context } = 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({
+        idempotencyKey: `execution:${context.executionId}`,
+        environmentVersionId,
+        executionId: context.executionId,
+        maxSteps: options.maxSteps,
+        ttlSeconds: options.ttlSeconds,
+    });
+    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,
+        });
+        let connectionBundle;
+        let mcp;
+        if (options.requested) {
+            const actualManifest = actualAgentManifestV2.parse(typeof options.requested.actualAgentManifest === "function"
+                ? await options.requested.actualAgentManifest({
+                    config: structuredClone(context.config),
+                    item: structuredClone(context.item),
+                    signal: options.signal,
+                })
+                : options.requested.actualAgentManifest);
+            let prepared;
+            try {
+                prepared = await options.client.prepareAttempt({
+                    schemaVersion: 2,
+                    idempotencyKey: randomUUID(),
+                    executionId: context.executionId,
+                    environmentRunId: run.id,
+                    expectedAgentManifestDigest: options.requested.expectedAgentManifestDigest,
+                    actualManifest,
+                    requestedProviders: options.requested.requestedProviders,
+                });
+            }
+            catch (error) {
+                // A transport failure or malformed credential-bearing response may follow a
+                // committed decision. The runner's running checkpoint prevents reacquisition
+                // and target replay on resume.
+                throw new TargetOutcomeUncertainError(context.executionId, { cause: error });
+            }
+            await progress({
+                type: "attempt_prepared",
+                environmentRunId: run.id,
+                bindingId: prepared.status === "ready" ? prepared.bundle.bindingId : prepared.bindingId,
+                status: prepared.status,
+                findingCodes: prepared.preflightReport.findings.map((finding) => finding.code),
+                ...(prepared.status === "ready"
+                    ? { executionManifestDigest: prepared.bundle.parity.executionManifestDigest }
+                    : {}),
+            });
+            if (prepared.status === "environment_incomplete") {
+                await seal(options.environmentClient, run.id, context.executionId, "completed");
+                finalized = true;
+                await Promise.resolve(progress({ type: "world_sealed", environmentRunId: run.id })).catch(() => undefined);
+                return undefined;
+            }
+            connectionBundle = validateAttemptConnectionBundleV2(prepared.bundle, {
+                requireFresh: true,
+            });
+            const projected = projectMcpConnectionV2(connectionBundle, options.requested.mcpSurface.providerInstanceKey);
+            if (!projected)
+                throw new TypeError("The prepared attempt has no selected MCP surface");
+            mcp = projected;
+        }
+        else {
+            mcp = await options.client.createSimulationMcpCapability({
+                runId: run.id,
+                executionId: context.executionId,
+            });
+        }
+        if (options.signal?.aborted)
+            throw new TargetCancelledError();
+        await progress({ type: "target_started", environmentRunId: run.id });
+        const output = await options.target(options.inputs, {
+            config: context.config,
+            item: context.item,
+            executionId: context.executionId,
+            environmentRunId: run.id,
+            trace: { traceId: context.span.traceId, spanId: context.span.spanId },
+            tools,
+            mcp,
+            ...(connectionBundle ? { connectionBundle } : {}),
+            signal: options.signal,
+        });
+        await seal(options.environmentClient, run.id, context.executionId, "completed");
+        finalized = true;
+        await Promise.resolve(progress({ type: "world_sealed", environmentRunId: run.id })).catch(() => undefined);
+        return output;
+    }
+    catch (error) {
+        if (error instanceof TargetOutcomeUncertainError || finalized)
+            throw error;
+        let environmentIncomplete;
+        try {
+            environmentIncomplete =
+                (await options.environmentClient.getRun(run.id)).validity === "environment_incomplete";
+        }
+        catch (inspectionError) {
+            throw new TargetOutcomeUncertainError(context.executionId, {
+                cause: new AggregateError([error, inspectionError]),
+            });
+        }
+        if (environmentIncomplete) {
+            try {
+                await seal(options.environmentClient, run.id, context.executionId, "completed");
+            }
+            catch (finalizationError) {
+                throw new TargetOutcomeUncertainError(context.executionId, {
+                    cause: new AggregateError([error, finalizationError]),
+                });
+            }
+            finalized = true;
+            await Promise.resolve(progress({ type: "world_sealed", environmentRunId: run.id })).catch(() => undefined);
+            return undefined;
+        }
+        try {
+            await seal(options.environmentClient, run.id, context.executionId, "abandoned");
+        }
+        catch (finalizationError) {
+            throw new TargetOutcomeUncertainError(context.executionId, {
+                cause: new AggregateError([error, finalizationError]),
+            });
+        }
+        await Promise.resolve(progress({ type: "world_sealed", environmentRunId: run.id })).catch(() => undefined);
+        if (options.signal?.aborted && !(error instanceof TargetCancelledError))
+            throw new TargetCancelledError();
+        throw error;
+    }
+}

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

@@ -0,0 +1,88 @@
+import type { HueClient } from "../client.js";
+import type { EnvironmentClient } from "../environment/client.js";
+import type { EnvironmentTool } from "../environment/tools.js";
+import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
+import type { EvaluationClient } from "./client.js";
+import { type RunnerReport } from "./runner.js";
+import type { ExperimentCase, JsonValue, LocalAgentRegistration, LocalScorer } from "./types.js";
+/** Candidate-visible context for one queued local agent execution. */
+export interface LocalAgentTargetContext {
+    /** Frozen candidate configuration, cloned before invocation. */
+    config: JsonValue;
+    /** Identity only. Expected outcomes, metadata and world definitions are evaluator-private. */
+    item: Pick<ExperimentCase, "id" | "externalKey">;
+    /** Identity of this target execution. */
+    executionId: string;
+    /** Stable world identity for adapter control operations such as coverage reporting. */
+    environmentRunId: string;
+    /** Trace identities without mutable span or grading data. */
+    trace: {
+        /** OpenTelemetry trace identifier. */
+        traceId: string;
+        /** Root execution span identifier. */
+        spanId: string;
+    };
+    /** Short-lived, execution-scoped hosted tools for model providers that execute MCP remotely. */
+    mcp: {
+        /** Execution-scoped MCP endpoint. */
+        url: string;
+        /** Short-lived bearer, never the project service key. */
+        token: string;
+        /** Capability expiry as an ISO timestamp. */
+        expiresAt: string;
+    };
+    /** Credential-bearing provider connections for this callback only. Hue never
+     * checkpoints, logs or adds this response to parity digests. */
+    connectionBundle?: AttemptConnectionBundleV2;
+}
+/** Fixed local callback, clients and durable queue-worker settings. */
+export interface RunLocalAgentOptions {
+    /** Evaluation client for the worker project. */
+    client: EvaluationClient;
+    /** Environment client for the same origin and project. */
+    environmentClient: EnvironmentClient;
+    /** Application telemetry client; required trace exports are acknowledged. */
+    hue: HueClient;
+    /** Private durable directory for worker identity and execution checkpoints. */
+    checkpointDirectory: string;
+    /** Fixed agent key and revision registered for queued runs. */
+    agent: LocalAgentRegistration;
+    /** Local scorer bindings matching the published source digests. */
+    scorers?: LocalScorer[];
+    /** Cases in flight, between 1 and 16; defaults to 1. */
+    concurrency?: number;
+    /** Polling interval in milliseconds, 250–60000; defaults to 2000. */
+    pollIntervalMillis?: number;
+    /** Stops polling cooperatively; does not cancel an active callback. */
+    signal?: AbortSignal;
+    /** Useful for one-shot jobs and deterministic acceptance. Omit to keep polling. */
+    maxRuns?: number;
+    /** 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: {
+        /** Frozen experiment configuration. */
+        config: JsonValue;
+        /** Full frozen case for resolving actual nonsecret evidence before candidate projection. */
+        item: ExperimentCase;
+        /** Cooperative worker stop signal. */
+        signal?: AbortSignal;
+    }) => ActualAgentManifestInputV2 | Promise<ActualAgentManifestInputV2>);
+    /** Exact provider instances and ordered surfaces asserted for strict preflight. */
+    requestedProviders?: RequestedAttemptProviderV2[];
+    /** Requested MCP surface projected to the backwards-compatible `context.mcp`. */
+    mcpSurface?: {
+        /** Provider instance selected from `requestedProviders`. */
+        providerInstanceKey: string;
+        /** Selected MCP surface. */
+        surfaceKey: "google.gmail/mcp" | "slack/mcp";
+    };
+    /** Invokes the existing agent against isolated tools and candidate-safe context. */
+    target(inputs: JsonValue, tools: Record<string, EnvironmentTool>, context: LocalAgentTargetContext): JsonValue | undefined | Promise<JsonValue | undefined>;
+    /** Called after the experiment and queue completion are acknowledged. */
+    onCompleted?(report: RunnerReport): void | Promise<void>;
+}
+/**
+ * Starts an outbound-only worker for one fixed local agent entry point. Hue chooses
+ * only the registered key/revision; no command or source is received from the cloud.
+ */
+export declare function runLocalAgent(options: RunLocalAgentOptions): Promise<void>;

package/dist/evals/local-worker.js

@@ -0,0 +1,171 @@
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { CheckpointStore } from "./checkpoint.js";
+import { pinRequestedAttemptV2, requestedAttemptV2, runEnvironmentTarget, } from "./environment-target.js";
+import { runExperiment, OutcomeSerializationError, TargetOutcomeUncertainError, UncertainExecutionError, } from "./runner.js";
+/** Allowlist the candidate surface instead of forwarding the generic evaluation context. */
+function localAgentTargetContext(context) {
+    return {
+        config: structuredClone(context.config),
+        item: { id: context.item.id, externalKey: context.item.externalKey },
+        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.connectionBundle
+            ? { connectionBundle: structuredClone(context.connectionBundle) }
+            : {}),
+    };
+}
+function validInterval(value) {
+    const interval = value ?? 2_000;
+    if (!Number.isInteger(interval) || interval < 250 || interval > 60_000)
+        throw new RangeError("pollIntervalMillis must be 250–60000");
+    return interval;
+}
+function stopReason(signal) {
+    return signal?.reason instanceof Error
+        ? signal.reason
+        : new Error("Local worker stopped", { cause: signal?.reason });
+}
+function wait(milliseconds, signal) {
+    if (signal?.aborted)
+        return Promise.reject(stopReason(signal));
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(done, milliseconds);
+        const aborted = () => {
+            clearTimeout(timeout);
+            reject(stopReason(signal));
+        };
+        function done() {
+            signal?.removeEventListener("abort", aborted);
+            resolve();
+        }
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+}
+function needsAttention(error, seen = new Set()) {
+    if (error instanceof TargetOutcomeUncertainError ||
+        error instanceof UncertainExecutionError ||
+        error instanceof OutcomeSerializationError)
+        return true;
+    if (!(error instanceof AggregateError) || seen.has(error))
+        return false;
+    seen.add(error);
+    return error.errors.some((nested) => needsAttention(nested, seen));
+}
+/**
+ * Starts an outbound-only worker for one fixed local agent entry point. Hue chooses
+ * only the registered key/revision; no command or source is received from the cloud.
+ */
+export async function runLocalAgent(options) {
+    const requestedConfiguration = requestedAttemptV2(options);
+    const interval = validInterval(options.pollIntervalMillis);
+    const maxRuns = options.maxRuns ?? Number.POSITIVE_INFINITY;
+    if (!(maxRuns === Number.POSITIVE_INFINITY || (Number.isInteger(maxRuns) && maxRuns > 0)))
+        throw new RangeError("maxRuns must be a positive integer");
+    if (options.environmentClient.baseUrl !== options.client.baseUrl)
+        throw new Error("Environments and evaluations must use the same Hue origin");
+    const directory = resolve(options.checkpointDirectory);
+    const project = await options.client.checkConnection();
+    const store = await CheckpointStore.acquire(directory, {
+        kind: "local-agent-worker",
+        projectId: project.id,
+        baseUrl: options.client.baseUrl,
+        agent: { key: options.agent.key, revision: options.agent.revision },
+    });
+    try {
+        let workerId = await store.read("worker-id");
+        if (workerId !== undefined &&
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(workerId))
+            throw new Error("Invalid local worker identity");
+        if (workerId === undefined) {
+            workerId = randomUUID();
+            await store.write("worker-id", workerId);
+        }
+        let completed = 0;
+        while (completed < maxRuns && !options.signal?.aborted) {
+            const agent = await options.client.registerLocalAgent({
+                ...options.agent,
+                capabilities: options.agent.capabilities ?? ["environment:v1"],
+                scorerDigests: options.agent.scorerDigests ??
+                    options.scorers?.map((item) => item.definition.sourceDigest) ??
+                    [],
+            });
+            const claim = await options.client.claimLocalAgentRun({ agentId: agent.id, workerId });
+            if (!claim) {
+                await wait(interval, options.signal);
+                continue;
+            }
+            const heartbeat = setInterval(() => {
+                void options.client
+                    .heartbeatLocalAgentRun({ runId: claim.runId, workerId })
+                    .catch(() => undefined);
+            }, Math.min(15_000, Math.max(1_000, interval)));
+            let experimentFinished = false;
+            try {
+                const requested = requestedConfiguration
+                    ? pinRequestedAttemptV2(requestedConfiguration, (await options.client.getExperiment(claim.experimentId)).config)
+                    : undefined;
+                const report = await runExperiment({
+                    client: options.client,
+                    hue: options.hue,
+                    experimentId: claim.experimentId,
+                    checkpointDirectory: join(directory, `experiment-${claim.experimentId}`),
+                    persistResultContent: true,
+                    environmentEvidence: "required",
+                    traceEvidence: { mode: "required" },
+                    scorers: options.scorers,
+                    concurrency: options.concurrency,
+                    target: (inputs, context) => runEnvironmentTarget({
+                        client: options.client,
+                        environmentClient: options.environmentClient,
+                        hue: options.hue,
+                        inputs,
+                        context,
+                        requested,
+                        signal: options.signal,
+                        target: (targetInputs, targetContext) => options.target(structuredClone(targetInputs), targetContext.tools, localAgentTargetContext(targetContext)),
+                    }),
+                });
+                // From this point onward the experiment outcome is authoritative. If reporting the
+                // queue completion fails, leave the claim intact for checkpointed recovery instead of
+                // rewriting a successful experiment as an agent failure.
+                experimentFinished = true;
+                await options.client.completeLocalAgentRun({
+                    runId: claim.runId,
+                    workerId,
+                    state: "completed",
+                });
+                await options.onCompleted?.(report);
+                completed++;
+            }
+            catch (error) {
+                // A durable outcome can still need completion/result uploads. Leave operational
+                // failures claimed so the same worker can resume them through its checkpoints.
+                // Attention is terminal in the queue and is reserved for explicit unsafe-to-resume
+                // outcomes that require operator intervention.
+                if (!experimentFinished && needsAttention(error))
+                    await options.client
+                        .completeLocalAgentRun({
+                        runId: claim.runId,
+                        workerId,
+                        state: "attention",
+                        failureType: error instanceof Error ? error.name.slice(0, 200) : "WorkerError",
+                    })
+                        .catch(() => undefined);
+                throw error;
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+        }
+    }
+    finally {
+        await store.release();
+    }
+}

package/dist/evals/simulation.d.ts

@@ -1,9 +1,9 @@
 import type { HueClient } from "../client.js";
 import { type EnvironmentClient } from "../environment/client.js";
-import { type EnvironmentTool } from "../environment/tools.js";
-import type { EnvironmentDefinition, EnvironmentIdentity } from "../environment/types.js";
+import type { EnvironmentTool } from "../environment/tools.js";
+import type { EnvironmentIdentity, PublishableEnvironmentDefinition } from "../environment/types.js";
 import { type EvaluationClient } from "./client.js";
-import { type ActualAgentManifestInputV2, type AttemptConnectionBundleV2, type RequestedAttemptProviderV2 } from "./attempt.js";
+import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
 import { type RunnerReport } from "./runner.js";
 import type { ExperimentCase, Identity, JsonValue, LocalScorer, ScorerDefinition, SimulationMcpCapability } from "./types.js";
 /** Repository-authored scorer identity and its public definition or local binding. */
@@ -40,7 +40,7 @@ export type SimulationScenario = {
     /** Environment identity and authored world definition. */
     environment: EnvironmentIdentity & {
         /** Definition normalized and published as an immutable version. */
-        definition: EnvironmentDefinition;
+        definition: PublishableEnvironmentDefinition;
     };
     /** Cases published into one frozen dataset version. */
     cases: RepositorySimulationCase[];
@@ -92,8 +92,8 @@ export type SimulationProgress = {
 export interface SimulationTargetContext {
     /** Frozen experiment configuration. */
     config: JsonValue;
-    /** Frozen case including its immutable environment-version pin. */
-    item: ExperimentCase;
+    /** Candidate-visible identity. References, metadata and source pins stay with grading. */
+    item: Pick<ExperimentCase, "id" | "externalKey">;
     /** Target execution identity. */
     executionId: string;
     /** Stable world identity for adapter control operations such as coverage reporting. */

package/dist/evals/simulation.js

@@ -1,56 +1,25 @@
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { HueEnvironmentError } from "../environment/client.js";
-import { bindEnvironmentTools } from "../environment/tools.js";
 import { HueApiError } from "./client.js";
 import { CheckpointStore } from "./checkpoint.js";
 import { MAX_ENVIRONMENT_STEPS } from "./environment-evidence.js";
 import { aggregateBounds, digest, json } from "./json.js";
 import { normalizeScorerDefinitionForPublication } from "./scorer-publication.js";
-import { actualAgentManifestV2, attemptBaselineV2, projectMcpConnectionV2, requestedAttemptProvidersV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
-import { runExperiment, TargetCancelledError, TargetOutcomeUncertainError, } from "./runner.js";
+import { pinRequestedAttemptV2, requestedAttemptV2, runEnvironmentTarget, } from "./environment-target.js";
+import { runExperiment } from "./runner.js";
 const scorerDefinition = (entry) => "definition" in entry.scorer ? entry.scorer.definition : entry.scorer;
-function requestedAttempt(options) {
-    const requested = options.requestedProviders !== undefined;
-    const selected = options.mcpSurface !== undefined;
-    if (!requested && !selected) {
-        if (options.actualAgentManifest !== undefined)
-            throw new TypeError("actualAgentManifest requires requestedProviders and mcpSurface");
-        return undefined;
-    }
-    if (!requested || !selected)
-        throw new TypeError("requestedProviders and mcpSurface must be supplied together");
-    const requestedProviders = requestedAttemptProvidersV2.parse(options.requestedProviders);
-    const mcpSurface = options.mcpSurface;
-    const provider = requestedProviders.find((candidate) => candidate.providerInstanceKey === mcpSurface.providerInstanceKey);
-    if (!provider?.surfaceKeys.includes(mcpSurface.surfaceKey))
-        throw new TypeError("mcpSurface must identify an exactly requested MCP surface");
-    const actualAgentManifest = typeof options.actualAgentManifest === "function"
-        ? options.actualAgentManifest
-        : actualAgentManifestV2.parse(options.actualAgentManifest);
-    return {
-        actualAgentManifest,
-        requestedProviders,
-        mcpSurface: { ...mcpSurface },
-    };
-}
-function expectedManifestDigest(config) {
-    if (!config || typeof config !== "object" || Array.isArray(config))
-        throw new TypeError("Provider-profile simulations require an immutable V2 attempt baseline");
-    const source = config;
-    const baseline = attemptBaselineV2.safeParse(source.attemptBaselineV2);
-    if (!baseline.success) {
-        if (source.attemptBaselineV2 === undefined && source.attemptBaselineV1 !== undefined)
-            throw new TypeError("Legacy V1 attempts require a fresh experiment with a V2 baseline");
-        if (source.attemptBaselineV2 !== undefined)
-            throw new TypeError("The immutable V2 attempt baseline is invalid");
-        throw new TypeError("Provider-profile simulations require an immutable V2 attempt baseline");
-    }
-    return baseline.data.expectedAgentManifestDigest;
-}
 function normalizedEnvironmentDefinition(definition) {
     return json({
         ...definition,
+        ...(definition.schemaVersion === 2
+            ? {
+                providerInstances: definition.providerInstances.map((instance) => ({
+                    ...instance,
+                    syntheticPrincipalId: instance.syntheticPrincipalId.toLowerCase(),
+                })),
+            }
+            : {}),
         determinism: {
             clock: {
                 startNs: definition.determinism?.clock?.startNs ?? "0",
@@ -341,24 +310,11 @@ async function resolveExperiment(options, idempotencyKey) {
         bindings: [...scorers.bindings, ...(options.localScorers ?? [])],
     };
 }
-async function seal(client, runId, executionId, status) {
-    try {
-        await client.finishRun(runId, {
-            idempotencyKey: `execution:${executionId}:${status}`,
-            status,
-        });
-    }
-    catch (error) {
-        const recovered = await client.getRun(runId).catch(() => undefined);
-        if (recovered?.status !== status)
-            throw error;
-    }
-}
 /** 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 requestedConfiguration = requestedAttempt(options);
+    const requestedConfiguration = requestedAttemptV2(options);
     if (options.maxSteps !== undefined &&
         (!Number.isInteger(options.maxSteps) ||
             options.maxSteps < 1 ||
@@ -408,10 +364,7 @@ export async function runSimulation(options) {
         const runUrl = new URL(`/experiments/${experimentId}`, options.client.baseUrl).toString();
         await options.onProgress?.({ type: "run_created", experimentId, runUrl });
         const requested = requestedConfiguration
-            ? {
-                ...requestedConfiguration,
-                expectedAgentManifestDigest: expectedManifestDigest((await options.client.getExperiment(experimentId)).config),
-            }
+            ? pinRequestedAttemptV2(requestedConfiguration, (await options.client.getExperiment(experimentId)).config)
             : undefined;
         const report = await runExperiment({
             client: options.client,
@@ -424,172 +377,42 @@ export async function runSimulation(options) {
             scorers: bindings,
             concurrency: options.concurrency,
             schemaTimeoutMillis: options.schemaTimeoutMillis,
-            target: async (inputs, context) => {
-                const environmentVersionId = context.item.environmentVersionId;
-                if (!environmentVersionId)
-                    throw new Error("The simulation case has no pinned environment version");
-                const run = await options.environmentClient.createRun({
-                    idempotencyKey: `execution:${context.executionId}`,
-                    environmentVersionId,
-                    executionId: context.executionId,
-                    maxSteps: options.maxSteps,
-                    ttlSeconds: options.ttlSeconds,
-                });
-                const progress = (type) => options.onProgress?.({
-                    type,
+            target: (inputs, context) => runEnvironmentTarget({
+                client: options.client,
+                environmentClient: options.environmentClient,
+                hue: options.hue,
+                inputs,
+                context,
+                requested,
+                maxSteps: options.maxSteps,
+                ttlSeconds: options.ttlSeconds,
+                signal: options.signal,
+                onProgress: (event) => options.onProgress?.({
+                    ...event,
                     experimentId,
                     executionId: context.executionId,
                     caseId: context.item.id,
-                    environmentRunId: run.id,
-                });
-                let finalized = false;
-                try {
-                    await progress("world_created");
-                    if (options.signal?.aborted)
-                        throw new TargetCancelledError();
-                    const tools = bindEnvironmentTools({
-                        hue: options.hue,
-                        client: options.environmentClient,
-                        run,
-                        parentContext: context.span.context,
-                    });
-                    let connectionBundle;
-                    let mcp;
-                    if (requested) {
-                        const actualManifest = actualAgentManifestV2.parse(typeof requested.actualAgentManifest === "function"
-                            ? await requested.actualAgentManifest({
-                                config: context.config,
-                                item: structuredClone(context.item),
-                                signal: options.signal,
-                            })
-                            : requested.actualAgentManifest);
-                        let prepared;
-                        try {
-                            prepared = await options.client.prepareAttempt({
-                                schemaVersion: 2,
-                                idempotencyKey: randomUUID(),
-                                executionId: context.executionId,
-                                environmentRunId: run.id,
-                                expectedAgentManifestDigest: requested.expectedAgentManifestDigest,
-                                actualManifest,
-                                requestedProviders: requested.requestedProviders,
-                            });
-                        }
-                        catch (error) {
-                            // A transport failure or malformed credential-bearing response may
-                            // follow a committed decision. Preserve the running checkpoint and
-                            // never reacquire credentials or replay the target on resume.
-                            throw new TargetOutcomeUncertainError(context.executionId, { cause: error });
-                        }
-                        await options.onProgress?.({
-                            type: "attempt_prepared",
-                            experimentId,
-                            executionId: context.executionId,
-                            caseId: context.item.id,
-                            environmentRunId: run.id,
-                            bindingId: prepared.status === "ready" ? prepared.bundle.bindingId : prepared.bindingId,
-                            status: prepared.status,
-                            findingCodes: prepared.preflightReport.findings.map((finding) => finding.code),
-                            ...(prepared.status === "ready"
-                                ? {
-                                    executionManifestDigest: prepared.bundle.parity.executionManifestDigest,
-                                }
-                                : {}),
-                        });
-                        if (prepared.status === "environment_incomplete") {
-                            try {
-                                await seal(options.environmentClient, run.id, context.executionId, "completed");
-                            }
-                            catch (error) {
-                                throw new TargetOutcomeUncertainError(context.executionId, { cause: error });
-                            }
-                            finalized = true;
-                            await Promise.resolve(progress("world_sealed")).catch(() => undefined);
-                            return undefined;
-                        }
-                        connectionBundle = validateAttemptConnectionBundleV2(prepared.bundle, {
-                            requireFresh: true,
-                        });
-                        const projected = projectMcpConnectionV2(connectionBundle, requested.mcpSurface.providerInstanceKey);
-                        if (!projected)
-                            throw new TypeError("The prepared attempt has no selected MCP surface");
-                        mcp = projected;
-                    }
-                    else {
-                        mcp = await options.client.createSimulationMcpCapability({
-                            runId: run.id,
-                            executionId: context.executionId,
-                        });
-                    }
-                    if (options.signal?.aborted)
-                        throw new TargetCancelledError();
-                    await progress("target_started");
-                    const output = await options.target(inputs, {
-                        config: context.config,
-                        item: context.item,
-                        executionId: context.executionId,
-                        environmentRunId: run.id,
-                        tools,
-                        mcp,
-                        ...(connectionBundle ? { connectionBundle } : {}),
-                        signal: options.signal,
-                    });
-                    try {
-                        await seal(options.environmentClient, run.id, context.executionId, "completed");
-                    }
-                    catch (error) {
-                        throw new TargetOutcomeUncertainError(context.executionId, { cause: error });
-                    }
-                    finalized = true;
-                    await Promise.resolve(progress("world_sealed")).catch(() => undefined);
-                    return output;
-                }
-                catch (error) {
-                    if (error instanceof TargetOutcomeUncertainError || finalized)
-                        throw error;
-                    let environmentIncomplete;
-                    try {
-                        environmentIncomplete =
-                            (await options.environmentClient.getRun(run.id)).validity ===
-                                "environment_incomplete";
-                    }
-                    catch (inspectionError) {
-                        // A target error can be the adapter surfacing a coverage gap. If the
-                        // authoritative run cannot be read, do not guess that it was an agent
-                        // failure or replay the target on resume.
-                        throw new TargetOutcomeUncertainError(context.executionId, {
-                            cause: new AggregateError([error, inspectionError]),
-                        });
-                    }
-                    // A durable coverage gap invalidates parity independently of caller timing;
-                    // do not let a racing local abort hide it as an ordinary cancellation.
-                    if (environmentIncomplete) {
-                        try {
-                            await seal(options.environmentClient, run.id, context.executionId, "completed");
-                        }
-                        catch (finalizationError) {
-                            throw new TargetOutcomeUncertainError(context.executionId, {
-                                cause: new AggregateError([error, finalizationError]),
-                            });
-                        }
-                        finalized = true;
-                        await Promise.resolve(progress("world_sealed")).catch(() => undefined);
-                        return undefined;
-                    }
-                    try {
-                        await seal(options.environmentClient, run.id, context.executionId, "abandoned");
-                    }
-                    catch (finalizationError) {
-                        throw new TargetOutcomeUncertainError(context.executionId, {
-                            cause: new AggregateError([error, finalizationError]),
-                        });
-                    }
-                    await Promise.resolve(progress("world_sealed")).catch(() => undefined);
-                    if (options.signal?.aborted && !(error instanceof TargetCancelledError))
-                        throw new TargetCancelledError();
-                    throw error;
-                }
-            },
+                }),
+                target: (targetInputs, targetContext) => options.target(structuredClone(targetInputs), {
+                    config: structuredClone(targetContext.config),
+                    item: {
+                        id: targetContext.item.id,
+                        externalKey: targetContext.item.externalKey,
+                    },
+                    executionId: targetContext.executionId,
+                    environmentRunId: targetContext.environmentRunId,
+                    tools: targetContext.tools,
+                    mcp: {
+                        url: targetContext.mcp.url,
+                        token: targetContext.mcp.token,
+                        expiresAt: targetContext.mcp.expiresAt,
+                    },
+                    ...(targetContext.connectionBundle
+                        ? { connectionBundle: structuredClone(targetContext.connectionBundle) }
+                        : {}),
+                    signal: targetContext.signal,
+                }),
+            }),
         });
         const complete = { ...report, experimentId, runUrl };
         attempt.stage = "completed";

package/dist/evals/types.d.ts

@@ -603,3 +603,34 @@ export interface SimulationMcpCapability {
     /** Credential expiry timestamp. */
     expiresAt: string;
 }
+/** Identity and capabilities of one fixed local agent entry point. */
+export interface LocalAgentRegistration {
+    /** Stable application-selected agent key. */
+    key: string;
+    /** Display name. */
+    name: string;
+    /** Application-selected revision of the agent configuration. */
+    revision: string;
+    /** Supported execution contracts; defaults to environment:v1 in the worker. */
+    capabilities?: string[];
+    /** Local scorer source digests available in this process. */
+    scorerDigests?: string[];
+}
+/** Server registration and heartbeat timestamps for a local agent. */
+export interface RegisteredLocalAgent extends Required<LocalAgentRegistration> {
+    /** Registered agent identity. */
+    id: string;
+    /** Whether Hue permits this registration to receive runs. */
+    enabled: boolean;
+    /** Latest registration heartbeat, as an ISO timestamp. */
+    lastSeenAt: string;
+    /** Registration creation timestamp. */
+    createdAt: string;
+}
+/** Queue claim connecting a local run to a pinned experiment. */
+export interface LocalAgentClaim {
+    /** Claimed queue-run identity. */
+    runId: string;
+    /** Pinned experiment to execute. */
+    experimentId: string;
+}

package/dist/evals.d.ts

@@ -9,3 +9,5 @@ export type { ActualAgentManifestInputV2, ActualAgentManifestV2, AttemptBaseline
 export { builtins, defineLocalScorer, scoreLocally } from "./evals/scorers.js";
 export { sourceDigest } from "./evals/json.js";
 export type * from "./evals/types.js";
+export { runLocalAgent } from "./evals/local-worker.js";
+export type { LocalAgentTargetContext, RunLocalAgentOptions } from "./evals/local-worker.js";

package/dist/evals.js

@@ -4,3 +4,4 @@ export { runSimulation } 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 { builtins, defineLocalScorer, scoreLocally } from "./evals/scorers.js";
 export { sourceDigest } from "./evals/json.js";
+export { runLocalAgent } from "./evals/local-worker.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.2.2";
+export declare const sdkVersion = "0.3.0";

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.2.2";
+export const sdkVersion = "0.3.0";

package/package.json

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