@hotmeshio/hotmesh 0.5.2 → 0.5.4

package/README.md

@@ -1,10 +1,10 @@
 # HotMesh
 
-**🧠 Workflow That Remembers**
+**Workflow That Remembers**
 
 ![beta release](https://img.shields.io/badge/release-beta-blue.svg)  ![made with typescript](https://img.shields.io/badge/built%20with-typescript-lightblue.svg)
 
-HotMesh brings a **memory model** to your automation: durable entities that hold context, support concurrency, and evolve across runs. Built on PostgreSQL, it treats your database not just as storage—but as the runtime hub for agents, pipelines, and long-lived processes.
+HotMesh brings a **memory model** to durable functions. Built on PostgreSQL, it treats your database as the runtime hub for agents, pipelines, and long-lived processes.
 
 Use HotMesh to:
 
@@ -106,9 +106,9 @@ This index improves performance for filtered queries while reducing index size.
 
 ## Durable AI Agents
 
-Agents often require memory—context that persists between invocations, spans multiple perspectives, or outlives a single process. HotMesh supports that natively.
+Agents often require memory—context that persists between invocations, spans multiple perspectives, or outlives a single process.
 
-The following example builds a "research agent" that runs sub-flows and self-reflects on the results.
+The following example builds a "research agent" that executes hooks with different perspectives and then synthesizes. The data-first approach sets up initial state and then uses temporary hook functions to augment over the lifecycle of the entity record.
 
 ### Research Agent Example
 
@@ -116,95 +116,58 @@ The following example builds a "research agent" that runs sub-flows and self-ref
 
 ```ts
 export async function researchAgent(query: string): Promise<any> {
-  const entity = await MemFlow.workflow.entity();
+  const agent = await MemFlow.workflow.entity();
 
   // Set up shared memory for this agent session
-  await entity.set({
+  const initialState = {
     query,
     findings: [],
     perspectives: {},
     confidence: 0,
-    status: 'researching'
-  });
+    verification: {},
+    status: 'researching',
+    startTime: new Date().toISOString(),
+  }
+  await agent.set<typeof initialState>(initialState);
 
-  // Launch perspective hooks in parallel (no need to await here)
-  const optimistic = MemFlow.workflow.execHook({
+  // Launch perspective hooks
+  await MemFlow.workflow.execHook({
     taskQueue: 'agents',
     workflowName: 'optimisticPerspective',
-    args: [query]
+    args: [query],
+    signalId: 'optimistic-complete'
   });
 
-  const skeptical = MemFlow.workflow.execHook({
+  await MemFlow.workflow.execHook({
     taskQueue: 'agents',
     workflowName: 'skepticalPerspective',
-    args: [query]
+    args: [query],
+    signalId: 'skeptical-complete'
   });
 
-  // Launch a child workflow with its own isolated entity/state
-  const factChecker = await MemFlow.workflow.execChild({
-    entity: 'fact-checker',
-    workflowName: 'factCheckAgent',
-    workflowId: `fact-check-${Date.now()}`,
+  await MemFlow.workflow.execHook({
+    taskQueue: 'agents',
+    workflowName: 'verificationHook',
     args: [query],
-    taskQueue: 'agents'
+    signalId: 'verification-complete'
   });
 
-  // Wait for all views to complete before analyzing
-  await Promise.all([optimistic, skeptical, factChecker]);
-
-  // Final synthesis: aggregate and compare all perspectives
   await MemFlow.workflow.execHook({
     taskQueue: 'perspectives',
     workflowName: 'synthesizePerspectives',
-    args: []
+    args: [],
+    signalId: 'synthesis-complete',
   });
 
-  return await entity.get();
-}
-```
-
-> 💡 **Developer Note**: A complete implementation of this Research Agent example with tests, OpenAI integration, and multi-perspective analysis can be found in the [test suite](./tests/memflow/agent).
-
-#### Hooks: Perspectives
-
-```ts
-// Optimistic hook looks for affirming evidence
-export async function optimisticPerspective(query: string, config: {signal: string}): Promise<void> {
-  const entity = await MemFlow.workflow.entity();
-  const findings = await searchForSupportingEvidence(query);
-  await entity.merge({ perspectives: { optimistic: { findings, confidence: 0.8 }}});
-  //signal the caller to notify all done
-  await MemFlow.workflow.signal(config.signal, {});
-}
-
-// Skeptical hook seeks out contradictions and counterpoints
-export async function skepticalPerspective(query: string, config: {signal: string}): Promise<void> {
-  const entity = await MemFlow.workflow.entity();
-  const counterEvidence = await searchForCounterEvidence(query);
-  await entity.merge({ perspectives: { skeptical: { counterEvidence, confidence: 0.6 }}});
-  await MemFlow.workflow.signal(config.signal, {});
+  // return analysis, verification, and synthesis
+  return await agent.get();
 }
 ```
 
-#### Child Agent: Fact Checker
-
-```ts
-// A dedicated child agent with its own entity type and context
-export async function factCheckAgent(query: string): Promise<any> {
-  const entity = await MemFlow.workflow.entity();
-  await entity.set({ query, sources: [], verifications: [] });
-
-  await MemFlow.workflow.execHook({
-    taskQueue: 'agents',
-    workflowName: 'verifySourceCredibility',
-    args: [query]
-  });
 
-  return await entity.get();
-}
-```
+Let's look at one of these hooks in detail - the synthesis hook that combines all perspectives into a final assessment:
 
-#### Synthesis
+#### Synthesis Hook
 
 ```ts
 // Synthesis hook aggregates different viewpoints
@@ -225,139 +188,94 @@ export async function synthesizePerspectives(config: {signal: string}): Promise<
   });
   await MemFlow.workflow.signal(config.signal, {});
 }
+
+//other hooks...
 ```
 
+> 💡 A complete implementation of this Research Agent example with tests, OpenAI integration, and multi-perspective analysis can be found in the [agent test suite](https://github.com/hotmeshio/sdk-typescript/tree/main/tests/memflow/agent).
+
 ---
 
 ## Building Pipelines with State
 
-HotMesh treats pipelines as long-lived records, not ephemeral jobs. Every pipeline run is stateful, resumable, and traceable.
+HotMesh treats pipelines as long-lived records. Every pipeline run is stateful, resumable, and traceable. Hooks can be re-run at any time, and can be invoked by external callers. Sleep and run on a cadence to keep the pipeline up to date.
 
 ### Setup a Data Pipeline
 
 ```ts
-export async function dataPipeline(source: string): Promise<void> {
-  const entity = await MemFlow.workflow.entity();
-
-  // Initial policy and tracking setup
-  await entity.set({
-    source,
-    pipeline: { version: 1, policy: { refreshInterval: '24 hours' } },
-    changeLog: []
-  });
-
-  // Trigger the recurring orchestration pipeline
-  await MemFlow.workflow.execHook({
-    taskQueue: 'pipeline',
-    workflowName: 'runPipeline',
-    args: [true]
-  });
-}
-```
-
-### Orchestration Hook
-
-```ts
-export async function runPipeline(repeat = false): Promise<void> {
-  do {
-    // Perform transformation step
-    await MemFlow.workflow.execHook({
-      taskQueue: 'transform',
-      workflowName: 'cleanData',
-      args: []
-    });
-
-    if (repeat) {
-      // Schedule next execution
-      await MemFlow.workflow.execHook({
-        taskQueue: 'scheduler',
-        workflowName: 'scheduleRefresh',
-        args: []
-      });
-    }
-  } while (repeat)
-}
-
-/**
- * Hook to clean and transform data
- */
-export async function cleanData(signalInfo?: { signal: string }): Promise<void> {
-  const entity = await MemFlow.workflow.entity();
+export async function documentProcessingPipeline(): Promise<any> {
+  const pipeline = await MemFlow.workflow.entity();
+
+  // Initialize pipeline state with empty arrays
+  const initialState = {
+    documentId: `doc-${Date.now()}`,
+    status: 'started',
+    startTime: new Date().toISOString(),
+    imageRefs: [],
+    extractedInfo: [],
+    validationResults: [],
+    finalResult: null,
+    processingSteps: [],
+    errors: [],
+    pageSignals: {}
+  };
   
-  // Simulate data cleaning
-  await entity.merge({
-    status: 'cleaning',
-    lastCleanedAt: new Date().toISOString()
-  });
+  await pipeline.set<typeof initialState>(initialState);
+
+  // Step 1: Get list of image file references
+  await pipeline.merge({status: 'loading-images'});
+  await pipeline.append('processingSteps', 'image-load-started');
+  const imageRefs = await activities.loadImagePages();
+  if (!imageRefs || imageRefs.length === 0) {
+    throw new Error('No image references found');
+  }
+  await pipeline.merge({imageRefs});
+  await pipeline.append('processingSteps', 'image-load-completed');
 
-  // Add to changelog
-  await entity.append('changeLog', {
-    action: 'clean',
-    timestamp: new Date().toISOString()
-  });
+  // Step 2: Launch processing hooks for each page
+  for (const [index, imageRef] of imageRefs.entries()) {
+    const pageNumber = index + 1;
 
-  // Signal completion if called via execHook
-  if (signalInfo?.signal) {
-    await MemFlow.workflow.signal(signalInfo.signal, { 
-      status: 'cleaned',
-      timestamp: new Date().toISOString()
+    await MemFlow.workflow.execHook({
+      taskQueue: 'pipeline',
+      workflowName: 'pageProcessingHook',
+      args: [imageRef, pageNumber, initialState.documentId],
+      signalId: `page-${pageNumber}-complete`
     });
-  }
-}
+  };
 
-/**
- * Hook to schedule the next refresh based on policy
- */
-export async function scheduleRefresh(signalInfo?: { signal: string }): Promise<void> {
-  const entity = await MemFlow.workflow.entity();
-  
-  // Get refresh interval from policy
-  const currentEntity = await entity.get();
-  const refreshInterval = currentEntity.pipeline.policy.refreshInterval;
-  
-  // Sleep for the configured interval
-  await MemFlow.workflow.sleepFor(refreshInterval);
-  
-  // Update status after sleep
-  await entity.merge({
-    status: 'ready_for_refresh',
-    nextRefreshAt: new Date().toISOString()
+  // Step 3: Launch validation hook
+  await MemFlow.workflow.execHook({
+    taskQueue: 'pipeline',
+    workflowName: 'validationHook',
+    args: [initialState.documentId],
+    signalId: 'validation-complete'
   });
 
-  // Add to changelog
-  await entity.append('changeLog', {
-    action: 'schedule_refresh',
-    timestamp: new Date().toISOString(),
-    nextRefresh: new Date().toISOString()
+  // Step 4: Launch approval hook
+  await MemFlow.workflow.execHook({
+    taskQueue: 'pipeline',
+    workflowName: 'approvalHook',
+    args: [initialState.documentId],
+    signalId: 'approval-complete',
   });
 
-  // Signal completion if called via execHook
-  if (signalInfo?.signal) {
-    await MemFlow.workflow.signal(signalInfo.signal, {
-      status: 'scheduled',
-      nextRefresh: new Date().toISOString()
-    });
-  }
-}
-```
-
-### Trigger from Outside
-
-```ts
-// External systems can trigger a single pipeline run
-export async function triggerRefresh() {
-  const client = new MemFlow.Client({/*...*/});
-
-  await client.workflow.hook({
-    workflowId: 'pipeline-123',
+  // Step 5: Launch notification hook
+  await MemFlow.workflow.execHook({
     taskQueue: 'pipeline',
-    workflowName: 'runPipeline',
-    args: []
+    workflowName: 'notificationHook',
+    args: [initialState.documentId],
+    signalId: 'processing-complete',
   });
+
+  // Step 6: Return final state
+  await pipeline.merge({status: 'completed', completedAt: new Date().toISOString()});
+  await pipeline.append('processingSteps', 'pipeline-completed');
+  return await pipeline.get();
 }
 ```
 
-> 💡 **Developer Note**: A complete implementation of this Pipeline example with OpenAI Vision integration, processing hooks, and document workflow automation can be found in the [test suite](./tests/memflow/pipeline).
+> 💡 A complete implementation of this Pipeline example with OpenAI Vision integration, processing hooks, and document workflow automation can be found in the [pipeline test suite](https://github.com/hotmeshio/sdk-typescript/tree/main/tests/memflow/pipeline).
 
 ---
 
@@ -370,4 +288,4 @@ export async function triggerRefresh() {
 
 ## License
 
-Apache 2.0 – See `LICENSE` for details.
+Apache 2.0 with commercial restrictions – See `LICENSE` for details.

package/build/index.d.ts

@@ -10,8 +10,6 @@ import { WorkerService as Worker } from './services/memflow/worker';
 import { WorkflowService as workflow } from './services/memflow/workflow';
 import { WorkflowHandleService as WorkflowHandle } from './services/memflow/handle';
 import { proxyActivities } from './services/memflow/workflow/proxyActivities';
-import { MeshData } from './services/meshdata';
-import { MeshOS } from './services/meshos';
 import * as Errors from './modules/errors';
 import * as Utils from './modules/utils';
 import * as Enums from './modules/enums';
@@ -22,5 +20,5 @@ import { RedisConnection as ConnectorIORedis } from './services/connector/provid
 import { RedisConnection as ConnectorRedis } from './services/connector/providers/redis';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
 export { Connector, //factory
-ConnectorIORedis, ConnectorNATS, ConnectorPostgres, ConnectorRedis, HotMesh, HotMeshConfig, MeshCall, MeshData, MemFlow, MeshOS, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
+ConnectorIORedis, ConnectorNATS, ConnectorPostgres, ConnectorRedis, HotMesh, HotMeshConfig, MeshCall, MemFlow, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
 export * as Types from './types';

package/build/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.MeshOS = exports.MemFlow = exports.MeshData = exports.MeshCall = exports.HotMesh = exports.ConnectorRedis = exports.ConnectorPostgres = exports.ConnectorNATS = exports.ConnectorIORedis = exports.Connector = void 0;
+exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.MemFlow = exports.MeshCall = exports.HotMesh = exports.ConnectorRedis = exports.ConnectorPostgres = exports.ConnectorNATS = exports.ConnectorIORedis = exports.Connector = void 0;
 const hotmesh_1 = require("./services/hotmesh");
 Object.defineProperty(exports, "HotMesh", { enumerable: true, get: function () { return hotmesh_1.HotMesh; } });
 const meshcall_1 = require("./services/meshcall");
@@ -46,10 +46,6 @@ const handle_1 = require("./services/memflow/handle");
 Object.defineProperty(exports, "WorkflowHandle", { enumerable: true, get: function () { return handle_1.WorkflowHandleService; } });
 const proxyActivities_1 = require("./services/memflow/workflow/proxyActivities");
 Object.defineProperty(exports, "proxyActivities", { enumerable: true, get: function () { return proxyActivities_1.proxyActivities; } });
-const meshdata_1 = require("./services/meshdata");
-Object.defineProperty(exports, "MeshData", { enumerable: true, get: function () { return meshdata_1.MeshData; } });
-const meshos_1 = require("./services/meshos");
-Object.defineProperty(exports, "MeshOS", { enumerable: true, get: function () { return meshos_1.MeshOS; } });
 const Errors = __importStar(require("./modules/errors"));
 exports.Errors = Errors;
 const Utils = __importStar(require("./modules/utils"));

package/build/modules/enums.d.ts

@@ -108,3 +108,7 @@ export declare const HMSH_EXPIRE_DURATION: number;
 export declare const HMSH_FIDELITY_SECONDS: number;
 export declare const HMSH_SCOUT_INTERVAL_SECONDS: number;
 export declare const HMSH_GUID_SIZE: number;
+/**
+ * Default task queue name used when no task queue is specified
+ */
+export declare const DEFAULT_TASK_QUEUE = "default";

package/build/modules/enums.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMSH_GUID_SIZE = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_MEMFLOW_RETRYABLE = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_CHILD = exports.HMSH_CODE_MEMFLOW_ALL = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_IS_CLUSTER = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
+exports.DEFAULT_TASK_QUEUE = exports.HMSH_GUID_SIZE = exports.HMSH_SCOUT_INTERVAL_SECONDS = exports.HMSH_FIDELITY_SECONDS = exports.HMSH_EXPIRE_DURATION = exports.HMSH_XPENDING_COUNT = exports.HMSH_XCLAIM_COUNT = exports.HMSH_XCLAIM_DELAY_MS = exports.HMSH_BLOCK_TIME_MS = exports.HMSH_MEMFLOW_EXP_BACKOFF = exports.HMSH_MEMFLOW_MAX_INTERVAL = exports.HMSH_MEMFLOW_MAX_ATTEMPTS = exports.HMSH_GRADUATED_INTERVAL_MS = exports.HMSH_MAX_TIMEOUT_MS = exports.HMSH_MAX_RETRIES = exports.MAX_DELAY = exports.MAX_STREAM_RETRIES = exports.INITIAL_STREAM_BACKOFF = exports.MAX_STREAM_BACKOFF = exports.HMSH_EXPIRE_JOB_SECONDS = exports.HMSH_OTT_WAIT_TIME = exports.HMSH_DEPLOYMENT_PAUSE = exports.HMSH_DEPLOYMENT_DELAY = exports.HMSH_ACTIVATION_MAX_RETRY = exports.HMSH_QUORUM_DELAY_MS = exports.HMSH_QUORUM_ROLLCALL_CYCLES = exports.HMSH_STATUS_UNKNOWN = exports.HMSH_CODE_MEMFLOW_RETRYABLE = exports.HMSH_CODE_MEMFLOW_FATAL = exports.HMSH_CODE_MEMFLOW_MAXED = exports.HMSH_CODE_MEMFLOW_TIMEOUT = exports.HMSH_CODE_MEMFLOW_WAIT = exports.HMSH_CODE_MEMFLOW_PROXY = exports.HMSH_CODE_MEMFLOW_CHILD = exports.HMSH_CODE_MEMFLOW_ALL = exports.HMSH_CODE_MEMFLOW_SLEEP = exports.HMSH_CODE_UNACKED = exports.HMSH_CODE_TIMEOUT = exports.HMSH_CODE_UNKNOWN = exports.HMSH_CODE_INTERRUPT = exports.HMSH_CODE_NOTFOUND = exports.HMSH_CODE_PENDING = exports.HMSH_CODE_SUCCESS = exports.HMSH_SIGNAL_EXPIRE = exports.HMSH_IS_CLUSTER = exports.HMSH_TELEMETRY = exports.HMSH_LOGLEVEL = void 0;
 /**
  * Determines the log level for the application. The default is 'info'.
  */
@@ -132,3 +132,7 @@ exports.HMSH_FIDELITY_SECONDS = process.env.HMSH_FIDELITY_SECONDS
 exports.HMSH_SCOUT_INTERVAL_SECONDS = parseInt(process.env.HMSH_SCOUT_INTERVAL_SECONDS, 10) || 60;
 // UTILS
 exports.HMSH_GUID_SIZE = Math.min(parseInt(process.env.HMSH_GUID_SIZE, 10) || 22, 32);
+/**
+ * Default task queue name used when no task queue is specified
+ */
+exports.DEFAULT_TASK_QUEUE = 'default';

package/build/modules/utils.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import { StoreService } from '../services/store';
 import { AppSubscriptions, AppTransitions, AppVID } from '../types/app';
-import { ProviderClient, ProviderConfig, ProviderTransaction, Providers, ProvidersConfig } from '../types/provider';
+import { ProviderClient, ProviderTransaction, Providers } from '../types/provider';
 import { StringAnyType } from '../types/serializer';
 import { StreamCode, StreamData, StreamStatus } from '../types/stream';
 import { SystemHealth } from '../types/quorum';
@@ -34,14 +34,6 @@ export declare const polyfill: {
      * `redis` is deprecated; `connection` is the generic replacement
      */
     providerConfig(obj: any): any;
-    /**
-     * NOTE: `redisClass and redisOptions` input parameters are deprecated; use `connection` for all configuration inputs
-     */
-    meshDataConfig(obj: {
-        connection?: Partial<ProviderConfig | ProvidersConfig>;
-        redisClass?: any;
-        redisOptions?: StringAnyType;
-    }): Partial<ProviderConfig> | Partial<ProvidersConfig>;
 };
 /**
  * @private

package/build/modules/utils.js

@@ -127,12 +127,6 @@ exports.polyfill = {
     providerConfig(obj) {
         return obj?.connection ?? obj?.redis ?? obj?.connections;
     },
-    /**
-     * NOTE: `redisClass and redisOptions` input parameters are deprecated; use `connection` for all configuration inputs
-     */
-    meshDataConfig(obj) {
-        return { ...obj.connection };
-    },
 };
 /**
  * @private

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.5.2",
+    "version": "0.5.4",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -20,7 +20,7 @@
         "lint:fix": "eslint . --fix --ext .ts",
         "start": "ts-node src/index.ts",
         "test": "NODE_ENV=test jest --detectOpenHandles --forceExit --verbose",
-        "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:compile": "NODE_ENV=test jest ./tests/functional/compile/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect": "NODE_ENV=test jest ./tests/unit/services/connector/* --detectOpenHandles --forceExit --verbose",
         "test:connect:ioredis": "NODE_ENV=test jest ./tests/unit/services/connector/providers/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
@@ -59,7 +59,7 @@
         "test:reporter": "NODE_ENV=test jest ./tests/unit/services/reporter/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:retry": "NODE_ENV=test jest ./tests/functional/retry/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=info jest ./tests/functional/sequence/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:signal": "NODE_ENV=test jest ./tests/functional/signal/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:status": "NODE_ENV=test jest ./tests/functional/status/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:providers": "NODE_ENV=test jest ./tests/functional/*/providers/*/*.test.ts --detectOpenHandles --forceExit --verbose",
@@ -75,7 +75,6 @@
         "test:sub:postgres": "NODE_ENV=test jest ./tests/functional/sub/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:sub:nats": "NODE_ENV=test jest ./tests/functional/sub/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
         "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:meshos": "HMSH_LOGLEVEL=info NODE_ENV=test HMSH_IS_CLUSTER=true jest ./tests/meshos/*.test.ts --forceExit --verbose --detectOpenHandles",
         "test:meshcall": "NODE_ENV=test jest ./tests/meshcall/*.test.ts --forceExit --verbose --detectOpenHandles",
         "test:unit": "NODE_ENV=test jest ./tests/unit/*/*/index.test.ts --detectOpenHandles --forceExit --verbose"
     },

package/build/services/connector/factory.d.ts

@@ -8,7 +8,7 @@ export declare class ConnectorService {
      * initialization, but the factory method provided here is useful
      * for testing provider configurations.
      */
-    static connectClient(ProviderConfig: ProviderConfig): Promise<ProviderNativeClient>;
+    static connectClient(ProviderConfig: ProviderConfig, taskQueue?: string): Promise<ProviderNativeClient>;
     /**
      * Initialize `store`, `stream`, and `subscription` clients for any provider.
      * @private
@@ -18,5 +18,5 @@ export declare class ConnectorService {
      * Binds a provider client native instance to the target object.
      * @private
      */
-    static initClient(ProviderConfig: ProviderConfig, target: HotMeshEngine | HotMeshWorker, field: string): Promise<void>;
+    static initClient(ProviderConfig: ProviderConfig, target: HotMeshEngine | HotMeshWorker, field: string, taskQueue?: string): Promise<void>;
 }

package/build/services/connector/factory.js

@@ -19,9 +19,9 @@ class ConnectorService {
      * initialization, but the factory method provided here is useful
      * for testing provider configurations.
      */
-    static async connectClient(ProviderConfig) {
+    static async connectClient(ProviderConfig, taskQueue) {
         const target = {};
-        await ConnectorService.initClient(ProviderConfig, target, 'client');
+        await ConnectorService.initClient(ProviderConfig, target, 'client', taskQueue);
         return target.client;
     }
     /**
@@ -38,15 +38,17 @@ class ConnectorService {
                 sub: { ...connection },
             };
         }
+        // Extract taskQueue from target for connection pooling
+        const taskQueue = target.taskQueue;
         // Expanded form
         if (connection.store) {
-            await ConnectorService.initClient(connection.store, target, 'store');
+            await ConnectorService.initClient(connection.store, target, 'store', taskQueue);
         }
         if (connection.stream) {
-            await ConnectorService.initClient(connection.stream, target, 'stream');
+            await ConnectorService.initClient(connection.stream, target, 'stream', taskQueue);
         }
         if (connection.sub) {
-            await ConnectorService.initClient(connection.sub, target, 'sub');
+            await ConnectorService.initClient(connection.sub, target, 'sub', taskQueue);
             // use store for publishing events if same as subscription
             if (connection.sub.class !== connection.store.class) {
                 //initialize a separate client for publishing events, using
@@ -56,7 +58,7 @@ class ConnectorService {
                     options: { ...connection.sub.options },
                     provider: connection.sub.provider,
                 };
-                await ConnectorService.initClient(connection.pub, target, 'pub');
+                await ConnectorService.initClient(connection.pub, target, 'pub', taskQueue);
             }
         }
     }
@@ -64,7 +66,7 @@ class ConnectorService {
      * Binds a provider client native instance to the target object.
      * @private
      */
-    static async initClient(ProviderConfig, target, field) {
+    static async initClient(ProviderConfig, target, field, taskQueue) {
         if (target[field]) {
             return;
         }
@@ -87,7 +89,8 @@ class ConnectorService {
             case 'postgres':
                 //if connecting as a poolClient for subscription, auto connect the client
                 const bAutoConnect = field === 'sub';
-                clientInstance = await postgres_1.PostgresConnection.connect(id, providerClass, options, { connect: bAutoConnect, provider: providerName });
+                // Use taskQueue-based connection pooling for PostgreSQL
+                clientInstance = await postgres_1.PostgresConnection.getOrCreateTaskQueueConnection(id, taskQueue, providerClass, options, { connect: bAutoConnect, provider: providerName });
                 break;
             default:
                 throw new Error(`Unknown provider type: ${providerType}`);

package/build/services/connector/providers/postgres.d.ts

@@ -4,17 +4,64 @@ declare class PostgresConnection extends AbstractConnection<PostgresClassType, P
     defaultOptions: PostgresClientOptions;
     protected static poolClientInstances: Set<PostgresPoolClientType>;
     protected static connectionInstances: Set<PostgresClientType>;
+    protected static taskQueueConnections: Map<string, PostgresConnection>;
+    /**
+     * Get comprehensive connection statistics for monitoring taskQueue pooling effectiveness
+     */
+    static getConnectionStats(): {
+        totalPoolClients: number;
+        totalConnections: number;
+        taskQueueConnections: number;
+        taskQueueDetails: Array<{
+            key: string;
+            connectionId: string;
+            reusedCount: number;
+        }>;
+    };
+    /**
+     * Log current connection statistics - useful for debugging connection pooling
+     */
+    static logConnectionStats(logger?: any): void;
+    /**
+     * Check taskQueue pooling effectiveness - returns metrics about connection reuse
+     */
+    static getPoolingEffectiveness(): {
+        totalConnections: number;
+        taskQueuePools: number;
+        totalReuses: number;
+        averageReusesPerPool: number;
+        poolingEfficiency: number;
+    };
     poolClientInstance: PostgresPoolClientType;
     createConnection(clientConstructor: any, options: PostgresClientOptions, config?: {
         connect?: boolean;
         provider?: string;
     }): Promise<PostgresClientType>;
     getClient(): PostgresClientType;
+    /**
+     * Get the connection ID for monitoring purposes
+     */
+    getConnectionId(): string | null;
     static disconnectAll(): Promise<void>;
     static disconnectPoolClients(): Promise<void>;
     static disconnectConnections(): Promise<void>;
     closeConnection(connection: PostgresClientType): Promise<void>;
     static isPoolClient(client: any): client is PostgresPoolClientType;
+    /**
+     * Creates a taskQueue-based connection key for connection pooling.
+     * This allows multiple providers (store, sub, stream) to reuse the same connection
+     * when they share the same taskQueue and database configuration.
+     */
+    private static createTaskQueueConnectionKey;
+    /**
+     * Gets or creates a PostgreSQL connection based on taskQueue and database configuration.
+     * If a connection already exists for the same taskQueue + config, it will be reused.
+     * This optimization reduces connection overhead for PostgreSQL providers.
+     */
+    static getOrCreateTaskQueueConnection(id: string, taskQueue: string | undefined, clientConstructor: PostgresClassType, options: PostgresClientOptions, config?: {
+        connect?: boolean;
+        provider?: string;
+    }): Promise<PostgresConnection>;
     static getTransactionClient(transactionClient: any): Promise<['client' | 'poolclient', PostgresClientType]>;
 }
 export { PostgresConnection };