@cuylabs/agent-runtime 0.5.0

package/dist/chunk-H6BHDIUX.js

@@ -0,0 +1,1466 @@
+import {
+  computeNextRunAtMs,
+  normalizeSchedule
+} from "./chunk-ZVISWF7S.js";
+
+// src/orchestration/types.ts
+var TERMINAL_STATUSES = {
+  queued: void 0,
+  running: void 0,
+  completed: true,
+  failed: true,
+  cancelled: true
+};
+function isTerminalRunStatus(status) {
+  return TERMINAL_STATUSES[status] === true;
+}
+
+// src/orchestration/stores/in-memory.ts
+function cloneRun(run) {
+  return structuredClone(run);
+}
+var InMemoryOrchestratorRunStore = class {
+  runs = /* @__PURE__ */ new Map();
+  async get(runId) {
+    const current = this.runs.get(runId);
+    return current ? cloneRun(current) : void 0;
+  }
+  async list() {
+    return [...this.runs.values()].map((entry) => cloneRun(entry)).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+  async upsert(run) {
+    const copy = cloneRun(run);
+    this.runs.set(copy.id, copy);
+    return cloneRun(copy);
+  }
+  async remove(runId) {
+    return this.runs.delete(runId);
+  }
+};
+
+// src/orchestration/service.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/logger.ts
+function noop() {
+}
+var silentRuntimeLogger = {
+  debug: noop,
+  info: noop,
+  warn: noop,
+  error: noop
+};
+function createConsoleRuntimeLogger(prefix = "agent-runtime") {
+  function format(message, meta) {
+    return meta ? `[${prefix}] ${message} ${JSON.stringify(meta)}` : `[${prefix}] ${message}`;
+  }
+  return {
+    debug(message, meta) {
+      console.debug(format(message, meta));
+    },
+    info(message, meta) {
+      console.info(format(message, meta));
+    },
+    warn(message, meta) {
+      console.warn(format(message, meta));
+    },
+    error(message, meta) {
+      console.error(format(message, meta));
+    }
+  };
+}
+
+// src/runtime.ts
+import { randomUUID } from "crypto";
+var DEFAULT_MAX_CONCURRENT_RUNS = 4;
+var DEFAULT_EXECUTION_TIMEOUT_MS = 15 * 60 * 1e3;
+var DEFAULT_ABORT_IN_FLIGHT_ON_STOP = true;
+var MAX_JOB_ID_LENGTH = 256;
+var MAX_JOB_NAME_LENGTH = 256;
+var MAX_METADATA_ENTRIES = 64;
+var MAX_METADATA_KEY_LENGTH = 128;
+var MAX_METADATA_VALUE_LENGTH = 2048;
+function normalizeExecutionTimeoutMs(value) {
+  if (value === void 0) {
+    return DEFAULT_EXECUTION_TIMEOUT_MS;
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(`executionTimeoutMs must be a finite number. Received: ${String(value)}`);
+  }
+  const normalized = Math.floor(value);
+  if (normalized <= 0) {
+    return void 0;
+  }
+  return normalized;
+}
+function normalizeMaxQueuedDispatches(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(`maxQueuedDispatches must be a finite number. Received: ${String(value)}`);
+  }
+  return Math.max(0, Math.floor(value));
+}
+function normalizeJobId(jobId) {
+  const normalized = jobId.trim();
+  if (!normalized) {
+    throw new Error("Job id must not be empty");
+  }
+  if (normalized.length > MAX_JOB_ID_LENGTH) {
+    throw new Error(
+      `Job id exceeds max length (${MAX_JOB_ID_LENGTH}). Received: ${normalized.length}`
+    );
+  }
+  return normalized;
+}
+function normalizeJobName(name) {
+  const normalized = name.trim();
+  if (!normalized) {
+    throw new Error("Job name must not be empty");
+  }
+  if (normalized.length > MAX_JOB_NAME_LENGTH) {
+    throw new Error(
+      `Job name exceeds max length (${MAX_JOB_NAME_LENGTH}). Received: ${normalized.length}`
+    );
+  }
+  return normalized;
+}
+function validateMetadata(metadata) {
+  if (!metadata) {
+    return;
+  }
+  const entries = Object.entries(metadata);
+  if (entries.length > MAX_METADATA_ENTRIES) {
+    throw new Error(
+      `Job metadata exceeds max entries (${MAX_METADATA_ENTRIES}). Received: ${entries.length}`
+    );
+  }
+  for (const [key, value] of entries) {
+    const normalizedKey = key.trim();
+    if (!normalizedKey) {
+      throw new Error("Job metadata keys must not be empty");
+    }
+    if (normalizedKey.length > MAX_METADATA_KEY_LENGTH) {
+      throw new Error(
+        `Job metadata key exceeds max length (${MAX_METADATA_KEY_LENGTH}). Received: ${normalizedKey.length}`
+      );
+    }
+    if (value.length > MAX_METADATA_VALUE_LENGTH) {
+      throw new Error(
+        `Job metadata value exceeds max length (${MAX_METADATA_VALUE_LENGTH}) for key "${normalizedKey}"`
+      );
+    }
+  }
+}
+function normalizeRetryPolicy(policy) {
+  if (!policy) {
+    return void 0;
+  }
+  if (!Number.isFinite(policy.maxAttempts)) {
+    throw new Error(`retryPolicy.maxAttempts must be a finite number. Received: ${String(policy.maxAttempts)}`);
+  }
+  const maxAttempts = Math.max(1, Math.floor(policy.maxAttempts));
+  const strategy = policy.strategy ?? "fixed";
+  if (strategy !== "fixed" && strategy !== "exponential") {
+    throw new Error(`retryPolicy.strategy must be "fixed" or "exponential". Received: ${String(policy.strategy)}`);
+  }
+  let backoffMs;
+  if (policy.backoffMs !== void 0) {
+    if (!Number.isFinite(policy.backoffMs) || policy.backoffMs < 0) {
+      throw new Error(`retryPolicy.backoffMs must be a non-negative finite number. Received: ${String(policy.backoffMs)}`);
+    }
+    backoffMs = Math.floor(policy.backoffMs);
+  }
+  let maxBackoffMs;
+  if (policy.maxBackoffMs !== void 0) {
+    if (!Number.isFinite(policy.maxBackoffMs) || policy.maxBackoffMs < 0) {
+      throw new Error(
+        `retryPolicy.maxBackoffMs must be a non-negative finite number. Received: ${String(policy.maxBackoffMs)}`
+      );
+    }
+    maxBackoffMs = Math.floor(policy.maxBackoffMs);
+  }
+  return {
+    maxAttempts,
+    ...backoffMs !== void 0 ? { backoffMs } : {},
+    strategy,
+    ...maxBackoffMs !== void 0 ? { maxBackoffMs } : {}
+  };
+}
+function computeRetryDelayMs(policy, attempt) {
+  const baseDelay = policy.backoffMs ?? 0;
+  if (baseDelay <= 0) {
+    return 0;
+  }
+  if (policy.strategy === "exponential") {
+    const rawDelay = baseDelay * 2 ** Math.max(0, attempt - 1);
+    return policy.maxBackoffMs !== void 0 ? Math.min(rawDelay, policy.maxBackoffMs) : rawDelay;
+  }
+  return policy.maxBackoffMs !== void 0 ? Math.min(baseDelay, policy.maxBackoffMs) : baseDelay;
+}
+function waitForSignalOrTimeout(ms, signal) {
+  if (ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    timeout.unref?.();
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(new Error("aborted"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var AgentRuntime = class {
+  driver;
+  executeJob;
+  logger;
+  maxConcurrentRuns;
+  maxQueuedDispatches;
+  createId;
+  executionTimeoutMs;
+  abortInFlightOnStop;
+  onDeadLetter;
+  observers;
+  started = false;
+  activeRuns = 0;
+  inFlight = /* @__PURE__ */ new Set();
+  runControllers = /* @__PURE__ */ new Map();
+  pendingDispatches = [];
+  pendingDispatchByJobId = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.driver = options.driver;
+    this.executeJob = options.execute;
+    this.logger = options.logger ?? silentRuntimeLogger;
+    this.maxConcurrentRuns = Math.max(
+      1,
+      Math.floor(options.maxConcurrentRuns ?? DEFAULT_MAX_CONCURRENT_RUNS)
+    );
+    this.maxQueuedDispatches = normalizeMaxQueuedDispatches(options.maxQueuedDispatches);
+    this.createId = options.createId ?? (() => randomUUID());
+    this.executionTimeoutMs = normalizeExecutionTimeoutMs(options.executionTimeoutMs);
+    this.abortInFlightOnStop = options.abortInFlightOnStop ?? DEFAULT_ABORT_IN_FLIGHT_ON_STOP;
+    this.onDeadLetter = options.onDeadLetter;
+    this.observers = options.observers ?? [];
+  }
+  async forEachObserver(label, meta, fn) {
+    for (const observer of this.observers) {
+      try {
+        await fn(observer);
+      } catch (error) {
+        this.logger.error(`Runtime observer failed during ${label}`, {
+          ...meta,
+          error: String(error)
+        });
+      }
+    }
+  }
+  async start() {
+    if (this.started) {
+      return;
+    }
+    this.started = true;
+    try {
+      await this.driver.start({
+        now: () => Date.now(),
+        logger: this.logger,
+        onDue: async (jobId) => {
+          return await this.dispatchDue(jobId);
+        }
+      });
+      await this.forEachObserver("runtime start", { driver: this.driver.name }, async (observer) => {
+        await observer.notifyRuntimeStart?.({
+          driver: this.driver.name,
+          at: Date.now()
+        });
+      });
+      this.logger.info("Runtime started", { driver: this.driver.name });
+    } catch (error) {
+      this.started = false;
+      throw error;
+    }
+  }
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+    if (this.abortInFlightOnStop && this.runControllers.size > 0) {
+      this.logger.warn("Aborting in-flight runtime jobs during stop", {
+        count: this.runControllers.size
+      });
+      for (const controller of this.runControllers.values()) {
+        controller.abort();
+      }
+    }
+    if (this.pendingDispatches.length > 0) {
+      const error = new Error("Runtime stopped before queued jobs could start");
+      for (const pending of this.pendingDispatches.splice(0)) {
+        this.pendingDispatchByJobId.delete(pending.jobId);
+        pending.reject(error);
+      }
+    }
+    await this.driver.stop();
+    await this.forEachObserver("runtime stop", { driver: this.driver.name }, async (observer) => {
+      await observer.notifyRuntimeStop?.({
+        driver: this.driver.name,
+        at: Date.now()
+      });
+    });
+    this.logger.info("Runtime stopped", { driver: this.driver.name });
+  }
+  status() {
+    return {
+      started: this.started,
+      driver: this.driver.name,
+      inFlightJobs: [...this.inFlight],
+      queuedJobs: this.pendingDispatches.map((entry) => entry.jobId),
+      maxConcurrentRuns: this.maxConcurrentRuns,
+      ...this.maxQueuedDispatches !== void 0 ? { maxQueuedDispatches: this.maxQueuedDispatches } : {}
+    };
+  }
+  async listJobs() {
+    return await this.driver.listJobs();
+  }
+  async getJob(jobId) {
+    if (this.driver.getJob) {
+      return await this.driver.getJob(jobId);
+    }
+    const jobs = await this.driver.listJobs();
+    return jobs.find((entry) => entry.id === jobId);
+  }
+  async schedule(input) {
+    const now = Date.now();
+    const existing = input.id ? await this.getJob(input.id) : void 0;
+    const schedule = normalizeSchedule(input.schedule);
+    const jobId = normalizeJobId(input.id ?? this.createId());
+    const name = normalizeJobName(input.name);
+    const metadata = input.metadata ?? existing?.metadata;
+    const retryPolicy = normalizeRetryPolicy(input.retryPolicy ?? existing?.retryPolicy);
+    validateMetadata(metadata);
+    let enabled = input.enabled ?? existing?.enabled ?? true;
+    let nextRunAtMs = enabled ? computeNextRunAtMs(schedule, now) : void 0;
+    if (enabled && schedule.kind === "at" && nextRunAtMs === void 0) {
+      enabled = false;
+      nextRunAtMs = void 0;
+    }
+    const record = {
+      id: jobId,
+      name,
+      payload: input.payload,
+      schedule,
+      ...retryPolicy ? { retryPolicy } : {},
+      enabled,
+      metadata,
+      createdAt: existing?.createdAt ?? new Date(now).toISOString(),
+      updatedAt: new Date(now).toISOString(),
+      state: {
+        ...existing?.state,
+        nextRunAtMs
+      }
+    };
+    return await this.driver.upsertJob(record);
+  }
+  async update(jobId, patch) {
+    const current = await this.requireJob(jobId);
+    const now = Date.now();
+    const name = normalizeJobName(patch.name ?? current.name);
+    const nextSchedule = patch.schedule ? normalizeSchedule(patch.schedule) : current.schedule;
+    const retryPolicy = normalizeRetryPolicy(patch.retryPolicy ?? current.retryPolicy);
+    let enabled = patch.enabled ?? current.enabled;
+    const metadata = patch.metadata ?? current.metadata;
+    validateMetadata(metadata);
+    let nextRunAtMs = current.state.nextRunAtMs;
+    if (patch.schedule || patch.enabled !== void 0) {
+      nextRunAtMs = enabled ? computeNextRunAtMs(nextSchedule, now) : void 0;
+    }
+    if (enabled && nextSchedule.kind === "at" && nextRunAtMs === void 0) {
+      enabled = false;
+      nextRunAtMs = void 0;
+    }
+    const nextRecord = {
+      ...current,
+      name,
+      payload: patch.payload ?? current.payload,
+      schedule: nextSchedule,
+      retryPolicy,
+      enabled,
+      metadata,
+      updatedAt: new Date(now).toISOString(),
+      state: {
+        ...current.state,
+        nextRunAtMs
+      }
+    };
+    return await this.driver.upsertJob(nextRecord);
+  }
+  async pause(jobId) {
+    return await this.update(jobId, { enabled: false });
+  }
+  async resume(jobId) {
+    return await this.update(jobId, { enabled: true });
+  }
+  async remove(jobId) {
+    return await this.driver.removeJob(jobId);
+  }
+  async runNow(jobId) {
+    return await this.dispatch({ jobId, trigger: "manual" });
+  }
+  async dispatch(input) {
+    return await this.runJob(input.jobId, input.trigger);
+  }
+  async dispatchDue(jobId) {
+    return await this.dispatch({ jobId, trigger: "due" });
+  }
+  async runJob(jobId, trigger) {
+    const reservation = this.tryReserveRun(jobId);
+    if (reservation === "already-running") {
+      const startedAt = Date.now();
+      return {
+        jobId,
+        trigger,
+        startedAt,
+        endedAt: startedAt,
+        status: "skipped",
+        error: "Job already running"
+      };
+    }
+    if (reservation === "queued") {
+      return await this.enqueuePendingDispatch(jobId, trigger);
+    }
+    return await this.executeReservedJob(jobId, trigger);
+  }
+  async requireJob(jobId) {
+    const current = await this.getJob(jobId);
+    if (!current) {
+      throw new Error(`Job not found: ${jobId}`);
+    }
+    return current;
+  }
+  tryReserveRun(jobId) {
+    if (this.inFlight.has(jobId)) {
+      return "already-running";
+    }
+    if (this.activeRuns >= this.maxConcurrentRuns) {
+      return "queued";
+    }
+    this.inFlight.add(jobId);
+    this.activeRuns += 1;
+    return "reserved";
+  }
+  async enqueuePendingDispatch(jobId, trigger) {
+    const existing = this.pendingDispatchByJobId.get(jobId);
+    if (existing) {
+      if (existing.trigger === "due" && trigger === "manual") {
+        existing.trigger = "manual";
+      }
+      return await existing.promise;
+    }
+    if (this.maxQueuedDispatches !== void 0 && this.pendingDispatches.length >= this.maxQueuedDispatches) {
+      const startedAt = Date.now();
+      await this.forEachObserver(
+        "dispatch dropped",
+        { jobId, trigger, queueLength: this.pendingDispatches.length },
+        async (observer) => {
+          await observer.notifyDispatchDropped?.({
+            jobId,
+            trigger,
+            droppedAt: startedAt,
+            queueLength: this.pendingDispatches.length,
+            reason: `Runtime dispatch queue is full (${this.maxQueuedDispatches})`
+          });
+        }
+      );
+      return {
+        jobId,
+        trigger,
+        startedAt,
+        endedAt: startedAt,
+        status: "skipped",
+        error: `Runtime dispatch queue is full (${this.maxQueuedDispatches})`
+      };
+    }
+    let resolvePending;
+    let rejectPending;
+    const promise = new Promise((resolve, reject) => {
+      resolvePending = resolve;
+      rejectPending = reject;
+    });
+    const pending = {
+      jobId,
+      trigger,
+      enqueuedAt: Date.now(),
+      promise,
+      resolve: resolvePending,
+      reject: rejectPending
+    };
+    this.pendingDispatches.push(pending);
+    this.pendingDispatchByJobId.set(jobId, pending);
+    await this.forEachObserver(
+      "dispatch queued",
+      { jobId, trigger, queueLength: this.pendingDispatches.length },
+      async (observer) => {
+        await observer.notifyDispatchQueued?.({
+          jobId,
+          trigger,
+          queuedAt: pending.enqueuedAt,
+          queueLength: this.pendingDispatches.length
+        });
+      }
+    );
+    this.logger.debug("Queued runtime job dispatch", {
+      jobId,
+      trigger,
+      queueLength: this.pendingDispatches.length
+    });
+    return await promise;
+  }
+  async executeJobAttempt(params) {
+    const attemptStartedAt = Date.now();
+    const attemptController = new AbortController();
+    const onRunAbort = () => attemptController.abort();
+    params.runSignal.addEventListener("abort", onRunAbort, { once: true });
+    let timeoutHandle;
+    let timedOut = false;
+    const deadlineAt = this.executionTimeoutMs ? attemptStartedAt + this.executionTimeoutMs : void 0;
+    if (this.executionTimeoutMs !== void 0) {
+      timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        attemptController.abort();
+      }, this.executionTimeoutMs);
+      timeoutHandle.unref?.();
+    }
+    let status = "ok";
+    let errorMessage;
+    try {
+      const result = await this.executeJob(params.job, {
+        trigger: params.trigger,
+        startedAt: attemptStartedAt,
+        attempt: params.attempt,
+        signal: attemptController.signal,
+        deadlineAt
+      });
+      if (result && typeof result === "object") {
+        status = result.status ?? status;
+        errorMessage = result.error ?? errorMessage;
+      }
+      if (timedOut) {
+        status = "error";
+        errorMessage = `Execution timed out after ${this.executionTimeoutMs}ms`;
+      } else if (params.runSignal.aborted && !this.started) {
+        status = "error";
+        errorMessage = "Execution aborted because runtime stopped";
+      }
+      if (status === "error" && !errorMessage) {
+        errorMessage = "Execution returned error status";
+      }
+    } catch (error) {
+      status = "error";
+      if (timedOut) {
+        errorMessage = `Execution timed out after ${this.executionTimeoutMs}ms`;
+      } else if (params.runSignal.aborted && !this.started) {
+        errorMessage = "Execution aborted because runtime stopped";
+      } else {
+        errorMessage = error instanceof Error ? error.message : String(error);
+      }
+    } finally {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      params.runSignal.removeEventListener("abort", onRunAbort);
+    }
+    return {
+      status,
+      ...errorMessage ? { errorMessage } : {}
+    };
+  }
+  async emitDeadLetter(event) {
+    if (!this.onDeadLetter) {
+      await this.forEachObserver("dead letter", { jobId: event.job.id }, async (observer) => {
+        await observer.notifyDeadLetter?.(event);
+      });
+      return;
+    }
+    try {
+      await this.onDeadLetter(event);
+    } catch (error) {
+      this.logger.error("Runtime dead-letter handler failed", {
+        jobId: event.job.id,
+        error: String(error)
+      });
+    }
+    await this.forEachObserver("dead letter", { jobId: event.job.id }, async (observer) => {
+      await observer.notifyDeadLetter?.(event);
+    });
+  }
+  async executeReservedJob(jobId, trigger) {
+    const startedAt = Date.now();
+    try {
+      const job = await this.getJob(jobId);
+      if (!job) {
+        return {
+          jobId,
+          trigger,
+          startedAt,
+          endedAt: startedAt,
+          status: "skipped",
+          error: "Job not found"
+        };
+      }
+      if (trigger === "due" && !job.enabled) {
+        return {
+          jobId,
+          trigger,
+          startedAt,
+          endedAt: startedAt,
+          status: "skipped",
+          error: "Job is disabled"
+        };
+      }
+      await this.driver.upsertJob({
+        ...job,
+        state: {
+          ...job.state,
+          running: true
+        }
+      }).catch((error) => {
+        this.logger.warn("Failed to mark job as running", {
+          jobId,
+          error: String(error)
+        });
+      });
+      await this.forEachObserver("run start", { jobId, trigger }, async (observer) => {
+        await observer.notifyRunStart?.({
+          job,
+          trigger,
+          startedAt
+        });
+      });
+      const retryPolicy = normalizeRetryPolicy(job.retryPolicy);
+      const maxAttempts = retryPolicy?.maxAttempts ?? 1;
+      const abortController = new AbortController();
+      this.runControllers.set(jobId, abortController);
+      let status = "ok";
+      let errorMessage;
+      let attemptCount = 0;
+      let deadLettered = false;
+      try {
+        while (attemptCount < maxAttempts) {
+          attemptCount += 1;
+          const attemptResult = await this.executeJobAttempt({
+            job,
+            trigger,
+            attempt: attemptCount,
+            runSignal: abortController.signal
+          });
+          status = attemptResult.status;
+          errorMessage = attemptResult.errorMessage;
+          if (status !== "error" || abortController.signal.aborted || attemptCount >= maxAttempts) {
+            break;
+          }
+          const delayMs = retryPolicy ? computeRetryDelayMs(retryPolicy, attemptCount) : 0;
+          this.logger.warn("Retrying runtime job after failure", {
+            jobId,
+            trigger,
+            attempt: attemptCount,
+            maxAttempts,
+            delayMs,
+            error: errorMessage
+          });
+          await this.forEachObserver(
+            "run retry",
+            { jobId, trigger, attempt: attemptCount, nextAttempt: attemptCount + 1 },
+            async (observer) => {
+              await observer.notifyRunRetry?.({
+                job,
+                trigger,
+                attempt: attemptCount,
+                nextAttempt: attemptCount + 1,
+                delayMs,
+                ...errorMessage ? { error: errorMessage } : {}
+              });
+            }
+          );
+          try {
+            await waitForSignalOrTimeout(delayMs, abortController.signal);
+          } catch {
+            if (abortController.signal.aborted && !this.started) {
+              status = "error";
+              errorMessage = "Execution aborted because runtime stopped";
+            }
+            break;
+          }
+        }
+        deadLettered = status === "error" && !abortController.signal.aborted && maxAttempts > 1 && attemptCount >= maxAttempts && Boolean(errorMessage);
+      } finally {
+        this.runControllers.delete(jobId);
+      }
+      const endedAt = Date.now();
+      const latest = await this.getJob(jobId) ?? job;
+      let enabled = latest.enabled;
+      let nextRunAtMs;
+      if (!enabled) {
+        nextRunAtMs = void 0;
+      } else if (latest.schedule.kind === "at") {
+        enabled = false;
+        nextRunAtMs = void 0;
+      } else {
+        nextRunAtMs = computeNextRunAtMs(latest.schedule, endedAt);
+      }
+      const persisted = {
+        ...latest,
+        enabled,
+        updatedAt: new Date(endedAt).toISOString(),
+        state: {
+          ...latest.state,
+          running: false,
+          lastRunAtMs: endedAt,
+          lastStatus: status,
+          lastError: status === "error" ? errorMessage : void 0,
+          ...attemptCount > 0 ? { lastAttemptCount: attemptCount } : {},
+          ...deadLettered ? {
+            deadLetterCount: (latest.state.deadLetterCount ?? 0) + 1,
+            lastDeadLetterAtMs: endedAt
+          } : {},
+          nextRunAtMs
+        }
+      };
+      await this.driver.upsertJob(persisted);
+      await this.forEachObserver(
+        "run complete",
+        { jobId, trigger, status },
+        async (observer) => {
+          await observer.notifyRunComplete?.({
+            job: persisted,
+            trigger,
+            startedAt,
+            endedAt,
+            attempts: attemptCount,
+            status,
+            ...errorMessage ? { error: errorMessage } : {},
+            ...deadLettered ? { deadLettered: true } : {}
+          });
+        }
+      );
+      if (deadLettered && errorMessage) {
+        await this.emitDeadLetter({
+          job: persisted,
+          trigger,
+          attempts: attemptCount,
+          startedAt,
+          endedAt,
+          error: errorMessage
+        });
+      }
+      return {
+        jobId,
+        trigger,
+        status,
+        startedAt,
+        endedAt,
+        ...errorMessage ? { error: errorMessage } : {}
+      };
+    } finally {
+      this.releaseRunReservation(jobId);
+    }
+  }
+  releaseRunReservation(jobId) {
+    this.inFlight.delete(jobId);
+    this.activeRuns = Math.max(0, this.activeRuns - 1);
+    void this.drainPendingDispatches();
+  }
+  async drainPendingDispatches() {
+    if (!this.started) {
+      return;
+    }
+    while (this.activeRuns < this.maxConcurrentRuns && this.pendingDispatches.length > 0) {
+      const next = this.pendingDispatches.shift();
+      if (!next) {
+        return;
+      }
+      if (this.pendingDispatchByJobId.get(next.jobId) !== next) {
+        continue;
+      }
+      const reservation = this.tryReserveRun(next.jobId);
+      if (reservation === "queued") {
+        this.pendingDispatches.unshift(next);
+        return;
+      }
+      this.pendingDispatchByJobId.delete(next.jobId);
+      if (reservation === "already-running") {
+        const startedAt = Date.now();
+        next.resolve({
+          jobId: next.jobId,
+          trigger: next.trigger,
+          startedAt,
+          endedAt: startedAt,
+          status: "skipped",
+          error: "Job already running"
+        });
+        continue;
+      }
+      void this.executeReservedJob(next.jobId, next.trigger).then((result) => {
+        next.resolve(result);
+      }).catch((error) => {
+        next.reject(error);
+      });
+    }
+  }
+};
+function createAgentRuntime(options) {
+  return new AgentRuntime(options);
+}
+
+// src/orchestration/service.ts
+var DEFAULT_JOB_ID_PREFIX = "orchestrator:run:";
+var DEFAULT_RUN_LABEL_PREFIX = "orchestrator-run";
+var DEFAULT_SCHEDULE_AHEAD_MS = 6e4;
+var DEFAULT_WAIT_TIMEOUT_ON_CLOSE_MS = 1e4;
+var GUIDE_RESTART_REASON = "__guide-restart__";
+function toErrorMessage(error) {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return String(error);
+}
+function normalizeNonEmpty(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`${label} must not be empty`);
+  }
+  return normalized;
+}
+function normalizeId(value, label) {
+  return normalizeNonEmpty(value, label);
+}
+function normalizeLimit(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(`limit must be a finite number. Received: ${String(value)}`);
+  }
+  return Math.max(0, Math.floor(value));
+}
+function normalizeScheduleAheadMs(value) {
+  if (value === void 0) {
+    return DEFAULT_SCHEDULE_AHEAD_MS;
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(`scheduleAheadMs must be a finite number. Received: ${String(value)}`);
+  }
+  return Math.max(1, Math.floor(value));
+}
+function resolveGuidedInputFallback(params) {
+  if (typeof params.currentInput === "string") {
+    return `${params.currentInput}
+
+[GUIDE]
+${params.guideMessage}`;
+  }
+  if (params.currentInput && typeof params.currentInput === "object") {
+    const inputObject = params.currentInput;
+    if (typeof inputObject.message === "string") {
+      return {
+        ...inputObject,
+        message: `${inputObject.message}
+
+[GUIDE]
+${params.guideMessage}`
+      };
+    }
+  }
+  throw new Error(
+    "Cannot derive guided input automatically for this payload shape. Provide `input` in guide(...) or configure `resolveGuidedInput`."
+  );
+}
+function nowIso(now = Date.now()) {
+  return new Date(now).toISOString();
+}
+var AgentOrchestrator = class {
+  runtime;
+  store;
+  executeRun;
+  logger;
+  createId;
+  jobIdPrefix;
+  runLabelPrefix;
+  scheduleAheadMs;
+  resolveGuidedInput;
+  waiters = /* @__PURE__ */ new Map();
+  runControllers = /* @__PURE__ */ new Map();
+  closeReasons = /* @__PURE__ */ new Map();
+  pendingGuides = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.executeRun = options.execute;
+    this.store = options.store ?? new InMemoryOrchestratorRunStore();
+    this.logger = options.logger ?? options.runtime?.logger ?? silentRuntimeLogger;
+    this.createId = options.createId ?? (() => randomUUID2());
+    this.jobIdPrefix = normalizeNonEmpty(options.jobIdPrefix ?? DEFAULT_JOB_ID_PREFIX, "jobIdPrefix");
+    this.runLabelPrefix = normalizeNonEmpty(
+      options.runLabelPrefix ?? DEFAULT_RUN_LABEL_PREFIX,
+      "runLabelPrefix"
+    );
+    this.scheduleAheadMs = normalizeScheduleAheadMs(options.scheduleAheadMs);
+    this.resolveGuidedInput = options.resolveGuidedInput ?? ((params) => resolveGuidedInputFallback({
+      currentInput: params.run.input,
+      guideMessage: params.guideMessage
+    }));
+    this.runtime = createAgentRuntime({
+      ...options.runtime,
+      logger: options.runtime?.logger ?? this.logger,
+      driver: options.driver,
+      execute: async (job, context) => {
+        return await this.executeRuntimeJob(job.payload, context);
+      }
+    });
+  }
+  async start() {
+    if (this.runtime.status().started) {
+      return;
+    }
+    await this.store.start?.();
+    try {
+      await this.runtime.start();
+    } catch (error) {
+      await this.store.stop?.().catch(() => {
+      });
+      throw error;
+    }
+  }
+  async stop() {
+    let runtimeError;
+    try {
+      await this.runtime.stop();
+    } catch (error) {
+      runtimeError = error;
+    }
+    try {
+      await this.store.stop?.();
+    } catch (error) {
+      if (!runtimeError) {
+        throw error;
+      }
+      this.logger.error("Failed to stop orchestrator run store after runtime stop failure", {
+        error: toErrorMessage(error)
+      });
+    }
+    if (runtimeError) {
+      throw runtimeError;
+    }
+  }
+  async status() {
+    const runs = await this.store.list();
+    const counts = {
+      total: runs.length,
+      queued: 0,
+      running: 0,
+      completed: 0,
+      failed: 0,
+      cancelled: 0
+    };
+    for (const run of runs) {
+      counts[run.state.status] += 1;
+    }
+    return {
+      runtime: this.runtime.status(),
+      runs: counts
+    };
+  }
+  async invoke(input) {
+    this.ensureStarted();
+    const runId = normalizeId(input.id ?? this.createId(), "runId");
+    const existing = await this.store.get(runId);
+    if (existing) {
+      throw new Error(`Run already exists: ${runId}`);
+    }
+    const now = Date.now();
+    const run = {
+      id: runId,
+      label: normalizeNonEmpty(input.label ?? `${this.runLabelPrefix}:${runId}`, "label"),
+      input: input.input,
+      parentRunId: input.parentRunId?.trim() || void 0,
+      metadata: input.metadata,
+      createdAt: nowIso(now),
+      updatedAt: nowIso(now),
+      state: {
+        status: "queued",
+        running: false,
+        attempt: 0,
+        guideCount: 0
+      }
+    };
+    await this.store.upsert(run);
+    let jobId;
+    try {
+      jobId = await this.launchRun(run, {
+        runId,
+        input: run.input,
+        mode: "invoke"
+      });
+    } catch (error) {
+      await this.failRunLaunch(run, error, "Failed to schedule run");
+      throw new Error(`Failed to schedule run "${runId}": ${toErrorMessage(error)}`);
+    }
+    return {
+      run: await this.requireRun(runId),
+      jobId
+    };
+  }
+  async get(runId) {
+    return await this.store.get(normalizeId(runId, "runId"));
+  }
+  async listInvocations(options = {}) {
+    const records = await this.store.list();
+    const statuses = this.resolveStatusFilter(options.status);
+    const parentRunId = options.parentRunId?.trim();
+    const limit = normalizeLimit(options.limit);
+    const filtered = records.filter((record) => {
+      if (statuses && !statuses.has(record.state.status)) {
+        return false;
+      }
+      if (parentRunId && record.parentRunId !== parentRunId) {
+        return false;
+      }
+      return true;
+    });
+    filtered.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return limit === void 0 ? filtered : filtered.slice(0, limit);
+  }
+  async waitForInvocation(runId, options = {}) {
+    const normalizedRunId = normalizeId(runId, "runId");
+    if (options.signal?.aborted) {
+      throw new Error(`Waiting for run "${normalizedRunId}" aborted`);
+    }
+    const current = await this.requireRun(normalizedRunId);
+    if (isTerminalRunStatus(current.state.status)) {
+      return current;
+    }
+    return await new Promise((resolve, reject) => {
+      let timeout;
+      let abortHandler;
+      const cleanup = () => {
+        if (timeout) {
+          clearTimeout(timeout);
+        }
+        if (abortHandler && options.signal) {
+          options.signal.removeEventListener("abort", abortHandler);
+        }
+        const currentGroup = this.waiters.get(normalizedRunId);
+        currentGroup?.delete(waiter);
+        if (currentGroup && currentGroup.size === 0) {
+          this.waiters.delete(normalizedRunId);
+        }
+      };
+      const waiter = {
+        resolve: (record) => {
+          cleanup();
+          resolve(record);
+        },
+        reject: (error) => {
+          cleanup();
+          reject(error);
+        }
+      };
+      const group = this.waiters.get(normalizedRunId) ?? /* @__PURE__ */ new Set();
+      group.add(waiter);
+      this.waiters.set(normalizedRunId, group);
+      if (options.signal) {
+        abortHandler = () => {
+          waiter.reject(new Error(`Waiting for run "${normalizedRunId}" aborted`));
+        };
+        if (options.signal.aborted) {
+          abortHandler();
+          return;
+        }
+        options.signal.addEventListener("abort", abortHandler, { once: true });
+      }
+      if (options.timeoutMs === void 0) {
+        return;
+      }
+      if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        waiter.reject(
+          new Error(`timeoutMs must be greater than zero. Received: ${String(options.timeoutMs)}`)
+        );
+        return;
+      }
+      const timeoutMs = Math.floor(options.timeoutMs);
+      timeout = setTimeout(() => {
+        waiter.reject(new Error(`Timed out waiting for run "${normalizedRunId}" after ${timeoutMs}ms`));
+      }, timeoutMs);
+      timeout.unref?.();
+    });
+  }
+  async close(runId, options = {}) {
+    const normalizedRunId = normalizeId(runId, "runId");
+    const run = await this.requireRun(normalizedRunId);
+    if (isTerminalRunStatus(run.state.status)) {
+      return run;
+    }
+    const reason = options.reason?.trim() || "Run cancelled";
+    const controller = this.runControllers.get(normalizedRunId);
+    if (controller) {
+      this.closeReasons.set(normalizedRunId, reason);
+      controller.abort();
+      try {
+        return await this.waitForInvocation(normalizedRunId, {
+          timeoutMs: DEFAULT_WAIT_TIMEOUT_ON_CLOSE_MS
+        });
+      } catch {
+        return await this.requireRun(normalizedRunId);
+      }
+    }
+    await this.disableRunJob(normalizedRunId);
+    const now = Date.now();
+    const cancelled = {
+      ...run,
+      updatedAt: nowIso(now),
+      state: {
+        ...run.state,
+        status: "cancelled",
+        running: false,
+        endedAtMs: now,
+        error: reason,
+        result: void 0
+      }
+    };
+    await this.store.upsert(cancelled);
+    this.notifyWaiters(cancelled);
+    return cancelled;
+  }
+  async guide(input) {
+    this.ensureStarted();
+    const runId = normalizeId(input.runId, "runId");
+    const guideMessage = normalizeNonEmpty(input.message, "message");
+    const run = await this.requireRun(runId);
+    if (isTerminalRunStatus(run.state.status)) {
+      throw new Error(`Cannot guide terminal run "${runId}" (${run.state.status})`);
+    }
+    const nextInput = input.input ?? this.resolveGuidedInput({
+      run,
+      guideMessage
+    });
+    const now = Date.now();
+    const next = {
+      ...run,
+      input: nextInput,
+      metadata: input.metadata ?? run.metadata,
+      updatedAt: nowIso(now),
+      state: {
+        ...run.state,
+        guideCount: run.state.guideCount + 1,
+        error: void 0,
+        result: void 0
+      }
+    };
+    await this.store.upsert(next);
+    const runningController = this.runControllers.get(runId);
+    if (runningController) {
+      this.pendingGuides.set(runId, {
+        message: guideMessage,
+        input: nextInput,
+        guideCount: next.state.guideCount,
+        metadata: input.metadata ?? run.metadata
+      });
+      this.closeReasons.set(runId, GUIDE_RESTART_REASON);
+      runningController.abort();
+      return await this.requireRun(runId);
+    }
+    try {
+      await this.launchRun(next, {
+        runId,
+        input: nextInput,
+        mode: "guide",
+        guideMessage
+      });
+    } catch (error) {
+      await this.failRunLaunch(next, error, "Failed to relaunch guided run");
+      throw new Error(`Failed to relaunch guided run "${runId}": ${toErrorMessage(error)}`);
+    }
+    return await this.requireRun(runId);
+  }
+  ensureStarted() {
+    if (!this.runtime.status().started) {
+      throw new Error("Orchestrator runtime is not started. Call start() before this operation.");
+    }
+  }
+  toJobId(runId) {
+    return `${this.jobIdPrefix}${runId}`;
+  }
+  resolveStatusFilter(status) {
+    if (status === void 0) {
+      return void 0;
+    }
+    const raw = Array.isArray(status) ? status : [status];
+    const normalized = raw.filter(Boolean);
+    if (normalized.length === 0) {
+      return void 0;
+    }
+    return new Set(normalized);
+  }
+  async requireRun(runId) {
+    const run = await this.store.get(runId);
+    if (!run) {
+      throw new Error(`Run not found: ${runId}`);
+    }
+    return run;
+  }
+  async failRunLaunch(run, error, prefix) {
+    const endedAt = Date.now();
+    const failed = {
+      ...run,
+      updatedAt: nowIso(endedAt),
+      state: {
+        ...run.state,
+        status: "failed",
+        running: false,
+        endedAtMs: endedAt,
+        error: `${prefix}: ${toErrorMessage(error)}`,
+        result: void 0
+      }
+    };
+    await this.store.upsert(failed);
+    this.notifyWaiters(failed);
+    return failed;
+  }
+  async failPendingRunLaunch(runId, error, prefix) {
+    const run = await this.store.get(runId);
+    if (!run || isTerminalRunStatus(run.state.status)) {
+      return;
+    }
+    await this.failRunLaunch(run, error, prefix);
+  }
+  async disableRunJob(runId) {
+    const jobId = this.toJobId(runId);
+    try {
+      await this.runtime.pause(jobId);
+    } catch {
+    }
+  }
+  async launchRun(run, payload) {
+    this.ensureStarted();
+    const jobId = this.toJobId(run.id);
+    const scheduleAt = Date.now() + this.scheduleAheadMs;
+    const existing = await this.runtime.getJob(jobId);
+    if (existing) {
+      await this.runtime.update(jobId, {
+        name: run.label,
+        payload,
+        enabled: true,
+        metadata: run.metadata,
+        schedule: {
+          kind: "at",
+          at: scheduleAt
+        }
+      });
+    } else {
+      await this.runtime.schedule({
+        id: jobId,
+        name: run.label,
+        payload,
+        enabled: true,
+        metadata: run.metadata,
+        schedule: {
+          kind: "at",
+          at: scheduleAt
+        }
+      });
+    }
+    void this.runtime.runNow(jobId).then((result) => {
+      if (result.status === "skipped") {
+        this.logger.debug("Run dispatch skipped", {
+          runId: run.id,
+          jobId,
+          reason: result.error
+        });
+      }
+    }).catch((error) => {
+      this.logger.error("Run dispatch failed", {
+        runId: run.id,
+        jobId,
+        error: toErrorMessage(error)
+      });
+      void this.failPendingRunLaunch(run.id, error, "Run dispatch failed").catch((persistError) => {
+        this.logger.error("Failed to persist run dispatch failure", {
+          runId: run.id,
+          jobId,
+          error: toErrorMessage(persistError)
+        });
+      });
+    });
+    return jobId;
+  }
+  notifyWaiters(run) {
+    if (!isTerminalRunStatus(run.state.status)) {
+      return;
+    }
+    const group = this.waiters.get(run.id);
+    if (!group || group.size === 0) {
+      return;
+    }
+    this.waiters.delete(run.id);
+    for (const waiter of group) {
+      waiter.resolve(run);
+    }
+  }
+  async executeRuntimeJob(payload, runtimeContext) {
+    const run = await this.store.get(payload.runId);
+    if (!run) {
+      return {
+        status: "error",
+        error: `Run not found: ${payload.runId}`
+      };
+    }
+    if (run.state.status === "cancelled") {
+      return {
+        status: "skipped",
+        error: "Run already cancelled"
+      };
+    }
+    const startedAt = Date.now();
+    const running = {
+      ...run,
+      input: payload.input,
+      updatedAt: nowIso(startedAt),
+      state: {
+        ...run.state,
+        status: "running",
+        running: true,
+        attempt: run.state.attempt + 1,
+        startedAtMs: startedAt,
+        endedAtMs: void 0,
+        error: void 0,
+        result: void 0
+      }
+    };
+    await this.store.upsert(running);
+    const runController = new AbortController();
+    const onRuntimeAbort = () => runController.abort();
+    runtimeContext.signal.addEventListener("abort", onRuntimeAbort, { once: true });
+    this.runControllers.set(run.id, runController);
+    try {
+      const result = await this.executeRun(running, {
+        signal: runController.signal,
+        trigger: runtimeContext.trigger,
+        mode: payload.mode,
+        attempt: running.state.attempt,
+        startedAt,
+        deadlineAt: runtimeContext.deadlineAt,
+        guideMessage: payload.guideMessage
+      });
+      const endedAt = Date.now();
+      const completed = {
+        ...running,
+        updatedAt: nowIso(endedAt),
+        state: {
+          ...running.state,
+          status: "completed",
+          running: false,
+          endedAtMs: endedAt,
+          result,
+          error: void 0
+        }
+      };
+      await this.store.upsert(completed);
+      this.notifyWaiters(completed);
+      return { status: "ok" };
+    } catch (error) {
+      const endedAt = Date.now();
+      const reason = this.closeReasons.get(run.id);
+      const wasAborted = runController.signal.aborted;
+      if (wasAborted && reason === GUIDE_RESTART_REASON) {
+        const pendingGuide = this.pendingGuides.get(run.id);
+        if (pendingGuide) {
+          this.pendingGuides.delete(run.id);
+          this.closeReasons.delete(run.id);
+          const queued = {
+            ...running,
+            input: pendingGuide.input,
+            metadata: pendingGuide.metadata ?? running.metadata,
+            updatedAt: nowIso(endedAt),
+            state: {
+              ...running.state,
+              guideCount: pendingGuide.guideCount,
+              status: "queued",
+              running: false,
+              endedAtMs: void 0,
+              error: void 0,
+              result: void 0
+            }
+          };
+          await this.store.upsert(queued);
+          const retryTimer = setTimeout(() => {
+            void this.launchRun(queued, {
+              runId: queued.id,
+              input: pendingGuide.input,
+              mode: "guide",
+              guideMessage: pendingGuide.message
+            }).catch((retryError) => {
+              this.logger.error("Failed to relaunch guided run", {
+                runId: queued.id,
+                error: toErrorMessage(retryError)
+              });
+              void this.failRunLaunch(queued, retryError, "Failed to relaunch guided run").catch(
+                (persistError) => {
+                  this.logger.error("Failed to persist guided relaunch failure", {
+                    runId: queued.id,
+                    error: toErrorMessage(persistError)
+                  });
+                }
+              );
+            });
+          }, 0);
+          retryTimer.unref?.();
+          return {
+            status: "skipped",
+            error: "Run restarted after guide"
+          };
+        }
+      }
+      const errorMessage = toErrorMessage(error);
+      const cancellationMessage = reason && reason !== GUIDE_RESTART_REASON ? reason : "Run cancelled";
+      const cancelled = wasAborted;
+      const terminal = {
+        ...running,
+        updatedAt: nowIso(endedAt),
+        state: {
+          ...running.state,
+          status: cancelled ? "cancelled" : "failed",
+          running: false,
+          endedAtMs: endedAt,
+          error: cancelled ? cancellationMessage : errorMessage,
+          result: void 0
+        }
+      };
+      await this.store.upsert(terminal);
+      this.notifyWaiters(terminal);
+      return {
+        status: "error",
+        error: terminal.state.error
+      };
+    } finally {
+      runtimeContext.signal.removeEventListener("abort", onRuntimeAbort);
+      this.runControllers.delete(run.id);
+      this.closeReasons.delete(run.id);
+    }
+  }
+};
+function createAgentOrchestrator(options) {
+  return new AgentOrchestrator(options);
+}
+
+export {
+  silentRuntimeLogger,
+  createConsoleRuntimeLogger,
+  AgentRuntime,
+  createAgentRuntime,
+  isTerminalRunStatus,
+  InMemoryOrchestratorRunStore,
+  AgentOrchestrator,
+  createAgentOrchestrator
+};