@hue-run/sdk 0.11.4 → 0.12.1

package/dist/evals/client.js

@@ -5,17 +5,51 @@ import { attemptBindingRead, parsePrepareAttemptResultV2, parseRefreshedAttemptR
 export class HueApiError extends Error {
     status;
     retryAfterSeconds;
+    diagnostic;
     constructor(
     /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
     status, 
     /** Seconds Hue asked the caller to wait (`Retry-After` on a 429 or 503), when it said. */
-    retryAfterSeconds) {
-        super(status ? `Hue API request failed (HTTP ${status})` : "Hue API connection or response failed");
+    retryAfterSeconds, 
+    /** Hue's `X-Hue-Diagnostic` code, which tells refusals of one status apart, when it sent one. */
+    diagnostic) {
+        super(status
+            ? `Hue API request failed (HTTP ${status}${diagnostic ? `, ${diagnostic}` : ""})`
+            : "Hue API connection or response failed");
         this.status = status;
         this.retryAfterSeconds = retryAfterSeconds;
+        this.diagnostic = diagnostic;
         this.name = "HueApiError";
     }
 }
+const TRANSIENT = new Set([408, 429, 500, 502, 503, 504]);
+/**
+ * Whether the same request, sent again, can succeed: a connection failure, a timeout, or a status
+ * Hue answers while it cannot act yet (408, 429, 500, 502, 503, 504). A refusal Hue decided on,
+ * any other 4xx, is not, and no number of attempts changes it.
+ */
+export function isTransientApiError(error) {
+    return (error instanceof HueApiError && (error.status === undefined || TRANSIENT.has(error.status)));
+}
+const DIAGNOSTIC = /^[a-z_]{1,64}$/;
+function diagnosticOf(response) {
+    const value = response.headers.get("x-hue-diagnostic");
+    return value !== null && DIAGNOSTIC.test(value) ? value : undefined;
+}
+/** Whether a request may be sent again after a transient failure: every read, and a mutation the
+ * server deduplicates, either by the `idempotencyKey` in its body or because its route is
+ * idempotent by design (the local worker's register, claim, heartbeat, completion and capability
+ * routes). A mutation without a key is sent once; its caller resolves the outcome before asking
+ * again. */
+function retryable(method, body, idempotent) {
+    if (idempotent !== undefined)
+        return idempotent;
+    if (method === "GET")
+        return true;
+    return (body !== null &&
+        typeof body === "object" &&
+        typeof body.idempotencyKey === "string");
+}
 /** An artifact download that ran past the size its caller expected; the rest is not read. */
 export class ArtifactSizeError extends Error {
     maxBytes;
@@ -128,16 +162,21 @@ function refusalRetryAfter(response) {
 }
 /**
  * Typed client for Hue's evaluation REST API: datasets, scorers, experiments, executions, runs,
- * results and hosted judge jobs. No implicit mutation retry: callers retain stable idempotency keys
- * for experiments and results. The one exception is a request Hue refused before acting on it with
- * a short `Retry-After` (HTTP 429 or 503, at most 5 seconds): it is sent again after that wait, up
- * to four times. Responses are bounded to 4 MiB.
+ * results and hosted judge jobs. A request Hue refused before acting on it with a short
+ * `Retry-After` (HTTP 429 or 503, at most 5 seconds) is sent again after that wait whatever its
+ * method, up to four times; a longer wait is the caller's error, carried as `retryAfterSeconds`.
+ * A read, or a mutation the server deduplicates by its idempotency key, is also sent again after
+ * a failure Hue did not time, a connection failure, a timeout or a 408 or 5xx without the header,
+ * up to `maxAttempts` times with a jittered backoff. A mutation without a key is never retried
+ * implicitly: callers retain stable idempotency keys for experiments and results. Responses are
+ * bounded to 4 MiB.
  */
 export class EvaluationClient {
     /** Validated Hue origin. */
     baseUrl;
     apiKey;
     timeoutMillis;
+    maxAttempts;
     constructor(options) {
         const validated = validateOptions({
             ...options,
@@ -147,6 +186,10 @@ export class EvaluationClient {
         this.baseUrl = validated.baseUrl;
         this.apiKey = validated.apiKey;
         this.timeoutMillis = validated.timeoutMillis;
+        const attempts = options.maxAttempts ?? 4;
+        if (!Number.isInteger(attempts) || attempts < 1 || attempts > 10)
+            throw new RangeError("maxAttempts must be 1–10");
+        this.maxAttempts = attempts;
     }
     /** Sends one request to Hue, again after the wait while Hue refuses it with a short
      * `Retry-After`. `init` runs for every attempt, so each has its own timeout; `signal` also ends
@@ -183,11 +226,44 @@ export class EvaluationClient {
                 throw new HueApiError(response.status, askedRetryAfter(response));
         }
     }
-    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }, signal) {
-        // Optional top-level fields are omitted intentionally; nested undefined remains invalid.
+    async request(method, path, body, bounds = { ...valueBounds, bytes: 1024 * 1024 }, signal, 
+    /** Overrides the retry decision `retryable` takes from the method and body. */
+    idempotent) {
+        // Serialized once, outside the attempts: a body this client cannot encode is a caller error
+        // no attempt fixes. Optional top-level fields are omitted intentionally; nested undefined
+        // remains invalid.
         const payload = body === undefined
             ? undefined
             : JSON.stringify(json(Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined)), bounds));
+        const attempts = retryable(method, body, idempotent) ? this.maxAttempts : 1;
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await this.requestOnce(method, path, payload, signal);
+            }
+            catch (error) {
+                // A refusal that carried `Retry-After` was already decided by `send`: sent again while
+                // the wait was short, the caller's error when it was long. This loop covers the failures
+                // Hue did not time: a lost connection, a timeout, a 5xx or 408 without the header.
+                if (!isTransientApiError(error) ||
+                    error.retryAfterSeconds !== undefined ||
+                    attempt >= attempts ||
+                    signal?.aborted)
+                    throw error;
+                const backoff = Math.min(100 * 2 ** (attempt - 1), 2000);
+                const wait = backoff + Math.random() * backoff;
+                await new Promise((resolve) => {
+                    const done = () => {
+                        clearTimeout(timer);
+                        signal?.removeEventListener("abort", done);
+                        resolve();
+                    };
+                    const timer = setTimeout(done, wait);
+                    signal?.addEventListener("abort", done, { once: true });
+                });
+            }
+        }
+    }
+    async requestOnce(method, path, payload, signal) {
         const response = await this.send(`${this.baseUrl}/api/v1${path}`, () => ({
             method,
             headers: {
@@ -200,7 +276,7 @@ export class EvaluationClient {
         }), signal);
         if (!response.ok) {
             await response.body?.cancel();
-            throw new HueApiError(response.status, askedRetryAfter(response));
+            throw new HueApiError(response.status, askedRetryAfter(response), diagnosticOf(response));
         }
         try {
             const reader = response.body?.getReader();
@@ -474,7 +550,9 @@ export class EvaluationClient {
     async prepareAttempt(input) {
         const request = prepareAttemptInputV2.parse(input);
         const { executionId, ...body } = request;
-        const response = await this.request("POST", `/experiment-executions/${executionId}/prepare-attempt`, body, { ...valueBounds, bytes: 128_000 });
+        // Sent once although keyed: a lost acknowledgement of a credential-bearing decision stays
+        // uncertain, and the worker never reacquires credentials.
+        const response = await this.request("POST", `/experiment-executions/${executionId}/prepare-attempt`, body, { ...valueBounds, bytes: 128_000 }, undefined, false);
         try {
             return parsePrepareAttemptResultV2(response, request);
         }
@@ -662,21 +740,21 @@ export class EvaluationClient {
     }
     /** Register or refresh the fixed local agent key and revision. */
     async registerLocalAgent(input) {
-        const agent = await this.request("POST", "/local-agent-worker/register", input);
+        const agent = await this.request("POST", "/local-agent-worker/register", input, undefined, undefined, true);
         // Hue's response names the key `agentKey`; read either name.
         return { ...agent, key: agent.key ?? agent.agentKey ?? input.key };
     }
     /** Claim a queued run for this agent and durable worker identity. */
     claimLocalAgentRun(input) {
-        return this.request("POST", "/local-agent-worker/claim", input);
+        return this.request("POST", "/local-agent-worker/claim", input, undefined, undefined, true);
     }
     /** Refresh the lease of a claimed local run. */
     heartbeatLocalAgentRun(input) {
-        return this.request("POST", "/local-agent-worker/runs/heartbeat", input);
+        return this.request("POST", "/local-agent-worker/runs/heartbeat", input, undefined, undefined, true);
     }
     /** Report acknowledged completion or an execution requiring attention. */
     completeLocalAgentRun(input) {
-        return this.request("POST", "/local-agent-worker/runs/complete", input);
+        return this.request("POST", "/local-agent-worker/runs/complete", input, undefined, undefined, true);
     }
     /** Lists Scenarios (draft and published) of the project; requires a Read and write key. */
     listCaseConversions(page) {
@@ -688,7 +766,7 @@ export class EvaluationClient {
     }
     /** Creates the legacy execution-scoped generic MCP capability for one world. */
     createSimulationMcpCapability(input) {
-        return this.request("POST", "/local-agent-worker/mcp-capability", input);
+        return this.request("POST", "/local-agent-worker/mcp-capability", input, undefined, undefined, true);
     }
 }
 /**

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

@@ -105,6 +105,9 @@ export interface RunEnvironmentTargetOptions {
 export declare const MAX_GRACE_WAIT_MS = 10000;
 export declare const SEAL_POLL_MS = 250;
 export declare const SEAL_WAIT_MS = 30000;
+/** How long past the world's `expiresAt` the target is given before it is stopped: room for a
+ * last call in flight at the deadline and for clock skew between the worker and Hue. */
+export declare const DEADLINE_MARGIN_MS = 5000;
 /** The seal wait's bounds. Only tests shorten them; the helpers always use the defaults. */
 export interface SealTiming {
     maxGraceWaitMs: number;
@@ -123,16 +126,20 @@ export declare function caseTraceparent(span: {
         };
     };
 }): string;
-/** What a deployment's credential-free gateway health said: `on` (200 with
- * `gateway: "simulation"`), `off` (the empty 404 the disabled handler answers, with no
- * `x-hue-diagnostic`), or `unknown` for anything else. */
+/** What a deployment's credential-free gateway probe said: `on` (the gateway answered, with its
+ * health or with a refusal carrying `x-hue-diagnostic`), `off` (the empty 404 the disabled
+ * handler answers, with no `x-hue-diagnostic`), or `unknown` for anything else. */
 export type GatewayState = "on" | "off" | "unknown";
 /**
- * Whether the deployment serves the simulation gateway, from its credential-free health
- * endpoint: 200 with `gateway: "simulation"` is on, the disabled handler's empty 404 (no
- * `x-hue-diagnostic`) is off, and anything else (a network failure, a timeout, a redirect, a
- * refusal carrying a diagnostic, another status or body) is unknown. Probed only after a create
- * was refused; on and off are remembered per origin, unknown is probed again next time.
+ * Whether the deployment serves the simulation gateway, from a credential-free probe of the
+ * gateway's reserved health path with no app named (`/api/sim/_hue/health`), so the answer does
+ * not depend on which apps the deployment mirrors. The gateway answers it on its own host with
+ * its health, 200 with `gateway: "simulation"`, and on the application host with a refusal that
+ * carries `x-hue-diagnostic` (`unmirrored_provider`: the reserved segment is no app); either is
+ * on, since only the enabled gateway writes that header. The disabled handler's empty 404 (no
+ * `x-hue-diagnostic`) is off, and anything else (a network failure, a timeout, a redirect, another
+ * status or body) is unknown. Probed only after a create was refused; on and off are remembered
+ * per origin, unknown is probed again next time.
  */
 export declare function gatewayState(baseUrl: string, fetchImpl?: (url: string, init?: RequestInit) => Promise<Response>): Promise<GatewayState>;
 /**

package/dist/evals/environment-target.js

@@ -3,7 +3,7 @@ import { HueEnvironmentError, isTransientEnvironmentError, } from "../environmen
 import { bindEnvironmentTools } from "../environment/tools.js";
 import { legacyMcpCapability, worldHandoff } from "../environment/world.js";
 import { actualAgentManifestV2, attemptBaselineV2, projectMcpConnectionV2, requestedAttemptProvidersV2, validateAttemptConnectionBundleV2, } from "./attempt.js";
-import { TargetCancelledError, TargetOutcomeUncertainError } from "./runner.js";
+import { TargetCancelledError, TargetOutcomeUncertainError, TargetTimeoutError } from "./runner.js";
 export function requestedAttemptV2(options) {
     const requested = options.requestedProviders !== undefined;
     const selected = options.mcpSurface !== undefined;
@@ -47,6 +47,9 @@ export function pinRequestedAttemptV2(requested, config) {
 export const MAX_GRACE_WAIT_MS = 10_000;
 export const SEAL_POLL_MS = 250;
 export const SEAL_WAIT_MS = 30_000;
+/** How long past the world's `expiresAt` the target is given before it is stopped: room for a
+ * last call in flight at the deadline and for clock skew between the worker and Hue. */
+export const DEADLINE_MARGIN_MS = 5_000;
 const SEAL_TIMING = {
     maxGraceWaitMs: MAX_GRACE_WAIT_MS,
     pollMs: SEAL_POLL_MS,
@@ -145,21 +148,28 @@ export function caseTraceparent(span) {
 }
 const gatewayStates = new Map();
 /**
- * Whether the deployment serves the simulation gateway, from its credential-free health
- * endpoint: 200 with `gateway: "simulation"` is on, the disabled handler's empty 404 (no
- * `x-hue-diagnostic`) is off, and anything else (a network failure, a timeout, a redirect, a
- * refusal carrying a diagnostic, another status or body) is unknown. Probed only after a create
- * was refused; on and off are remembered per origin, unknown is probed again next time.
+ * Whether the deployment serves the simulation gateway, from a credential-free probe of the
+ * gateway's reserved health path with no app named (`/api/sim/_hue/health`), so the answer does
+ * not depend on which apps the deployment mirrors. The gateway answers it on its own host with
+ * its health, 200 with `gateway: "simulation"`, and on the application host with a refusal that
+ * carries `x-hue-diagnostic` (`unmirrored_provider`: the reserved segment is no app); either is
+ * on, since only the enabled gateway writes that header. The disabled handler's empty 404 (no
+ * `x-hue-diagnostic`) is off, and anything else (a network failure, a timeout, a redirect, another
+ * status or body) is unknown. Probed only after a create was refused; on and off are remembered
+ * per origin, unknown is probed again next time.
  */
 export function gatewayState(baseUrl, fetchImpl = fetch) {
     const origin = new URL(baseUrl).origin;
     const remembered = gatewayStates.get(origin);
     if (remembered)
         return remembered;
-    const probe = fetchImpl(`${origin}/api/sim/gmailmcp.googleapis.com/_hue/health`, { redirect: "error", signal: AbortSignal.timeout(5_000) })
+    const probe = fetchImpl(`${origin}/api/sim/_hue/health`, {
+        redirect: "error",
+        signal: AbortSignal.timeout(5_000),
+    })
         .then(async (response) => {
         if (response.status === 404)
-            return response.headers.has("x-hue-diagnostic") ? "unknown" : "off";
+            return response.headers.has("x-hue-diagnostic") ? "on" : "off";
         if (!response.ok)
             return "unknown";
         const body = (await response.json());
@@ -307,20 +317,50 @@ export async function runEnvironmentTarget(options) {
         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,
-            ...(world ? { world } : {}),
-            ...(mcp ? { mcp } : {}),
-            ...(connectionBundle ? { connectionBundle } : {}),
-            files: structuredClone(context.files),
-            outputDirectory: context.outputDirectory,
-            signal: options.signal,
+        // The world's deadline bounds the target: once the world expires its mirrors refuse every
+        // call, so an agent still running can achieve nothing more. The target is told through its
+        // signal a moment after the deadline and, whether or not it listens, its case ends as a
+        // `TargetTimeout` and the world is sealed abandoned; a promise that never settles is left
+        // behind rather than holding the run open for good.
+        const expiresAt = Date.parse(run.expiresAt);
+        const deadline = new AbortController();
+        let timer;
+        const timedOut = new Promise((_, reject) => {
+            if (!Number.isFinite(expiresAt))
+                return;
+            timer = setTimeout(() => {
+                // The timeout is decided before the target is told: a target that rejects with its
+                // own abort error on the signal must not win the race and be saved as its own error.
+                const error = new TargetTimeoutError(run.id, run.expiresAt);
+                reject(error);
+                deadline.abort(error);
+            }, Math.max(0, expiresAt + DEADLINE_MARGIN_MS - Date.now()));
         });
+        let output;
+        try {
+            output = await Promise.race([
+                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,
+                    ...(world ? { world } : {}),
+                    ...(mcp ? { mcp } : {}),
+                    ...(connectionBundle ? { connectionBundle } : {}),
+                    files: structuredClone(context.files),
+                    outputDirectory: context.outputDirectory,
+                    signal: options.signal
+                        ? AbortSignal.any([options.signal, deadline.signal])
+                        : deadline.signal,
+                }),
+                timedOut,
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
         await seal(options.environmentClient, run.id, context.executionId, "completed", timing);
         finalized = true;
         await Promise.resolve(progress({ type: "world_sealed", environmentRunId: run.id })).catch(() => undefined);

package/dist/evals/failure.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What a target's throw shows about a service the agent called, when a service rather than the
+ * agent's own code stopped it: `ServiceRefused` for a retryable HTTP status (408, 429 or 5xx) a
+ * model provider, Hue or another service answered with, such as a rate limit or an outage;
+ * `ConnectionFailed` for a connection that failed; `TimedOut` for a call that timed out; and
+ * `ConfigurationRejected` for any other status Hue's own clients answered with (a 4xx: a key, a
+ * project, an environment version or a world Hue refused), which is the caller's configuration;
+ * the clients fetch with `redirect: "error"`, so a redirect surfaces without a status, as a
+ * failed connection.
+ * The runner records the type on the execution in place of `TargetError`; Hue classes the first
+ * three as infrastructure and the last as configuration, so an error from Hue's own clients is
+ * never filed as the agent's. Anything else is the agent's own error.
+ */
+export type ServiceFailureType = "ServiceRefused" | "ConnectionFailed" | "TimedOut" | "ConfigurationRejected";
+/** The service failure a target's throw shows, by the errors linked from it, in precedence
+ * order: a timeout, a failed connection, a retryable refusal, a status Hue's own client was
+ * refused with; null for the agent's own error. */
+export declare function serviceFailureType(error: unknown): ServiceFailureType | null;

package/dist/evals/failure.js

@@ -0,0 +1,150 @@
+import { HueConnectionError } from "../client.js";
+import { HueEnvironmentError } from "../environment/client.js";
+import { HueApiError } from "./client.js";
+const TIMEOUT_NAMES = new Set(["TimeoutError", "APIConnectionTimeoutError", "APITimeoutError"]);
+/** Node's and Undici's codes for a call that timed out, connecting or waiting on the answer. */
+const TIMEOUT_CODES = new Set([
+    "ETIMEDOUT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+]);
+const NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EPIPE",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "UND_ERR_SOCKET",
+]);
+/** Links followed from the thrown error, and errors read at most. */
+const MAX_DEPTH = 6;
+const MAX_ERRORS = 64;
+/** The errors an error links to: its `cause`, and the `errors` and `lastError` of an
+ * `AggregateError` or a retry error. A property that throws when read links nothing. */
+function links(error) {
+    try {
+        const { cause, lastError, errors } = error;
+        return [cause, lastError, ...(Array.isArray(errors) ? errors.slice(0, MAX_ERRORS) : [])];
+    }
+    catch {
+        return [];
+    }
+}
+/** The thrown error and every error within `MAX_DEPTH` links of it, each once, so a cycle ends
+ * the walk. */
+function linked(error) {
+    const found = [];
+    const seen = new Set();
+    let level = [error];
+    for (let depth = 0; depth <= MAX_DEPTH && level.length; depth++) {
+        const next = [];
+        for (const item of level) {
+            if (typeof item !== "object" || item === null || seen.has(item))
+                continue;
+            if (found.length === MAX_ERRORS)
+                return found;
+            seen.add(item);
+            found.push(item);
+            next.push(...links(item));
+        }
+        level = next;
+    }
+    return found;
+}
+/** The error's `name` and its class names, since some SDKs never set `name`. */
+function names(error) {
+    const found = [];
+    const name = error.name;
+    if (typeof name === "string")
+        found.push(name);
+    let prototype = Object.getPrototypeOf(error);
+    for (let depth = 0; depth < MAX_DEPTH && prototype; depth++) {
+        const constructor = prototype.constructor;
+        if (typeof constructor?.name === "string")
+            found.push(constructor.name);
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return found;
+}
+const retryable = (status) => typeof status === "number" &&
+    (status === 408 || status === 429 || (status >= 500 && status < 600));
+function timedOut(error) {
+    const { code } = error;
+    return ((typeof code === "string" && TIMEOUT_CODES.has(code)) ||
+        names(error).some((name) => TIMEOUT_NAMES.has(name)));
+}
+/** An error one of Hue's own clients threw, which carries the status Hue answered or none. */
+function hueClientError(error) {
+    return (error instanceof HueConnectionError ||
+        error instanceof HueEnvironmentError ||
+        error instanceof HueApiError);
+}
+function disconnected(error) {
+    // Hue's clients report a request that got no usable response without a status.
+    if (hueClientError(error) && error.status === undefined)
+        return true;
+    const { code, message } = error;
+    const classes = names(error);
+    return ((typeof code === "string" && NETWORK_CODES.has(code)) ||
+        classes.includes("APIConnectionError") ||
+        (classes.includes("TypeError") && message === "fetch failed"));
+}
+/** A retryable status a service answered with: on Hue's own clients, or on an error that also
+ * carries the exchange it came from (the OpenAI and Anthropic SDKs' `headers`, the AI SDK's
+ * `url` or `responseHeaders`, a fetch `response`), so an agent's own error that only names a
+ * status stays the agent's. */
+function refused(error) {
+    if (hueClientError(error))
+        return retryable(error.status);
+    const { status, statusCode, headers, response, url, responseHeaders } = error;
+    const exchanged = [headers, response, url, responseHeaders].some((item) => item !== undefined && item !== null);
+    // A fetch `Response` carries the status itself.
+    const answered = response !== null && typeof response === "object"
+        ? response
+        : {};
+    return (exchanged &&
+        (retryable(status) ||
+            retryable(statusCode) ||
+            retryable(answered.status) ||
+            retryable(answered.statusCode)));
+}
+/** A status Hue's own client answered with that is neither a success nor retryable, a 3xx or a
+ * 4xx: Hue refused the caller's key, project, environment version or world, so the case could
+ * not run as configured. The clients fetch with `redirect: "error"`, so a redirect reaches here
+ * only as a status some caller constructed; a real one surfaces without a status, as a failed
+ * connection. Only Hue's clients show it; another service's 4xx stays the agent's. */
+function rejected(error) {
+    const { status } = error;
+    return (hueClientError(error) &&
+        typeof status === "number" &&
+        status >= 300 &&
+        status < 500 &&
+        !retryable(status));
+}
+/** Whether any error shows the signal; one whose properties throw when read shows none. */
+const any = (errors, signal) => errors.some((error) => {
+    try {
+        return signal(error);
+    }
+    catch {
+        return false;
+    }
+});
+/** The service failure a target's throw shows, by the errors linked from it, in precedence
+ * order: a timeout, a failed connection, a retryable refusal, a status Hue's own client was
+ * refused with; null for the agent's own error. */
+export function serviceFailureType(error) {
+    const errors = linked(error);
+    if (any(errors, timedOut))
+        return "TimedOut";
+    if (any(errors, disconnected))
+        return "ConnectionFailed";
+    if (any(errors, refused))
+        return "ServiceRefused";
+    if (any(errors, rejected))
+        return "ConfigurationRejected";
+    return null;
+}

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

@@ -1,11 +1,11 @@
 import type { HueClient } from "../client.js";
-import type { EnvironmentClient } from "../environment/client.js";
+import { type EnvironmentClient } from "../environment/client.js";
 import type { EnvironmentTool } from "../environment/tools.js";
 import type { WorldHandoff } from "../environment/types.js";
 import type { ActualAgentManifestInputV2, AttemptConnectionBundleV2, RequestedAttemptProviderV2 } from "./attempt.js";
 import type { EvaluationClient } from "./client.js";
 import { type RunExperimentTargetContext, type RunnerReport, type TelemetryNotAccepted } from "./runner.js";
-import type { ExperimentCase, JsonValue, LocalAgentRegistration, LocalFile, LocalScorer, TargetResult } from "./types.js";
+import type { ExperimentCase, JsonValue, LocalAgentClaim, 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. */
@@ -58,6 +58,9 @@ export interface LocalAgentTargetContext {
     /** Private directory for this case, removed after it; return generated files with
      * `withFiles`. */
     outputDirectory: string;
+    /** Ends when the worker stops or the world's deadline passes; a target that listens stops
+     * its work, and one that does not is left behind when its case ends as a `TargetTimeout`. */
+    signal?: AbortSignal;
 }
 /** Candidate-visible context for one queued ordinary case run directly on this machine. */
 export interface LocalAgentDirectContext {
@@ -101,7 +104,7 @@ export interface RunLocalAgentOptions {
     concurrency?: number;
     /** What a case does when its telemetry is not accepted; see
      * `traceNotAccepted` of {@link runExperiment}. Defaults to `"stop"`. */
-    traceNotAccepted?: "stop" | "fail_case";
+    traceNotAccepted?: "stop" | "fail_case" | "pending";
     /** Called as each case is failed for its telemetry; see `onTelemetryNotAccepted` of
      * {@link runExperiment}. */
     onTelemetryNotAccepted?(entry: TelemetryNotAccepted): void | Promise<void>;
@@ -109,8 +112,27 @@ export interface RunLocalAgentOptions {
     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. */
+    /** Stop after this many runs settle: completed, or given up as `attention`. Useful for
+     * one-shot jobs and deterministic acceptance. Omit to keep polling. */
     maxRuns?: number;
+    /** How many times one run is resumed after a transient failure (a request Hue refused
+     * transiently past the client's own retries, a world seal not read back, a lost network,
+     * telemetry not accepted) before the worker gives it up as `attention`. Default 5, range
+     * 1–20. A failure that would recur (an uncertain target outcome, an unserializable output, a
+     * refusal Hue decided on, an input the SDK refuses) is attention at once. */
+    maxRunAttempts?: number;
+    /** The lifetime of each world the worker creates for a case, in seconds (1–86400); the
+     * server's default, an hour, applies when omitted. The target is stopped when the world
+     * expires: its case ends as a `TargetTimeout` error and the world is sealed abandoned. */
+    worldTtlSeconds?: number;
+    /** Called when a poll (registration or claim) fails transiently; the worker waits and polls
+     * again. A refusal it cannot recover from (a revoked key, a disabled agent) is thrown. */
+    onPollError?(error: unknown): void | Promise<void>;
+    /** Called when a claimed run's attempt fails: `retry` says the worker keeps the claim and
+     * resumes it after `waitMillis`; `attention` says the run was given up and needs a project
+     * member (requeue or cancel); `refused` says Hue no longer accepts this worker's outcome for
+     * the run (it was released or cancelled meanwhile). */
+    onRunFailed?(failure: LocalRunFailure): void | Promise<void>;
     /** Emit a one-time `DeprecationWarning` when the deployment serves a legacy world; on by default. */
     deprecationWarnings?: boolean;
     /** Opt into the experiment's immutable V2 provider profile. These three values are
@@ -151,6 +173,19 @@ export declare function registeredCapabilities(options: {
     /** The ordinary-case callback, when supplied. */
     directTarget?: unknown;
 }): string[];
+/** Why a claimed run's attempt ended without completing, and what the worker did about it. */
+export interface LocalRunFailure extends LocalAgentClaim {
+    /** What failed. */
+    error: unknown;
+    /** Failed attempts of this run in this process, this one included; 0 when not counted. */
+    attempt: number;
+    /** `retry`: the claim is kept and the run resumes after `waitMillis`. `attention`: the run
+     * was given up for a project member to requeue or cancel. `refused`: Hue no longer accepts
+     * this worker's outcome for the run, which was released or cancelled meanwhile. */
+    outcome: "retry" | "attention" | "refused";
+    /** The wait before the run resumes, for `retry`. */
+    waitMillis?: number;
+}
 /**
  * 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.