@agentium/queue 1.0.0

package/README.md

@@ -0,0 +1,32 @@
+# @agentium/queue
+
+Background job processing for Agentium agents using BullMQ and Redis.
+
+## Install
+
+```bash
+npm install @agentium/queue bullmq ioredis
+```
+
+## Quick Start
+
+```typescript
+import { Agent, openai } from "@agentium/core";
+import { AgentQueue, AgentWorker } from "@agentium/queue";
+
+const agent = new Agent({ name: "assistant", model: openai("gpt-4o") });
+const connection = { host: "localhost", port: 6379 };
+
+const queue = new AgentQueue({ connection });
+const worker = new AgentWorker({ agents: { assistant: agent }, connection });
+
+await queue.enqueueAgentRun({ agentName: "assistant", input: "Hello!" });
+```
+
+## Documentation
+
+Full docs at [agentium.mintlify.dev](https://agentium.mintlify.dev)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,306 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentQueue: () => AgentQueue,
+  AgentWorker: () => AgentWorker,
+  bridgeEventBusToJob: () => bridgeEventBusToJob
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/job-producer.ts
+var AgentQueue = class {
+  queue;
+  queueEvents;
+  queueName;
+  constructor(config) {
+    this.queueName = config.queueName ?? "agentium:jobs";
+    const connection = typeof config.connection === "string" ? { url: config.connection } : config.connection;
+    try {
+      const { Queue, QueueEvents } = require("bullmq");
+      this.queue = new Queue(this.queueName, {
+        connection,
+        defaultJobOptions: config.defaultJobOptions
+      });
+      this.queueEvents = new QueueEvents(this.queueName, {
+        connection
+      });
+    } catch (err) {
+      if (err?.code === "MODULE_NOT_FOUND" || err?.message?.includes("Cannot find module")) {
+        throw new Error("bullmq and ioredis are required for AgentQueue. Install them: npm install bullmq ioredis");
+      }
+      throw err;
+    }
+  }
+  async enqueueAgentRun(opts) {
+    const payload = {
+      type: "agent",
+      agentName: opts.agentName,
+      input: opts.input,
+      sessionId: opts.sessionId,
+      userId: opts.userId
+    };
+    const jobOpts = {};
+    if (opts.priority !== void 0) jobOpts.priority = opts.priority;
+    if (opts.delay !== void 0) jobOpts.delay = opts.delay;
+    if (opts.attempts !== void 0) jobOpts.attempts = opts.attempts;
+    if (opts.backoff) jobOpts.backoff = opts.backoff;
+    if (opts.repeat) jobOpts.repeat = opts.repeat;
+    const job = await this.queue.add(`agent:${opts.agentName}`, payload, jobOpts);
+    return { jobId: job.id };
+  }
+  async enqueueWorkflow(opts) {
+    const payload = {
+      type: "workflow",
+      workflowName: opts.workflowName,
+      initialState: opts.initialState,
+      sessionId: opts.sessionId
+    };
+    const jobOpts = {};
+    if (opts.priority !== void 0) jobOpts.priority = opts.priority;
+    if (opts.delay !== void 0) jobOpts.delay = opts.delay;
+    if (opts.attempts !== void 0) jobOpts.attempts = opts.attempts;
+    if (opts.backoff) jobOpts.backoff = opts.backoff;
+    if (opts.repeat) jobOpts.repeat = opts.repeat;
+    const job = await this.queue.add(`workflow:${opts.workflowName}`, payload, jobOpts);
+    return { jobId: job.id };
+  }
+  async enqueueTeamRun(opts) {
+    const payload = {
+      type: "team",
+      teamName: opts.teamName,
+      input: opts.input,
+      sessionId: opts.sessionId,
+      userId: opts.userId
+    };
+    const jobOpts = {};
+    if (opts.priority !== void 0) jobOpts.priority = opts.priority;
+    if (opts.delay !== void 0) jobOpts.delay = opts.delay;
+    if (opts.attempts !== void 0) jobOpts.attempts = opts.attempts;
+    if (opts.backoff) jobOpts.backoff = opts.backoff;
+    if (opts.repeat) jobOpts.repeat = opts.repeat;
+    const job = await this.queue.add(`team:${opts.teamName}`, payload, jobOpts);
+    return { jobId: job.id };
+  }
+  async getJobStatus(jobId) {
+    const job = await this.queue.getJob(jobId);
+    if (!job) {
+      throw new Error(`Job ${jobId} not found`);
+    }
+    const state = await job.getState();
+    return {
+      jobId: job.id,
+      state,
+      progress: typeof job.progress === "number" ? job.progress : void 0,
+      result: job.returnvalue,
+      error: job.failedReason,
+      createdAt: new Date(job.timestamp),
+      processedAt: job.processedOn ? new Date(job.processedOn) : void 0,
+      finishedAt: job.finishedOn ? new Date(job.finishedOn) : void 0
+    };
+  }
+  async cancelJob(jobId) {
+    const job = await this.queue.getJob(jobId);
+    if (job) {
+      await job.remove();
+    }
+  }
+  onCompleted(handler) {
+    this.queueEvents.on("completed", ({ jobId, returnvalue }) => {
+      handler(jobId, returnvalue);
+    });
+  }
+  onFailed(handler) {
+    this.queueEvents.on("failed", ({ jobId, failedReason }) => {
+      handler(jobId, new Error(failedReason));
+    });
+  }
+  async schedule(opts) {
+    if (!opts.agent && !opts.workflow) {
+      throw new Error("schedule() requires either agent or workflow");
+    }
+    if (opts.agent && opts.workflow) {
+      throw new Error("schedule() accepts either agent or workflow, not both");
+    }
+    const repeat = { pattern: opts.cron, ...opts.timezone ? { tz: opts.timezone } : {} };
+    if (opts.agent) {
+      return this.enqueueAgentRun({
+        agentName: opts.agent.name,
+        input: opts.agent.input,
+        sessionId: opts.agent.sessionId,
+        userId: opts.agent.userId,
+        repeat
+      });
+    }
+    if (opts.team) {
+      return this.enqueueTeamRun({
+        teamName: opts.team.name,
+        input: opts.team.input,
+        sessionId: opts.team.sessionId,
+        userId: opts.team.userId,
+        repeat
+      });
+    }
+    return this.enqueueWorkflow({
+      workflowName: opts.workflow.name,
+      initialState: opts.workflow.initialState,
+      repeat
+    });
+  }
+  async unschedule(id) {
+    const jobs = await this.queue.getRepeatableJobs();
+    const match = jobs.find((j) => j.name === `agent:${id}` || j.name === `workflow:${id}` || j.name === id);
+    if (!match) {
+      throw new Error(`Schedule "${id}" not found`);
+    }
+    await this.queue.removeRepeatableByKey(match.key);
+  }
+  async listSchedules() {
+    const jobs = await this.queue.getRepeatableJobs();
+    return jobs.map((j) => ({
+      id: j.name,
+      pattern: j.pattern ?? j.cron,
+      timezone: j.tz ?? void 0,
+      next: j.next ? new Date(j.next) : /* @__PURE__ */ new Date()
+    }));
+  }
+  async close() {
+    const results = await Promise.allSettled([this.queue.close(), this.queueEvents.close()]);
+    for (const r of results) {
+      if (r.status === "rejected") console.warn("[JobProducer] Error during close:", r.reason);
+    }
+  }
+};
+
+// src/job-worker.ts
+var AgentWorker = class {
+  worker;
+  constructor(config) {
+    const queueName = config.queueName ?? "agentium:jobs";
+    const concurrency = config.concurrency ?? 5;
+    const connection = typeof config.connection === "string" ? { url: config.connection } : config.connection;
+    const defaultJobOptions = {
+      attempts: config.attempts ?? 3,
+      backoff: {
+        type: "exponential",
+        delay: config.backoffDelay ?? 1e3
+      }
+    };
+    try {
+      const { Worker } = require("bullmq");
+      this.worker = new Worker(
+        queueName,
+        async (job) => {
+          const payload = job.data;
+          if (payload.type === "agent") {
+            const agent = config.agentRegistry[payload.agentName];
+            if (!agent) {
+              throw new Error(`Agent "${payload.agentName}" not found in registry`);
+            }
+            const onChunk = (_evt) => {
+              job.updateProgress(typeof job.progress === "number" ? job.progress + 1 : 1);
+            };
+            agent.eventBus.on("run.stream.chunk", onChunk);
+            try {
+              const result = await agent.run(payload.input, {
+                sessionId: payload.sessionId,
+                userId: payload.userId
+              });
+              return result;
+            } finally {
+              agent.eventBus.off("run.stream.chunk", onChunk);
+            }
+          }
+          if (payload.type === "workflow") {
+            const workflow = config.workflowRegistry?.[payload.workflowName];
+            if (!workflow) {
+              throw new Error(`Workflow "${payload.workflowName}" not found in registry`);
+            }
+            const result = await workflow.run({
+              sessionId: payload.sessionId
+            });
+            return result;
+          }
+          if (payload.type === "team") {
+            const team = config.teamRegistry?.[payload.teamName];
+            if (!team) {
+              throw new Error(`Team "${payload.teamName}" not found in registry`);
+            }
+            const result = await team.run(payload.input, {
+              sessionId: payload.sessionId,
+              userId: payload.userId
+            });
+            return result;
+          }
+          throw new Error(`Unknown job type: ${payload.type}`);
+        },
+        {
+          connection,
+          concurrency,
+          defaultJobOptions
+        }
+      );
+    } catch (err) {
+      if (err?.code === "MODULE_NOT_FOUND" || err?.message?.includes("Cannot find module")) {
+        throw new Error("bullmq and ioredis are required for AgentWorker. Install them: npm install bullmq ioredis");
+      }
+      throw err;
+    }
+  }
+  start() {
+  }
+  async stop(timeoutMs = 3e4) {
+    await Promise.race([
+      this.worker.close(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("Worker drain timeout")), timeoutMs))
+    ]).catch((err) => {
+      console.warn("[JobWorker] Error during stop:", err?.message ?? err);
+    });
+  }
+};
+
+// src/progress.ts
+function bridgeEventBusToJob(eventBus, job, runId) {
+  let progressCount = 0;
+  const onChunk = (evt) => {
+    if (evt.runId !== runId) return;
+    progressCount++;
+    job.updateProgress(progressCount).catch(() => {
+    });
+  };
+  const onToolCall = (evt) => {
+    if (evt.runId !== runId) return;
+    job.log(`Tool call: ${evt.toolName}`).catch(() => {
+    });
+  };
+  eventBus.on("run.stream.chunk", onChunk);
+  eventBus.on("tool.call", onToolCall);
+  return () => {
+    eventBus.off("run.stream.chunk", onChunk);
+    eventBus.off("tool.call", onToolCall);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentQueue,
+  AgentWorker,
+  bridgeEventBusToJob
+});

package/dist/index.d.cts

@@ -0,0 +1,171 @@
+import * as _agentium_core from '@agentium/core';
+import { RunOutput, Agent, Workflow, EventBus } from '@agentium/core';
+
+type AgentJobPayload = {
+    type: "agent";
+    agentName: string;
+    input: string;
+    sessionId?: string;
+    userId?: string;
+};
+type WorkflowJobPayload = {
+    type: "workflow";
+    workflowName: string;
+    initialState?: Record<string, unknown>;
+    sessionId?: string;
+};
+type TeamJobPayload = {
+    type: "team";
+    teamName: string;
+    input: string;
+    sessionId?: string;
+    userId?: string;
+};
+type JobPayload = AgentJobPayload | WorkflowJobPayload | TeamJobPayload;
+type ScheduleInfo = {
+    id: string;
+    pattern: string;
+    timezone?: string;
+    next: Date;
+};
+type JobStatus = {
+    jobId: string;
+    state: "waiting" | "active" | "completed" | "failed" | "delayed";
+    progress?: number;
+    result?: RunOutput;
+    error?: string;
+    createdAt: Date;
+    processedAt?: Date;
+    finishedAt?: Date;
+};
+
+interface QueueConfig {
+    connection: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+        tls?: boolean;
+    } | string;
+    queueName?: string;
+    defaultJobOptions?: Record<string, unknown>;
+}
+declare class AgentQueue {
+    private queue;
+    private queueEvents;
+    private queueName;
+    constructor(config: QueueConfig);
+    enqueueAgentRun(opts: {
+        agentName: string;
+        input: string;
+        sessionId?: string;
+        userId?: string;
+        priority?: number;
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: "exponential" | "fixed";
+            delay: number;
+        };
+        repeat?: {
+            pattern: string;
+            timezone?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    enqueueWorkflow(opts: {
+        workflowName: string;
+        initialState?: Record<string, unknown>;
+        sessionId?: string;
+        priority?: number;
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: "exponential" | "fixed";
+            delay: number;
+        };
+        repeat?: {
+            pattern: string;
+            timezone?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    enqueueTeamRun(opts: {
+        teamName: string;
+        input: string;
+        sessionId?: string;
+        userId?: string;
+        priority?: number;
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: "exponential" | "fixed";
+            delay: number;
+        };
+        repeat?: {
+            pattern: string;
+            timezone?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    getJobStatus(jobId: string): Promise<JobStatus>;
+    cancelJob(jobId: string): Promise<void>;
+    onCompleted(handler: (jobId: string, result: RunOutput) => void): void;
+    onFailed(handler: (jobId: string, error: Error) => void): void;
+    schedule(opts: {
+        id: string;
+        cron: string;
+        timezone?: string;
+        agent?: {
+            name: string;
+            input: string;
+            sessionId?: string;
+            userId?: string;
+        };
+        workflow?: {
+            name: string;
+            initialState?: Record<string, unknown>;
+        };
+        team?: {
+            name: string;
+            input: string;
+            sessionId?: string;
+            userId?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    unschedule(id: string): Promise<void>;
+    listSchedules(): Promise<ScheduleInfo[]>;
+    close(): Promise<void>;
+}
+
+interface WorkerConfig {
+    connection: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+        tls?: boolean;
+    } | string;
+    queueName?: string;
+    concurrency?: number;
+    attempts?: number;
+    backoffDelay?: number;
+    agentRegistry: Record<string, Agent>;
+    workflowRegistry?: Record<string, Workflow<any>>;
+    teamRegistry?: Record<string, _agentium_core.Team>;
+}
+declare class AgentWorker {
+    private worker;
+    constructor(config: WorkerConfig);
+    start(): void;
+    stop(timeoutMs?: number): Promise<void>;
+}
+
+declare function bridgeEventBusToJob(eventBus: EventBus, job: any, runId: string): () => void;
+
+export { type AgentJobPayload, AgentQueue, AgentWorker, type JobPayload, type JobStatus, type QueueConfig, type ScheduleInfo, type TeamJobPayload, type WorkerConfig, type WorkflowJobPayload, bridgeEventBusToJob };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import * as _agentium_core from '@agentium/core';
+import { RunOutput, Agent, Workflow, EventBus } from '@agentium/core';
+
+type AgentJobPayload = {
+    type: "agent";
+    agentName: string;
+    input: string;
+    sessionId?: string;
+    userId?: string;
+};
+type WorkflowJobPayload = {
+    type: "workflow";
+    workflowName: string;
+    initialState?: Record<string, unknown>;
+    sessionId?: string;
+};
+type TeamJobPayload = {
+    type: "team";
+    teamName: string;
+    input: string;
+    sessionId?: string;
+    userId?: string;
+};
+type JobPayload = AgentJobPayload | WorkflowJobPayload | TeamJobPayload;
+type ScheduleInfo = {
+    id: string;
+    pattern: string;
+    timezone?: string;
+    next: Date;
+};
+type JobStatus = {
+    jobId: string;
+    state: "waiting" | "active" | "completed" | "failed" | "delayed";
+    progress?: number;
+    result?: RunOutput;
+    error?: string;
+    createdAt: Date;
+    processedAt?: Date;
+    finishedAt?: Date;
+};
+
+interface QueueConfig {
+    connection: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+        tls?: boolean;
+    } | string;
+    queueName?: string;
+    defaultJobOptions?: Record<string, unknown>;
+}
+declare class AgentQueue {
+    private queue;
+    private queueEvents;
+    private queueName;
+    constructor(config: QueueConfig);
+    enqueueAgentRun(opts: {
+        agentName: string;
+        input: string;
+        sessionId?: string;
+        userId?: string;
+        priority?: number;
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: "exponential" | "fixed";
+            delay: number;
+        };
+        repeat?: {
+            pattern: string;
+            timezone?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    enqueueWorkflow(opts: {
+        workflowName: string;
+        initialState?: Record<string, unknown>;
+        sessionId?: string;
+        priority?: number;
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: "exponential" | "fixed";
+            delay: number;
+        };
+        repeat?: {
+            pattern: string;
+            timezone?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    enqueueTeamRun(opts: {
+        teamName: string;
+        input: string;
+        sessionId?: string;
+        userId?: string;
+        priority?: number;
+        delay?: number;
+        attempts?: number;
+        backoff?: {
+            type: "exponential" | "fixed";
+            delay: number;
+        };
+        repeat?: {
+            pattern: string;
+            timezone?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    getJobStatus(jobId: string): Promise<JobStatus>;
+    cancelJob(jobId: string): Promise<void>;
+    onCompleted(handler: (jobId: string, result: RunOutput) => void): void;
+    onFailed(handler: (jobId: string, error: Error) => void): void;
+    schedule(opts: {
+        id: string;
+        cron: string;
+        timezone?: string;
+        agent?: {
+            name: string;
+            input: string;
+            sessionId?: string;
+            userId?: string;
+        };
+        workflow?: {
+            name: string;
+            initialState?: Record<string, unknown>;
+        };
+        team?: {
+            name: string;
+            input: string;
+            sessionId?: string;
+            userId?: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    unschedule(id: string): Promise<void>;
+    listSchedules(): Promise<ScheduleInfo[]>;
+    close(): Promise<void>;
+}
+
+interface WorkerConfig {
+    connection: {
+        host: string;
+        port: number;
+        password?: string;
+        db?: number;
+        tls?: boolean;
+    } | string;
+    queueName?: string;
+    concurrency?: number;
+    attempts?: number;
+    backoffDelay?: number;
+    agentRegistry: Record<string, Agent>;
+    workflowRegistry?: Record<string, Workflow<any>>;
+    teamRegistry?: Record<string, _agentium_core.Team>;
+}
+declare class AgentWorker {
+    private worker;
+    constructor(config: WorkerConfig);
+    start(): void;
+    stop(timeoutMs?: number): Promise<void>;
+}
+
+declare function bridgeEventBusToJob(eventBus: EventBus, job: any, runId: string): () => void;
+
+export { type AgentJobPayload, AgentQueue, AgentWorker, type JobPayload, type JobStatus, type QueueConfig, type ScheduleInfo, type TeamJobPayload, type WorkerConfig, type WorkflowJobPayload, bridgeEventBusToJob };

package/dist/index.js

@@ -0,0 +1,284 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/job-producer.ts
+var AgentQueue = class {
+  queue;
+  queueEvents;
+  queueName;
+  constructor(config) {
+    this.queueName = config.queueName ?? "agentium:jobs";
+    const connection = typeof config.connection === "string" ? { url: config.connection } : config.connection;
+    try {
+      const { Queue, QueueEvents } = __require("bullmq");
+      this.queue = new Queue(this.queueName, {
+        connection,
+        defaultJobOptions: config.defaultJobOptions
+      });
+      this.queueEvents = new QueueEvents(this.queueName, {
+        connection
+      });
+    } catch (err) {
+      if (err?.code === "MODULE_NOT_FOUND" || err?.message?.includes("Cannot find module")) {
+        throw new Error("bullmq and ioredis are required for AgentQueue. Install them: npm install bullmq ioredis");
+      }
+      throw err;
+    }
+  }
+  async enqueueAgentRun(opts) {
+    const payload = {
+      type: "agent",
+      agentName: opts.agentName,
+      input: opts.input,
+      sessionId: opts.sessionId,
+      userId: opts.userId
+    };
+    const jobOpts = {};
+    if (opts.priority !== void 0) jobOpts.priority = opts.priority;
+    if (opts.delay !== void 0) jobOpts.delay = opts.delay;
+    if (opts.attempts !== void 0) jobOpts.attempts = opts.attempts;
+    if (opts.backoff) jobOpts.backoff = opts.backoff;
+    if (opts.repeat) jobOpts.repeat = opts.repeat;
+    const job = await this.queue.add(`agent:${opts.agentName}`, payload, jobOpts);
+    return { jobId: job.id };
+  }
+  async enqueueWorkflow(opts) {
+    const payload = {
+      type: "workflow",
+      workflowName: opts.workflowName,
+      initialState: opts.initialState,
+      sessionId: opts.sessionId
+    };
+    const jobOpts = {};
+    if (opts.priority !== void 0) jobOpts.priority = opts.priority;
+    if (opts.delay !== void 0) jobOpts.delay = opts.delay;
+    if (opts.attempts !== void 0) jobOpts.attempts = opts.attempts;
+    if (opts.backoff) jobOpts.backoff = opts.backoff;
+    if (opts.repeat) jobOpts.repeat = opts.repeat;
+    const job = await this.queue.add(`workflow:${opts.workflowName}`, payload, jobOpts);
+    return { jobId: job.id };
+  }
+  async enqueueTeamRun(opts) {
+    const payload = {
+      type: "team",
+      teamName: opts.teamName,
+      input: opts.input,
+      sessionId: opts.sessionId,
+      userId: opts.userId
+    };
+    const jobOpts = {};
+    if (opts.priority !== void 0) jobOpts.priority = opts.priority;
+    if (opts.delay !== void 0) jobOpts.delay = opts.delay;
+    if (opts.attempts !== void 0) jobOpts.attempts = opts.attempts;
+    if (opts.backoff) jobOpts.backoff = opts.backoff;
+    if (opts.repeat) jobOpts.repeat = opts.repeat;
+    const job = await this.queue.add(`team:${opts.teamName}`, payload, jobOpts);
+    return { jobId: job.id };
+  }
+  async getJobStatus(jobId) {
+    const job = await this.queue.getJob(jobId);
+    if (!job) {
+      throw new Error(`Job ${jobId} not found`);
+    }
+    const state = await job.getState();
+    return {
+      jobId: job.id,
+      state,
+      progress: typeof job.progress === "number" ? job.progress : void 0,
+      result: job.returnvalue,
+      error: job.failedReason,
+      createdAt: new Date(job.timestamp),
+      processedAt: job.processedOn ? new Date(job.processedOn) : void 0,
+      finishedAt: job.finishedOn ? new Date(job.finishedOn) : void 0
+    };
+  }
+  async cancelJob(jobId) {
+    const job = await this.queue.getJob(jobId);
+    if (job) {
+      await job.remove();
+    }
+  }
+  onCompleted(handler) {
+    this.queueEvents.on("completed", ({ jobId, returnvalue }) => {
+      handler(jobId, returnvalue);
+    });
+  }
+  onFailed(handler) {
+    this.queueEvents.on("failed", ({ jobId, failedReason }) => {
+      handler(jobId, new Error(failedReason));
+    });
+  }
+  async schedule(opts) {
+    if (!opts.agent && !opts.workflow) {
+      throw new Error("schedule() requires either agent or workflow");
+    }
+    if (opts.agent && opts.workflow) {
+      throw new Error("schedule() accepts either agent or workflow, not both");
+    }
+    const repeat = { pattern: opts.cron, ...opts.timezone ? { tz: opts.timezone } : {} };
+    if (opts.agent) {
+      return this.enqueueAgentRun({
+        agentName: opts.agent.name,
+        input: opts.agent.input,
+        sessionId: opts.agent.sessionId,
+        userId: opts.agent.userId,
+        repeat
+      });
+    }
+    if (opts.team) {
+      return this.enqueueTeamRun({
+        teamName: opts.team.name,
+        input: opts.team.input,
+        sessionId: opts.team.sessionId,
+        userId: opts.team.userId,
+        repeat
+      });
+    }
+    return this.enqueueWorkflow({
+      workflowName: opts.workflow.name,
+      initialState: opts.workflow.initialState,
+      repeat
+    });
+  }
+  async unschedule(id) {
+    const jobs = await this.queue.getRepeatableJobs();
+    const match = jobs.find((j) => j.name === `agent:${id}` || j.name === `workflow:${id}` || j.name === id);
+    if (!match) {
+      throw new Error(`Schedule "${id}" not found`);
+    }
+    await this.queue.removeRepeatableByKey(match.key);
+  }
+  async listSchedules() {
+    const jobs = await this.queue.getRepeatableJobs();
+    return jobs.map((j) => ({
+      id: j.name,
+      pattern: j.pattern ?? j.cron,
+      timezone: j.tz ?? void 0,
+      next: j.next ? new Date(j.next) : /* @__PURE__ */ new Date()
+    }));
+  }
+  async close() {
+    const results = await Promise.allSettled([this.queue.close(), this.queueEvents.close()]);
+    for (const r of results) {
+      if (r.status === "rejected") console.warn("[JobProducer] Error during close:", r.reason);
+    }
+  }
+};
+
+// src/job-worker.ts
+var AgentWorker = class {
+  worker;
+  constructor(config) {
+    const queueName = config.queueName ?? "agentium:jobs";
+    const concurrency = config.concurrency ?? 5;
+    const connection = typeof config.connection === "string" ? { url: config.connection } : config.connection;
+    const defaultJobOptions = {
+      attempts: config.attempts ?? 3,
+      backoff: {
+        type: "exponential",
+        delay: config.backoffDelay ?? 1e3
+      }
+    };
+    try {
+      const { Worker } = __require("bullmq");
+      this.worker = new Worker(
+        queueName,
+        async (job) => {
+          const payload = job.data;
+          if (payload.type === "agent") {
+            const agent = config.agentRegistry[payload.agentName];
+            if (!agent) {
+              throw new Error(`Agent "${payload.agentName}" not found in registry`);
+            }
+            const onChunk = (_evt) => {
+              job.updateProgress(typeof job.progress === "number" ? job.progress + 1 : 1);
+            };
+            agent.eventBus.on("run.stream.chunk", onChunk);
+            try {
+              const result = await agent.run(payload.input, {
+                sessionId: payload.sessionId,
+                userId: payload.userId
+              });
+              return result;
+            } finally {
+              agent.eventBus.off("run.stream.chunk", onChunk);
+            }
+          }
+          if (payload.type === "workflow") {
+            const workflow = config.workflowRegistry?.[payload.workflowName];
+            if (!workflow) {
+              throw new Error(`Workflow "${payload.workflowName}" not found in registry`);
+            }
+            const result = await workflow.run({
+              sessionId: payload.sessionId
+            });
+            return result;
+          }
+          if (payload.type === "team") {
+            const team = config.teamRegistry?.[payload.teamName];
+            if (!team) {
+              throw new Error(`Team "${payload.teamName}" not found in registry`);
+            }
+            const result = await team.run(payload.input, {
+              sessionId: payload.sessionId,
+              userId: payload.userId
+            });
+            return result;
+          }
+          throw new Error(`Unknown job type: ${payload.type}`);
+        },
+        {
+          connection,
+          concurrency,
+          defaultJobOptions
+        }
+      );
+    } catch (err) {
+      if (err?.code === "MODULE_NOT_FOUND" || err?.message?.includes("Cannot find module")) {
+        throw new Error("bullmq and ioredis are required for AgentWorker. Install them: npm install bullmq ioredis");
+      }
+      throw err;
+    }
+  }
+  start() {
+  }
+  async stop(timeoutMs = 3e4) {
+    await Promise.race([
+      this.worker.close(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("Worker drain timeout")), timeoutMs))
+    ]).catch((err) => {
+      console.warn("[JobWorker] Error during stop:", err?.message ?? err);
+    });
+  }
+};
+
+// src/progress.ts
+function bridgeEventBusToJob(eventBus, job, runId) {
+  let progressCount = 0;
+  const onChunk = (evt) => {
+    if (evt.runId !== runId) return;
+    progressCount++;
+    job.updateProgress(progressCount).catch(() => {
+    });
+  };
+  const onToolCall = (evt) => {
+    if (evt.runId !== runId) return;
+    job.log(`Tool call: ${evt.toolName}`).catch(() => {
+    });
+  };
+  eventBus.on("run.stream.chunk", onChunk);
+  eventBus.on("tool.call", onToolCall);
+  return () => {
+    eventBus.off("run.stream.chunk", onChunk);
+    eventBus.off("tool.call", onToolCall);
+  };
+}
+export {
+  AgentQueue,
+  AgentWorker,
+  bridgeEventBusToJob
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@agentium/queue",
+  "version": "1.0.0",
+  "description": "Background job processing for Agentium agents using BullMQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentiumOS/agentium.git",
+    "directory": "packages/queue"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "queue",
+    "bullmq",
+    "redis",
+    "background-jobs"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --shims --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --shims --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "@agentium/core": "^1.0.0",
+    "bullmq": "^5.0.0",
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "bullmq": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  }
+}