@hue-run/sdk 0.2.2 → 0.3.1

package/CLI.md

@@ -0,0 +1,52 @@
+# Hue setup-session CLI contract
+
+Unreleased TypeScript `0.3.1` includes the merged local setup-session CLI core:
+
+```sh
+hue setup
+hue setup --agent
+hue resume
+hue status
+hue claim # reports account attachment unavailable in this local core
+```
+
+These commands belong only to an installer setup session. They do not create or launch a Hue Run,
+Scenario, evaluation, or worker. `claim` only means attaching the anonymous setup project to an
+account; there is no generic `connect` command or local-agent connection in this CLI.
+
+`setup` only inspects bounded manifest and lockfile metadata. It does not execute repository code,
+change project files, open a browser, ask a question, create a trial, or contact Hue. `claim` also
+makes no network request in this build and reports that account attachment is unavailable. `resume`
+deterministically continues the same setup-session checkpoint; `status` reads it without changing
+it.
+
+Checkpoints are secret-free JSON files outside the project, under the operating system's user state
+directory. On POSIX, directories use mode `0700` and files use mode `0600`; Windows uses its
+per-user local state directory without interpreting POSIX mode bits. Writes are atomic, and a
+configured state location inside the project is rejected. Checkpoints contain project categories
+and hashes, never environment values, credentials, source contents, or claim URLs.
+
+`--agent` is explicitly noninteractive JSONL. It never uses ANSI, stdin, or a browser, and each
+invocation emits exactly one terminal `run.completed` or `run.failed` installer event. Those names
+describe the setup-session lifecycle, not a Hue Run. Human output is an append-only inline
+transcript. Plain and JSONL output contain no ANSI; `NO_COLOR`, `TERM=dumb`, CI, and non-TTY output
+select plain mode automatically.
+
+Every JSONL record carries `contractVersion: 1`. The TypeScript union is exported from
+`@hue-run/sdk/setup`; the JSON Schema is exported as
+`@hue-run/sdk/setup-events.schema.json`. Consumers must ignore neither unknown versions nor terminal
+failures.
+
+The future Fern implementation plugs into `SetupBackendAdapter`. Its three installer operations
+create an anonymous setup trial hard-pinned to `trial_metadata_v1`, verify instrumentation-only
+receipt evidence, and read account-claim state. Inputs carry deterministic idempotency keys and an
+optional abort signal. Adapter results must use bounded, non-secret IDs; claim URLs may be sensitive
+and therefore must never be checkpointed. Receipt verification does not prove that task or
+environment content was captured and must never authorize Scenario publication. The adapter must
+not create a Scenario, evaluation, worker, or Hue Run. No live implementation ships in this slice.
+
+The V1 handoff is deliberately staged: setup verifies the anonymous instrumentation trace; `hue claim`
+preserves the project and trace history; then the user performs an explicit content-approved capture
+or rerun, with a prepared tester as the first golden path. Only that content-approved trace passes to
+the separate review/publication flow for a Scenario. The actual URL and that handoff contract remain
+deferred. Setup itself does not capture content, create, publish, or run a Scenario.

package/ENVIRONMENTS.md

@@ -1,6 +1,6 @@
 # Simulated environments
 
-Install the optional evaluation runtime-contract peer with the SDK:
+The provider-aware environment APIs shipped in TypeScript `0.3.0` and are publicly available:
 
 ```bash
 npm install @hue-run/sdk zod
@@ -77,11 +77,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 +98,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 +188,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 shipped in `@hue-run/sdk@0.3.0`.
+
+`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";
@@ -118,7 +120,11 @@ All declared metrics must appear exactly once and satisfy pinned types, bounds a
 
 ### Hosted and manual scorer pins
 
-The local runner leaves `llm_judge` and `manual` pins pending and reports their IDs in `deferredScorerVersionIds`. It does not upload a synthetic skipped result that would occupy their immutable result slot. Manual results require a human session. Hosted dispatch is an explicit separate API operation: inspect `getJudgeBudget()`, then call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
+In TypeScript `0.3.1` (unreleased), the local runner executes only the three known built-in entries and bound `local_code` scorers. It leaves every other pin pending and reports its ID in `deferredScorerVersionIds`, including kinds and built-in entries introduced by a newer server. It never uploads a placeholder result that would occupy the immutable result slot, including placeholders already saved in an older SDK's checkpoint. Direct `scoreLocally()` calls reject pins that require another executor.
+
+`world_outcome` pins run inside Hue and need no local callback or executable source digest. A supporting server owns their execution from saved world evidence. Legacy `local_code` pins still require the exact registered callback; changing the worker cannot convert those immutable pins into hosted ones.
+
+Manual results require a human session. Hosted model-judge dispatch is an explicit separate API operation: inspect `getJudgeBudget()`, then call `createJudgeJobs(runId,{idempotencyKey,jobs:[{evaluationItemId,scorerVersionId}]})`. `listJudgeJobs`, `getJudgeJob` and `cancelJudgeJob` expose job progress and cancellation requests. These methods never claim that local execution has hosted provenance. Hosted job endpoints are covered by HTTP contract tests here; live hosted model execution is a separate platform acceptance phase. `listResults` and `getResult` read recorded local or hosted results.
 
 When present, the budget's `authentication` reports credential resolution only. An
 `available` status or `configured: true` does not prove that a provider accepted the
@@ -150,4 +156,65 @@ 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` shipped in `@hue-run/sdk@0.3.0` and is publicly available. Install
+`npm install @hue-run/sdk zod`. 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 provider availability.
+
+`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",
+    scorers: [], // Hue-executed scorers require no local callback registration.
+    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,26 @@ 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
+
+`runLocalAgent()` shipped in TypeScript `0.3.0` and is available from npm. It connects a fixed local
+callback to app-launched simulation work while keeping the agent and provider orchestration in
+the developer's process. 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.
+
+Unreleased TypeScript `0.3.1` defers all scorers the SDK does not execute locally. Only built-ins
+and bound `local_code` callbacks run here; other pins remain pending for their authorized executor.
+See [scorer execution](EVALUATIONS.md#hosted-and-manual-scorer-pins).
+
+The [setup CLI](CLI.md) is a resumable local inspection core. Existing customers connect their
+agents with `runLocalAgent()`; setup does not register workers or launch Scenarios.
+
 ## 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;
+    }
+}