@cuylabs/agent-runtime 0.5.0

package/dist/index.js

@@ -0,0 +1,408 @@
+import {
+  InMemoryRuntimeDriver
+} from "./chunk-DBQSJ476.js";
+import {
+  AgentOrchestrator,
+  AgentRuntime,
+  InMemoryOrchestratorRunStore,
+  createAgentOrchestrator,
+  createAgentRuntime,
+  createConsoleRuntimeLogger,
+  isTerminalRunStatus,
+  silentRuntimeLogger
+} from "./chunk-H6BHDIUX.js";
+import {
+  computeNextRunAtMs,
+  normalizeSchedule
+} from "./chunk-ZVISWF7S.js";
+
+// src/metrics.ts
+var DEFAULT_METRIC_PREFIX = "agent_runtime";
+var DEFAULT_DURATION_BUCKETS_MS = [
+  10,
+  50,
+  100,
+  250,
+  500,
+  1e3,
+  2500,
+  5e3,
+  1e4,
+  3e4,
+  6e4
+];
+var PROMETHEUS_TEXT_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+function normalizeMetricPrefix(value) {
+  const normalized = (value ?? DEFAULT_METRIC_PREFIX).trim().replace(/[^a-zA-Z0-9_:]/g, "_").replace(/^[^a-zA-Z_:]+/, "");
+  if (!normalized) {
+    throw new Error("metricPrefix must contain at least one valid Prometheus metric character");
+  }
+  return normalized;
+}
+function normalizeDurationBuckets(value) {
+  const buckets = [...value ?? DEFAULT_DURATION_BUCKETS_MS].map((bucket) => Math.floor(bucket)).filter((bucket) => Number.isFinite(bucket) && bucket > 0).sort((left, right) => left - right);
+  if (buckets.length === 0) {
+    throw new Error("durationBucketsMs must include at least one positive bucket");
+  }
+  return [...new Set(buckets)];
+}
+function escapeMetricHelp(text) {
+  return text.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+}
+function escapeLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+}
+function cloneLabels(labels) {
+  return Object.fromEntries(
+    Object.entries(labels).filter(([, value]) => value !== void 0).sort(([left], [right]) => left.localeCompare(right))
+  );
+}
+function serializeLabels(labels) {
+  const entries = Object.entries(labels).sort(([left], [right]) => left.localeCompare(right));
+  return entries.map(([key, value]) => `${key}="${escapeLabelValue(value)}"`).join(",");
+}
+function labelsKey(labels) {
+  return serializeLabels(labels);
+}
+function mergeLabels(defaultLabels, extra) {
+  const labels = { ...defaultLabels };
+  for (const [key, value] of Object.entries(extra)) {
+    if (value === void 0) {
+      continue;
+    }
+    labels[key] = String(value);
+  }
+  return cloneLabels(labels);
+}
+function getOrCreateMetricEntry(store, labels) {
+  const key = labelsKey(labels);
+  const existing = store.get(key);
+  if (existing) {
+    return existing;
+  }
+  const entry = {
+    labels,
+    value: 0
+  };
+  store.set(key, entry);
+  return entry;
+}
+function getOrCreateHistogramEntry(store, labels, bucketCount) {
+  const key = labelsKey(labels);
+  const existing = store.get(key);
+  if (existing) {
+    return existing;
+  }
+  const entry = {
+    labels,
+    count: 0,
+    sum: 0,
+    bucketCounts: new Array(bucketCount).fill(0)
+  };
+  store.set(key, entry);
+  return entry;
+}
+function sortMetricEntries(entries) {
+  return [...entries].sort(
+    (left, right) => labelsKey(left.labels).localeCompare(labelsKey(right.labels))
+  );
+}
+function createPrometheusRuntimeMetrics(options = {}) {
+  const metricPrefix = normalizeMetricPrefix(options.metricPrefix);
+  const defaultLabels = cloneLabels(options.defaultLabels ?? {});
+  const durationBucketsMs = normalizeDurationBuckets(options.durationBucketsMs);
+  const counters = /* @__PURE__ */ new Map();
+  const gauges = /* @__PURE__ */ new Map();
+  const histograms = /* @__PURE__ */ new Map();
+  const counter = (name, help) => {
+    const fullName = `${metricPrefix}_${name}`;
+    const existing = counters.get(fullName);
+    if (existing) {
+      return existing.entries;
+    }
+    const entries = /* @__PURE__ */ new Map();
+    counters.set(fullName, { help, type: "counter", entries });
+    return entries;
+  };
+  const gauge = (name, help) => {
+    const fullName = `${metricPrefix}_${name}`;
+    const existing = gauges.get(fullName);
+    if (existing) {
+      return existing.entries;
+    }
+    const entries = /* @__PURE__ */ new Map();
+    gauges.set(fullName, { help, type: "gauge", entries });
+    return entries;
+  };
+  const histogram = (name, help) => {
+    const fullName = `${metricPrefix}_${name}`;
+    const existing = histograms.get(fullName);
+    if (existing) {
+      return existing.entries;
+    }
+    const entries = /* @__PURE__ */ new Map();
+    histograms.set(fullName, { help, type: "histogram", entries });
+    return entries;
+  };
+  const runtimeStartCounter = counter(
+    "starts_total",
+    "Total number of runtime start events."
+  );
+  const runtimeStopCounter = counter(
+    "stops_total",
+    "Total number of runtime stop events."
+  );
+  const dispatchQueuedCounter = counter(
+    "dispatch_queued_total",
+    "Total number of dispatches accepted into the runtime queue."
+  );
+  const dispatchDroppedCounter = counter(
+    "dispatch_dropped_total",
+    "Total number of dispatches dropped before execution."
+  );
+  const runStartedCounter = counter(
+    "run_started_total",
+    "Total number of runtime runs started."
+  );
+  const runRetriedCounter = counter(
+    "run_retried_total",
+    "Total number of runtime retries scheduled."
+  );
+  const runCompletedCounter = counter(
+    "run_completed_total",
+    "Total number of runtime runs completed."
+  );
+  const deadLetterCounter = counter(
+    "dead_letter_total",
+    "Total number of runtime runs that exhausted retries and were dead-lettered."
+  );
+  const queueDepthGauge = gauge(
+    "queue_depth",
+    "Current number of queued dispatches waiting for capacity."
+  );
+  const inFlightGauge = gauge(
+    "in_flight_runs",
+    "Current number of runtime runs in flight."
+  );
+  const runDurationHistogram = histogram(
+    "run_duration_ms",
+    "Observed runtime run duration in milliseconds."
+  );
+  const baseGaugeLabels = cloneLabels(defaultLabels);
+  getOrCreateMetricEntry(queueDepthGauge, baseGaugeLabels).value = 0;
+  getOrCreateMetricEntry(inFlightGauge, baseGaugeLabels).value = 0;
+  const incrementCounter = (store, labels, amount = 1) => {
+    getOrCreateMetricEntry(store, labels).value += amount;
+  };
+  const setGauge = (store, labels, value) => {
+    getOrCreateMetricEntry(store, labels).value = value;
+  };
+  const adjustGauge = (store, labels, delta) => {
+    const entry = getOrCreateMetricEntry(store, labels);
+    entry.value = Math.max(0, entry.value + delta);
+  };
+  const observeRunDuration = (status, trigger, durationMs) => {
+    const labels = mergeLabels(defaultLabels, { status, trigger });
+    const entry = getOrCreateHistogramEntry(
+      runDurationHistogram,
+      labels,
+      durationBucketsMs.length
+    );
+    const normalizedDuration = Math.max(0, durationMs);
+    entry.count += 1;
+    entry.sum += normalizedDuration;
+    durationBucketsMs.forEach((bucket, index) => {
+      if (normalizedDuration <= bucket) {
+        entry.bucketCounts[index] += 1;
+      }
+    });
+  };
+  const observer = {
+    notifyRuntimeStart: async (event) => {
+      incrementCounter(
+        runtimeStartCounter,
+        mergeLabels(defaultLabels, { driver: event.driver })
+      );
+    },
+    notifyRuntimeStop: async (event) => {
+      incrementCounter(
+        runtimeStopCounter,
+        mergeLabels(defaultLabels, { driver: event.driver })
+      );
+      setGauge(queueDepthGauge, baseGaugeLabels, 0);
+      setGauge(inFlightGauge, baseGaugeLabels, 0);
+    },
+    notifyDispatchQueued: async (event) => {
+      incrementCounter(
+        dispatchQueuedCounter,
+        mergeLabels(defaultLabels, { trigger: event.trigger })
+      );
+      setGauge(queueDepthGauge, baseGaugeLabels, event.queueLength);
+    },
+    notifyDispatchDropped: async (event) => {
+      incrementCounter(
+        dispatchDroppedCounter,
+        mergeLabels(defaultLabels, {
+          trigger: event.trigger,
+          reason: event.reason
+        })
+      );
+      setGauge(queueDepthGauge, baseGaugeLabels, event.queueLength);
+    },
+    notifyRunStart: async (event) => {
+      incrementCounter(
+        runStartedCounter,
+        mergeLabels(defaultLabels, { trigger: event.trigger })
+      );
+      adjustGauge(inFlightGauge, baseGaugeLabels, 1);
+      const queueDepth = getOrCreateMetricEntry(queueDepthGauge, baseGaugeLabels);
+      if (queueDepth.value > 0) {
+        queueDepth.value -= 1;
+      }
+    },
+    notifyRunRetry: async (event) => {
+      incrementCounter(
+        runRetriedCounter,
+        mergeLabels(defaultLabels, { trigger: event.trigger })
+      );
+    },
+    notifyRunComplete: async (event) => {
+      incrementCounter(
+        runCompletedCounter,
+        mergeLabels(defaultLabels, {
+          trigger: event.trigger,
+          status: event.status
+        })
+      );
+      observeRunDuration(
+        event.status,
+        event.trigger,
+        Math.max(0, event.endedAt - event.startedAt)
+      );
+      adjustGauge(inFlightGauge, baseGaugeLabels, -1);
+    },
+    notifyDeadLetter: async (event) => {
+      incrementCounter(
+        deadLetterCounter,
+        mergeLabels(defaultLabels, { trigger: event.trigger })
+      );
+    }
+  };
+  const snapshot = () => {
+    const counterSnapshot = Object.fromEntries(
+      [...counters.entries()].map(([name, store]) => [
+        name,
+        sortMetricEntries(store.entries.values()).map((entry) => ({
+          labels: cloneLabels(entry.labels),
+          value: entry.value
+        }))
+      ])
+    );
+    const gaugeSnapshot = Object.fromEntries(
+      [...gauges.entries()].map(([name, store]) => [
+        name,
+        sortMetricEntries(store.entries.values()).map((entry) => ({
+          labels: cloneLabels(entry.labels),
+          value: entry.value
+        }))
+      ])
+    );
+    const histogramSnapshot = Object.fromEntries(
+      [...histograms.entries()].map(([name, store]) => [
+        name,
+        sortMetricEntries(store.entries.values()).map((entry) => ({
+          labels: cloneLabels(entry.labels),
+          count: entry.count,
+          sum: entry.sum,
+          buckets: durationBucketsMs.map((bucket, index) => ({
+            le: bucket,
+            value: entry.bucketCounts[index]
+          }))
+        }))
+      ])
+    );
+    return {
+      counters: counterSnapshot,
+      gauges: gaugeSnapshot,
+      histograms: histogramSnapshot
+    };
+  };
+  const render = () => {
+    const lines = [];
+    for (const [name, store] of [...counters.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+      lines.push(`# HELP ${name} ${escapeMetricHelp(store.help)}`);
+      lines.push(`# TYPE ${name} ${store.type}`);
+      for (const entry of sortMetricEntries(store.entries.values())) {
+        const labels = serializeLabels(entry.labels);
+        lines.push(`${name}${labels ? `{${labels}}` : ""} ${entry.value}`);
+      }
+    }
+    for (const [name, store] of [...gauges.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+      lines.push(`# HELP ${name} ${escapeMetricHelp(store.help)}`);
+      lines.push(`# TYPE ${name} ${store.type}`);
+      for (const entry of sortMetricEntries(store.entries.values())) {
+        const labels = serializeLabels(entry.labels);
+        lines.push(`${name}${labels ? `{${labels}}` : ""} ${entry.value}`);
+      }
+    }
+    for (const [name, store] of [...histograms.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+      lines.push(`# HELP ${name} ${escapeMetricHelp(store.help)}`);
+      lines.push(`# TYPE ${name} ${store.type}`);
+      for (const entry of sortMetricEntries(store.entries.values())) {
+        const baseLabels = cloneLabels(entry.labels);
+        durationBucketsMs.forEach((bucket, index) => {
+          const labels = serializeLabels({
+            ...baseLabels,
+            le: String(bucket)
+          });
+          lines.push(`${name}_bucket{${labels}} ${entry.bucketCounts[index]}`);
+        });
+        const infiniteLabels = serializeLabels({
+          ...baseLabels,
+          le: "+Inf"
+        });
+        const seriesLabels = serializeLabels(baseLabels);
+        lines.push(`${name}_bucket{${infiniteLabels}} ${entry.count}`);
+        lines.push(`${name}_sum${seriesLabels ? `{${seriesLabels}}` : ""} ${entry.sum}`);
+        lines.push(`${name}_count${seriesLabels ? `{${seriesLabels}}` : ""} ${entry.count}`);
+      }
+    }
+    return `${lines.join("\n")}
+`;
+  };
+  const reset = () => {
+    for (const store of counters.values()) {
+      store.entries.clear();
+    }
+    for (const store of gauges.values()) {
+      store.entries.clear();
+    }
+    for (const store of histograms.values()) {
+      store.entries.clear();
+    }
+    getOrCreateMetricEntry(queueDepthGauge, baseGaugeLabels).value = 0;
+    getOrCreateMetricEntry(inFlightGauge, baseGaugeLabels).value = 0;
+  };
+  return {
+    observer,
+    contentType: PROMETHEUS_TEXT_CONTENT_TYPE,
+    snapshot,
+    render,
+    reset
+  };
+}
+export {
+  AgentOrchestrator,
+  AgentRuntime,
+  InMemoryOrchestratorRunStore,
+  InMemoryRuntimeDriver,
+  PROMETHEUS_TEXT_CONTENT_TYPE,
+  computeNextRunAtMs,
+  createAgentOrchestrator,
+  createAgentRuntime,
+  createConsoleRuntimeLogger,
+  createPrometheusRuntimeMetrics,
+  isTerminalRunStatus,
+  normalizeSchedule,
+  silentRuntimeLogger
+};

package/dist/orchestration/index.d.ts

@@ -0,0 +1,2 @@
+export { A as AgentOrchestrator, a as AgentOrchestratorOptions, I as InMemoryOrchestratorRunStore, O as OrchestratorCloseOptions, d as OrchestratorExecutionContext, e as OrchestratorExecutor, f as OrchestratorGuideInput, g as OrchestratorGuidedInputResolver, h as OrchestratorInvokeInput, i as OrchestratorInvokeResult, j as OrchestratorJobPayload, k as OrchestratorListOptions, l as OrchestratorRunMode, m as OrchestratorRunRecord, n as OrchestratorRunState, o as OrchestratorRunStatus, p as OrchestratorRunStore, q as OrchestratorWaitOptions, x as createAgentOrchestrator, z as isTerminalRunStatus } from '../index-CbLKNFMq.js';
+import '../driver-KdyMlXQq.js';

package/dist/orchestration/index.js

@@ -0,0 +1,13 @@
+import {
+  AgentOrchestrator,
+  InMemoryOrchestratorRunStore,
+  createAgentOrchestrator,
+  isTerminalRunStatus
+} from "../chunk-H6BHDIUX.js";
+import "../chunk-ZVISWF7S.js";
+export {
+  AgentOrchestrator,
+  InMemoryOrchestratorRunStore,
+  createAgentOrchestrator,
+  isTerminalRunStatus
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@cuylabs/agent-runtime",
+  "version": "0.5.0",
+  "description": "Agent runtime orchestration layer - scheduling, execution, and pluggable runtime drivers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./orchestration": {
+      "types": "./dist/orchestration/index.d.ts",
+      "import": "./dist/orchestration/index.js",
+      "default": "./dist/orchestration/index.js"
+    },
+    "./drivers/in-memory": {
+      "types": "./dist/drivers/in-memory.d.ts",
+      "import": "./dist/drivers/in-memory.js",
+      "default": "./dist/drivers/in-memory.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "croner": "^10.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "agent",
+    "runtime",
+    "scheduler",
+    "cron",
+    "orchestration"
+  ],
+  "author": "cuylabs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuylabs-ai/agents-ts.git",
+    "directory": "packages/agent-runtime"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/orchestration/index.ts src/drivers/in-memory.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/orchestration/index.ts src/drivers/in-memory.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}