@hue-run/sdk 0.4.2 → 0.5.0

package/dist/evals/client.js

@@ -1,4 +1,4 @@
-import { validateOptions } from "../config.js";
+import { isLoopbackHost, validateOptions } from "../config.js";
 import { json, uuid, valueBounds } from "./json.js";
 import { attemptBindingRead, parsePrepareAttemptResultV2, parseRefreshedAttemptResultV2, parseRevocationResult, prepareAttemptInputV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
 /** Thrown for a failed evaluation API request; the message is fixed and never includes response text. */
@@ -83,6 +83,73 @@ export class EvaluationClient {
             throw new HueApiError();
         }
     }
+    /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size. */
+    async downloadArtifact(id) {
+        let response;
+        try {
+            response = await fetch(`${this.baseUrl}/api/v1/artifacts/${uuid(id)}/download`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                redirect: "error",
+                signal: AbortSignal.timeout(Math.max(this.timeoutMillis, 120_000)),
+            });
+        }
+        catch {
+            throw new HueApiError();
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new HueApiError(response.status);
+        }
+        try {
+            const reader = response.body?.getReader();
+            if (!reader)
+                throw new Error("Missing response");
+            const chunks = [];
+            let size = 0;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.byteLength;
+                    if (size > 25 * 1024 * 1024)
+                        throw new Error("Oversized artifact");
+                    chunks.push(value);
+                }
+            }
+            finally {
+                await reader.cancel();
+            }
+            return new Uint8Array(Buffer.concat(chunks));
+        }
+        catch {
+            throw new HueApiError();
+        }
+    }
+    /** Stage bytes at the storage capability Hue issued. The Hue key is never sent to storage. */
+    async uploadArtifactBytes(upload, bytes, contentType) {
+        const uploadUrl = signedUploadUrl(upload.uploadUrl);
+        if (upload.method !== "PUT")
+            throw new HueApiError();
+        const headers = signedUploadHeaders(upload.headers, contentType);
+        let response;
+        try {
+            response = await fetch(uploadUrl, {
+                method: "PUT",
+                headers,
+                body: bytes,
+                redirect: "error",
+                signal: AbortSignal.timeout(Math.max(this.timeoutMillis, 120_000)),
+            });
+        }
+        catch {
+            throw new HueApiError();
+        }
+        await response.body?.cancel().catch(() => undefined);
+        if (!response.ok)
+            throw new HueApiError(response.status);
+    }
     page(options = {}) {
         const query = new URLSearchParams();
         if (options.after)
@@ -253,6 +320,22 @@ export class EvaluationClient {
             throw new HueApiError();
         }
     }
+    /** Reads one artifact reservation and its verification state. */
+    getArtifact(id) {
+        return this.request("GET", `/artifacts/${uuid(id)}`);
+    }
+    /** Reserves an artifact by declared identity; replaying the key returns the same reservation. */
+    reserveArtifact(input) {
+        return this.request("POST", "/artifacts", input);
+    }
+    /** Issues a short-lived storage capability for staging the reserved artifact's bytes. */
+    requestArtifactUpload(id) {
+        return this.request("POST", `/artifacts/${uuid(id)}/upload`, {});
+    }
+    /** Asks Hue to verify the staged bytes against the declared identity. */
+    completeArtifact(id) {
+        return this.request("POST", `/artifacts/${uuid(id)}/complete`, {});
+    }
     /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id, input) {
         return this.request("POST", `/experiment-executions/${uuid(id)}/complete`, input);
@@ -269,6 +352,10 @@ export class EvaluationClient {
     getEvaluationRun(id) {
         return this.request("GET", `/evaluation-runs/${uuid(id)}`);
     }
+    /** Every evaluation run of the project, oldest first; a grading worker polls this for pending pins. */
+    listEvaluationRuns(page) {
+        return this.request("GET", `/evaluation-runs${this.page(page)}`);
+    }
     /** Lists the subjects of an evaluation run. */
     listEvaluationItems(id, page) {
         return this.request("GET", `/evaluation-runs/${uuid(id)}/items${this.page(page)}`);
@@ -325,6 +412,14 @@ export class EvaluationClient {
     completeLocalAgentRun(input) {
         return this.request("POST", "/local-agent-worker/runs/complete", input);
     }
+    /** Lists Scenarios (draft and published) of the project; requires a Tracing and evaluations key. */
+    listCaseConversions(page) {
+        return this.request("GET", `/case-conversions${this.page(page)}`);
+    }
+    /** Reads one Scenario with its immutable publication pins. */
+    getCaseConversion(id) {
+        return this.request("GET", `/case-conversions/${uuid(id)}`);
+    }
     /** Creates the legacy execution-scoped generic MCP capability for one world. */
     createSimulationMcpCapability(input) {
         return this.request("POST", "/local-agent-worker/mcp-capability", input);
@@ -338,3 +433,45 @@ export class EvaluationClient {
 export function createEvaluationClient(options) {
     return new EvaluationClient(options);
 }
+function signedUploadUrl(value) {
+    // eslint-disable-next-line no-control-regex -- control characters are rejected deliberately
+    if (typeof value !== "string" || value.length > 8192 || /[\x00-\x20\x7f]/u.test(value))
+        throw new HueApiError();
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new HueApiError();
+    }
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) ||
+        url.username ||
+        url.password ||
+        url.hash)
+        throw new HueApiError();
+    // Validate without rewriting the provider's signed capability.
+    return value;
+}
+function signedUploadHeaders(value, contentType) {
+    const headers = { "content-type": contentType };
+    if (value === undefined || value === null)
+        return headers;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new HueApiError();
+    for (const [name, raw] of Object.entries(value)) {
+        if (typeof raw !== "string" ||
+            !raw ||
+            raw.length > 255 ||
+            // eslint-disable-next-line no-control-regex -- control characters are rejected deliberately
+            /[\x00-\x1f\x7f]/u.test(raw))
+            throw new HueApiError();
+        const lower = name.toLowerCase();
+        if (lower === "content-type" && raw === contentType)
+            headers[lower] = raw;
+        else if (lower === "x-vercel-blob-access" && raw === "private")
+            headers[lower] = raw;
+        else
+            throw new HueApiError();
+    }
+    return headers;
+}

package/dist/evals/files.d.ts

@@ -0,0 +1,50 @@
+import { type EvaluationClient } from "./client.js";
+import type { CaseFile, LocalFile, OutputFile, SubjectFile } from "./types.js";
+/** Roles the target receives. Organization templates stay with grading, as in the managed protocol. */
+export declare const targetFileRoles: readonly CaseFile["role"][];
+/** Hue's artifact policy: the pilot file size and the accepted document types. */
+export declare const outputFileLimits: {
+    /** Maximum number of generated files per execution. */
+    readonly count: 32;
+    /** Maximum size of one generated file in bytes (25 MiB). */
+    readonly bytes: number;
+};
+/** Content types Hue accepts for generated files. */
+export declare const outputContentTypes: readonly string[];
+/** A generated file the runner copied next to its checkpoint before uploading it. */
+export interface StagedOutputFile {
+    /** Sanitized file name, unique within the execution. */
+    filename: string;
+    /** Declared content type. */
+    contentType: string;
+    /** Size of the staged bytes. */
+    byteSize: number;
+    /** SHA-256 of the staged bytes, hex encoded. */
+    sha256: string;
+    /** Absolute path of the staged copy. */
+    path: string;
+    /** Whether the target declared this file as the primary document. */
+    primary: boolean;
+    /** Hue artifact identity once the upload was verified. */
+    artifactId?: string;
+}
+/** Thrown when the target's declared files cannot be used; recorded as the target's error. */
+export declare class OutputFileError extends Error {
+    constructor(message: string);
+}
+/** Reduce a declared file name to a single printable path segment, at most 200 characters. */
+export declare function safeFilename(name: string): string;
+/**
+ * Save verified copies of a case's pinned input files under `directory`. A file already
+ * present with the pinned identity is reused, so a resumed run does not download again.
+ */
+export declare function downloadCaseFiles(client: EvaluationClient, files: SubjectFile[], directory: string, primaryArtifactId?: string | null): Promise<LocalFile[]>;
+/** Copy the target's generated files next to the checkpoint and record their identities. */
+export declare function stageOutputFiles(files: OutputFile[], directory: string): Promise<StagedOutputFile[]>;
+/**
+ * Publish staged files as verified artifacts. Reservations use stable keys derived from the
+ * execution and the bytes, so a resumed upload settles on the same artifact.
+ */
+export declare function uploadOutputFiles(client: EvaluationClient, executionId: string, files: StagedOutputFile[], save: () => Promise<void>): Promise<void>;
+/** Project uploaded staged files as the verified local files handed to scorers. */
+export declare function localOutputFiles(files: StagedOutputFile[]): LocalFile[];

package/dist/evals/files.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { copyFile, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { HueApiError } from "./client.js";
+/** Roles the target receives. Organization templates stay with grading, as in the managed protocol. */
+export const targetFileRoles = [
+    "source",
+    "attached_template",
+    "attached_reference",
+    "original",
+];
+/** Hue's artifact policy: the pilot file size and the accepted document types. */
+export const outputFileLimits = {
+    /** Maximum number of generated files per execution. */
+    count: 32,
+    /** Maximum size of one generated file in bytes (25 MiB). */
+    bytes: 25 * 1024 * 1024,
+};
+/** Content types Hue accepts for generated files. */
+export const outputContentTypes = [
+    "application/pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/json",
+    "text/plain",
+    "text/csv",
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+];
+/** Thrown when the target's declared files cannot be used; recorded as the target's error. */
+export class OutputFileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "OutputFileError";
+    }
+}
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Reduce a declared file name to a single printable path segment, at most 200 characters. */
+export function safeFilename(name) {
+    const cleaned = [...name]
+        .filter((c) => c.charCodeAt(0) >= 32 && c.charCodeAt(0) !== 127 && c !== "/" && c !== "\\")
+        .join("")
+        .trim();
+    return cleaned && cleaned !== "." && cleaned !== ".."
+        ? [...cleaned].slice(0, 200).join("")
+        : "file";
+}
+async function privateDirectory(path) {
+    const root = resolve(path);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const info = await lstat(root);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error("Use a private files directory (no symlink)");
+    return root;
+}
+async function writePrivate(path, bytes) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const file = await open(temporary, "wx", 0o600);
+    try {
+        await file.writeFile(bytes);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+}
+async function verifiedBytes(path, expected) {
+    const bytes = await readFile(path);
+    if (bytes.byteLength !== expected.byteSize || sha256(bytes) !== expected.sha256)
+        throw new Error(`Saved file ${path} no longer matches its verified identity`);
+    return bytes;
+}
+/**
+ * Save verified copies of a case's pinned input files under `directory`. A file already
+ * present with the pinned identity is reused, so a resumed run does not download again.
+ */
+export async function downloadCaseFiles(client, files, directory, primaryArtifactId) {
+    const root = await privateDirectory(directory);
+    const saved = [];
+    for (const [index, file] of files.entries()) {
+        const path = join(root, `${index + 1}-${safeFilename(file.filename)}`);
+        let present = false;
+        try {
+            await verifiedBytes(path, file);
+            present = true;
+        }
+        catch {
+            present = false;
+        }
+        if (!present) {
+            const bytes = await client.downloadArtifact(file.artifactId);
+            if (bytes.byteLength !== file.byteSize || sha256(bytes) !== file.sha256)
+                throw new Error(`Downloaded input ${file.filename} does not match its pinned identity`);
+            await writePrivate(path, bytes);
+        }
+        saved.push({
+            artifactId: file.artifactId,
+            role: file.role,
+            filename: file.filename,
+            contentType: file.contentType,
+            byteSize: file.byteSize,
+            sha256: file.sha256,
+            path,
+            ...(file.role === "output" && file.artifactId === primaryArtifactId ? { primary: true } : {}),
+        });
+    }
+    return saved;
+}
+/** Copy the target's generated files next to the checkpoint and record their identities. */
+export async function stageOutputFiles(files, directory) {
+    if (!Array.isArray(files) || !files.length)
+        throw new OutputFileError("No generated files");
+    if (files.length > outputFileLimits.count)
+        throw new OutputFileError(`At most ${outputFileLimits.count} generated files are supported`);
+    if (files.filter((file) => file.primary).length > 1)
+        throw new OutputFileError("Declare at most one primary generated file");
+    const root = await privateDirectory(directory);
+    await rm(root, { recursive: true, force: true });
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const staged = [];
+    const names = new Set();
+    for (const file of files) {
+        if (typeof file.filename !== "string" || !file.filename.trim())
+            throw new OutputFileError("Generated files need a filename");
+        const filename = safeFilename(file.filename);
+        if (names.has(filename))
+            throw new OutputFileError(`Duplicate generated file ${filename}`);
+        names.add(filename);
+        if (!outputContentTypes.includes(file.contentType))
+            throw new OutputFileError(`Unsupported generated file type ${String(file.contentType)}`);
+        let bytes;
+        try {
+            bytes = file.bytes ?? (await readFile(file.path));
+        }
+        catch {
+            throw new OutputFileError(`Generated file ${filename} could not be read`);
+        }
+        if (!bytes.byteLength)
+            throw new OutputFileError(`Generated file ${filename} is empty`);
+        if (bytes.byteLength > outputFileLimits.bytes)
+            throw new OutputFileError(`Generated file ${filename} exceeds 25 MiB`);
+        const path = join(root, filename);
+        if (file.bytes)
+            await writePrivate(path, bytes);
+        else {
+            await copyFile(file.path, path);
+            await verifiedBytes(path, { byteSize: bytes.byteLength, sha256: sha256(bytes) });
+        }
+        staged.push({
+            filename,
+            contentType: file.contentType,
+            byteSize: bytes.byteLength,
+            sha256: sha256(bytes),
+            path,
+            primary: file.primary === true,
+        });
+    }
+    return staged;
+}
+/**
+ * Publish staged files as verified artifacts. Reservations use stable keys derived from the
+ * execution and the bytes, so a resumed upload settles on the same artifact.
+ */
+export async function uploadOutputFiles(client, executionId, files, save) {
+    for (const file of files) {
+        if (file.artifactId)
+            continue;
+        const bytes = await verifiedBytes(file.path, file);
+        const reserved = await client.reserveArtifact({
+            idempotencyKey: `hue-sdk:${executionId}:${file.sha256}:${sha256(Buffer.from(file.filename)).slice(0, 16)}`,
+            filename: file.filename,
+            contentType: file.contentType,
+            byteSize: file.byteSize,
+            sha256: file.sha256,
+        });
+        let state = reserved.state;
+        if (state !== "ready") {
+            if (reserved.copyState !== "acknowledged") {
+                const upload = await client.requestArtifactUpload(reserved.id);
+                try {
+                    await client.uploadArtifactBytes(upload, bytes, file.contentType);
+                }
+                catch {
+                    // A lost staging acknowledgement or an immutable object already present can only be
+                    // settled by verified completion; never rewrite a final object here.
+                }
+            }
+            let attempt = 0;
+            for (;;) {
+                try {
+                    state = (await client.completeArtifact(reserved.id)).state;
+                    break;
+                }
+                catch (error) {
+                    if (!(error instanceof HueApiError) || error.status !== 503 || attempt++ >= 2)
+                        throw error;
+                    await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+                }
+            }
+        }
+        if (state !== "ready")
+            throw new Error(`Generated file ${file.filename} was not verified by Hue (${state})`);
+        file.artifactId = reserved.id;
+        await save();
+    }
+}
+/** Project uploaded staged files as the verified local files handed to scorers. */
+export function localOutputFiles(files) {
+    return files.map((file) => ({
+        artifactId: file.artifactId,
+        role: "output",
+        filename: file.filename,
+        contentType: file.contentType,
+        byteSize: file.byteSize,
+        sha256: file.sha256,
+        path: file.path,
+        ...(file.primary ? { primary: true } : {}),
+    }));
+}

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

@@ -3,8 +3,16 @@ 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";
+import { type RunExperimentTargetContext, type RunnerReport } from "./runner.js";
+import type { ExperimentCase, JsonValue, LocalAgentRegistration, LocalFile, LocalScorer, TargetResult } from "./types.js";
+/** Capability strings a registration declares; Hue offers only matching cases. */
+export declare const localAgentCapabilities: {
+    /** Cases pinned to a hosted synthetic world. */
+    readonly environment: "environment:v1";
+    /** Ordinary cases run directly on this machine: JSON inputs and pinned input files in,
+     * JSON output and generated files out. */
+    readonly direct: "direct:v1";
+};
 /** Candidate-visible context for one queued local agent execution. */
 export interface LocalAgentTargetContext {
     /** Frozen candidate configuration, cloned before invocation. */
@@ -35,6 +43,30 @@ export interface LocalAgentTargetContext {
      * checkpoints, logs or adds this response to parity digests. */
     connectionBundle?: AttemptConnectionBundleV2;
 }
+/** Candidate-visible context for one queued ordinary case run directly on this machine. */
+export interface LocalAgentDirectContext {
+    /** Frozen candidate configuration, cloned before invocation. */
+    config: JsonValue;
+    /** Identity only. Expected outcomes and metadata are evaluator-private. */
+    item: Pick<ExperimentCase, "id" | "externalKey">;
+    /** Identity of this target execution. */
+    executionId: string;
+    /** Trace identities without mutable span or grading data. */
+    trace: {
+        /** OpenTelemetry trace identifier. */
+        traceId: string;
+        /** Root execution span identifier. */
+        spanId: string;
+    };
+    /** Verified copies of the case's input files meant for the agent. */
+    files: LocalFile[];
+    /** Private scratch directory for this case; return generated files with `withFiles`. */
+    outputDirectory: string;
+    /** Cooperative worker stop signal. */
+    signal?: AbortSignal;
+}
+/** Allowlist the candidate surface for an ordinary case; frozen expectations stay with grading. */
+export declare function localAgentDirectContext(context: RunExperimentTargetContext, signal?: AbortSignal): LocalAgentDirectContext;
 /** Fixed local callback, clients and durable queue-worker settings. */
 export interface RunLocalAgentOptions {
     /** Evaluation client for the worker project. */
@@ -76,11 +108,24 @@ export interface RunLocalAgentOptions {
         /** 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>;
+    /** Runs cases pinned to a hosted world (`environment:v1`): 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>;
+    /** Runs ordinary cases without a world (`direct:v1`): the agent receives the case inputs
+     * and verified input files and returns JSON output and/or generated files. */
+    directTarget?(inputs: JsonValue, context: LocalAgentDirectContext): JsonValue | TargetResult | undefined | Promise<JsonValue | TargetResult | undefined>;
     /** Called after the experiment and queue completion are acknowledged. */
     onCompleted?(report: RunnerReport): void | Promise<void>;
 }
+/** The registration's capabilities: explicit values plus one per supplied callback. */
+export declare function registeredCapabilities(options: {
+    /** Fixed agent key, revision and declared capabilities. */
+    agent: LocalAgentRegistration;
+    /** The environment-case callback, when supplied. */
+    target?: unknown;
+    /** The ordinary-case callback, when supplied. */
+    directTarget?: unknown;
+}): string[];
 /**
  * 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.

package/dist/evals/local-worker.js

@@ -3,6 +3,26 @@ 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";
+/** Capability strings a registration declares; Hue offers only matching cases. */
+export const localAgentCapabilities = {
+    /** Cases pinned to a hosted synthetic world. */
+    environment: "environment:v1",
+    /** Ordinary cases run directly on this machine: JSON inputs and pinned input files in,
+     * JSON output and generated files out. */
+    direct: "direct:v1",
+};
+/** Allowlist the candidate surface for an ordinary case; frozen expectations stay with grading. */
+export function localAgentDirectContext(context, signal) {
+    return {
+        config: structuredClone(context.config),
+        item: { id: context.item.id, externalKey: context.item.externalKey },
+        executionId: context.executionId,
+        trace: { traceId: context.span.traceId, spanId: context.span.spanId },
+        files: structuredClone(context.files),
+        outputDirectory: context.outputDirectory,
+        ...(signal ? { signal } : {}),
+    };
+}
 /** Allowlist the candidate surface instead of forwarding the generic evaluation context. */
 function localAgentTargetContext(context) {
     return {
@@ -21,6 +41,23 @@ function localAgentTargetContext(context) {
             : {}),
     };
 }
+/** The registration's capabilities: explicit values plus one per supplied callback. */
+export function registeredCapabilities(options) {
+    if (!options.target && !options.directTarget)
+        throw new TypeError("Supply target for environment cases, directTarget for ordinary cases, or both");
+    const declared = options.agent.capabilities ?? [];
+    if (declared.includes(localAgentCapabilities.direct) && !options.directTarget)
+        throw new TypeError("direct:v1 requires a directTarget callback");
+    if (declared.includes(localAgentCapabilities.environment) && !options.target)
+        throw new TypeError("environment:v1 requires a target callback");
+    return [
+        ...new Set([
+            ...declared,
+            ...(options.target ? [localAgentCapabilities.environment] : []),
+            ...(options.directTarget ? [localAgentCapabilities.direct] : []),
+        ]),
+    ];
+}
 function validInterval(value) {
     const interval = value ?? 2_000;
     if (!Number.isInteger(interval) || interval < 250 || interval > 60_000)
@@ -63,6 +100,7 @@ function needsAttention(error, seen = new Set()) {
  * only the registered key/revision; no command or source is received from the cloud.
  */
 export async function runLocalAgent(options) {
+    const capabilities = registeredCapabilities(options);
     const requestedConfiguration = requestedAttemptV2(options);
     const interval = validInterval(options.pollIntervalMillis);
     const maxRuns = options.maxRuns ?? Number.POSITIVE_INFINITY;
@@ -91,7 +129,7 @@ export async function runLocalAgent(options) {
         while (completed < maxRuns && !options.signal?.aborted) {
             const agent = await options.client.registerLocalAgent({
                 ...options.agent,
-                capabilities: options.agent.capabilities ?? ["environment:v1"],
+                capabilities,
                 scorerDigests: options.agent.scorerDigests ??
                     options.scorers?.map((item) => item.definition.sourceDigest) ??
                     [],
@@ -117,20 +155,33 @@ export async function runLocalAgent(options) {
                     experimentId: claim.experimentId,
                     checkpointDirectory: join(directory, `experiment-${claim.experimentId}`),
                     persistResultContent: true,
-                    environmentEvidence: "required",
+                    // Worker dispatch uses the case pin: directTarget never receives a world.
+                    environmentEvidence: options.directTarget ? "when_pinned" : "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)),
-                    }),
+                    target: (inputs, context) => {
+                        if (!context.item.environmentVersionId) {
+                            // Hue offers ordinary cases only to registrations that declared direct:v1.
+                            if (!options.directTarget)
+                                throw new Error("This worker runs only cases pinned to a Hue environment");
+                            return options.directTarget(structuredClone(inputs), localAgentDirectContext(context, options.signal));
+                        }
+                        if (!options.target)
+                            throw new Error("This worker runs only cases without a Hue environment");
+                        // Bound to the options object, as the previous direct `options.target(...)` call was.
+                        const target = options.target.bind(options);
+                        return runEnvironmentTarget({
+                            client: options.client,
+                            environmentClient: options.environmentClient,
+                            hue: options.hue,
+                            inputs,
+                            context,
+                            requested,
+                            signal: options.signal,
+                            target: (targetInputs, targetContext) => 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