@cuylabs/agent-runtime 0.5.0 → 0.7.0

package/README.md

@@ -1,16 +1,40 @@
 # @cuylabs/agent-runtime
 
-Runtime orchestration layer for agent workloads.
+Workload orchestration layer for agent and background workloads.
 
 `@cuylabs/agent-core` focuses on single-turn agent execution.  
 `@cuylabs/agent-runtime` manages scheduling and execution of recurring/background work.
 
+The package now makes one architectural seam explicit:
+
+- `agent-core` defines turn/task execution semantics
+- `agent-runtime` consumes a generic workload contract
+- infrastructure packages such as `agent-runtime-dapr` implement that contract
+
+## Package Boundary
+
+Use `@cuylabs/agent-runtime` when you need outer orchestration:
+
+- job definitions and schedules
+- dispatch, retries, and concurrency limits
+- pluggable runtime drivers
+- runtime observers and metrics
+- orchestration APIs for invoking and guiding long-running work
+
+This package does not own in-process model or tool interception.
+
+- `agent-core` owns middleware, tool execution, model execution, and turn semantics
+- `agent-runtime` owns workload scheduling and dispatch around that execution
+
+So most users start with `agent-core`, then add `agent-runtime` when they need workers, jobs, or orchestrated execution.
+
 ## What This Package Owns
 
 - Job definitions and lifecycle (`schedule`, `update`, `pause`, `resume`, `runNow`, `dispatch`)
 - Schedule evaluation (`at`, `every`, `cron`)
 - Execution loop with concurrency limits
 - Pluggable runtime drivers (in-memory now, Dapr/others later)
+- Neutral workload adapter for plugging application work into the runtime
 - Optional app-level orchestration API (`invoke`, `listInvocations`, `waitForInvocation`, `close`, `guide`)
 
 ## Layered Architecture
@@ -24,7 +48,7 @@ host app / worker process
 ```
 
 - `agent-core`: tool loop + model calls + business logic
-- `agent-runtime`: scheduling/execution orchestration
+- `agent-runtime`: scheduling/execution orchestration + workload contract
 - driver package (for example `agent-runtime-dapr`): infrastructure adapter
 
 The runtime does not require Dapr. Dapr is one driver/store implementation.
@@ -33,17 +57,46 @@ See `docs/architecture.md` for a concrete package/folder layout across `agent-co
 See `docs/capability-matrix.md` for the difference between shared runtime contract and backend-specific guarantees.
 See `docs/production-hardening.md` for the current path from local/in-memory runtime to durable/distributed deployments.
 
+## How It Connects To `agent-core`
+
+`agent-runtime` does not depend on the `Agent` class directly. It runs generic
+workloads.
+
+When you want to schedule agent work, the usual handoff is:
+
+```text
+agent-core
+  -> createAgentTaskRunner(agent)
+    -> agent-runtime workload adapter
+      -> WorkloadRuntime
+```
+
+That means:
+
+- `agent-core` turns a live `Agent` into a task-shaped function
+- `agent-runtime` schedules and dispatches that task like any other workload
+- backend packages such as `agent-runtime-dapr` can then add durability,
+  persistence, and host integration on top
+
+This separation is intentional:
+
+- `agent-core` owns agent semantics
+- `agent-runtime` owns outer orchestration semantics
+- the bridge between them is the workload contract
+
 ## Package Structure
 
 ```text
 src/
   index.ts                 # Public exports
   types.ts                 # Runtime/job contracts
+  workload/
+    index.ts               # Generic workload contract + adapter helper
   observer.ts              # Runtime lifecycle/queue/run observer contracts
   logger.ts                # Logger interface + defaults
   schedule.ts              # Schedule normalization + next-run calculation
   driver.ts                # Driver interface
-  runtime.ts               # AgentRuntime orchestration class
+  runtime.ts               # WorkloadRuntime orchestration class
   drivers/
     in-memory.ts           # Default local runtime driver
   orchestration/
@@ -70,13 +123,14 @@ Focused imports are also available when you want the package surface to match th
 ```ts
 import { createAgentOrchestrator } from "@cuylabs/agent-runtime/orchestration";
 import { InMemoryRuntimeDriver } from "@cuylabs/agent-runtime/drivers/in-memory";
+import { createRuntimeWorkloadExecutor } from "@cuylabs/agent-runtime/workload";
 ```
 
 ## Quick Start
 
 ```ts
 import {
-  createAgentRuntime,
+  createWorkloadRuntime,
   createPrometheusRuntimeMetrics,
   InMemoryRuntimeDriver,
   type RuntimeJobRecord,
@@ -88,7 +142,7 @@ const metrics = createPrometheusRuntimeMetrics<Payload>({
   defaultLabels: { service: "digest-worker" },
 });
 
-const runtime = createAgentRuntime<Payload>({
+const runtime = createWorkloadRuntime<Payload>({
   driver: new InMemoryRuntimeDriver(),
   execute: async (job: RuntimeJobRecord<Payload>) => {
     console.log(`[job:${job.id}]`, job.payload.message);
@@ -118,6 +172,37 @@ const job = await runtime.schedule({
 console.log("scheduled", job.id);
 ```
 
+## Workload Contract
+
+Use the workload adapter when you want your app logic to stay independent from
+the runtime internals:
+
+```ts
+import {
+  createWorkloadRuntime,
+  createRuntimeWorkloadExecutor,
+  InMemoryRuntimeDriver,
+} from "@cuylabs/agent-runtime";
+
+const runDigest = async (
+  payload: { message: string },
+  context: { jobId: string; signal: AbortSignal },
+) => {
+  console.log(context.jobId, payload.message);
+  return { delivered: true };
+};
+
+const runtime = createWorkloadRuntime({
+  driver: new InMemoryRuntimeDriver(),
+  execute: createRuntimeWorkloadExecutor({
+    run: runDigest,
+  }),
+});
+```
+
+For agent workloads, `@cuylabs/agent-core` already provides
+`createAgentTaskRunner(...)`, which fits naturally into this workload boundary.
+
 ## Dispatch API
 
 `dispatch` lets host apps route explicit triggers into the runtime:
@@ -131,7 +216,7 @@ Use this from transport callbacks (HTTP/gRPC/event handlers) after you map exter
 
 ## Production Guardrails
 
-`createAgentRuntime(...)` includes baseline guardrails:
+`createWorkloadRuntime(...)` includes baseline guardrails:
 
 - `maxConcurrentRuns` (default `4`)
 - `maxQueuedDispatches` (optional cap for pending dispatches)
@@ -146,7 +231,7 @@ Use this from transport callbacks (HTTP/gRPC/event handlers) after you map exter
 
 ## Runtime Observers
 
-`AgentRuntime` exposes a small observer surface for production hooks, and the package now ships a concrete Prometheus-style collector for the common case.
+`WorkloadRuntime` exposes a small observer surface for production hooks, and the package now ships a concrete Prometheus-style collector for the common case.
 
 ```ts
 import {

package/dist/chunk-INCALI7Z.js

@@ -0,0 +1,53 @@
+// src/workload/index.ts
+function toErrorMessage(error) {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  return String(error);
+}
+function createRuntimeWorkloadContext(job, context) {
+  return {
+    ...context,
+    jobId: job.id,
+    jobName: job.name,
+    ...job.metadata ? { metadata: job.metadata } : {}
+  };
+}
+function createRuntimeWorkloadExecutor(options) {
+  return async (job, runtimeContext) => {
+    const workloadContext = createRuntimeWorkloadContext(job, runtimeContext);
+    try {
+      const result = await options.run(job.payload, workloadContext);
+      if (options.onResult) {
+        await options.onResult({
+          job,
+          context: workloadContext,
+          result
+        });
+      }
+      return { status: "ok" };
+    } catch (error) {
+      const message = toErrorMessage(error);
+      if (options.onError) {
+        try {
+          await options.onError({
+            job,
+            context: workloadContext,
+            error,
+            message
+          });
+        } catch {
+        }
+      }
+      return {
+        status: "error",
+        error: message
+      };
+    }
+  };
+}
+
+export {
+  createRuntimeWorkloadContext,
+  createRuntimeWorkloadExecutor
+};

package/dist/{chunk-H6BHDIUX.js → chunk-MAVHVV2U.js}

@@ -216,7 +216,7 @@ function waitForSignalOrTimeout(ms, signal) {
     signal.addEventListener("abort", onAbort, { once: true });
   });
 }
-var AgentRuntime = class {
+var WorkloadRuntime = class {
   driver;
   executeJob;
   logger;
@@ -812,8 +812,8 @@ var AgentRuntime = class {
     }
   }
 };
-function createAgentRuntime(options) {
-  return new AgentRuntime(options);
+function createWorkloadRuntime(options) {
+  return new WorkloadRuntime(options);
 }
 
 // src/orchestration/service.ts
@@ -911,7 +911,7 @@ var AgentOrchestrator = class {
       currentInput: params.run.input,
       guideMessage: params.guideMessage
     }));
-    this.runtime = createAgentRuntime({
+    this.runtime = createWorkloadRuntime({
       ...options.runtime,
       logger: options.runtime?.logger ?? this.logger,
       driver: options.driver,
@@ -1457,8 +1457,8 @@ function createAgentOrchestrator(options) {
 export {
   silentRuntimeLogger,
   createConsoleRuntimeLogger,
-  AgentRuntime,
-  createAgentRuntime,
+  WorkloadRuntime,
+  createWorkloadRuntime,
   isTerminalRunStatus,
   InMemoryOrchestratorRunStore,
   AgentOrchestrator,

package/dist/driver-CKBCu2Gb.d.ts

@@ -0,0 +1,28 @@
+import { o as RuntimeRunResult, R as RuntimeJobRecord } from './types-DllX9NP8.js';
+
+type RuntimeLogMeta = Record<string, unknown>;
+interface RuntimeLogger {
+    debug(message: string, meta?: RuntimeLogMeta): void;
+    info(message: string, meta?: RuntimeLogMeta): void;
+    warn(message: string, meta?: RuntimeLogMeta): void;
+    error(message: string, meta?: RuntimeLogMeta): void;
+}
+declare const silentRuntimeLogger: RuntimeLogger;
+declare function createConsoleRuntimeLogger(prefix?: string): RuntimeLogger;
+
+interface RuntimeDriverContext<TPayload = unknown> {
+    now: () => number;
+    onDue: (jobId: string) => Promise<void | RuntimeRunResult>;
+    logger: RuntimeLogger;
+}
+interface RuntimeDriver<TPayload = unknown> {
+    readonly name: string;
+    start(context: RuntimeDriverContext<TPayload>): Promise<void>;
+    stop(): Promise<void>;
+    listJobs(): Promise<RuntimeJobRecord<TPayload>[]>;
+    getJob?(jobId: string): Promise<RuntimeJobRecord<TPayload> | undefined>;
+    upsertJob(job: RuntimeJobRecord<TPayload>): Promise<RuntimeJobRecord<TPayload>>;
+    removeJob(jobId: string): Promise<boolean>;
+}
+
+export { type RuntimeDriver as R, type RuntimeDriverContext as a, type RuntimeLogMeta as b, type RuntimeLogger as c, createConsoleRuntimeLogger as d, silentRuntimeLogger as s };

package/dist/drivers/in-memory.d.ts

@@ -1,4 +1,5 @@
-import { R as RuntimeDriver, a as RuntimeDriverContext, b as RuntimeJobRecord } from '../driver-KdyMlXQq.js';
+import { R as RuntimeDriver, a as RuntimeDriverContext } from '../driver-CKBCu2Gb.js';
+import { R as RuntimeJobRecord } from '../types-DllX9NP8.js';
 
 interface InMemoryRuntimeDriverOptions {
     maxTimerDelayMs?: number;

package/dist/{index-CbLKNFMq.d.ts → index-Cp7CPYy7.d.ts}

@@ -1,4 +1,5 @@
-import { w as RuntimeTrigger, b as RuntimeJobRecord, t as RuntimeRunStatus, h as RuntimeDeadLetterEvent, R as RuntimeDriver, m as RuntimeExecutor, p as RuntimeLogger, u as RuntimeScheduleInput, v as RuntimeSchedulePatch, s as RuntimeRunResult, i as RuntimeDispatchInput } from './driver-KdyMlXQq.js';
+import { s as RuntimeTrigger, R as RuntimeJobRecord, p as RuntimeRunStatus, h as RuntimeDeadLetterEvent, b as RuntimeExecutor, q as RuntimeScheduleInput, r as RuntimeSchedulePatch, o as RuntimeRunResult, i as RuntimeDispatchInput } from './types-DllX9NP8.js';
+import { R as RuntimeDriver, c as RuntimeLogger } from './driver-CKBCu2Gb.js';
 
 interface RuntimeLifecycleEvent {
     driver: string;
@@ -51,7 +52,7 @@ interface RuntimeObserver<TPayload = unknown> {
     notifyDeadLetter?(event: RuntimeDeadLetterEvent<TPayload>): void | Promise<void>;
 }
 
-interface AgentRuntimeOptions<TPayload = unknown> {
+interface WorkloadRuntimeOptions<TPayload = unknown> {
     driver: RuntimeDriver<TPayload>;
     execute: RuntimeExecutor<TPayload>;
     logger?: RuntimeLogger;
@@ -63,7 +64,7 @@ interface AgentRuntimeOptions<TPayload = unknown> {
     onDeadLetter?: (event: RuntimeDeadLetterEvent<TPayload>) => void | Promise<void>;
     observers?: RuntimeObserver<TPayload>[];
 }
-declare class AgentRuntime<TPayload = unknown> {
+declare class WorkloadRuntime<TPayload = unknown> {
     private readonly driver;
     private readonly executeJob;
     private readonly logger;
@@ -80,7 +81,7 @@ declare class AgentRuntime<TPayload = unknown> {
     private readonly runControllers;
     private readonly pendingDispatches;
     private readonly pendingDispatchByJobId;
-    constructor(options: AgentRuntimeOptions<TPayload>);
+    constructor(options: WorkloadRuntimeOptions<TPayload>);
     private forEachObserver;
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -112,7 +113,7 @@ declare class AgentRuntime<TPayload = unknown> {
     private releaseRunReservation;
     private drainPendingDispatches;
 }
-declare function createAgentRuntime<TPayload = unknown>(options: AgentRuntimeOptions<TPayload>): AgentRuntime<TPayload>;
+declare function createWorkloadRuntime<TPayload = unknown>(options: WorkloadRuntimeOptions<TPayload>): WorkloadRuntime<TPayload>;
 
 type OrchestratorRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
 type OrchestratorRunMode = "invoke" | "guide";
@@ -207,7 +208,7 @@ declare class InMemoryOrchestratorRunStore<TInput = unknown, TResult = unknown>
 interface AgentOrchestratorOptions<TInput = unknown, TResult = unknown> {
     driver: RuntimeDriver<OrchestratorJobPayload<TInput>>;
     execute: OrchestratorExecutor<TInput, TResult>;
-    runtime?: Omit<AgentRuntimeOptions<OrchestratorJobPayload<TInput>>, "driver" | "execute">;
+    runtime?: Omit<WorkloadRuntimeOptions<OrchestratorJobPayload<TInput>>, "driver" | "execute">;
     store?: OrchestratorRunStore<TInput, TResult>;
     logger?: RuntimeLogger;
     createId?: () => string;
@@ -217,7 +218,7 @@ interface AgentOrchestratorOptions<TInput = unknown, TResult = unknown> {
     resolveGuidedInput?: OrchestratorGuidedInputResolver<TInput, TResult>;
 }
 declare class AgentOrchestrator<TInput = unknown, TResult = unknown> {
-    readonly runtime: AgentRuntime<OrchestratorJobPayload<TInput>>;
+    readonly runtime: WorkloadRuntime<OrchestratorJobPayload<TInput>>;
     private readonly store;
     private readonly executeRun;
     private readonly logger;
@@ -234,7 +235,7 @@ declare class AgentOrchestrator<TInput = unknown, TResult = unknown> {
     start(): Promise<void>;
     stop(): Promise<void>;
     status(): Promise<{
-        runtime: ReturnType<AgentRuntime<OrchestratorJobPayload<TInput>>["status"]>;
+        runtime: ReturnType<WorkloadRuntime<OrchestratorJobPayload<TInput>>["status"]>;
         runs: {
             total: number;
             queued: number;
@@ -263,4 +264,4 @@ declare class AgentOrchestrator<TInput = unknown, TResult = unknown> {
 }
 declare function createAgentOrchestrator<TInput = unknown, TResult = unknown>(options: AgentOrchestratorOptions<TInput, TResult>): AgentOrchestrator<TInput, TResult>;
 
-export { AgentOrchestrator as A, InMemoryOrchestratorRunStore as I, type OrchestratorCloseOptions as O, type RuntimeObserver as R, type AgentOrchestratorOptions as a, AgentRuntime as b, type AgentRuntimeOptions as c, type OrchestratorExecutionContext as d, type OrchestratorExecutor as e, type OrchestratorGuideInput as f, type OrchestratorGuidedInputResolver as g, type OrchestratorInvokeInput as h, type OrchestratorInvokeResult as i, type OrchestratorJobPayload as j, type OrchestratorListOptions as k, type OrchestratorRunMode as l, type OrchestratorRunRecord as m, type OrchestratorRunState as n, type OrchestratorRunStatus as o, type OrchestratorRunStore as p, type OrchestratorWaitOptions as q, type RuntimeDispatchDroppedEvent as r, type RuntimeDispatchQueuedEvent as s, type RuntimeLifecycleEvent as t, type RuntimeRunCompleteEvent as u, type RuntimeRunRetryEvent as v, type RuntimeRunStartEvent as w, createAgentOrchestrator as x, createAgentRuntime as y, isTerminalRunStatus as z };
+export { AgentOrchestrator as A, InMemoryOrchestratorRunStore as I, type OrchestratorCloseOptions as O, type RuntimeObserver as R, WorkloadRuntime as W, type AgentOrchestratorOptions as a, type OrchestratorExecutionContext as b, type OrchestratorExecutor as c, type OrchestratorGuideInput as d, type OrchestratorGuidedInputResolver as e, type OrchestratorInvokeInput as f, type OrchestratorInvokeResult as g, type OrchestratorJobPayload as h, type OrchestratorListOptions as i, type OrchestratorRunMode as j, type OrchestratorRunRecord as k, type OrchestratorRunState as l, type OrchestratorRunStatus as m, type OrchestratorRunStore as n, type OrchestratorWaitOptions as o, type RuntimeDispatchDroppedEvent as p, type RuntimeDispatchQueuedEvent as q, type RuntimeLifecycleEvent as r, type RuntimeRunCompleteEvent as s, type RuntimeRunRetryEvent as t, type RuntimeRunStartEvent as u, type WorkloadRuntimeOptions as v, createAgentOrchestrator as w, createWorkloadRuntime as x, isTerminalRunStatus as y };

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { c as RuntimeJobSchedule, d as RuntimeJobScheduleInput } from './driver-KdyMlXQq.js';
-export { e as RuntimeAtSchedule, f as RuntimeAtScheduleInput, g as RuntimeCronSchedule, h as RuntimeDeadLetterEvent, i as RuntimeDispatchInput, R as RuntimeDriver, a as RuntimeDriverContext, j as RuntimeEverySchedule, k as RuntimeExecutionContext, l as RuntimeExecutionResult, m as RuntimeExecutor, b as RuntimeJobRecord, n as RuntimeJobState, o as RuntimeLogMeta, p as RuntimeLogger, q as RuntimeRetryPolicy, r as RuntimeRetryStrategy, s as RuntimeRunResult, t as RuntimeRunStatus, u as RuntimeScheduleInput, v as RuntimeSchedulePatch, w as RuntimeTrigger, x as createConsoleRuntimeLogger, y as silentRuntimeLogger } from './driver-KdyMlXQq.js';
-import { R as RuntimeObserver } from './index-CbLKNFMq.js';
-export { A as AgentOrchestrator, a as AgentOrchestratorOptions, b as AgentRuntime, c as AgentRuntimeOptions, 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, r as RuntimeDispatchDroppedEvent, s as RuntimeDispatchQueuedEvent, t as RuntimeLifecycleEvent, u as RuntimeRunCompleteEvent, v as RuntimeRunRetryEvent, w as RuntimeRunStartEvent, x as createAgentOrchestrator, y as createAgentRuntime, z as isTerminalRunStatus } from './index-CbLKNFMq.js';
+import { c as RuntimeJobSchedule, d as RuntimeJobScheduleInput } from './types-DllX9NP8.js';
+export { e as RuntimeAtSchedule, f as RuntimeAtScheduleInput, g as RuntimeCronSchedule, h as RuntimeDeadLetterEvent, i as RuntimeDispatchInput, j as RuntimeEverySchedule, a as RuntimeExecutionContext, k as RuntimeExecutionResult, b as RuntimeExecutor, R as RuntimeJobRecord, l as RuntimeJobState, m as RuntimeRetryPolicy, n as RuntimeRetryStrategy, o as RuntimeRunResult, p as RuntimeRunStatus, q as RuntimeScheduleInput, r as RuntimeSchedulePatch, s as RuntimeTrigger } from './types-DllX9NP8.js';
+export { RuntimeWorkloadContext, RuntimeWorkloadErrorContext, RuntimeWorkloadExecutorOptions, RuntimeWorkloadResultContext, RuntimeWorkloadRunner, createRuntimeWorkloadContext, createRuntimeWorkloadExecutor } from './workload/index.js';
+export { R as RuntimeDriver, a as RuntimeDriverContext, b as RuntimeLogMeta, c as RuntimeLogger, d as createConsoleRuntimeLogger, s as silentRuntimeLogger } from './driver-CKBCu2Gb.js';
+import { R as RuntimeObserver } from './index-Cp7CPYy7.js';
+export { A as AgentOrchestrator, a as AgentOrchestratorOptions, I as InMemoryOrchestratorRunStore, O as OrchestratorCloseOptions, b as OrchestratorExecutionContext, c as OrchestratorExecutor, d as OrchestratorGuideInput, e as OrchestratorGuidedInputResolver, f as OrchestratorInvokeInput, g as OrchestratorInvokeResult, h as OrchestratorJobPayload, i as OrchestratorListOptions, j as OrchestratorRunMode, k as OrchestratorRunRecord, l as OrchestratorRunState, m as OrchestratorRunStatus, n as OrchestratorRunStore, o as OrchestratorWaitOptions, p as RuntimeDispatchDroppedEvent, q as RuntimeDispatchQueuedEvent, r as RuntimeLifecycleEvent, s as RuntimeRunCompleteEvent, t as RuntimeRunRetryEvent, u as RuntimeRunStartEvent, W as WorkloadRuntime, v as WorkloadRuntimeOptions, w as createAgentOrchestrator, x as createWorkloadRuntime, y as isTerminalRunStatus } from './index-Cp7CPYy7.js';
 export { InMemoryRuntimeDriver } from './drivers/in-memory.js';
 
 declare const PROMETHEUS_TEXT_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";

package/dist/index.js

@@ -3,18 +3,22 @@ import {
 } from "./chunk-DBQSJ476.js";
 import {
   AgentOrchestrator,
-  AgentRuntime,
   InMemoryOrchestratorRunStore,
+  WorkloadRuntime,
   createAgentOrchestrator,
-  createAgentRuntime,
   createConsoleRuntimeLogger,
+  createWorkloadRuntime,
   isTerminalRunStatus,
   silentRuntimeLogger
-} from "./chunk-H6BHDIUX.js";
+} from "./chunk-MAVHVV2U.js";
 import {
   computeNextRunAtMs,
   normalizeSchedule
 } from "./chunk-ZVISWF7S.js";
+import {
+  createRuntimeWorkloadContext,
+  createRuntimeWorkloadExecutor
+} from "./chunk-INCALI7Z.js";
 
 // src/metrics.ts
 var DEFAULT_METRIC_PREFIX = "agent_runtime";
@@ -393,15 +397,17 @@ function createPrometheusRuntimeMetrics(options = {}) {
 }
 export {
   AgentOrchestrator,
-  AgentRuntime,
   InMemoryOrchestratorRunStore,
   InMemoryRuntimeDriver,
   PROMETHEUS_TEXT_CONTENT_TYPE,
+  WorkloadRuntime,
   computeNextRunAtMs,
   createAgentOrchestrator,
-  createAgentRuntime,
   createConsoleRuntimeLogger,
   createPrometheusRuntimeMetrics,
+  createRuntimeWorkloadContext,
+  createRuntimeWorkloadExecutor,
+  createWorkloadRuntime,
   isTerminalRunStatus,
   normalizeSchedule,
   silentRuntimeLogger

package/dist/orchestration/index.d.ts

@@ -1,2 +1,3 @@
-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';
+export { A as AgentOrchestrator, a as AgentOrchestratorOptions, I as InMemoryOrchestratorRunStore, O as OrchestratorCloseOptions, b as OrchestratorExecutionContext, c as OrchestratorExecutor, d as OrchestratorGuideInput, e as OrchestratorGuidedInputResolver, f as OrchestratorInvokeInput, g as OrchestratorInvokeResult, h as OrchestratorJobPayload, i as OrchestratorListOptions, j as OrchestratorRunMode, k as OrchestratorRunRecord, l as OrchestratorRunState, m as OrchestratorRunStatus, n as OrchestratorRunStore, o as OrchestratorWaitOptions, w as createAgentOrchestrator, y as isTerminalRunStatus } from '../index-Cp7CPYy7.js';
+import '../types-DllX9NP8.js';
+import '../driver-CKBCu2Gb.js';

package/dist/orchestration/index.js

@@ -3,7 +3,7 @@ import {
   InMemoryOrchestratorRunStore,
   createAgentOrchestrator,
   isTerminalRunStatus
-} from "../chunk-H6BHDIUX.js";
+} from "../chunk-MAVHVV2U.js";
 import "../chunk-ZVISWF7S.js";
 export {
   AgentOrchestrator,

package/dist/{driver-KdyMlXQq.d.ts → types-DllX9NP8.d.ts}

@@ -99,29 +99,4 @@ interface RuntimeDeadLetterEvent<TPayload = unknown> {
     error: string;
 }
 
-type RuntimeLogMeta = Record<string, unknown>;
-interface RuntimeLogger {
-    debug(message: string, meta?: RuntimeLogMeta): void;
-    info(message: string, meta?: RuntimeLogMeta): void;
-    warn(message: string, meta?: RuntimeLogMeta): void;
-    error(message: string, meta?: RuntimeLogMeta): void;
-}
-declare const silentRuntimeLogger: RuntimeLogger;
-declare function createConsoleRuntimeLogger(prefix?: string): RuntimeLogger;
-
-interface RuntimeDriverContext<TPayload = unknown> {
-    now: () => number;
-    onDue: (jobId: string) => Promise<void | RuntimeRunResult>;
-    logger: RuntimeLogger;
-}
-interface RuntimeDriver<TPayload = unknown> {
-    readonly name: string;
-    start(context: RuntimeDriverContext<TPayload>): Promise<void>;
-    stop(): Promise<void>;
-    listJobs(): Promise<RuntimeJobRecord<TPayload>[]>;
-    getJob?(jobId: string): Promise<RuntimeJobRecord<TPayload> | undefined>;
-    upsertJob(job: RuntimeJobRecord<TPayload>): Promise<RuntimeJobRecord<TPayload>>;
-    removeJob(jobId: string): Promise<boolean>;
-}
-
-export { type RuntimeDriver as R, type RuntimeDriverContext as a, type RuntimeJobRecord as b, type RuntimeJobSchedule as c, type RuntimeJobScheduleInput as d, type RuntimeAtSchedule as e, type RuntimeAtScheduleInput as f, type RuntimeCronSchedule as g, type RuntimeDeadLetterEvent as h, type RuntimeDispatchInput as i, type RuntimeEverySchedule as j, type RuntimeExecutionContext as k, type RuntimeExecutionResult as l, type RuntimeExecutor as m, type RuntimeJobState as n, type RuntimeLogMeta as o, type RuntimeLogger as p, type RuntimeRetryPolicy as q, type RuntimeRetryStrategy as r, type RuntimeRunResult as s, type RuntimeRunStatus as t, type RuntimeScheduleInput as u, type RuntimeSchedulePatch as v, type RuntimeTrigger as w, createConsoleRuntimeLogger as x, silentRuntimeLogger as y };
+export type { RuntimeJobRecord as R, RuntimeExecutionContext as a, RuntimeExecutor as b, RuntimeJobSchedule as c, RuntimeJobScheduleInput as d, RuntimeAtSchedule as e, RuntimeAtScheduleInput as f, RuntimeCronSchedule as g, RuntimeDeadLetterEvent as h, RuntimeDispatchInput as i, RuntimeEverySchedule as j, RuntimeExecutionResult as k, RuntimeJobState as l, RuntimeRetryPolicy as m, RuntimeRetryStrategy as n, RuntimeRunResult as o, RuntimeRunStatus as p, RuntimeScheduleInput as q, RuntimeSchedulePatch as r, RuntimeTrigger as s };

package/dist/workload/index.d.ts

@@ -0,0 +1,47 @@
+import { a as RuntimeExecutionContext, R as RuntimeJobRecord, b as RuntimeExecutor } from '../types-DllX9NP8.js';
+
+/**
+ * Context exposed to domain workloads that run inside `WorkloadRuntime`.
+ *
+ * This extends the low-level runtime execution context with stable job
+ * identity so application code does not need to understand runtime internals.
+ */
+interface RuntimeWorkloadContext extends RuntimeExecutionContext {
+    jobId: string;
+    jobName: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Domain workload function executed by the runtime.
+ *
+ * `agent-core` task runners, queue workers, and other app-level executors can
+ * all implement this shape and stay independent from any particular backend.
+ */
+type RuntimeWorkloadRunner<TPayload = unknown, TResult = unknown> = (payload: TPayload, context: RuntimeWorkloadContext) => Promise<TResult> | TResult;
+interface RuntimeWorkloadResultContext<TPayload = unknown, TResult = unknown> {
+    job: RuntimeJobRecord<TPayload>;
+    context: RuntimeWorkloadContext;
+    result: TResult;
+}
+interface RuntimeWorkloadErrorContext<TPayload = unknown> {
+    job: RuntimeJobRecord<TPayload>;
+    context: RuntimeWorkloadContext;
+    error: unknown;
+    message: string;
+}
+interface RuntimeWorkloadExecutorOptions<TPayload = unknown, TResult = unknown> {
+    run: RuntimeWorkloadRunner<TPayload, TResult>;
+    onResult?(context: RuntimeWorkloadResultContext<TPayload, TResult>): void | Promise<void>;
+    onError?(context: RuntimeWorkloadErrorContext<TPayload>): void | Promise<void>;
+}
+declare function createRuntimeWorkloadContext<TPayload>(job: RuntimeJobRecord<TPayload>, context: RuntimeExecutionContext): RuntimeWorkloadContext;
+/**
+ * Adapt a domain workload into the lower-level `RuntimeExecutor` contract.
+ *
+ * This is the seam between the orchestration layer and application-specific
+ * work. Most packages should plug into the runtime through this helper rather
+ * than constructing `execute(job, context)` inline.
+ */
+declare function createRuntimeWorkloadExecutor<TPayload = unknown, TResult = unknown>(options: RuntimeWorkloadExecutorOptions<TPayload, TResult>): RuntimeExecutor<TPayload>;
+
+export { type RuntimeWorkloadContext, type RuntimeWorkloadErrorContext, type RuntimeWorkloadExecutorOptions, type RuntimeWorkloadResultContext, type RuntimeWorkloadRunner, createRuntimeWorkloadContext, createRuntimeWorkloadExecutor };

package/dist/workload/index.js

@@ -0,0 +1,8 @@
+import {
+  createRuntimeWorkloadContext,
+  createRuntimeWorkloadExecutor
+} from "../chunk-INCALI7Z.js";
+export {
+  createRuntimeWorkloadContext,
+  createRuntimeWorkloadExecutor
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cuylabs/agent-runtime",
-  "version": "0.5.0",
-  "description": "Agent runtime orchestration layer - scheduling, execution, and pluggable runtime drivers",
+  "version": "0.7.0",
+  "description": "Workload runtime orchestration layer - scheduling, execution, and pluggable runtime drivers",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,6 +16,11 @@
       "import": "./dist/orchestration/index.js",
       "default": "./dist/orchestration/index.js"
     },
+    "./workload": {
+      "types": "./dist/workload/index.d.ts",
+      "import": "./dist/workload/index.js",
+      "default": "./dist/workload/index.js"
+    },
     "./drivers/in-memory": {
       "types": "./dist/drivers/in-memory.d.ts",
       "import": "./dist/drivers/in-memory.js",
@@ -56,8 +61,8 @@
     "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",
+    "build": "tsup src/index.ts src/orchestration/index.ts src/workload/index.ts src/drivers/in-memory.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/orchestration/index.ts src/workload/index.ts src/drivers/in-memory.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",