@cogitator-ai/worker 0.3.20 → 0.4.1

package/README.md

@@ -5,13 +5,15 @@ Distributed job queue for Cogitator agent execution. Built on BullMQ for reliabl
 ## Installation
 
 ```bash
-pnpm add @cogitator-ai/worker ioredis
+pnpm add @cogitator-ai/worker @cogitator-ai/core ioredis
 ```
 
 ## Features
 
 - **BullMQ-Based** - Reliable job processing with Redis
-- **Job Types** - Agents, workflows, and swarms
+- **Job Types** - Agents, workflow graphs, swarms and distributed swarm turns
+- **Worker Runtime** - Run jobs with your own `Cogitator` (provider keys, memory) and tool implementations
+- **Distributed Swarms** - `DistributedSwarmWorker` executes agent turns for `@cogitator-ai/swarms`
 - **Auto-Retry** - Exponential backoff for failed jobs
 - **Priority Queue** - Process important jobs first
 - **Delayed Jobs** - Schedule jobs for later execution
@@ -35,7 +37,7 @@ const queue = new JobQueue({
 const agentConfig = {
   name: 'Assistant',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-4',
+  model: 'openai/gpt-4o',
   provider: 'openai' as const,
   tools: [],
 };
@@ -51,17 +53,24 @@ console.log(`Job added: ${job.id}`);
 ### Consumer: Process Jobs
 
 ```typescript
+import { Cogitator } from '@cogitator-ai/core';
 import { WorkerPool } from '@cogitator-ai/worker';
 
 const pool = new WorkerPool({
   redis: { host: 'localhost', port: 6379 },
   concurrency: 5,
   workerCount: 2,
+  cogitator: new Cogitator({
+    llm: { providers: { openai: { apiKey: process.env.OPENAI_API_KEY } } },
+  }),
+  tools: [searchTool], // implementations for tools referenced by serialized agents
 });
 
 await pool.start();
 ```
 
+Serialized agents reference tools by name. The worker resolves them from its `tools`; a job whose agent needs a tool the worker does not provide fails with `Tools not registered on this worker: <names>`.
+
 ---
 
 ## Job Queue
@@ -122,10 +131,11 @@ interface QueueConfig {
 const agentConfig: SerializedAgent = {
   name: 'Researcher',
   instructions: 'Research and summarize topics.',
-  model: 'openai/gpt-4',
+  model: 'openai/gpt-4o', // or 'gpt-4o' — the provider is prepended when missing
   provider: 'openai',
   temperature: 0.7,
   maxTokens: 2048,
+  maxIterations: 5,
   tools: [
     {
       name: 'search',
@@ -145,38 +155,60 @@ const job = await queue.addAgentJob(agentConfig, 'Research quantum computing', {
 
 **Workflow Jobs:**
 
+Workflow jobs run a DAG over a shared state object initialised from the job input. Nodes run as soon as their predecessors settle; independent branches run concurrently.
+
 ```typescript
 const workflowConfig: SerializedWorkflow = {
-  id: 'data-pipeline',
-  name: 'Data Pipeline',
+  id: 'triage',
+  name: 'Ticket triage',
   nodes: [
-    { id: 'fetch', type: 'agent', config: { agentConfig: fetchAgent } },
-    { id: 'process', type: 'transform', config: { transform: 'uppercase' } },
-    { id: 'store', type: 'agent', config: { agentConfig: storeAgent } },
+    {
+      id: 'classify',
+      type: 'agent',
+      config: {
+        agentConfig: classifierAgent, // SerializedAgent
+        prompt: 'Classify this ticket as BUG or QUESTION: {{ticket}}',
+        outputKey: 'category',
+      },
+    },
+    { id: 'normalize', type: 'transform', config: { transform: 'trim', inputKey: 'category' } },
+    {
+      id: 'is-bug',
+      type: 'condition',
+      config: { key: 'normalize', operator: 'contains', value: 'BUG' },
+    },
+    {
+      id: 'summary',
+      type: 'transform',
+      config: { transform: 'template', template: 'Bug report: {{ticket}}' },
+    },
   ],
   edges: [
-    { from: 'fetch', to: 'process' },
-    { from: 'process', to: 'store' },
+    { from: 'classify', to: 'normalize' },
+    { from: 'normalize', to: 'is-bug' },
+    { from: 'is-bug', to: 'summary', condition: 'true' },
   ],
 };
 
-await queue.addWorkflowJob(
-  workflowConfig,
-  { source: 'api' },
-  {
-    runId: 'run-789',
-    priority: 2,
-  }
-);
+await queue.addWorkflowJob(workflowConfig, { ticket: 'App crashes on login' });
 ```
 
+| Node type   | Config                                                                                                                                    |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent`     | `{ agentConfig, prompt?, outputKey? }` — `prompt` supports `{{path}}` placeholders; default prompt is the state as JSON                   |
+| `transform` | `{ transform, inputKey?, outputKey?, template? }` — `uppercase`, `lowercase`, `trim`, `json-parse`, `json-stringify`, `template`          |
+| `condition` | `{ key, operator, value? }` — `equals`, `not-equals`, `contains`, `exists`, `gt`, `lt`; outgoing edges use `condition: 'true' \| 'false'` |
+| `parallel`  | `{}` — fan-out marker; successors run concurrently                                                                                        |
+
+Node outputs are stored in the state under `outputKey` (default: node id). Nodes reachable only through untaken condition branches are skipped (`{ skipped: true }` in `nodeResults`). Graphs are validated before execution (unknown nodes, invalid configs, cycles).
+
 **Swarm Jobs:**
 
 ```typescript
 const swarmConfig: SerializedSwarm = {
-  topology: 'collaborative',
+  topology: 'voting',
   agents: [researcherConfig, writerConfig, editorConfig],
-  coordinator: coordinatorConfig,
+  coordinator: coordinatorConfig, // decides when no consensus is reached
   maxRounds: 3,
   consensusThreshold: 0.8,
 };
@@ -187,6 +219,14 @@ await queue.addSwarmJob(swarmConfig, 'Write an article about AI', {
 });
 ```
 
+| Topology        | Swarm strategy | Notes                                                        |
+| --------------- | -------------- | ------------------------------------------------------------ |
+| `sequential`    | `pipeline`     | One stage per agent, in order                                |
+| `hierarchical`  | `hierarchical` | `coordinator` is required and becomes the supervisor         |
+| `collaborative` | `round-robin`  |                                                              |
+| `debate`        | `debate`       | `maxRounds` rounds, `coordinator` moderates                  |
+| `voting`        | `consensus`    | `consensusThreshold`, `maxRounds`; `coordinator` breaks ties |
+
 ### Queue Methods
 
 ```typescript
@@ -254,6 +294,8 @@ interface WorkerConfig extends QueueConfig {
   concurrency?: number; // Default: 5
   lockDuration?: number; // Default: 30000ms
   stalledInterval?: number; // Default: 30000ms
+  cogitator?: Cogitator; // Default: new Cogitator()
+  tools?: Tool[]; // Tool implementations, resolved by name
 }
 ```
 
@@ -268,7 +310,7 @@ interface WorkerConfig extends QueueConfig {
 
 ```typescript
 interface WorkerPoolEvents {
-  onJobStarted?: (jobId: string, type: 'agent' | 'workflow' | 'swarm') => void;
+  onJobStarted?: (jobId: string, type: 'agent' | 'workflow' | 'swarm' | 'swarm-agent') => void;
   onJobCompleted?: (jobId: string, result: JobResult) => void;
   onJobFailed?: (jobId: string, error: Error) => void;
   onWorkerError?: (error: Error) => void;
@@ -286,7 +328,10 @@ pool.getWorkerCount();
 
 const metrics = await pool.getMetrics(await queue.getMetrics());
 
-// Graceful shutdown (waits up to 30s for active jobs)
+// Job duration histogram and per-type counters
+pool.metrics.format(await pool.getMetrics(await queue.getMetrics()));
+
+// Graceful shutdown (waits up to 30s for active jobs, then force-closes)
 await pool.stop(30000);
 
 // Force shutdown
@@ -301,26 +346,62 @@ Built-in processors handle each job type.
 
 ### Using Processors Directly
 
+Processors take the job payload and an optional runtime (`{ cogitator, tools }`):
+
 ```typescript
-import { processAgentJob, processSwarmJob, processSwarmAgentJob } from '@cogitator-ai/worker';
-
-const agentResult = await processAgentJob({
-  type: 'agent',
-  jobId: 'job-1',
-  agentConfig: myAgentConfig,
-  input: 'Hello!',
-  threadId: 'thread-1',
-});
+import { processAgentJob, processWorkflowJob, processSwarmJob } from '@cogitator-ai/worker';
 
-const swarmResult = await processSwarmJob({
-  type: 'swarm',
-  jobId: 'job-3',
-  swarmConfig: mySwarmConfig,
-  input: 'Solve this problem',
-});
+const runtime = { cogitator, tools: [searchTool] };
+
+const agentResult = await processAgentJob(
+  { type: 'agent', jobId: 'job-1', agentConfig: myAgentConfig, input: 'Hello!', threadId: 't-1' },
+  runtime
+);
+
+const workflowResult = await processWorkflowJob(
+  { type: 'workflow', jobId: 'job-2', runId: 'run-1', workflowConfig, input: { ticket: '...' } },
+  runtime
+);
+
+const swarmResult = await processSwarmJob(
+  { type: 'swarm', jobId: 'job-3', swarmConfig: mySwarmConfig, input: 'Solve this problem' },
+  runtime
+);
+```
+
+`processSwarmAgentJob(payload, { publisher, isFinalAttempt, ...runtime })` executes one distributed swarm turn and publishes the result (tagged with the job id) to `payload.stateKeys.results`; `executeSwarmAgentJob` returns the result without publishing.
+
+---
+
+## Distributed Swarm Workers
+
+Swarms created with `distributed.enabled` (see `@cogitator-ai/swarms`) dispatch every agent turn to a Redis queue. `DistributedSwarmWorker` consumes those turns:
+
+```typescript
+import { Cogitator } from '@cogitator-ai/core';
+import { DistributedSwarmWorker } from '@cogitator-ai/worker';
+
+const worker = new DistributedSwarmWorker(
+  {
+    redis: { host: 'localhost', port: 6379 },
+    keyPrefix: 'swarm', // must match the swarm's distributed.redis.keyPrefix
+    queue: 'swarm-agent-jobs', // must match distributed.queue
+    concurrency: 4,
+    cogitator: new Cogitator({ llm: { defaultModel: 'ollama/llama3.2' } }),
+    tools: [searchTool],
+  },
+  {
+    onJobCompleted: (job) => console.log('done', job.agentName),
+    onJobFailed: (job, error) => console.error(job.agentName, error.message),
+    onError: (error) => console.error(error),
+  }
+);
+
+await worker.start();
+process.on('SIGTERM', () => void worker.stop()); // waits for in-flight turns
 ```
 
-> **Note:** `processWorkflowJob` is not yet implemented — it throws an error. Workflows should be executed directly via `WorkflowExecutor` from `@cogitator-ai/workflows`.
+Failed turns are reported back to the swarm as errors, so the swarm's own `errorHandling` (retry, failover, skip) applies.
 
 ---
 
@@ -381,24 +462,18 @@ Built-in metrics for monitoring and Kubernetes HPA.
 ### Exposing Metrics
 
 ```typescript
-import {
-  JobQueue,
-  WorkerPool,
-  MetricsCollector,
-  formatPrometheusMetrics,
-} from '@cogitator-ai/worker';
+import { JobQueue, WorkerPool } from '@cogitator-ai/worker';
 import express from 'express';
 
 const queue = new JobQueue({ redis: { host: 'localhost', port: 6379 } });
 const pool = new WorkerPool({ redis: { host: 'localhost', port: 6379 } });
-const metrics = new MetricsCollector();
+await pool.start();
 
 const app = express();
 
 app.get('/metrics', async (req, res) => {
-  const queueMetrics = await queue.getMetrics();
-  const fullMetrics = await pool.getMetrics(queueMetrics);
-  res.type('text/plain').send(metrics.format(fullMetrics));
+  const queueMetrics = await queue.getMetrics(); // workerCount = workers connected to the queue
+  res.type('text/plain').send(pool.metrics.format(queueMetrics));
 });
 
 app.listen(9090);
@@ -414,7 +489,7 @@ app.listen(9090);
 | `cogitator_queue_completed_total` | counter   | Total completed jobs           |
 | `cogitator_queue_failed_total`    | counter   | Total failed jobs              |
 | `cogitator_queue_delayed`         | gauge     | Scheduled/delayed jobs         |
-| `cogitator_workers_total`         | gauge     | Active workers                 |
+| `cogitator_workers_total`         | gauge     | Workers connected to the queue |
 | `cogitator_job_duration_seconds`  | histogram | Job processing time            |
 | `cogitator_jobs_by_type_total`    | counter   | Jobs by type                   |
 
@@ -489,6 +564,8 @@ const queue = new JobQueue({
 
 ### Redis Cluster
 
+Queues and workers connect to all cluster nodes (keys use the `{cogitator}` hash tag so they live in one slot):
+
 ```typescript
 const queue = new JobQueue({
   redis: {
@@ -516,11 +593,12 @@ Jobs use serialized configurations that can be stored in Redis.
 interface SerializedAgent {
   name: string;
   instructions: string;
-  model: string;
-  provider: 'ollama' | 'openai' | 'anthropic';
+  model: string; // may include the provider prefix
+  provider: LLMProvider; // used when model has no prefix
   temperature?: number;
   maxTokens?: number;
-  tools: ToolSchema[];
+  maxIterations?: number;
+  tools: ToolSchema[]; // resolved by name against the worker's tools
 }
 ```
 
@@ -543,10 +621,12 @@ interface SerializedWorkflowNode {
 interface SerializedWorkflowEdge {
   from: string;
   to: string;
-  condition?: string;
+  condition?: string; // 'true' | 'false' for edges leaving condition nodes
 }
 ```
 
+Node configs are typed as `AgentNodeConfig`, `TransformNodeConfig` and `ConditionNodeConfig`.
+
 ### SerializedSwarm
 
 ```typescript
@@ -578,7 +658,7 @@ async function main() {
   const agentConfig = {
     name: 'Summarizer',
     instructions: 'Summarize the given text concisely.',
-    model: 'openai/gpt-4',
+    model: 'openai/gpt-4o',
     provider: 'openai' as const,
     tools: [],
   };
@@ -694,6 +774,9 @@ import type {
   SerializedWorkflow,
   SerializedWorkflowNode,
   SerializedWorkflowEdge,
+  AgentNodeConfig,
+  TransformNodeConfig,
+  ConditionNodeConfig,
   SerializedSwarm,
 
   // Job payloads
@@ -713,7 +796,10 @@ import type {
   // Configuration
   QueueConfig,
   WorkerConfig,
+  WorkerRuntime,
   QueueMetrics,
+  DistributedSwarmWorkerConfig,
+  DistributedSwarmWorkerEvents,
 } from '@cogitator-ai/worker';
 ```
 

package/dist/connection.d.ts

@@ -0,0 +1,29 @@
+import { Cluster, Redis } from 'ioredis';
+import type { ConnectionOptions } from 'bullmq';
+import type { QueueConfig } from './types.js';
+export declare const DEFAULT_QUEUE_NAME = "cogitator-jobs";
+export type RedisClient = Redis | Cluster;
+type RedisConnectionConfig = QueueConfig['redis'];
+/**
+ * BullMQ key prefix; cluster mode needs a hash tag so all queue keys share a slot.
+ */
+export declare function queuePrefix(redis: RedisConnectionConfig): string;
+export interface BullConnection {
+    connection: ConnectionOptions;
+    /** Close connections that BullMQ treats as shared (cluster instances) */
+    dispose(): Promise<void>;
+}
+/**
+ * Connection for BullMQ queues and workers. Blocking (worker) connections must not limit
+ * retries per request, as BullMQ requires. Cluster instances are shared with BullMQ, which
+ * does not close them, so callers must `dispose()` them.
+ */
+export declare function createBullConnection(redis: RedisConnectionConfig, options?: {
+    blocking?: boolean;
+}): BullConnection;
+/**
+ * Plain client (e.g. for publishing swarm results) using the same Redis configuration.
+ */
+export declare function createRedisClient(redis: RedisConnectionConfig): RedisClient;
+export {};
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C,KAAK,qBAAqB,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;AAElD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAEhE;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,yEAAyE;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACnC,cAAc,CAiChB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,qBAAqB,GAAG,WAAW,CAa3E"}

package/dist/connection.js

@@ -0,0 +1,63 @@
+import { Cluster, Redis } from 'ioredis';
+export const DEFAULT_QUEUE_NAME = 'cogitator-jobs';
+/**
+ * BullMQ key prefix; cluster mode needs a hash tag so all queue keys share a slot.
+ */
+export function queuePrefix(redis) {
+    return redis.cluster ? '{cogitator}' : 'cogitator';
+}
+/**
+ * Connection for BullMQ queues and workers. Blocking (worker) connections must not limit
+ * retries per request, as BullMQ requires. Cluster instances are shared with BullMQ, which
+ * does not close them, so callers must `dispose()` them.
+ */
+export function createBullConnection(redis, options = {}) {
+    const maxRetriesPerRequest = options.blocking ? null : undefined;
+    if (redis.cluster) {
+        if (redis.cluster.nodes.length === 0) {
+            throw new Error('Redis cluster configuration requires at least one node');
+        }
+        const cluster = new Cluster(redis.cluster.nodes, {
+            lazyConnect: true,
+            redisOptions: { password: redis.password, maxRetriesPerRequest },
+        });
+        return {
+            connection: cluster,
+            dispose: async () => {
+                if (cluster.status === 'end')
+                    return;
+                if (cluster.status === 'wait') {
+                    cluster.disconnect();
+                    return;
+                }
+                await cluster.quit();
+            },
+        };
+    }
+    return {
+        connection: {
+            host: redis.host ?? 'localhost',
+            port: redis.port ?? 6379,
+            password: redis.password,
+            maxRetriesPerRequest,
+        },
+        dispose: async () => { },
+    };
+}
+/**
+ * Plain client (e.g. for publishing swarm results) using the same Redis configuration.
+ */
+export function createRedisClient(redis) {
+    if (redis.cluster) {
+        if (redis.cluster.nodes.length === 0) {
+            throw new Error('Redis cluster configuration requires at least one node');
+        }
+        return new Cluster(redis.cluster.nodes, { redisOptions: { password: redis.password } });
+    }
+    return new Redis({
+        host: redis.host ?? 'localhost',
+        port: redis.port ?? 6379,
+        password: redis.password,
+    });
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAMnD;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAA4B;IACtD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC;AACrD,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAA4B,EAC5B,UAAkC,EAAE;IAEpC,MAAM,oBAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAEjE,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE;YAC/C,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,oBAAoB,EAAE;SACjE,CAAC,CAAC;QACH,OAAO;YACL,UAAU,EAAE,OAAO;YACnB,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;oBAAE,OAAO;gBACrC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;oBAC9B,OAAO,CAAC,UAAU,EAAE,CAAC;oBACrB,OAAO;gBACT,CAAC;gBACD,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;YACvB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU,EAAE;YACV,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,WAAW;YAC/B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;YACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,oBAAoB;SACrB;QACD,OAAO,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;KACxB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAA4B;IAC5D,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED,OAAO,IAAI,KAAK,CAAC;QACf,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,WAAW;QAC/B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC,CAAC;AACL,CAAC"}

package/dist/distributed-swarm-worker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Worker node for distributed swarms.
+ *
+ * Consumes agent turns dispatched by `DistributedSwarmCoordinator` (from
+ * `@cogitator-ai/swarms`), runs them with the worker's Cogitator and tools, and publishes
+ * each result back to the coordinator's results channel.
+ */
+import type { SwarmAgentJobPayload, SwarmAgentJobResult, WorkerRuntime } from './types.js';
+export interface DistributedSwarmWorkerConfig extends WorkerRuntime {
+    /** Redis holding the swarm job queue (must match the swarm's `distributed.redis`) */
+    redis?: {
+        host?: string;
+        port?: number;
+        password?: string;
+        db?: number;
+    };
+    /** Swarm key prefix (must match `distributed.redis.keyPrefix`, default: 'swarm') */
+    keyPrefix?: string;
+    /** Job queue name (must match `distributed.queue`, default: 'swarm-agent-jobs') */
+    queue?: string;
+    /** Agent turns processed concurrently by this worker (default: 4) */
+    concurrency?: number;
+    /** Seconds a blocking poll waits for new jobs before re-checking state (default: 1) */
+    pollTimeout?: number;
+}
+export interface DistributedSwarmWorkerEvents {
+    onJobStarted?: (job: SwarmAgentJobPayload) => void;
+    onJobCompleted?: (job: SwarmAgentJobPayload, result: SwarmAgentJobResult) => void;
+    onJobFailed?: (job: SwarmAgentJobPayload, error: Error) => void;
+    onError?: (error: Error) => void;
+}
+export declare class DistributedSwarmWorker {
+    private readonly config;
+    private readonly events;
+    private readonly runtime;
+    private readonly queueKey;
+    private consumer?;
+    private publisher?;
+    private loop?;
+    private running;
+    private readonly active;
+    constructor(config?: DistributedSwarmWorkerConfig, events?: DistributedSwarmWorkerEvents);
+    /**
+     * Start consuming jobs. Resolves once the worker is connected.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop taking new jobs, wait for in-flight jobs to finish and close connections.
+     */
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    getActiveJobCount(): number;
+    private consume;
+    private handle;
+}
+//# sourceMappingURL=distributed-swarm-worker.d.ts.map

package/dist/distributed-swarm-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distributed-swarm-worker.d.ts","sourceRoot":"","sources":["../src/distributed-swarm-worker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAKxF,MAAM,WAAW,4BAA6B,SAAQ,aAAa;IACjE,qFAAqF;IACrF,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,CAAC;IACF,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,4BAA4B;IAC3C,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACnD,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAClF,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAgBD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,CAAQ;IACzB,OAAO,CAAC,SAAS,CAAC,CAAQ;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAgB;IAC7B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAGjD,MAAM,GAAE,4BAAiC,EACzC,MAAM,GAAE,4BAAiC;IAW3C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B,SAAS,IAAI,OAAO;IAIpB,iBAAiB,IAAI,MAAM;YAIb,OAAO;YA6BP,MAAM;CAgCrB"}

package/dist/distributed-swarm-worker.js

@@ -0,0 +1,151 @@
+/**
+ * Worker node for distributed swarms.
+ *
+ * Consumes agent turns dispatched by `DistributedSwarmCoordinator` (from
+ * `@cogitator-ai/swarms`), runs them with the worker's Cogitator and tools, and publishes
+ * each result back to the coordinator's results channel.
+ */
+import { Redis } from 'ioredis';
+import { swarmJobQueueKey } from '@cogitator-ai/swarms';
+import { executeSwarmAgentJob } from './processors/swarm-agent.js';
+import { toErrorMessage } from './processors/shared.js';
+import { Cogitator } from '@cogitator-ai/core';
+function isSwarmAgentJob(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const job = value;
+    return (job.type === 'swarm-agent' &&
+        typeof job.jobId === 'string' &&
+        typeof job.agentName === 'string' &&
+        typeof job.input === 'string' &&
+        typeof job.agentConfig === 'object' &&
+        job.agentConfig !== null &&
+        typeof job.stateKeys?.results === 'string');
+}
+export class DistributedSwarmWorker {
+    config;
+    events;
+    runtime;
+    queueKey;
+    consumer;
+    publisher;
+    loop;
+    running = false;
+    active = new Set();
+    constructor(config = {}, events = {}) {
+        this.config = config;
+        this.events = events;
+        this.runtime = {
+            cogitator: config.cogitator ?? new Cogitator(),
+            tools: config.tools ?? [],
+        };
+        this.queueKey = swarmJobQueueKey(config.keyPrefix, config.queue);
+    }
+    /**
+     * Start consuming jobs. Resolves once the worker is connected.
+     */
+    async start() {
+        if (this.running)
+            return;
+        const options = {
+            host: this.config.redis?.host ?? 'localhost',
+            port: this.config.redis?.port ?? 6379,
+            password: this.config.redis?.password,
+            db: this.config.redis?.db ?? 0,
+            lazyConnect: true,
+        };
+        const consumer = new Redis({ ...options, maxRetriesPerRequest: null });
+        const publisher = new Redis(options);
+        try {
+            await Promise.all([consumer.connect(), publisher.connect()]);
+        }
+        catch (error) {
+            consumer.disconnect();
+            publisher.disconnect();
+            throw error;
+        }
+        this.consumer = consumer;
+        this.publisher = publisher;
+        this.running = true;
+        this.loop = this.consume();
+    }
+    /**
+     * Stop taking new jobs, wait for in-flight jobs to finish and close connections.
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.consumer?.disconnect();
+        await this.loop;
+        await Promise.allSettled([...this.active]);
+        await this.publisher?.quit();
+        this.consumer = undefined;
+        this.publisher = undefined;
+        this.loop = undefined;
+    }
+    isRunning() {
+        return this.running;
+    }
+    getActiveJobCount() {
+        return this.active.size;
+    }
+    async consume() {
+        const concurrency = Math.max(1, this.config.concurrency ?? 4);
+        const pollTimeout = Math.max(0.1, this.config.pollTimeout ?? 1);
+        while (this.running) {
+            if (this.active.size >= concurrency) {
+                await Promise.race(this.active);
+                continue;
+            }
+            let entry;
+            try {
+                entry = await this.consumer.blpop(this.queueKey, pollTimeout);
+            }
+            catch (error) {
+                if (!this.running)
+                    return;
+                this.events.onError?.(error instanceof Error ? error : new Error(toErrorMessage(error)));
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+                continue;
+            }
+            if (!entry)
+                continue;
+            const task = this.handle(entry[1]).finally(() => {
+                this.active.delete(task);
+            });
+            this.active.add(task);
+        }
+    }
+    async handle(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.events.onError?.(new Error('Discarded swarm job with invalid JSON'));
+            return;
+        }
+        if (!isSwarmAgentJob(parsed)) {
+            this.events.onError?.(new Error('Discarded malformed swarm job payload'));
+            return;
+        }
+        const job = parsed;
+        this.events.onJobStarted?.(job);
+        const result = await executeSwarmAgentJob(job, this.runtime);
+        try {
+            await this.publisher.publish(job.stateKeys.results, JSON.stringify(result));
+        }
+        catch (error) {
+            this.events.onError?.(error instanceof Error ? error : new Error(toErrorMessage(error)));
+            return;
+        }
+        if (result.error !== undefined) {
+            this.events.onJobFailed?.(job, new Error(result.error));
+        }
+        else {
+            this.events.onJobCompleted?.(job, result);
+        }
+    }
+}
+//# sourceMappingURL=distributed-swarm-worker.js.map