@hue-run/sdk 0.11.3 → 0.12.0

package/dist/environment/world.js

@@ -53,16 +53,25 @@ export function stripHueControlPlaneCredentials(parent) {
     }
     return child;
 }
+/** Variables a world or its server owns: a parent's value belongs to another world (a runner
+ * started inside a case, a shell left from an earlier run) or to the server (a signing key), and
+ * would send this world's token to a mirror this world does not have. The whole `HUE_WORLD_`
+ * prefix is the world's. */
+const WORLD_SCOPED = /^(?:HUE_WORLD_[A-Z0-9_]+|HUE_MCP_(?:CONFIG|URL|TOKEN|EXPIRES_AT)|HUE_SIM_[A-Z0-9_]+_(?:URL|ALIAS))$/;
+/** `environment` without any variable a world or its server owns. */
+export function withoutWorldVariables(environment) {
+    return Object.fromEntries(Object.entries(environment).filter(([name]) => !WORLD_SCOPED.test(name)));
+}
 /**
  * The environment for an agent child process running one case (the coordination briefs'
- * recommended policy): the parent's variables minus Hue control-plane credentials, then the
- * world's carriers, which win over anything the parent set. Nothing here is logged.
+ * recommended policy): the parent's variables minus Hue control-plane credentials and any
+ * world-scoped variable, then the world's carriers. Nothing here is logged.
  */
 export function agentEnvironment(world, options = {}) {
     const parent = options.parent ?? process.env;
-    const child = options.includeHueCredentials
+    const child = withoutWorldVariables(options.includeHueCredentials
         ? Object.fromEntries(Object.entries(parent).filter((entry) => entry[1] !== undefined))
-        : stripHueControlPlaneCredentials(parent);
+        : stripHueControlPlaneCredentials(parent));
     Object.assign(child, world.env);
     if (options.legacyMcpVariables ?? true) {
         const legacy = legacyMcpCapability(world);

package/dist/evals/client.d.ts

@@ -9,6 +9,10 @@ export interface EvaluationClientOptions {
     baseUrl?: string;
     /** Per-request budget in milliseconds, 100–60000. Default 10000. */
     timeoutMillis?: number;
+    /** Bounded attempts for a read or a mutation the server deduplicates by its key, after a
+     * connection failure, a timeout or a 408 or 5xx Hue did not time with `Retry-After`. Default 4,
+     * maximum 10; 1 sends every such request once. */
+    maxAttempts?: number;
 }
 /** Thrown for a failed evaluation API request; the message is fixed and never includes response text. */
 export declare class HueApiError extends Error {
@@ -16,12 +20,22 @@ export declare class HueApiError extends Error {
     readonly status?: number | undefined;
     /** Seconds Hue asked the caller to wait (`Retry-After` on a 429 or 503), when it said. */
     readonly retryAfterSeconds?: number | undefined;
+    /** Hue's `X-Hue-Diagnostic` code, which tells refusals of one status apart, when it sent one. */
+    readonly diagnostic?: string | undefined;
     constructor(
     /** HTTP status when Hue answered; absent for network, timeout and parsing failures. */
     status?: number | undefined, 
     /** Seconds Hue asked the caller to wait (`Retry-After` on a 429 or 503), when it said. */
-    retryAfterSeconds?: number | undefined);
+    retryAfterSeconds?: number | undefined, 
+    /** Hue's `X-Hue-Diagnostic` code, which tells refusals of one status apart, when it sent one. */
+    diagnostic?: string | undefined);
 }
+/**
+ * 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 declare function isTransientApiError(error: unknown): boolean;
 /** An artifact download that ran past the size its caller expected; the rest is not read. */
 export declare class ArtifactSizeError extends Error {
     /** The size the caller expected, in bytes. */
@@ -32,22 +46,28 @@ export declare class ArtifactSizeError extends Error {
 }
 /**
  * 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 declare class EvaluationClient {
     /** Validated Hue origin. */
     readonly baseUrl: string;
     private readonly apiKey;
     private readonly timeoutMillis;
+    private readonly maxAttempts;
     constructor(options: EvaluationClientOptions);
     /** 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
      * each attempt, and a wait to send one again, whose refusal is then the caller's error. */
     private send;
     private request;
+    private requestOnce;
     /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size.
      * With `maxBytes`, the download stops one byte past it and throws `ArtifactSizeError`. */
     downloadArtifact(id: string, options?: {

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/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 {
@@ -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.