@helmr/sdk 0.1.1-rc.4 → 0.1.1-rc.5

package/dist/index.js

@@ -1,9 +1,92 @@
+// sdk/typescript/src/schema/payload.ts
+var payloadSchemaValidationErrorBrand = Symbol.for("helmr.sdk.PayloadSchemaValidationError");
+
+class PayloadSchemaValidationError extends Error {
+  issues;
+  constructor(label, issues) {
+    super(formatPayloadSchemaValidationMessage(label, issues));
+    this.name = "PayloadSchemaValidationError";
+    this.issues = issues;
+    Object.defineProperty(this, payloadSchemaValidationErrorBrand, { value: true });
+  }
+  static [Symbol.hasInstance](value) {
+    return this === PayloadSchemaValidationError && typeof value === "object" && value !== null && payloadSchemaValidationErrorBrand in value;
+  }
+}
+function assertPayloadSchema(value, label = "payload") {
+  if (value === undefined) {
+    return;
+  }
+  assertStandardSchema(value, label);
+}
+function assertStandardSchema(value, label = "schema") {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    throw new Error(`${label} must implement the Standard Schema v1 interface`);
+  }
+  const standard = value["~standard"];
+  if (standard === null || typeof standard !== "object") {
+    throw new Error(`${label} must implement the Standard Schema v1 interface`);
+  }
+  const record = standard;
+  if (record["version"] !== 1 || typeof record["validate"] !== "function") {
+    throw new Error(`${label} must implement the Standard Schema v1 interface`);
+  }
+}
+async function parsePayloadWithSchema(schema, payload, label) {
+  assertStandardSchema(schema, label);
+  const result = await schema["~standard"].validate(payload);
+  if ("issues" in result && result.issues !== undefined) {
+    throw new PayloadSchemaValidationError(label, result.issues);
+  }
+  return result.value;
+}
+function formatPayloadSchemaValidationMessage(label, issues) {
+  if (issues.length === 0) {
+    return `${label} failed validation`;
+  }
+  const formattedIssues = issues.slice(0, 5).map(formatPayloadSchemaIssue);
+  const suffix = issues.length > formattedIssues.length ? `; and ${issues.length - formattedIssues.length} more` : "";
+  return `${label} failed validation: ${formattedIssues.join("; ")}${suffix}`;
+}
+function formatPayloadSchemaIssue(issue) {
+  const path = formatPayloadSchemaIssuePath(issue.path);
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+function formatPayloadSchemaIssuePath(path) {
+  if (path === undefined || path.length === 0) {
+    return "";
+  }
+  let formatted = "payload";
+  for (const segment of path) {
+    const key = typeof segment === "object" && segment !== null && "key" in segment ? segment.key : segment;
+    if (typeof key === "string" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) {
+      formatted += `.${key}`;
+    } else if (typeof key === "string" && isArrayIndexKey(key)) {
+      formatted += `[${key}]`;
+    } else if (typeof key === "number") {
+      formatted += `[${key}]`;
+    } else {
+      formatted += `[${JSON.stringify(String(key))}]`;
+    }
+  }
+  return formatted;
+}
+function isArrayIndexKey(value) {
+  if (!/^(0|[1-9]\d*)$/.test(value)) {
+    return false;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed);
+}
+
 // sdk/typescript/src/schema/task.ts
 var TASK_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$";
 var TASK_ID_MAX_LENGTH = 128;
 var DEFAULT_MAX_DURATION_SECONDS = 900;
 var MIN_MAX_DURATION_SECONDS = 5;
 var MAX_DURATION_SECONDS = 86400;
+var QUEUE_NAME_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$";
+var QUEUE_NAME_MAX_LENGTH = 256;
 
 class TaskIdError extends Error {
   name = "TaskIdError";
@@ -57,36 +140,60 @@ function readOptionalMaxDurationSeconds(value, label = "task maxDuration") {
 function validateOptionalMaxDurationSeconds(value, label = "task maxDuration") {
   readOptionalMaxDurationSeconds(value, label);
 }
-function isAsciiAlnum(code) {
-  return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122;
-}
 
-// sdk/typescript/src/internal.ts
-var approvalTimeoutErrorBrand = Symbol.for("helmr.sdk.ApprovalTimeoutError");
-var messageTimeoutErrorBrand = Symbol.for("helmr.sdk.MessageTimeoutError");
-var concurrentWaitErrorBrand = Symbol.for("helmr.sdk.ConcurrentWaitError");
+class TaskQueueNameError extends Error {
+  name = "TaskQueueNameError";
+  value;
+  constructor(value) {
+    super(`queue name must match ${QUEUE_NAME_PATTERN}: ${JSON.stringify(value)}`);
+    this.value = value;
+  }
+}
 
-class ApprovalTimeoutError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ApprovalTimeoutError";
-    Object.defineProperty(this, approvalTimeoutErrorBrand, { value: true });
+class TaskQueueConcurrencyLimitError extends Error {
+  name = "TaskQueueConcurrencyLimitError";
+  value;
+  constructor(value) {
+    super("queue concurrencyLimit must be a positive integer");
+    this.value = value;
   }
-  static [Symbol.hasInstance](value) {
-    return this === ApprovalTimeoutError && typeof value === "object" && value !== null && approvalTimeoutErrorBrand in value;
+}
+function validateQueueName(value) {
+  if (!isValidQueueName(value)) {
+    throw new TaskQueueNameError(value);
   }
 }
-
-class MessageTimeoutError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "MessageTimeoutError";
-    Object.defineProperty(this, messageTimeoutErrorBrand, { value: true });
+function isValidQueueName(value) {
+  if (value.length === 0 || value.length > QUEUE_NAME_MAX_LENGTH) {
+    return false;
   }
-  static [Symbol.hasInstance](value) {
-    return this === MessageTimeoutError && typeof value === "object" && value !== null && messageTimeoutErrorBrand in value;
+  const first = value.charCodeAt(0);
+  if (!isAsciiAlnum(first)) {
+    return false;
+  }
+  for (let index = 1;index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (!(isAsciiAlnum(code) || code === 46 || code === 95 || code === 45 || code === 47)) {
+      return false;
+    }
+  }
+  return true;
+}
+function validateOptionalQueueConcurrencyLimit(value) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value > 0) {
+    return;
   }
+  throw new TaskQueueConcurrencyLimitError(value);
 }
+function isAsciiAlnum(code) {
+  return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122;
+}
+
+// sdk/typescript/src/internal.ts
+var concurrentWaitErrorBrand = Symbol.for("helmr.sdk.ConcurrentWaitError");
 
 class ConcurrentWaitError extends Error {
   constructor(message) {
@@ -162,12 +269,136 @@ var sandboxBuilderBrand = Symbol.for("helmr.sdk.SandboxBuilder");
 var sourceFileRefBrand = Symbol.for("helmr.sdk.SourceFileRef");
 var sourceDirRefBrand = Symbol.for("helmr.sdk.SourceDirRef");
 function markTask(config) {
+  if ("schedule" in config) {
+    throw new Error(`task ${JSON.stringify(config.id)} must use schedules.task(...) for declarative schedules`);
+  }
+  return markTaskInternal(config, undefined);
+}
+function markScheduledTask(config, schedule) {
+  return markTaskInternal(config, schedule);
+}
+function markTaskInternal(config, schedule) {
   validateTaskId(config.id);
   validateOptionalMaxDurationSeconds(config.maxDuration);
+  validateTaskQueue(config.id, config.queue);
+  validateTaskSchedule(config.id, schedule);
+  validateOptionalTTL(config.ttl, `task ${JSON.stringify(config.id)} ttl`);
+  assertPayloadSchema(config.payload, `task ${JSON.stringify(config.id)} payload`);
+  if (schedule !== undefined) {
+    Object.defineProperty(config, "schedule", {
+      value: Object.freeze({ ...schedule }),
+      enumerable: true
+    });
+  }
   Object.defineProperty(config, taskBrand, { value: true });
   Object.defineProperty(config, taskOriginBrand, { value: captureTaskOrigin() });
   return config;
 }
+function validateTaskSchedule(taskId, value) {
+  if (value === undefined) {
+    return;
+  }
+  if (value.cron.trim() === "") {
+    throw new Error(`task ${JSON.stringify(taskId)} schedule cron is required`);
+  }
+  if (value.timezone !== undefined && value.timezone.trim() === "") {
+    throw new Error(`task ${JSON.stringify(taskId)} schedule timezone must not be empty`);
+  }
+  if (value.workspace.kind !== "github") {
+    throw new Error(`task ${JSON.stringify(taskId)} schedule workspace must be workspace.github(...)`);
+  }
+  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) {
+    return;
+  }
+  if (value.name !== undefined) {
+    validateQueueName(value.name);
+  }
+  validateOptionalQueueConcurrencyLimit(value.concurrencyLimit);
+  if (value.name === undefined && value.concurrencyLimit === undefined) {
+    throw new Error(`task ${JSON.stringify(taskId)} queue must include name or concurrencyLimit`);
+  }
+}
+function validateOptionalTTL(value, label = "ttl") {
+  if (value === undefined) {
+    return;
+  }
+  if (typeof value === "string" && isPositiveDurationString(value)) {
+    return;
+  }
+  throw new Error(`${label} must be a positive duration string`);
+}
+function isPositiveDurationString(value) {
+  const raw = value.trim();
+  if (raw === "") {
+    return false;
+  }
+  if (/^[1-9][0-9]*d$/.test(raw)) {
+    return true;
+  }
+  const sign = raw.startsWith("+") || raw.startsWith("-") ? raw.slice(0, 1) : "";
+  if (sign === "-") {
+    return false;
+  }
+  const body = sign === "" ? raw : raw.slice(1);
+  const tokenPattern = /([0-9]+(?:\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h)/gy;
+  let totalNanoseconds = 0;
+  let offset = 0;
+  for (;; ) {
+    tokenPattern.lastIndex = offset;
+    const match = tokenPattern.exec(body);
+    if (match === null) {
+      return offset === body.length && totalNanoseconds >= 1;
+    }
+    if (match.index !== offset) {
+      return false;
+    }
+    const amount = Number(match[1]);
+    if (!Number.isFinite(amount) || amount < 0) {
+      return false;
+    }
+    totalNanoseconds += amount * durationUnitNanoseconds(match[2] ?? "");
+    offset = tokenPattern.lastIndex;
+  }
+}
+function durationUnitNanoseconds(unit) {
+  switch (unit) {
+    case "ns":
+      return 1;
+    case "us":
+    case "µs":
+    case "μs":
+      return 1000;
+    case "ms":
+      return 1e6;
+    case "s":
+      return 1e9;
+    case "m":
+      return 60000000000;
+    case "h":
+      return 3600000000000;
+    default:
+      return 0;
+  }
+}
+async function parseTaskPayload(task, payload) {
+  if (task.payload === undefined) {
+    throw new Error(`task ${JSON.stringify(task.id)} does not accept payload`);
+  }
+  return await parsePayloadWithSchema(task.payload, payload, `task ${JSON.stringify(task.id)} payload`);
+}
 function markConfig(config) {
   Object.defineProperty(config, configBrand, { value: true });
   return config;
@@ -300,6 +531,55 @@ function hasBrand(value, brand) {
   return value !== null && typeof value === "object" && value[brand] === true;
 }
 
+// sdk/typescript/src/idempotency.ts
+import { createHash } from "node:crypto";
+var idempotencyKeys = {
+  create(key, options = {}) {
+    const scope = options.scope ?? "run";
+    return {
+      value: createIdempotencyKey(key, scope, options),
+      key,
+      scope
+    };
+  }
+};
+function runIdempotencyRequestFields(input, ttl) {
+  if (input === undefined) {
+    return {};
+  }
+  const key = isIdempotencyKey(input) ? input : idempotencyKeys.create(input);
+  return {
+    idempotency_key: key.value,
+    ...ttl === undefined ? {} : { idempotency_key_ttl: ttl },
+    idempotency_key_options: {
+      key: key.key,
+      scope: key.scope
+    }
+  };
+}
+function createIdempotencyKey(key, scope, options) {
+  const material = {
+    scope,
+    key: Array.isArray(key) ? [...key] : [key]
+  };
+  const runId = "runId" in options ? options.runId : undefined;
+  const attemptNumber = "attemptNumber" in options ? options.attemptNumber : undefined;
+  if (scope === "run" && runId !== undefined) {
+    material["runId"] = runId;
+  }
+  if (scope === "attempt") {
+    if (runId === undefined || attemptNumber === undefined) {
+      throw new Error("attempt-scoped idempotency keys require runId and attemptNumber");
+    }
+    material["runId"] = runId;
+    material["attemptNumber"] = attemptNumber;
+  }
+  return createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+function isIdempotencyKey(value) {
+  return typeof value === "object" && value !== null && "value" in value && "key" in value && "scope" in value;
+}
+
 // sdk/typescript/src/runtime/errors.ts
 class RunNotFoundError extends Error {
   runId;
@@ -352,27 +632,18 @@ function runSnapshot(snapshot) {
 function pendingWaitpointFromResponse(runId, wait) {
   if (wait === undefined || wait === null)
     return null;
-  if (wait.kind === "approval") {
-    return {
-      kind: "approval",
-      runId,
-      waitpointId: wait.waitpoint_id,
-      message: wait.message ?? "",
-      timeout: wait.timeout ?? null,
-      requestedAt: wait.requested_at
-    };
-  }
   return {
-    kind: "message",
+    kind: wait.kind,
     runId,
     waitpointId: wait.waitpoint_id,
-    prompt: wait.prompt ?? null,
     timeout: wait.timeout ?? null,
+    request: wait.request === undefined ? {} : wait.request,
+    displayText: wait.display_text ?? "",
     requestedAt: wait.requested_at
   };
 }
 function isTerminalRunStatus(status) {
-  return status === "succeeded" || status === "failed" || status === "cancelled";
+  return status === "succeeded" || status === "failed" || status === "cancelled" || status === "expired";
 }
 function runId(value) {
   return typeof value === "string" ? value : value.id;
@@ -396,6 +667,7 @@ function runStatus(status) {
     case "succeeded":
     case "failed":
     case "cancelled":
+    case "expired":
       return status;
     default:
       throw new Error(`unsupported run status ${JSON.stringify(status)}`);
@@ -413,6 +685,7 @@ function runWorkspaceFromSpec(spec) {
 
 // sdk/typescript/src/runtime/client.ts
 var MAX_SSE_BUFFER_CHARS = 1024 * 1024;
+var triggerTaskClientMethod = Symbol.for("helmr.sdk.client.triggerTask");
 
 class HelmrClient {
   #baseUrl;
@@ -445,24 +718,57 @@ class HelmrClient {
     }
   }
   tasks = {
-    trigger: async (task, opts) => {
-      const runWorkspace = runWorkspaceFromSpec(opts.workspace);
-      const maxDurationSeconds = readOptionalMaxDurationSeconds(task.maxDuration);
-      const response = await this.#fetch("/api/runs", {
-        method: "POST",
-        body: JSON.stringify({
-          task_id: task.id,
-          secrets: opts.secrets ?? {},
-          payload: opts.payload,
-          workspace: runWorkspace,
-          max_duration_seconds: maxDurationSeconds
-        }),
-        headers: { "content-type": "application/json" }
-      });
-      const run = await response.json();
-      return runHandle(run.id, run.task_id);
+    trigger: async (...args) => {
+      const taskId = args[0];
+      const hasPayload = args.length === 3;
+      const payload = hasPayload ? args[1] : undefined;
+      const opts = hasPayload ? args[2] : args[1];
+      if (hasPayload && payload === undefined) {
+        throw new Error(`task ${JSON.stringify(taskId)} requires payload`);
+      }
+      return await this.#triggerRun(taskId, payload, opts);
     }
   };
+  async[triggerTaskClientMethod](task, ...args) {
+    const hasPayload = task.payload !== undefined;
+    const payload = hasPayload ? args[0] : undefined;
+    const opts = hasPayload ? args[1] : args[0];
+    if (task.payload !== undefined) {
+      if (payload === undefined) {
+        throw new Error(`task ${JSON.stringify(task.id)} requires payload`);
+      }
+      await parseTaskPayload(task, payload);
+    } else if (args.length > 1) {
+      throw new Error(`task ${JSON.stringify(task.id)} does not accept payload`);
+    }
+    return await this.#triggerRun(task.id, payload, opts, readOptionalMaxDurationSeconds(task.maxDuration));
+  }
+  async#triggerRun(taskId, payload, opts, maxDurationSeconds) {
+    const runWorkspace = runWorkspaceFromSpec(opts.workspace);
+    const runOptions = {
+      ...opts.deploymentId === undefined ? {} : { deployment_id: opts.deploymentId },
+      ...opts.version === undefined ? {} : { version: opts.version },
+      ...opts.queue === undefined ? {} : { queue: { name: opts.queue } },
+      ...opts.concurrencyKey === undefined ? {} : { concurrency_key: opts.concurrencyKey },
+      ...opts.priority === undefined ? {} : { priority: opts.priority },
+      ...opts.ttl === undefined ? {} : { ttl: opts.ttl },
+      ...maxDurationSeconds === undefined ? {} : { max_duration_seconds: maxDurationSeconds },
+      ...runIdempotencyRequestFields(opts.idempotencyKey, opts.idempotencyKeyTTL)
+    };
+    const response = await this.#fetch("/api/runs", {
+      method: "POST",
+      body: JSON.stringify({
+        task_id: taskId,
+        secrets: opts.secrets ?? {},
+        ...payload === undefined ? {} : { payload },
+        workspace: runWorkspace,
+        ...Object.keys(runOptions).length === 0 ? {} : { options: runOptions }
+      }),
+      headers: { "content-type": "application/json" }
+    });
+    const run = await response.json();
+    return runHandle(run.id, run.task_id);
+  }
   runs = {
     retrieve: async (idOrHandle, opts = {}) => {
       const response = await this.#json(`/api/runs/${encodeURIComponent(runId(idOrHandle))}`, requestSignal(opts.signal));
@@ -519,27 +825,19 @@ class HelmrClient {
     }
   };
   waitpoints = {
-    approve: async (target, waitpointIdOrOpts, opts = {}) => {
-      const resolved = resolveWaitpointArgs(target, waitpointIdOrOpts, opts);
-      await this.#fetch(`/api/runs/${encodeURIComponent(resolved.runId)}/waitpoints/${encodeURIComponent(resolved.waitpointId)}/approve`, {
+    create: async (opts) => {
+      const response = await this.#json("/api/waitpoints", {
         method: "POST",
-        body: JSON.stringify(approvalBody(resolved.opts)),
+        body: JSON.stringify(waitpointCreateBody(opts)),
         headers: { "content-type": "application/json" }
       });
+      return waitpointFromResponse(response);
     },
-    deny: async (target, waitpointIdOrOpts, opts = {}) => {
+    respond: async (target, waitpointIdOrOpts, opts = {}) => {
       const resolved = resolveWaitpointArgs(target, waitpointIdOrOpts, opts);
-      await this.#fetch(`/api/runs/${encodeURIComponent(resolved.runId)}/waitpoints/${encodeURIComponent(resolved.waitpointId)}/deny`, {
+      await this.#fetch(`/api/waitpoints/${encodeURIComponent(resolved.waitpointId)}/respond`, {
         method: "POST",
-        body: JSON.stringify(approvalBody(resolved.opts)),
-        headers: { "content-type": "application/json" }
-      });
-    },
-    reply: async (target, waitpointIdOrOpts, opts) => {
-      const resolved = resolveWaitpointArgs(target, waitpointIdOrOpts, opts);
-      await this.#fetch(`/api/runs/${encodeURIComponent(resolved.runId)}/waitpoints/${encodeURIComponent(resolved.waitpointId)}/message`, {
-        method: "POST",
-        body: JSON.stringify({ text: resolved.opts.text, attachments: [] }),
+        body: JSON.stringify(waitpointRespondBody(resolved.opts)),
         headers: { "content-type": "application/json" }
       });
     },
@@ -548,21 +846,77 @@ class HelmrClient {
         const resolved = resolveWaitpointArgs(target, waitpointIdOrOpts, opts);
         const response = await this.#json("/api/waitpoints/tokens", {
           method: "POST",
-          body: JSON.stringify(waitpointTokenCreateBody(resolved.runId, resolved.waitpointId, resolved.opts)),
+          body: JSON.stringify(waitpointTokenCreateBody(resolved.waitpointId, resolved.opts)),
           headers: { "content-type": "application/json" }
         });
         return waitpointResponseTokenFromResponse(response);
       },
-      complete: async (target, tokenOrOpts, maybeOpts) => {
-        const resolved = typeof target === "string" ? resolveWaitpointTokenCompleteArgs(target, tokenOrOpts, maybeOpts) : { id: target.id, token: target.token, opts: tokenOrOpts };
-        await this.#fetch(`/api/waitpoints/tokens/${encodeURIComponent(resolved.id)}/complete`, {
+      respond: async (target, tokenOrOpts, maybeOpts) => {
+        const resolved = typeof target === "string" ? resolveWaitpointTokenRespondArgs(target, tokenOrOpts, maybeOpts) : { id: target.id, token: target.token, opts: tokenOrOpts };
+        await this.#fetch(`/api/waitpoints/tokens/${encodeURIComponent(resolved.id)}/respond`, {
           method: "POST",
-          body: JSON.stringify(waitpointTokenCompleteBody(resolved.token, resolved.opts)),
+          body: JSON.stringify(waitpointTokenRespondBody(resolved.token, resolved.opts)),
           headers: { "content-type": "application/json" }
         });
       }
     }
   };
+  schedules = {
+    create: async (opts) => {
+      const response = await this.#json("/api/schedules", {
+        method: "POST",
+        body: JSON.stringify(scheduleCreateBody(opts)),
+        headers: { "content-type": "application/json" }
+      });
+      return scheduleFromResponse(response);
+    },
+    list: async (opts = {}) => {
+      const query = scheduleScopeQuery(opts);
+      const suffix = query.size === 0 ? "" : `?${query}`;
+      const response = await this.#json(`/api/schedules${suffix}`, requestSignal(opts.signal));
+      return response.schedules.map(scheduleFromResponse);
+    },
+    update: async (id, opts) => {
+      const query = scheduleScopeQuery(opts);
+      const suffix = query.size === 0 ? "" : `?${query}`;
+      const response = await this.#json(`/api/schedules/${encodeURIComponent(id)}${suffix}`, {
+        method: "PUT",
+        body: JSON.stringify(scheduleCreateBody(opts)),
+        headers: { "content-type": "application/json" },
+        ...requestSignal(opts.signal)
+      });
+      return scheduleFromResponse(response);
+    },
+    retrieve: async (id, opts = {}) => {
+      const query = scheduleScopeQuery(opts);
+      const suffix = query.size === 0 ? "" : `?${query}`;
+      return scheduleFromResponse(await this.#json(`/api/schedules/${encodeURIComponent(id)}${suffix}`, requestSignal(opts.signal)));
+    },
+    activate: async (id, opts = {}) => {
+      const query = scheduleScopeQuery(opts);
+      const suffix = query.size === 0 ? "" : `?${query}`;
+      return scheduleFromResponse(await this.#json(`/api/schedules/${encodeURIComponent(id)}/activate${suffix}`, {
+        method: "POST",
+        ...requestSignal(opts.signal)
+      }));
+    },
+    deactivate: async (id, opts = {}) => {
+      const query = scheduleScopeQuery(opts);
+      const suffix = query.size === 0 ? "" : `?${query}`;
+      return scheduleFromResponse(await this.#json(`/api/schedules/${encodeURIComponent(id)}/deactivate${suffix}`, {
+        method: "POST",
+        ...requestSignal(opts.signal)
+      }));
+    },
+    delete: async (id, opts = {}) => {
+      const query = scheduleScopeQuery(opts);
+      const suffix = query.size === 0 ? "" : `?${query}`;
+      await this.#fetch(`/api/schedules/${encodeURIComponent(id)}${suffix}`, {
+        method: "DELETE",
+        ...requestSignal(opts.signal)
+      });
+    }
+  };
   async#retrieveLogs(id, signal) {
     const response = await this.#json(`/api/runs/${encodeURIComponent(id)}/logs`, requestSignal(signal));
     return {
@@ -664,43 +1018,122 @@ function runResponseToSnapshot(response) {
     exitCode: response.exit_code ?? null,
     ...response.created_at === undefined ? {} : { createdAt: response.created_at },
     ...response.updated_at === undefined ? {} : { updatedAt: response.updated_at },
-    pendingWaitpoint: pendingWaitpointFromResponse(response.id, response.pending_wait),
+    pendingWaitpoint: pendingWaitpointFromResponse(response.id, response.pending_waitpoint),
     ..."output" in response ? { output: response.output } : {}
   });
 }
-function approvalBody(opts) {
-  return opts.reason === undefined ? {} : { reason: opts.reason };
+function scheduleCreateBody(opts) {
+  return {
+    ..."deduplicationKey" in opts && opts.deduplicationKey !== undefined ? { deduplication_key: opts.deduplicationKey } : {},
+    ...opts.projectId === undefined ? {} : { project_id: opts.projectId },
+    ...opts.environmentId === undefined ? {} : { environment_id: opts.environmentId },
+    ...opts.externalId === undefined ? {} : { external_id: opts.externalId },
+    task: opts.task,
+    cron: opts.cron,
+    ...opts.timezone === undefined ? {} : { timezone: opts.timezone },
+    ...opts.active === undefined ? {} : { active: opts.active },
+    workspace: runWorkspaceFromSpec(opts.workspace),
+    ...opts.secretBindings === undefined ? {} : { secret_bindings: opts.secretBindings },
+    ...opts.options === undefined ? {} : { options: runOptionsBody(opts.options) }
+  };
 }
-function waitpointTokenCreateBody(runId2, waitpointId, opts) {
+function runOptionsBody(opts) {
+  if (opts === undefined)
+    return {};
+  return {
+    ...opts.deploymentId === undefined ? {} : { deployment_id: opts.deploymentId },
+    ...opts.version === undefined ? {} : { version: opts.version },
+    ...opts.queue === undefined ? {} : { queue: { name: opts.queue } },
+    ...opts.concurrencyKey === undefined ? {} : { concurrency_key: opts.concurrencyKey },
+    ...opts.priority === undefined ? {} : { priority: opts.priority },
+    ...opts.ttl === undefined ? {} : { ttl: opts.ttl },
+    ...opts.maxDurationSeconds === undefined ? {} : { max_duration_seconds: opts.maxDurationSeconds }
+  };
+}
+function scheduleScopeQuery(opts) {
+  const query = new URLSearchParams;
+  if (opts.projectId !== undefined)
+    query.set("project_id", opts.projectId);
+  if (opts.environmentId !== undefined)
+    query.set("environment_id", opts.environmentId);
+  return query;
+}
+function scheduleFromResponse(response) {
+  return {
+    id: response.id,
+    type: response.type,
+    projectId: response.project_id,
+    environmentId: response.environment_id,
+    task: response.task,
+    ...response.deduplication_key === undefined || response.deduplication_key === "" ? {} : { deduplicationKey: response.deduplication_key },
+    ...response.external_id === undefined || response.external_id === "" ? {} : { externalId: response.external_id },
+    cron: response.cron,
+    timezone: response.timezone,
+    active: response.active,
+    status: response.status,
+    ...response.last_error === undefined || response.last_error === "" ? {} : { lastError: response.last_error },
+    ..."workspace" in response ? { workspace: response.workspace } : {},
+    ...response.next_scheduled_at === undefined ? {} : { nextScheduledAt: response.next_scheduled_at },
+    ...response.last_scheduled_at === undefined ? {} : { lastScheduledAt: response.last_scheduled_at },
+    createdAt: response.created_at,
+    updatedAt: response.updated_at
+  };
+}
+function waitpointTokenCreateBody(waitpointId, opts) {
   return {
-    run_id: runId2,
     waitpoint_id: waitpointId,
-    ...opts.actions === undefined ? {} : { actions: opts.actions },
     ...opts.expiresInSeconds === undefined ? {} : { expires_in_seconds: opts.expiresInSeconds },
     ...opts.expiresAt === undefined ? {} : { expires_at: opts.expiresAt },
     ...opts.metadata === undefined ? {} : { metadata: opts.metadata }
   };
 }
-function waitpointTokenCompleteBody(token, opts) {
+function waitpointCreateBody(opts) {
   return {
-    token,
-    action: opts.action,
-    ..."reason" in opts && opts.reason === undefined ? {} : ("reason" in opts) ? { reason: opts.reason } : {},
-    ..."text" in opts ? { text: opts.text } : {},
+    ...opts.projectId === undefined ? {} : { project_id: opts.projectId },
+    ...opts.environmentId === undefined ? {} : { environment_id: opts.environmentId },
+    ...opts.request === undefined ? {} : { request: opts.request },
+    ...opts.displayText === undefined ? {} : { display_text: opts.displayText },
+    expires_at: opts.expiresAt,
+    ...opts.idempotencyKey === undefined ? {} : { idempotency_key: opts.idempotencyKey },
+    ...opts.idempotencyKeyExpiresAt === undefined ? {} : { idempotency_key_expires_at: opts.idempotencyKeyExpiresAt },
+    ...opts.idempotencyKeyTTLSeconds === undefined ? {} : { idempotency_key_ttl_seconds: opts.idempotencyKeyTTLSeconds }
+  };
+}
+function waitpointFromResponse(response) {
+  return {
+    id: response.id,
+    projectId: response.project_id,
+    environmentId: response.environment_id,
+    kind: response.kind,
+    status: response.status,
+    request: response.request ?? {},
+    displayText: response.display_text ?? "",
+    expiresAt: response.expires_at ?? null,
+    createdAt: response.created_at
+  };
+}
+function waitpointRespondBody(opts) {
+  return {
+    ..."value" in opts ? { value: opts.value } : {},
     ...opts.externalSubject === undefined ? {} : { external_subject: opts.externalSubject },
     ...opts.metadata === undefined ? {} : { metadata: opts.metadata }
   };
 }
-function resolveWaitpointTokenCompleteArgs(id, token, opts) {
+function waitpointTokenRespondBody(token, opts) {
+  return {
+    token,
+    ...waitpointRespondBody(opts)
+  };
+}
+function resolveWaitpointTokenRespondArgs(id, token, opts) {
   if (typeof token !== "string" || opts === undefined) {
-    throw new Error("waitpoint token secret is required when completing by token id");
+    throw new Error("waitpoint token secret is required when responding by token id");
   }
   return { id, token, opts };
 }
 function waitpointResponseTokenFromResponse(response) {
   return {
     id: response.id,
-    runId: response.run_id,
     waitpointId: response.waitpoint_id,
     url: response.url,
     token: response.token,
@@ -709,27 +1142,21 @@ function waitpointResponseTokenFromResponse(response) {
 }
 function resolveWaitpointArgs(target, waitpointIdOrOpts, opts) {
   if (isWaitpointRef(target)) {
-    const resolvedOpts = waitpointIdOrOpts !== undefined && typeof waitpointIdOrOpts !== "string" ? waitpointIdOrOpts : opts;
     return {
-      runId: target.runId,
       waitpointId: target.waitpointId,
-      opts: resolvedOpts ?? {}
+      opts: waitpointIdOrOpts ?? opts ?? {}
     };
   }
-  if (typeof waitpointIdOrOpts !== "string") {
-    throw new Error("waitpoint id is required when resolving a waitpoint by run id");
-  }
   return {
-    runId: target,
-    waitpointId: waitpointIdOrOpts,
-    opts: opts ?? {}
+    waitpointId: target,
+    opts: waitpointIdOrOpts ?? opts ?? {}
   };
 }
 function isWaitpointRef(value) {
   if (value === null || typeof value !== "object")
     return false;
   const record = value;
-  return typeof record["runId"] === "string" && typeof record["waitpointId"] === "string";
+  return typeof record["waitpointId"] === "string";
 }
 function retrieveOptions(signal) {
   return signal === undefined ? {} : { signal };
@@ -831,7 +1258,14 @@ function parseSseFrame(raw) {
   if (data === "") {
     return;
   }
-  return runEventRecordToRunEvent(JSON.parse(data));
+  try {
+    return runEventRecordToRunEvent(JSON.parse(data));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return;
+    }
+    throw error;
+  }
 }
 function findSseBoundary(buffer) {
   const lf = buffer.indexOf(`
@@ -847,121 +1281,102 @@ function findSseBoundary(buffer) {
   return Math.min(lf, crlf);
 }
 function runEventRecordToRunEvent(event) {
-  const attributes = objectRecord(event.attributes);
-  const runId2 = event.run_id ?? stringValue(attributes?.["run_id"]) ?? "";
-  if (event.message === "log.stdout" || event.message === "log.stderr") {
-    const stream = event.message === "log.stdout" ? "stdout" : "stderr";
+  const record = objectRecord(event);
+  const message = stringValue(record?.["message"]);
+  const at = stringValue(record?.["at"]);
+  if (record === undefined || message === undefined || at === undefined) {
+    return;
+  }
+  const attributes = objectRecord(record["attributes"]);
+  const runId2 = stringValue(record["run_id"]) ?? stringValue(attributes?.["run_id"]) ?? "";
+  if (message === "log.stdout" || message === "log.stderr") {
+    const stream = message === "log.stdout" ? "stdout" : "stderr";
     return {
       type: "log",
       run_id: runId2,
       stream,
       bytes: numberValue(attributes?.["bytes"]) ?? 0,
       observed_seq: numberValue(attributes?.["observed_seq"]) ?? 0,
-      at: event.at
+      at
     };
   }
-  if (event.message === "waitpoint.requested" && stringValue(attributes?.["kind"]) === "approval") {
-    const message = stringValue(attributes?.["display_text"]);
+  if (message === "waitpoint.requested") {
     const waitpointId = stringValue(attributes?.["waitpoint_id"]);
+    const kind = stringValue(attributes?.["kind"]);
     if (waitpointId === undefined)
       return;
-    return {
-      type: "approval_request",
-      run_id: runId2,
-      waitpoint_id: waitpointId,
-      message: message ?? "",
-      ...optionalNumber("timeout", attributes?.["timeout"]),
-      at: event.at
-    };
-  }
-  if (event.message === "waitpoint.resolved" && stringValue(attributes?.["kind"]) === "approval") {
-    const waitpointId = stringValue(attributes?.["waitpoint_id"]);
-    const resolution = stringValue(attributes?.["resolution_kind"]);
-    if (waitpointId === undefined)
-      return;
-    if (resolution !== "approved" && resolution !== "denied")
-      return;
-    return {
-      type: "approval_decided",
-      run_id: runId2,
-      waitpoint_id: waitpointId,
-      decision: resolution,
-      ...optionalString("reason", attributes?.["reason"]),
-      at: event.at
-    };
-  }
-  if (event.message === "waitpoint.requested" && stringValue(attributes?.["kind"]) === "message") {
-    const request = objectRecord(attributes?.["request"]);
-    const message = stringValue(attributes?.["display_text"]) ?? stringValue(request?.["prompt"]);
-    const waitpointId = stringValue(attributes?.["waitpoint_id"]);
-    if (waitpointId === undefined)
+    if (kind === undefined)
       return;
     return {
-      type: "message_request",
+      type: "waitpoint_request",
       run_id: runId2,
       waitpoint_id: waitpointId,
-      ...optionalString("prompt", message),
+      kind,
+      displayText: stringValue(attributes?.["display_text"]) ?? "",
+      request: attributes?.["request"] ?? {},
       ...optionalNumber("timeout", attributes?.["timeout"]),
-      at: event.at
+      at
     };
   }
-  if (event.message === "waitpoint.resolved" && stringValue(attributes?.["kind"]) === "message") {
-    const result = objectRecord(attributes?.["result"]);
-    const text = stringValue(result?.["text"]);
+  if (message === "waitpoint.resolved") {
     const waitpointId = stringValue(attributes?.["waitpoint_id"]);
+    const kind = stringValue(attributes?.["kind"]);
+    const resolution = stringValue(attributes?.["resolution_kind"]);
     if (waitpointId === undefined)
       return;
-    if (stringValue(attributes?.["resolution_kind"]) !== "replied")
+    if (kind === undefined || resolution === undefined)
       return;
     return {
-      type: "message_received",
+      type: "waitpoint_resolved",
       run_id: runId2,
       waitpoint_id: waitpointId,
-      text: text ?? "",
-      at: event.at
+      kind,
+      resolutionKind: resolution,
+      value: attributes?.["result"],
+      at
     };
   }
-  if (event.message.startsWith("emit.")) {
+  if (message.startsWith("emit.")) {
     return {
       type: "emit",
       run_id: runId2,
-      event_type: stringValue(attributes?.["type"]) ?? event.message.slice("emit.".length),
+      event_type: stringValue(attributes?.["type"]) ?? message.slice("emit.".length),
       content: attributes?.["content"],
-      at: event.at
+      at
     };
   }
-  if (event.message === "run.completed") {
+  if (message === "run.completed") {
     return {
-      type: "task_complete",
+      type: "task_result",
       run_id: runId2,
       exit_code: numberValue(attributes?.["exit_code"]) ?? 0,
-      at: event.at
+      at
     };
   }
-  if (event.message === "run.failed") {
+  if (message === "run.failed") {
     return {
       type: "run_failed",
       run_id: runId2,
       failure_kind: stringValue(attributes?.["failure_kind"]) ?? "task_failed",
       detail: attributes?.["detail"],
-      at: event.at
+      at
     };
   }
-  if (event.message === "run.timeout") {
+  if (message === "run.cancelled") {
     return {
-      type: "run_timeout",
+      type: "run_cancelled",
       run_id: runId2,
-      elapsed_secs: numberValue(attributes?.["elapsed_active_secs"]) ?? 0,
-      limit_secs: numberValue(attributes?.["limit_secs"]) ?? 0,
-      at: event.at
+      ...optionalString("reason", attributes?.["reason"]),
+      at
     };
   }
-  if (event.message === "run.cancelled") {
+  if (message === "run.expired") {
     return {
-      type: "run_cancelled",
+      type: "run_expired",
       run_id: runId2,
-      ...optionalString("reason", attributes?.["reason"]),
-      at: event.at
+      ...optionalString("ttl", attributes?.["ttl"]),
+      ...optionalString("message", attributes?.["message"]),
+      at
     };
   }
   return;
@@ -1039,11 +1454,6 @@ function defineConfig(config) {
   });
 }
 
-// sdk/typescript/src/task.ts
-function task(config) {
-  return markTask(config);
-}
-
 // sdk/typescript/src/trigger.ts
 var defaultClient;
 function getDefaultClient() {
@@ -1051,10 +1461,102 @@ function getDefaultClient() {
   return defaultClient;
 }
 var tasks = {
-  trigger(task2, opts) {
-    return getDefaultClient().tasks.trigger(task2, opts);
+  trigger(...args) {
+    return getDefaultClient().tasks.trigger(...args);
   }
 };
+function triggerTask(task, ...args) {
+  return getDefaultClient()[triggerTaskClientMethod](task, ...args);
+}
+
+// sdk/typescript/src/task.ts
+function task(config) {
+  const marked = markTask(config);
+  Object.defineProperty(marked, "trigger", {
+    value: (...args) => triggerTask(marked, ...args)
+  });
+  return marked;
+}
+function queue(config) {
+  return Object.freeze({ ...config });
+}
+
+// sdk/typescript/src/schedules.ts
+function task2(config) {
+  const { cron, workspace, secretBindings, ...taskConfig } = config;
+  const taskId = config.id;
+  if (cron !== undefined && workspace === undefined) {
+    throw new Error(`task ${JSON.stringify(taskId)} schedule workspace is required`);
+  }
+  const schedule = cron === undefined ? undefined : {
+    cron: typeof cron === "string" ? cron : cron.pattern,
+    ...typeof cron === "string" || cron.timezone === undefined ? {} : { timezone: cron.timezone },
+    workspace,
+    ...secretBindings === undefined ? {} : { secretBindings }
+  };
+  const marked = markScheduledTask({ ...taskConfig, payload: scheduledTaskPayloadSchema }, schedule);
+  Object.defineProperty(marked, "trigger", {
+    value: (...args) => triggerTask(marked, ...args)
+  });
+  return marked;
+}
+var scheduledTaskPayloadSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "helmr",
+    validate(value) {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return { issues: [{ message: "expected scheduled task payload object" }] };
+      }
+      const input = value;
+      const timestamp = parseDateField(input["timestamp"], "timestamp");
+      const lastTimestamp = parseOptionalDateField(input["lastTimestamp"], "lastTimestamp");
+      const timezone = input["timezone"];
+      const scheduleId = input["scheduleId"];
+      const externalId = input["externalId"];
+      const upcoming = input["upcoming"];
+      const issues = [
+        ...timestamp.issues,
+        ...lastTimestamp.issues,
+        ...typeof timezone === "string" && timezone.trim() !== "" ? [] : [{ message: "expected string", path: ["timezone"] }],
+        ...typeof scheduleId === "string" && scheduleId.trim() !== "" ? [] : [{ message: "expected string", path: ["scheduleId"] }],
+        ...externalId === undefined || typeof externalId === "string" ? [] : [{ message: "expected string", path: ["externalId"] }],
+        ...Array.isArray(upcoming) ? [] : [{ message: "expected array", path: ["upcoming"] }]
+      ];
+      const upcomingDates = Array.isArray(upcoming) ? upcoming.map((item, index) => parseDateField(item, `upcoming.${index}`)) : [];
+      issues.push(...upcomingDates.flatMap((item) => item.issues));
+      if (issues.length > 0) {
+        return { issues };
+      }
+      return {
+        value: {
+          timestamp: timestamp.value,
+          ...lastTimestamp.value === undefined ? {} : { lastTimestamp: lastTimestamp.value },
+          timezone,
+          scheduleId,
+          ...externalId === undefined ? {} : { externalId },
+          upcoming: upcomingDates.map((item) => item.value)
+        }
+      };
+    }
+  }
+};
+function parseDateField(value, path) {
+  if (typeof value !== "string") {
+    return { value: new Date(0), issues: [{ message: "expected ISO timestamp", path: path.split(".") }] };
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return { value: new Date(0), issues: [{ message: "expected ISO timestamp", path: path.split(".") }] };
+  }
+  return { value: date, issues: [] };
+}
+function parseOptionalDateField(value, path) {
+  if (value === undefined || value === null) {
+    return { issues: [] };
+  }
+  return parseDateField(value, path);
+}
 // sdk/typescript/src/index.ts
 var image = (id) => new ImageBuilderImpl(id);
 var cache = (id) => ({ id });
@@ -1097,6 +1599,16 @@ var waitpoints = new Proxy({}, {
     return Reflect.get(getDefaultClient().waitpoints, property, receiver);
   }
 });
+var schedules = Object.freeze({
+  task: task2,
+  create: (...args) => getDefaultClient().schedules.create(...args),
+  update: (...args) => getDefaultClient().schedules.update(...args),
+  list: (...args) => getDefaultClient().schedules.list(...args),
+  retrieve: (...args) => getDefaultClient().schedules.retrieve(...args),
+  activate: (...args) => getDefaultClient().schedules.activate(...args),
+  deactivate: (...args) => getDefaultClient().schedules.deactivate(...args),
+  delete: (...args) => getDefaultClient().schedules.delete(...args)
+});
 export {
   workspace,
   waitpoints,
@@ -1104,17 +1616,19 @@ export {
   tasks,
   task,
   source,
+  schedules,
   sandbox,
   runs,
+  queue,
   image,
+  idempotencyKeys,
   defineConfig,
   cache,
   UnsupportedTransportError,
   TimeoutError,
   RunNotFoundError,
-  MessageTimeoutError,
+  PayloadSchemaValidationError,
   HelmrClient,
   ConcurrentWaitError,
-  AuthError,
-  ApprovalTimeoutError
+  AuthError
 };