@helmr/sdk 0.1.1-rc.6 → 0.1.1-rc.8

package/README.md

@@ -13,9 +13,9 @@ Keep this layer stable and ergonomic. Runtime adapter internals, VM details, and
 
 Payload is audit data: Helmr persists it in plaintext in the `run.created` event, DB, and events stream. Do not put secret values (tokens, API keys, credentials, or PII) in payload; use `secrets:` instead. Use payload for business context such as PR numbers, repo names, ticket ids, and other identifiers.
 
-Remote API/CLI run secret bindings are vault references, not host-local sources. Use
-`vault:SECRET_NAME` in `POST /api/runs` `secrets` and `helmr run --secret NAME=vault:SECRET_NAME`.
-Schemes such as `env:` and `file:` are local runner sources and are rejected for remote runs.
+Task code declares required secret names and runtime placements. Store each value
+with `helmr secret set NAME`; run creation does not accept secret values or
+binding maps.
 
 ## TypeScript Runtime Client
 
@@ -37,7 +37,7 @@ const handle = await client.tasks.trigger<typeof impl>(
 
 const current = await client.runs.retrieve(handle)
 const pendingWaitpoint = current.pendingWaitpoint
-if (pendingWaitpoint !== null && pendingWaitpoint.kind === "manual") {
+if (pendingWaitpoint !== null && pendingWaitpoint.kind === "human") {
   await client.waitpoints.respond(pendingWaitpoint, {
     value: { approved: true },
   })
@@ -69,10 +69,6 @@ await client.waitpoints.respond("waitpoint-456", {
 
 ### `POST /api/runs`
 
-`payload` is a JSON field for tasks that accept payload. Payload is audit data: Helmr persists it in plaintext in the `run.created` event, DB, and events stream. Do not put secret values (tokens, API keys, credentials, or PII) in payload; use `secrets:` instead. Use payload for business context such as PR numbers, repo names, ticket ids, and other identifiers.
+`payload` is a JSON field for tasks that accept payload. Payload is audit data: Helmr persists it in plaintext in the `run.created` event, DB, and events stream. Do not put secret values (tokens, API keys, credentials, or PII) in payload; declare task secrets instead. Use payload for business context such as PR numbers, repo names, ticket ids, and other identifiers.
 
-`secrets` maps declared task secret names to vault URIs:
-
-```json
-{ "OPENAI_API_KEY": "vault:openai-api-key" }
-```
+Runs do not accept a `secrets` field. Secret names and placements are part of the deployed task definition.

package/dist/compile.js

@@ -14,6 +14,7 @@ import {
   FromSchema,
   ImageSpecSchema,
   ImageStepSchema,
+  NetworkPolicySchema,
   PlacementSchema as BundlePlacementSchema,
   PlatformSchema,
   QueueSpecSchema,
@@ -68,12 +69,8 @@ function validateSecretName(name, label = "secret name") {
   if (name.length > 128) {
     throw new Error(`${label} must be at most 128 characters`);
   }
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-    throw new Error(`${label} must match /^[A-Za-z_][A-Za-z0-9_]*$/`);
-  }
-  const upper = name.toUpperCase();
-  if (upper === "CON" || upper === "PRN" || upper === "AUX" || upper === "NUL" || /^COM[1-9]$/.test(upper) || /^LPT[1-9]$/.test(upper)) {
-    throw new Error(`${label} is reserved`);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(name)) {
+    throw new Error(`${label} must match /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/`);
   }
 }
 var taskBrand = Symbol.for("helmr.sdk.Task");
@@ -116,6 +113,7 @@ function compile(opts) {
   const subImages = compiler.compileSubImages(imageSpec);
   const workspace = compiler.compileWorkspace(task.sandbox);
   const resources = task.sandbox.resourceSpec;
+  const network = task.sandbox.networkSpec;
   const maxDurationSeconds = readOptionalMaxDurationSeconds(task.maxDuration, `task "${task.id}" maxDuration`);
   const sandboxSpec = create(SandboxSpecSchema, {
     id: task.sandbox.id,
@@ -126,7 +124,8 @@ function compile(opts) {
         ...resources.memory === undefined ? {} : { memory: resources.memory },
         ...resources.disk === undefined ? {} : { disk: resources.disk }
       })
-    } : {}
+    } : {},
+    ...network ? { network: compileNetwork(network) } : {}
   });
   return create(BundleSchema, {
     image: imageSpec,
@@ -143,6 +142,7 @@ function compile(opts) {
         ...task.queue?.concurrencyLimit === undefined || task.queue.concurrencyLimit === null ? {} : { concurrencyLimit: task.queue.concurrencyLimit }
       }),
       ...task.ttl === undefined ? {} : { ttl: task.ttl },
+      retryPolicyJson: JSON.stringify(task.retry ?? false),
       schedules: compileTaskSchedules(task.schedule),
       secrets: Object.entries(readSecretDecls(task.secrets)).map(([name, placement]) => create(BundleSecretPlacementSchema, {
         name,
@@ -151,6 +151,13 @@ function compile(opts) {
     })
   });
 }
+function compileNetwork(network) {
+  return create(NetworkPolicySchema, {
+    internet: network.internet,
+    allow: [...network.allow],
+    deny: [...network.deny]
+  });
+}
 function compileTaskSchedules(schedule) {
   if (schedule === undefined) {
     return [];
@@ -159,8 +166,7 @@ function compileTaskSchedules(schedule) {
     create(TaskScheduleSpecSchema, {
       id: "",
       cron: schedule.cron,
-      timezone: schedule.timezone ?? "UTC",
-      secretBindings: { ...schedule.secretBindings }
+      timezone: schedule.timezone ?? "UTC"
     })
   ];
 }
@@ -426,14 +432,27 @@ function readSecretDecls(value) {
   if (value === undefined) {
     return {};
   }
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error("task secrets must be an object literal");
+  if (!Array.isArray(value)) {
+    throw new Error("task secrets must be an array");
   }
-  const record = value;
-  return Object.fromEntries(Object.entries(record).map(([name, placement]) => {
-    validateSecretName(name, `task secrets.${name}`);
-    return [name, readPlacement(placement, `task secrets.${name}`)];
-  }));
+  const output = {};
+  value.forEach((item, index) => {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`task secrets.${index} must be a secret object`);
+    }
+    const record = item;
+    const name = record["name"];
+    if (typeof name !== "string") {
+      throw new Error(`task secrets.${index}.name must be a string`);
+    }
+    validateSecretName(name, `task secrets.${index}.name`);
+    if (Object.hasOwn(output, name)) {
+      throw new Error(`task secrets contains duplicate secret ${JSON.stringify(name)}`);
+    }
+    const { name: _name, ...placement } = record;
+    output[name] = readPlacement(placement, `task secrets.${index}`);
+  });
+  return output;
 }
 function readPlacement(value, label) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -445,6 +464,7 @@ function readPlacement(value, label) {
     if (Object.keys(record).length !== 1 || !isNonEmptyPlacementString(env)) {
       throw new Error(`${label} must be { env: string }`);
     }
+    validateEnvPlacementName(env, `${label}.env`);
     return { env };
   }
   if ("file" in record) {
@@ -508,6 +528,11 @@ function validatePlacementMode(mode, label) {
     throw new Error(`${label} must only contain permission bits`);
   }
 }
+function validateEnvPlacementName(value, label) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`${label} must match /^[A-Za-z_][A-Za-z0-9_]*$/`);
+  }
+}
 function validatePlacementPath(path, label) {
   const normalized = path.trim().replaceAll("\\", "/");
   if (path !== path.trim()) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConcurrentWaitError, validateSecretName, type CacheBuilder, type CacheMount, type CacheMountBinding, type EmitContent, type EmitEvent, type ImageBuilder, type ImageRunOptions, type NoPayload, type Placement, type SandboxBuilder, type SecretDecls, type SecretMountBinding, type SourceCapabilities, type SourceDirRef, type SourceDirectoryOptions, type SourceFileRef, type TaskContext, type TaskWorkspace, type TaskOutput, type TaskPayload, type TaskTriggerPayload, type WaitCapabilities, type WaitForInput, type WaitJson, type WaitOptions, type WaitResolution, type WaitManualOptions, type WaitUntilInput } from "./internal.js";
+import { ConcurrentWaitError, validateSecretName, type CacheBuilder, type CacheMount, type CacheMountBinding, type EmitContent, type EmitEvent, type ImageBuilder, type ImageRunOptions, type NoPayload, type Placement, type SandboxBuilder, type SandboxNetwork, type SecretDecls, type SecretMountBinding, type SourceCapabilities, type SourceDirRef, type SourceDirectoryOptions, type SourceFileRef, type TaskContext, type TaskWorkspace, type TaskOutput, type TaskPayload, type TaskTriggerPayload, type WaitCapabilities, type WaitForInput, type WaitJson, type WaitOptions, type WaitResolution, type WaitHumanOptions, type WaitUntilInput } from "./internal.js";
 import { PayloadSchemaValidationError } from "./schema/payload.js";
 import { idempotencyKeys } from "./idempotency.js";
 export type { IdempotencyKey, IdempotencyKeyCreateOptions, IdempotencyKeyInput, IdempotencyKeyScope } from "./idempotency.js";
@@ -12,9 +12,9 @@ import { task as scheduledTask, type ScheduleCron, type ScheduledTaskConfig, typ
 import { tasks } from "./trigger.js";
 export { AuthError, RunNotFoundError, TimeoutError, UnsupportedTransportError } from "./runtime/errors.js";
 export { ConcurrentWaitError, PayloadSchemaValidationError };
-export { type LogSnapshot, type ListRunEventsOptions, type ListRunsOptions, type PendingDelayWaitpoint, type PendingManualWaitpoint, type PendingWaitpoint, type RetrieveRunOptions, type RunEvent, type RunEventRecord, type RunEventRecordPage, type RunHandle, type RunSnapshot, type RunStatus, type RunSummary, type RunWaitOptions, type SubscribeRunEventsOptions, type WaitpointRespondOptions, type WaitpointRef, } from "./runtime/run.js";
+export { type LogSnapshot, type ListRunEventsOptions, type ListRunsOptions, type PendingDelayWaitpoint, type PendingHumanWaitpoint, type PendingWaitpoint, type RetrieveRunOptions, type RunEvent, type RunEventRecord, type RunEventRecordPage, type RunHandle, type RunSnapshot, type RunStatus, type RunSummary, type RunWaitOptions, type SubscribeRunEventsOptions, type WaitpointRespondOptions, type WaitpointRef, } from "./runtime/run.js";
 export { defineConfig, idempotencyKeys, queue, sandbox, task, tasks };
-export type { HelmrConfig, HelmrConfigInput, Placement, SecretDecls, Task, TaskConfig, TaskQueueConfig, TaskOutput, TaskPayload, TaskTriggerPayload, WaitCapabilities, WaitForInput, WaitJson, WaitOptions, WaitResolution, WaitManualOptions, WaitUntilInput, PayloadSchema, StandardSchemaV1, NoPayload, };
+export type { HelmrConfig, HelmrConfigInput, Placement, SandboxNetwork, SecretDecls, Task, TaskConfig, TaskQueueConfig, TaskOutput, TaskPayload, TaskTriggerPayload, WaitCapabilities, WaitForInput, WaitJson, WaitOptions, WaitResolution, WaitHumanOptions, WaitUntilInput, PayloadSchema, StandardSchemaV1, NoPayload, };
 export declare const image: (id: string) => ImageBuilder;
 export declare const cache: (id: string) => CacheBuilder;
 export declare const source: SourceCapabilities;
@@ -23,6 +23,8 @@ export { validateSecretName };
 export declare const runs: {
     retrieve: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./index.js").RetrieveRunOptions) => Promise<import("./index.js").RunSnapshot<TOutput>>;
     wait: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./index.js").RunWaitOptions) => Promise<import("./index.js").RunSnapshot<TOutput>>;
+    cancel: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./runtime/run.js").CancelRunOptions) => Promise<import("./index.js").RunSnapshot<TOutput>>;
+    replay: <TPayload = unknown, TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: import("./runtime/run.js").ReplayRunOptions<TPayload>) => Promise<import("./index.js").RunHandle<TOutput>>;
     list: (opts?: import("./index.js").ListRunsOptions) => Promise<import("./index.js").RunSummary[]>;
     logs: {
         retrieve: <TOutput = unknown>(idOrHandle: string | import("./index.js").RunHandle<TOutput>, opts?: {

package/dist/index.js

@@ -212,12 +212,8 @@ function validateSecretName(name, label = "secret name") {
   if (name.length > 128) {
     throw new Error(`${label} must be at most 128 characters`);
   }
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-    throw new Error(`${label} must match /^[A-Za-z_][A-Za-z0-9_]*$/`);
-  }
-  const upper = name.toUpperCase();
-  if (upper === "CON" || upper === "PRN" || upper === "AUX" || upper === "NUL" || /^COM[1-9]$/.test(upper) || /^LPT[1-9]$/.test(upper)) {
-    throw new Error(`${label} is reserved`);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(name)) {
+    throw new Error(`${label} must match /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/`);
   }
 }
 function validateImageBuildSecretRef(name) {
@@ -283,6 +279,7 @@ function markTaskInternal(config, schedule) {
   validateTaskQueue(config.id, config.queue);
   validateTaskSchedule(config.id, schedule);
   validateOptionalTTL(config.ttl, `task ${JSON.stringify(config.id)} ttl`);
+  validateRetryPolicy(config.retry, `task ${JSON.stringify(config.id)} retry`);
   assertPayloadSchema(config.payload, `task ${JSON.stringify(config.id)} payload`);
   if (schedule !== undefined) {
     Object.defineProperty(config, "schedule", {
@@ -294,6 +291,54 @@ function markTaskInternal(config, schedule) {
   Object.defineProperty(config, taskOriginBrand, { value: captureTaskOrigin() });
   return config;
 }
+function validateRetryPolicy(value, label = "retry") {
+  if (value === undefined || value === false) {
+    return;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be false or a retry policy object`);
+  }
+  const record = value;
+  for (const key of Object.keys(record)) {
+    if (key !== "maxAttempts" && key !== "backoff") {
+      throw new Error(`${label}.${key} is not supported`);
+    }
+  }
+  if (typeof record["maxAttempts"] !== "number" || !Number.isInteger(record["maxAttempts"]) || record["maxAttempts"] < 1 || record["maxAttempts"] > 10) {
+    throw new Error(`${label}.maxAttempts must be an integer between 1 and 10`);
+  }
+  const backoff = record["backoff"];
+  if (backoff !== undefined) {
+    if (backoff === null || typeof backoff !== "object" || Array.isArray(backoff)) {
+      throw new Error(`${label}.backoff must be an object`);
+    }
+    const backoffRecord = backoff;
+    for (const key of Object.keys(backoffRecord)) {
+      if (key !== "minMs" && key !== "maxMs" && key !== "factor" && key !== "jitter") {
+        throw new Error(`${label}.backoff.${key} is not supported`);
+      }
+    }
+    validateOptionalPositiveInteger(backoffRecord["minMs"], `${label}.backoff.minMs`);
+    validateOptionalPositiveInteger(backoffRecord["maxMs"], `${label}.backoff.maxMs`);
+    const factor = backoffRecord["factor"];
+    if (factor !== undefined && (typeof factor !== "number" || !Number.isFinite(factor) || factor <= 0)) {
+      throw new Error(`${label}.backoff.factor must be a positive number`);
+    }
+    const jitter = backoffRecord["jitter"];
+    if (jitter !== undefined && jitter !== "none" && jitter !== "full") {
+      throw new Error(`${label}.backoff.jitter must be "none" or "full"`);
+    }
+  }
+}
+function validateOptionalPositiveInteger(value, label) {
+  if (value === undefined) {
+    return;
+  }
+  if (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value > 0) {
+    return;
+  }
+  throw new Error(`${label} must be a positive integer`);
+}
 function validateTaskSchedule(taskId, value) {
   if (value === undefined) {
     return;
@@ -304,17 +349,6 @@ function validateTaskSchedule(taskId, value) {
   if (value.timezone !== undefined && value.timezone.trim() === "") {
     throw new Error(`task ${JSON.stringify(taskId)} schedule timezone must not be empty`);
   }
-  if (value.secretBindings !== undefined) {
-    if (value.secretBindings === null || typeof value.secretBindings !== "object" || Array.isArray(value.secretBindings)) {
-      throw new Error(`task ${JSON.stringify(taskId)} schedule secretBindings must be an object`);
-    }
-    for (const [name, binding] of Object.entries(value.secretBindings)) {
-      validateSecretName(name, `task ${JSON.stringify(taskId)} schedule secretBindings.${name}`);
-      if (typeof binding !== "string" || binding.trim() === "") {
-        throw new Error(`task ${JSON.stringify(taskId)} schedule secretBindings.${name} must be a non-empty string`);
-      }
-    }
-  }
 }
 function validateTaskQueue(taskId, value) {
   if (value === undefined) {
@@ -479,21 +513,23 @@ class SandboxBuilderImpl {
   imageBuilder;
   workspaceBinding;
   resourceSpec;
-  constructor(id, imageBuilder, workspaceBinding, resourceSpec) {
+  networkSpec;
+  constructor(id, imageBuilder, workspaceBinding, resourceSpec, networkSpec) {
     Object.defineProperty(this, sandboxBuilderBrand, { value: true });
     this.id = id;
     this.imageBuilder = imageBuilder;
     this.workspaceBinding = workspaceBinding;
     this.resourceSpec = resourceSpec;
+    this.networkSpec = networkSpec;
   }
   image(img) {
     if (!isImageBuilder(img)) {
       throw new Error("sandbox.image() requires an ImageBuilder created by image()");
     }
-    return new SandboxBuilderImpl(this.id, img, this.workspaceBinding, this.resourceSpec);
+    return new SandboxBuilderImpl(this.id, img, this.workspaceBinding, this.resourceSpec, this.networkSpec);
   }
   workspace(mountPath = "/workspace") {
-    return new SandboxBuilderImpl(this.id, this.imageBuilder, { mountPath: normalizeWorkspaceMountPath(mountPath) }, this.resourceSpec);
+    return new SandboxBuilderImpl(this.id, this.imageBuilder, { mountPath: normalizeWorkspaceMountPath(mountPath) }, this.resourceSpec, this.networkSpec);
   }
   resources(opts) {
     const resourceSpec = {
@@ -501,9 +537,38 @@ class SandboxBuilderImpl {
       ...opts.memory === undefined ? {} : { memory: opts.memory },
       ...opts.disk === undefined ? {} : { disk: opts.disk }
     };
-    return new SandboxBuilderImpl(this.id, this.imageBuilder, this.workspaceBinding, resourceSpec);
+    return new SandboxBuilderImpl(this.id, this.imageBuilder, this.workspaceBinding, resourceSpec, this.networkSpec);
+  }
+  network(opts) {
+    return new SandboxBuilderImpl(this.id, this.imageBuilder, this.workspaceBinding, this.resourceSpec, normalizeSandboxNetwork(opts));
   }
 }
+function normalizeSandboxNetwork(opts) {
+  const value = opts.internet;
+  if (value === undefined || value === true) {
+    return { internet: true, allow: [], deny: [] };
+  }
+  if (value === false) {
+    return { internet: false, allow: [], deny: [] };
+  }
+  return {
+    internet: true,
+    allow: normalizeNetworkEntries(value.allow, "network.internet.allow"),
+    deny: normalizeNetworkEntries(value.deny, "network.internet.deny")
+  };
+}
+function normalizeNetworkEntries(entries, label) {
+  if (entries === undefined) {
+    return [];
+  }
+  return entries.map((entry, index) => {
+    const normalized = entry.trim();
+    if (normalized === "") {
+      throw new Error(`${label}[${index}] must not be empty`);
+    }
+    return normalized;
+  });
+}
 
 class SourceFileRefImpl {
   path;
@@ -609,6 +674,13 @@ class UnsupportedTransportError extends Error {
   }
 }
 
+// sdk/typescript/src/version.ts
+var HELMR_API_VERSION = "2026-06-06";
+var HELMR_API_VERSION_HEADER = "Helmr-API-Version";
+var HELMR_SDK_VERSION_HEADER = "Helmr-SDK-Version";
+var SOURCE_PACKAGE_VERSION = "0.1.0";
+var HELMR_SDK_VERSION = "0.1.1-rc.8".trim() !== "" ? "0.1.1-rc.8" : SOURCE_PACKAGE_VERSION;
+
 // sdk/typescript/src/runtime/run.ts
 function runHandle(id, taskId) {
   return { id, taskId };
@@ -623,6 +695,12 @@ function runSnapshot(snapshot) {
     createdAt: snapshot.createdAt ?? null,
     updatedAt: snapshot.updatedAt ?? null,
     pendingWaitpoint: snapshot.pendingWaitpoint ?? null,
+    ...snapshot.version === undefined && snapshot.deploymentVersion === undefined ? {} : { version: snapshot.version ?? snapshot.deploymentVersion ?? null },
+    ...snapshot.deploymentVersion === undefined && snapshot.version === undefined ? {} : { deploymentVersion: snapshot.deploymentVersion ?? snapshot.version ?? null },
+    ...snapshot.apiVersion === undefined ? {} : { apiVersion: snapshot.apiVersion },
+    ...snapshot.sdkVersion === undefined ? {} : { sdkVersion: snapshot.sdkVersion },
+    ...snapshot.cliVersion === undefined ? {} : { cliVersion: snapshot.cliVersion },
+    attemptNumber: snapshot.attemptNumber ?? null,
     ...runStateBooleans(status),
     ...snapshot.output === undefined ? {} : { output: snapshot.output }
   };
@@ -733,6 +811,7 @@ class HelmrClient {
     return await this.#triggerRun(task.id, payload, opts, readOptionalMaxDurationSeconds(task.maxDuration));
   }
   async#triggerRun(taskId, payload, opts, maxDurationSeconds) {
+    validateRetryPolicy(opts.retry, "retry");
     const runOptions = {
       ...opts.deploymentId === undefined ? {} : { deployment_id: opts.deploymentId },
       ...opts.version === undefined ? {} : { version: opts.version },
@@ -740,6 +819,9 @@ class HelmrClient {
       ...opts.concurrencyKey === undefined ? {} : { concurrency_key: opts.concurrencyKey },
       ...opts.priority === undefined ? {} : { priority: opts.priority },
       ...opts.ttl === undefined ? {} : { ttl: opts.ttl },
+      ...opts.retry === undefined ? {} : { retry: opts.retry },
+      ...opts.metadata === undefined ? {} : { metadata: opts.metadata },
+      ...opts.tags === undefined ? {} : { tags: opts.tags },
       ...maxDurationSeconds === undefined ? {} : { max_duration_seconds: maxDurationSeconds },
       ...runIdempotencyRequestFields(opts.idempotencyKey, opts.idempotencyKeyTTL)
     };
@@ -747,7 +829,6 @@ class HelmrClient {
       method: "POST",
       body: JSON.stringify({
         task_id: taskId,
-        secrets: opts.secrets ?? {},
         ...payload === undefined ? {} : { payload },
         ...Object.keys(runOptions).length === 0 ? {} : { options: runOptions }
       }),
@@ -783,6 +864,24 @@ class HelmrClient {
         wait.cleanup();
       }
     },
+    cancel: async (idOrHandle, opts = {}) => {
+      const response = await this.#json(`/api/runs/${encodeURIComponent(runId(idOrHandle))}/cancel`, {
+        method: "POST",
+        body: JSON.stringify(cancelRunBody(opts)),
+        headers: { "content-type": "application/json" },
+        ...requestSignal(opts.signal)
+      });
+      return runResponseToSnapshot(response.run);
+    },
+    replay: async (idOrHandle, opts = {}) => {
+      const response = await this.#json(`/api/runs/${encodeURIComponent(runId(idOrHandle))}/replay`, {
+        method: "POST",
+        body: JSON.stringify(replayRunBody(opts)),
+        headers: { "content-type": "application/json" },
+        ...requestSignal(opts.signal)
+      });
+      return runHandle(response.run.id, response.run.task_id);
+    },
     list: async (opts = {}) => {
       const query = new URLSearchParams;
       if (opts.status !== undefined)
@@ -948,6 +1047,8 @@ class HelmrClient {
   }
   async#fetch(path, init = {}) {
     const headers = new Headers(init.headers);
+    headers.set(HELMR_API_VERSION_HEADER, HELMR_API_VERSION);
+    headers.set(HELMR_SDK_VERSION_HEADER, HELMR_SDK_VERSION);
     if (this.#apiKey !== undefined) {
       headers.set("authorization", `Bearer ${this.#apiKey}`);
     }
@@ -1001,6 +1102,12 @@ function runResponseToSnapshot(response) {
   return runSnapshot({
     id: response.id,
     taskId: response.task_id,
+    ...response.version === undefined && response.deployment_version === undefined ? {} : { version: response.version ?? response.deployment_version ?? null },
+    ...response.deployment_version === undefined && response.version === undefined ? {} : { deploymentVersion: response.deployment_version ?? response.version ?? null },
+    ...response.api_version === undefined ? {} : { apiVersion: response.api_version },
+    ...response.sdk_version === undefined ? {} : { sdkVersion: response.sdk_version },
+    ...response.cli_version === undefined ? {} : { cliVersion: response.cli_version },
+    attemptNumber: response.attempt_number ?? null,
     status: response.status,
     exitCode: response.exit_code ?? null,
     ...response.created_at === undefined ? {} : { createdAt: response.created_at },
@@ -1009,6 +1116,23 @@ function runResponseToSnapshot(response) {
     ..."output" in response ? { output: response.output } : {}
   });
 }
+function cancelRunBody(opts) {
+  return {
+    ...opts.reason === undefined ? {} : { reason: opts.reason },
+    ...opts.force === undefined ? {} : { force: opts.force },
+    ...opts.idempotencyKey === undefined ? {} : { idempotency_key: opts.idempotencyKey }
+  };
+}
+function replayRunBody(opts) {
+  return {
+    ...opts.version === undefined ? {} : { version: opts.version },
+    ...opts.payload === undefined ? {} : { payload: opts.payload },
+    ...opts.reason === undefined ? {} : { reason: opts.reason },
+    ...opts.idempotencyKey === undefined ? {} : { idempotency_key: opts.idempotencyKey },
+    ...opts.metadata === undefined ? {} : { metadata: opts.metadata },
+    ...opts.tags === undefined ? {} : { tags: opts.tags }
+  };
+}
 function scheduleCreateBody(opts) {
   return {
     ..."deduplicationKey" in opts && opts.deduplicationKey !== undefined ? { deduplication_key: opts.deduplicationKey } : {},
@@ -1019,7 +1143,6 @@ function scheduleCreateBody(opts) {
     cron: opts.cron,
     ...opts.timezone === undefined ? {} : { timezone: opts.timezone },
     ...opts.active === undefined ? {} : { active: opts.active },
-    ...opts.secretBindings === undefined ? {} : { secret_bindings: opts.secretBindings },
     ...opts.options === undefined ? {} : { options: runOptionsBody(opts.options) }
   };
 }
@@ -1468,11 +1591,10 @@ function queue(config) {
 
 // sdk/typescript/src/schedules.ts
 function task2(config) {
-  const { cron, secretBindings, ...taskConfig } = config;
+  const { cron, ...taskConfig } = config;
   const schedule = cron === undefined ? undefined : {
     cron: typeof cron === "string" ? cron : cron.pattern,
-    ...typeof cron === "string" || cron.timezone === undefined ? {} : { timezone: cron.timezone },
-    ...secretBindings === undefined ? {} : { secretBindings }
+    ...typeof cron === "string" || cron.timezone === undefined ? {} : { timezone: cron.timezone }
   };
   const marked = markScheduledTask({ ...taskConfig, payload: scheduledTaskPayloadSchema }, schedule);
   Object.defineProperty(marked, "trigger", {

package/dist/internal.d.ts

@@ -40,7 +40,7 @@ export interface WaitOptions {
     readonly policy?: string;
     readonly displayText?: string;
 }
-export interface WaitManualOptions<TSchema extends PayloadSchema<any, any> = PayloadSchema<any, any>> extends WaitOptions {
+export interface WaitHumanOptions<TSchema extends PayloadSchema<any, any> = PayloadSchema<any, any>> extends WaitOptions {
     readonly schema?: TSchema;
 }
 export interface WaitResolution<TPayload = unknown> {
@@ -62,8 +62,8 @@ export type WaitUntilInput = string | Date | {
 export interface WaitCapabilities {
     for(input: WaitForInput, opts?: Omit<WaitOptions, "timeout" | "policy">): Promise<void>;
     until(input: WaitUntilInput, opts?: Omit<WaitOptions, "timeout" | "policy">): Promise<void>;
-    manual<TSchema extends PayloadSchema<any, any>>(opts: WaitManualOptions<TSchema>): Promise<PayloadSchemaOutput<TSchema>>;
-    manual<TPayload = unknown>(opts?: WaitManualOptions): Promise<TPayload>;
+    human<TSchema extends PayloadSchema<any, any>>(opts: WaitHumanOptions<TSchema>): Promise<PayloadSchemaOutput<TSchema>>;
+    human<TPayload = unknown>(opts?: WaitHumanOptions): Promise<TPayload>;
 }
 export declare class ConcurrentWaitError extends Error {
     constructor(message: string);
@@ -80,7 +80,20 @@ export type Placement = {
     readonly mode?: string;
     readonly owner?: string;
 };
-export type SecretDecls = Record<string, Placement>;
+export type SecretDecl = ({
+    readonly env: string;
+} | {
+    readonly file: string;
+    readonly mode?: string;
+    readonly owner?: string;
+} | {
+    readonly dir: string;
+    readonly mode?: string;
+    readonly owner?: string;
+}) & {
+    readonly name: string;
+};
+export type SecretDecls = readonly SecretDecl[];
 export declare function validateSecretName(name: string, label?: string): void;
 export interface TaskContext {
     readonly wait: WaitCapabilities;
@@ -93,6 +106,11 @@ export interface TaskContext {
     readonly signal: AbortSignal;
     readonly run: {
         readonly id: string;
+        readonly attemptId?: string;
+        readonly attemptNumber?: number;
+        readonly sessionId?: string;
+        readonly snapshotVersion?: number;
+        readonly replayedFromRunId?: string;
     };
     readonly task: {
         readonly id: string;
@@ -127,12 +145,13 @@ declare const noPayloadBrand: unique symbol;
 export interface NoPayload {
     readonly [noPayloadBrand]: "NoPayload";
 }
-export interface TaskConfigBase<TSecrets extends SecretDecls = Record<never, never>> {
+export interface TaskConfigBase<TSecrets extends SecretDecls = readonly []> {
     readonly id: string;
     readonly sandbox: SandboxBuilder;
     readonly maxDuration?: number;
     readonly queue?: TaskQueueConfig;
     readonly ttl?: string;
+    readonly retry?: RetryPolicy;
     readonly secrets?: TSecrets;
 }
 export interface TaskQueueConfig {
@@ -142,7 +161,6 @@ export interface TaskQueueConfig {
 export interface InternalTaskScheduleConfig {
     readonly cron: string;
     readonly timezone?: string;
-    readonly secretBindings?: Record<string, string>;
 }
 export type TaskRunOptions<TSecrets extends SecretDecls> = {
     readonly deploymentId?: string;
@@ -151,26 +169,32 @@ export type TaskRunOptions<TSecrets extends SecretDecls> = {
     readonly concurrencyKey?: string;
     readonly priority?: number;
     readonly ttl?: string;
+    readonly retry?: RetryPolicy;
+    readonly metadata?: Record<string, unknown>;
+    readonly tags?: readonly string[];
     readonly idempotencyKey?: IdempotencyKeyInput;
     readonly idempotencyKeyTTL?: string;
-} & ([keyof TSecrets] extends [never] ? {
-    readonly secrets?: Record<never, never>;
-} : {
-    readonly secrets: {
-        readonly [K in keyof TSecrets]: string;
+};
+export type RetryPolicy = false | {
+    readonly maxAttempts: number;
+    readonly backoff?: {
+        readonly minMs?: number;
+        readonly maxMs?: number;
+        readonly factor?: number;
+        readonly jitter?: "none" | "full";
     };
-});
+};
 export type TaskDirectTrigger<TPayloadInput, TOutput, TSecrets extends SecretDecls> = [TPayloadInput] extends [NoPayload] ? (opts: TaskRunOptions<TSecrets>) => Promise<RunHandle<Awaited<TOutput>>> : (payload: TPayloadInput, opts: TaskRunOptions<TSecrets>) => Promise<RunHandle<Awaited<TOutput>>>;
-export type TaskConfigWithPayload<TPayloadSchema extends PayloadSchema<any, any>, TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>> = TaskConfigBase<TSecrets> & {
+export type TaskConfigWithPayload<TPayloadSchema extends PayloadSchema<any, any>, TOutput = unknown, TSecrets extends SecretDecls = readonly []> = TaskConfigBase<TSecrets> & {
     readonly payload: TPayloadSchema;
     readonly run: (payload: PayloadSchemaOutput<TPayloadSchema>, ctx: TaskContext) => MaybePromise<TOutput>;
 };
-export type TaskConfigWithoutPayload<TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>> = TaskConfigBase<TSecrets> & {
+export type TaskConfigWithoutPayload<TOutput = unknown, TSecrets extends SecretDecls = readonly []> = TaskConfigBase<TSecrets> & {
     readonly payload?: undefined;
     readonly run: (ctx: TaskContext) => MaybePromise<TOutput>;
 };
-export type TaskConfig<TPayload = NoPayload, TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>, TPayloadSchema extends PayloadSchema<any, any> | undefined = undefined> = TPayloadSchema extends PayloadSchema<any, any> ? TaskConfigWithPayload<TPayloadSchema, TOutput, TSecrets> : TaskConfigWithoutPayload<TOutput, TSecrets>;
-export type Task<TPayload = NoPayload, TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>, TPayloadInput = TPayload> = TaskConfigBase<TSecrets> & {
+export type TaskConfig<TPayload = NoPayload, TOutput = unknown, TSecrets extends SecretDecls = readonly [], TPayloadSchema extends PayloadSchema<any, any> | undefined = undefined> = TPayloadSchema extends PayloadSchema<any, any> ? TaskConfigWithPayload<TPayloadSchema, TOutput, TSecrets> : TaskConfigWithoutPayload<TOutput, TSecrets>;
+export type Task<TPayload = NoPayload, TOutput = unknown, TSecrets extends SecretDecls = readonly [], TPayloadInput = TPayload> = TaskConfigBase<TSecrets> & {
     readonly "~types"?: {
         readonly payloadInput: TPayloadInput;
         readonly payload: TPayload;
@@ -238,6 +262,7 @@ export interface SandboxBuilder {
         readonly memory?: string;
         readonly disk?: string;
     }): SandboxBuilder;
+    network(opts: SandboxNetwork): SandboxBuilder;
 }
 export type ImageBuildStep = {
     readonly kind: "from";
@@ -275,9 +300,21 @@ export interface SandboxResources {
     readonly memory?: string;
     readonly disk?: string;
 }
+export type SandboxNetwork = {
+    readonly internet?: boolean | {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    };
+};
+export interface SandboxNetworkSpec {
+    readonly internet: boolean;
+    readonly allow: readonly string[];
+    readonly deny: readonly string[];
+}
 export type MarkedTask<TPayload, TOutput, TSecrets extends SecretDecls, TPayloadSchema extends PayloadSchema<any, any> | undefined> = TPayloadSchema extends PayloadSchema<any, any> ? Task<PayloadSchemaOutput<TPayloadSchema>, Awaited<TOutput>, TSecrets, PayloadSchemaInput<TPayloadSchema>> : Task<NoPayload, Awaited<TOutput>, TSecrets, NoPayload>;
 export declare function markTask<TPayload, TOutput, TSecrets extends SecretDecls, TPayloadSchema extends PayloadSchema<any, any> | undefined>(config: TaskConfig<TPayload, TOutput, TSecrets, TPayloadSchema>): MarkedTask<TPayload, TOutput, TSecrets, TPayloadSchema>;
 export declare function markScheduledTask<TPayload, TOutput, TSecrets extends SecretDecls, TPayloadSchema extends PayloadSchema<any, any> | undefined>(config: TaskConfig<TPayload, TOutput, TSecrets, TPayloadSchema>, schedule: InternalTaskScheduleConfig | undefined): MarkedTask<TPayload, TOutput, TSecrets, TPayloadSchema>;
+export declare function validateRetryPolicy(value: unknown, label?: string): void;
 export declare function validateTaskSchedule(taskId: string, value: InternalTaskScheduleConfig | undefined): void;
 export declare function validateTaskQueue(taskId: string, value: TaskQueueConfig | undefined): void;
 export declare function defaultTaskQueueName(taskId: string): string;
@@ -313,7 +350,8 @@ export declare class SandboxBuilderImpl implements SandboxBuilder {
     readonly imageBuilder: ImageBuilderImpl | undefined;
     readonly workspaceBinding: SandboxWorkspace | undefined;
     readonly resourceSpec: SandboxResources | undefined;
-    constructor(id: string, imageBuilder?: ImageBuilderImpl, workspaceBinding?: SandboxWorkspace, resourceSpec?: SandboxResources);
+    readonly networkSpec: SandboxNetworkSpec | undefined;
+    constructor(id: string, imageBuilder?: ImageBuilderImpl, workspaceBinding?: SandboxWorkspace, resourceSpec?: SandboxResources, networkSpec?: SandboxNetworkSpec);
     image(img: ImageBuilder): SandboxBuilder;
     workspace(mountPath?: string): SandboxBuilder;
     resources(opts: {
@@ -321,6 +359,7 @@ export declare class SandboxBuilderImpl implements SandboxBuilder {
         readonly memory?: string;
         readonly disk?: string;
     }): SandboxBuilder;
+    network(opts: SandboxNetwork): SandboxBuilder;
 }
 export declare class SourceFileRefImpl implements SourceFileRef {
     readonly path: string;

package/dist/internal.js

@@ -212,12 +212,8 @@ function validateSecretName(name, label = "secret name") {
   if (name.length > 128) {
     throw new Error(`${label} must be at most 128 characters`);
   }
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
-    throw new Error(`${label} must match /^[A-Za-z_][A-Za-z0-9_]*$/`);
-  }
-  const upper = name.toUpperCase();
-  if (upper === "CON" || upper === "PRN" || upper === "AUX" || upper === "NUL" || /^COM[1-9]$/.test(upper) || /^LPT[1-9]$/.test(upper)) {
-    throw new Error(`${label} is reserved`);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(name)) {
+    throw new Error(`${label} must match /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/`);
   }
 }
 function validateImageBuildSecretRef(name) {
@@ -283,6 +279,7 @@ function markTaskInternal(config, schedule) {
   validateTaskQueue(config.id, config.queue);
   validateTaskSchedule(config.id, schedule);
   validateOptionalTTL(config.ttl, `task ${JSON.stringify(config.id)} ttl`);
+  validateRetryPolicy(config.retry, `task ${JSON.stringify(config.id)} retry`);
   assertPayloadSchema(config.payload, `task ${JSON.stringify(config.id)} payload`);
   if (schedule !== undefined) {
     Object.defineProperty(config, "schedule", {
@@ -294,6 +291,54 @@ function markTaskInternal(config, schedule) {
   Object.defineProperty(config, taskOriginBrand, { value: captureTaskOrigin() });
   return config;
 }
+function validateRetryPolicy(value, label = "retry") {
+  if (value === undefined || value === false) {
+    return;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be false or a retry policy object`);
+  }
+  const record = value;
+  for (const key of Object.keys(record)) {
+    if (key !== "maxAttempts" && key !== "backoff") {
+      throw new Error(`${label}.${key} is not supported`);
+    }
+  }
+  if (typeof record["maxAttempts"] !== "number" || !Number.isInteger(record["maxAttempts"]) || record["maxAttempts"] < 1 || record["maxAttempts"] > 10) {
+    throw new Error(`${label}.maxAttempts must be an integer between 1 and 10`);
+  }
+  const backoff = record["backoff"];
+  if (backoff !== undefined) {
+    if (backoff === null || typeof backoff !== "object" || Array.isArray(backoff)) {
+      throw new Error(`${label}.backoff must be an object`);
+    }
+    const backoffRecord = backoff;
+    for (const key of Object.keys(backoffRecord)) {
+      if (key !== "minMs" && key !== "maxMs" && key !== "factor" && key !== "jitter") {
+        throw new Error(`${label}.backoff.${key} is not supported`);
+      }
+    }
+    validateOptionalPositiveInteger(backoffRecord["minMs"], `${label}.backoff.minMs`);
+    validateOptionalPositiveInteger(backoffRecord["maxMs"], `${label}.backoff.maxMs`);
+    const factor = backoffRecord["factor"];
+    if (factor !== undefined && (typeof factor !== "number" || !Number.isFinite(factor) || factor <= 0)) {
+      throw new Error(`${label}.backoff.factor must be a positive number`);
+    }
+    const jitter = backoffRecord["jitter"];
+    if (jitter !== undefined && jitter !== "none" && jitter !== "full") {
+      throw new Error(`${label}.backoff.jitter must be "none" or "full"`);
+    }
+  }
+}
+function validateOptionalPositiveInteger(value, label) {
+  if (value === undefined) {
+    return;
+  }
+  if (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value > 0) {
+    return;
+  }
+  throw new Error(`${label} must be a positive integer`);
+}
 function validateTaskSchedule(taskId, value) {
   if (value === undefined) {
     return;
@@ -304,17 +349,6 @@ function validateTaskSchedule(taskId, value) {
   if (value.timezone !== undefined && value.timezone.trim() === "") {
     throw new Error(`task ${JSON.stringify(taskId)} schedule timezone must not be empty`);
   }
-  if (value.secretBindings !== undefined) {
-    if (value.secretBindings === null || typeof value.secretBindings !== "object" || Array.isArray(value.secretBindings)) {
-      throw new Error(`task ${JSON.stringify(taskId)} schedule secretBindings must be an object`);
-    }
-    for (const [name, binding] of Object.entries(value.secretBindings)) {
-      validateSecretName(name, `task ${JSON.stringify(taskId)} schedule secretBindings.${name}`);
-      if (typeof binding !== "string" || binding.trim() === "") {
-        throw new Error(`task ${JSON.stringify(taskId)} schedule secretBindings.${name} must be a non-empty string`);
-      }
-    }
-  }
 }
 function validateTaskQueue(taskId, value) {
   if (value === undefined) {
@@ -495,21 +529,23 @@ class SandboxBuilderImpl {
   imageBuilder;
   workspaceBinding;
   resourceSpec;
-  constructor(id, imageBuilder, workspaceBinding, resourceSpec) {
+  networkSpec;
+  constructor(id, imageBuilder, workspaceBinding, resourceSpec, networkSpec) {
     Object.defineProperty(this, sandboxBuilderBrand, { value: true });
     this.id = id;
     this.imageBuilder = imageBuilder;
     this.workspaceBinding = workspaceBinding;
     this.resourceSpec = resourceSpec;
+    this.networkSpec = networkSpec;
   }
   image(img) {
     if (!isImageBuilder(img)) {
       throw new Error("sandbox.image() requires an ImageBuilder created by image()");
     }
-    return new SandboxBuilderImpl(this.id, img, this.workspaceBinding, this.resourceSpec);
+    return new SandboxBuilderImpl(this.id, img, this.workspaceBinding, this.resourceSpec, this.networkSpec);
   }
   workspace(mountPath = "/workspace") {
-    return new SandboxBuilderImpl(this.id, this.imageBuilder, { mountPath: normalizeWorkspaceMountPath(mountPath) }, this.resourceSpec);
+    return new SandboxBuilderImpl(this.id, this.imageBuilder, { mountPath: normalizeWorkspaceMountPath(mountPath) }, this.resourceSpec, this.networkSpec);
   }
   resources(opts) {
     const resourceSpec = {
@@ -517,8 +553,37 @@ class SandboxBuilderImpl {
       ...opts.memory === undefined ? {} : { memory: opts.memory },
       ...opts.disk === undefined ? {} : { disk: opts.disk }
     };
-    return new SandboxBuilderImpl(this.id, this.imageBuilder, this.workspaceBinding, resourceSpec);
+    return new SandboxBuilderImpl(this.id, this.imageBuilder, this.workspaceBinding, resourceSpec, this.networkSpec);
+  }
+  network(opts) {
+    return new SandboxBuilderImpl(this.id, this.imageBuilder, this.workspaceBinding, this.resourceSpec, normalizeSandboxNetwork(opts));
+  }
+}
+function normalizeSandboxNetwork(opts) {
+  const value = opts.internet;
+  if (value === undefined || value === true) {
+    return { internet: true, allow: [], deny: [] };
   }
+  if (value === false) {
+    return { internet: false, allow: [], deny: [] };
+  }
+  return {
+    internet: true,
+    allow: normalizeNetworkEntries(value.allow, "network.internet.allow"),
+    deny: normalizeNetworkEntries(value.deny, "network.internet.deny")
+  };
+}
+function normalizeNetworkEntries(entries, label) {
+  if (entries === undefined) {
+    return [];
+  }
+  return entries.map((entry, index) => {
+    const normalized = entry.trim();
+    if (normalized === "") {
+      throw new Error(`${label}[${index}] must not be empty`);
+    }
+    return normalized;
+  });
 }
 
 class SourceFileRefImpl {
@@ -557,6 +622,7 @@ export {
   validateTaskSchedule,
   validateTaskQueue,
   validateSecretName,
+  validateRetryPolicy,
   validateOptionalTTL,
   taskOriginFile,
   taskOriginBrand,

package/dist/runtime/client.d.ts

@@ -1,5 +1,5 @@
 import { type AnyTask, type NoPayload, type SecretDecls, type TaskOutput, type TaskRunOptions, type TaskSecrets, type TaskTriggerPayload } from "../internal.js";
-import { type LogSnapshot, type ListRunEventsOptions, type ListRunsOptions, type PendingManualWaitpoint, type PendingWaitpointResponse, type RetrieveRunOptions, type RunHandle, type RunEvent, type RunSnapshot, type RunSummary, type RunWaitOptions, type SubscribeRunEventsOptions, type WaitpointRespondOptions, type WaitpointRef } from "./run.js";
+import { type LogSnapshot, type CancelRunOptions, type ListRunEventsOptions, type ListRunsOptions, type PendingHumanWaitpoint, type PendingWaitpointResponse, type RetrieveRunOptions, type RunHandle, type RunEvent, type RunSnapshot, type RunSummary, type RunWaitOptions, type ReplayRunOptions, type SubscribeRunEventsOptions, type WaitpointRespondOptions, type WaitpointRef } from "./run.js";
 export interface HelmrClientOptions {
     readonly url?: string;
     readonly apiKey?: string;
@@ -15,12 +15,12 @@ export declare const triggerTaskClientMethod: unique symbol;
 export interface WaitpointsApi {
     readonly create: (opts: WaitpointCreateOptions) => Promise<Waitpoint>;
     readonly respond: {
-        (target: PendingManualWaitpoint | WaitpointRef, opts?: WaitpointRespondOptions): Promise<void>;
+        (target: PendingHumanWaitpoint | WaitpointRef, opts?: WaitpointRespondOptions): Promise<void>;
         (waitpointId: string, opts?: WaitpointRespondOptions): Promise<void>;
     };
     readonly tokens: {
         readonly create: {
-            (target: PendingManualWaitpoint | WaitpointRef, opts?: WaitpointTokenCreateOptions): Promise<WaitpointResponseToken>;
+            (target: PendingHumanWaitpoint | WaitpointRef, opts?: WaitpointTokenCreateOptions): Promise<WaitpointResponseToken>;
             (waitpointId: string, opts?: WaitpointTokenCreateOptions): Promise<WaitpointResponseToken>;
         };
         readonly respond: {
@@ -47,7 +47,6 @@ export interface ScheduleCreateOptions {
     readonly cron: string;
     readonly timezone?: string;
     readonly active?: boolean;
-    readonly secretBindings?: Record<string, string>;
     readonly options?: ScheduleRunOptions;
 }
 export type ScheduleUpdateOptions = Omit<ScheduleCreateOptions, "deduplicationKey"> & {
@@ -122,7 +121,7 @@ export interface Waitpoint {
     readonly id: string;
     readonly projectId: string;
     readonly environmentId: string;
-    readonly kind: "manual" | "delay";
+    readonly kind: "human" | "delay";
     readonly status: "pending" | "completed" | "expired" | "cancelled";
     readonly request: unknown;
     readonly displayText: string;
@@ -139,6 +138,8 @@ export declare class HelmrClient {
     readonly runs: {
         retrieve: <TOutput = unknown>(idOrHandle: string | RunHandle<TOutput>, opts?: RetrieveRunOptions) => Promise<RunSnapshot<TOutput>>;
         wait: <TOutput = unknown>(idOrHandle: string | RunHandle<TOutput>, opts?: RunWaitOptions) => Promise<RunSnapshot<TOutput>>;
+        cancel: <TOutput = unknown>(idOrHandle: string | RunHandle<TOutput>, opts?: CancelRunOptions) => Promise<RunSnapshot<TOutput>>;
+        replay: <TPayload = unknown, TOutput = unknown>(idOrHandle: string | RunHandle<TOutput>, opts?: ReplayRunOptions<TPayload>) => Promise<RunHandle<TOutput>>;
         list: (opts?: ListRunsOptions) => Promise<RunSummary[]>;
         logs: {
             retrieve: <TOutput = unknown>(idOrHandle: string | RunHandle<TOutput>, opts?: {
@@ -157,6 +158,12 @@ export interface RunResponse {
     readonly id: string;
     readonly project_id?: string;
     readonly environment_id?: string;
+    readonly version?: string;
+    readonly deployment_version?: string;
+    readonly api_version?: string;
+    readonly sdk_version?: string;
+    readonly cli_version?: string;
+    readonly attempt_number?: number | null;
     readonly task_id: string;
     readonly status: string;
     readonly exit_code?: number | null;

package/dist/runtime/run.d.ts

@@ -20,6 +20,12 @@ export interface RunStateBooleans {
 export interface RunSnapshot<TOutput = unknown> extends RunStateBooleans {
     readonly id: string;
     readonly taskId: string;
+    readonly version?: string | null;
+    readonly deploymentVersion?: string | null;
+    readonly apiVersion?: string | null;
+    readonly sdkVersion?: string | null;
+    readonly cliVersion?: string | null;
+    readonly attemptNumber: number | null;
     readonly status: RunStatus;
     readonly exitCode: number | null;
     readonly createdAt: string | null;
@@ -28,7 +34,7 @@ export interface RunSnapshot<TOutput = unknown> extends RunStateBooleans {
     readonly output?: TOutput;
 }
 export type RunSummary<TOutput = unknown> = RunSnapshot<TOutput>;
-export type PendingWaitpoint = PendingManualWaitpoint | PendingDelayWaitpoint;
+export type PendingWaitpoint = PendingHumanWaitpoint | PendingDelayWaitpoint;
 interface PendingWaitpointBase {
     readonly runId: string;
     readonly waitpointId: string;
@@ -37,8 +43,8 @@ interface PendingWaitpointBase {
     readonly request: unknown;
     readonly displayText: string;
 }
-export interface PendingManualWaitpoint extends PendingWaitpointBase {
-    readonly kind: "manual";
+export interface PendingHumanWaitpoint extends PendingWaitpointBase {
+    readonly kind: "human";
 }
 export interface PendingDelayWaitpoint extends PendingWaitpointBase {
     readonly kind: "delay";
@@ -57,6 +63,21 @@ export interface RunWaitOptions {
     readonly intervalMs?: number;
     readonly signal?: AbortSignal;
 }
+export interface CancelRunOptions {
+    readonly reason?: string;
+    readonly force?: boolean;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface ReplayRunOptions<TPayload = unknown> {
+    readonly version?: "original" | "latest" | string;
+    readonly payload?: TPayload;
+    readonly reason?: string;
+    readonly idempotencyKey?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly tags?: readonly string[];
+    readonly signal?: AbortSignal;
+}
 export interface RetrieveRunOptions {
     readonly signal?: AbortSignal;
 }
@@ -132,6 +153,8 @@ export type RunEvent = {
 export interface RunEventRecord {
     readonly id: string;
     readonly run_id?: string | null;
+    readonly session_id?: string | null;
+    readonly attempt_number?: number | null;
     readonly kind: string;
     readonly message: string;
     readonly at: string;
@@ -154,7 +177,7 @@ export interface LogSnapshot {
     readonly truncated: boolean;
 }
 export interface PendingWaitpointResponse {
-    readonly kind: "manual" | "delay";
+    readonly kind: "human" | "delay";
     readonly waitpoint_id: string;
     readonly timeout?: number | null;
     readonly request?: unknown;
@@ -165,6 +188,12 @@ export declare function runHandle<TOutput = unknown>(id: string, taskId: string)
 export declare function runSnapshot<TOutput = unknown>(snapshot: {
     readonly id: string;
     readonly taskId: string;
+    readonly version?: string | null;
+    readonly deploymentVersion?: string | null;
+    readonly apiVersion?: string | null;
+    readonly sdkVersion?: string | null;
+    readonly cliVersion?: string | null;
+    readonly attemptNumber?: number | null;
     readonly status: string;
     readonly exitCode?: number | null;
     readonly createdAt?: string | null;

package/dist/sandbox.d.ts

@@ -1,3 +1,3 @@
-import { type SandboxBuilder } from "./internal.js";
+import { type SandboxBuilder, type SandboxNetwork } from "./internal.js";
 export declare const sandbox: (id: string) => SandboxBuilder;
-export type { SandboxBuilder };
+export type { SandboxBuilder, SandboxNetwork };

package/dist/schedules.d.ts

@@ -14,15 +14,13 @@ export type ScheduleCron = string | {
 };
 type DeclarativeScheduleFields = {
     readonly cron: ScheduleCron;
-    readonly secretBindings?: Record<string, string>;
 } | {
     readonly cron?: undefined;
-    readonly secretBindings?: undefined;
 };
-export type ScheduledTaskConfig<TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>> = Omit<TaskConfigBase<TSecrets>, "payload"> & DeclarativeScheduleFields & {
+export type ScheduledTaskConfig<TOutput = unknown, TSecrets extends SecretDecls = readonly []> = Omit<TaskConfigBase<TSecrets>, "payload"> & DeclarativeScheduleFields & {
     readonly payload?: never;
     readonly run: (payload: ScheduledTaskPayload, ctx: TaskContext) => MaybePromise<TOutput>;
 };
-export declare function task<TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>>(config: ScheduledTaskConfig<TOutput, TSecrets>): MarkedTask<ScheduledTaskPayload, Awaited<TOutput>, TSecrets, typeof scheduledTaskPayloadSchema>;
+export declare function task<TOutput = unknown, TSecrets extends SecretDecls = readonly []>(config: ScheduledTaskConfig<TOutput, TSecrets>): MarkedTask<ScheduledTaskPayload, Awaited<TOutput>, TSecrets, typeof scheduledTaskPayloadSchema>;
 declare const scheduledTaskPayloadSchema: PayloadSchema<unknown, ScheduledTaskPayload>;
 export {};

package/dist/task.d.ts

@@ -1,6 +1,6 @@
 import { type NoPayload, type SecretDecls, type Task, type TaskConfig, type TaskQueueConfig, type TaskConfigWithPayload, type TaskConfigWithoutPayload, type TaskRunOptions, type TaskOutput, type TaskPayload, type TaskTriggerPayload } from "./internal.js";
 import type { PayloadSchema, PayloadSchemaInput, PayloadSchemaOutput } from "./schema/payload.js";
-export declare function task<TPayloadSchema extends PayloadSchema<any, any>, TOutput, TSecrets extends SecretDecls = Record<never, never>>(config: TaskConfigWithPayload<TPayloadSchema, TOutput, TSecrets>): Task<PayloadSchemaOutput<TPayloadSchema>, Awaited<TOutput>, TSecrets, PayloadSchemaInput<TPayloadSchema>>;
-export declare function task<TOutput = unknown, TSecrets extends SecretDecls = Record<never, never>>(config: TaskConfigWithoutPayload<TOutput, TSecrets>): Task<NoPayload, Awaited<TOutput>, TSecrets, NoPayload>;
+export declare function task<TPayloadSchema extends PayloadSchema<any, any>, TOutput, TSecrets extends SecretDecls = readonly []>(config: TaskConfigWithPayload<TPayloadSchema, TOutput, TSecrets>): Task<PayloadSchemaOutput<TPayloadSchema>, Awaited<TOutput>, TSecrets, PayloadSchemaInput<TPayloadSchema>>;
+export declare function task<TOutput = unknown, TSecrets extends SecretDecls = readonly []>(config: TaskConfigWithoutPayload<TOutput, TSecrets>): Task<NoPayload, Awaited<TOutput>, TSecrets, NoPayload>;
 export declare function queue(config: TaskQueueConfig): TaskQueueConfig;
 export type { NoPayload, Task, TaskConfig, TaskOutput, TaskPayload, TaskQueueConfig, TaskRunOptions, TaskTriggerPayload };

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+export declare const HELMR_API_VERSION = "2026-06-06";
+export declare const HELMR_API_VERSION_HEADER = "Helmr-API-Version";
+export declare const HELMR_SDK_VERSION_HEADER = "Helmr-SDK-Version";
+export declare const HELMR_SDK_VERSION: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helmr/sdk",
-  "version": "0.1.1-rc.6",
+  "version": "0.1.1-rc.8",
   "description": "TypeScript SDK for authoring and triggering Helmr tasks.",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,6 +43,6 @@
   ],
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
-    "@helmr/proto": "0.1.1-rc.6"
+    "@helmr/proto": "0.1.1-rc.8"
   }
 }