@hotmeshio/hotmesh 0.4.1 → 0.4.3

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

@@ -18,6 +18,7 @@ import { KVTables } from './kvtables';
 declare class PostgresStoreService extends StoreService<ProviderClient, ProviderTransaction> {
     pgClient: PostgresClientType;
     kvTables: ReturnType<typeof KVTables>;
+    isScout: boolean;
     transact(): ProviderTransaction;
     constructor(storeClient: ProviderClient);
     init(namespace: string, appId: string, logger: ILogger): Promise<HotMeshApps>;
@@ -82,7 +83,7 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
      * `purposeful re-entry`.
      */
     collateSynthetic(jobId: string, guid: string, amount: number, transaction?: ProviderTransaction): Promise<number>;
-    setStateNX(jobId: string, appId: string, status?: number): Promise<boolean>;
+    setStateNX(jobId: string, appId: string, status?: number, entity?: string): Promise<boolean>;
     getSchema(activityId: string, appVersion: AppVID): Promise<ActivityType>;
     getSchemas(appVersion: AppVID): Promise<Record<string, ActivityType>>;
     setSchemas(schemas: Record<string, ActivityType>, appVersion: AppVID): Promise<any>;
@@ -141,5 +142,37 @@ declare class PostgresStoreService extends StoreService<ProviderClient, Provider
     setThrottleRate(options: ThrottleOptions): Promise<void>;
     getThrottleRates(): Promise<StringStringType>;
     getThrottleRate(topic: string): Promise<number>;
+    /**
+     * Deploy time-aware notification triggers and functions
+     */
+    private deployTimeNotificationTriggers;
+    /**
+     * Enhanced time scout that uses LISTEN/NOTIFY to reduce polling
+     */
+    startTimeScoutWithNotifications(timeEventCallback: (jobId: string, gId: string, activityId: string, type: WorkListTaskType) => Promise<void>): Promise<void>;
+    /**
+     * Handle time notifications from PostgreSQL
+     */
+    private handleTimeNotification;
+    /**
+     * Process time hooks that are ready to be awakened
+     */
+    private processReadyTimeHooks;
+    /**
+     * Enhanced time scout process that uses notifications
+     */
+    private processTimeHooksWithNotifications;
+    /**
+     * Get the next awakening time from the database
+     */
+    private getNextAwakeningTime;
+    /**
+     * Update the time scout's sleep timing based on schedule changes
+     */
+    private updateTimeScoutSleep;
+    /**
+     * Enhanced shouldScout that can handle notifications
+     */
+    shouldScout(): Promise<boolean>;
 }
 export { PostgresStoreService };

package/build/services/store/providers/postgres/postgres.js

@@ -39,6 +39,7 @@ class PostgresStoreService extends __1.StoreService {
     }
     constructor(storeClient) {
         super(storeClient);
+        this.isScout = false;
         //Instead of directly referencing the 'pg' package and methods like 'query',
         //  the PostgresStore wraps the 'pg' client in a class that implements
         //  the Redis client interface. This allows the same methods to be called
@@ -58,6 +59,8 @@ class PostgresStoreService extends __1.StoreService {
         this.logger = logger;
         //confirm db tables exist
         await this.kvTables.deploy(appId);
+        // Deploy time notification triggers
+        await this.deployTimeNotificationTriggers(appId);
         //note: getSettings will contact db to confirm r/w access
         const settings = await this.getSettings(true);
         this.cache = new cache_1.Cache(appId, settings);
@@ -564,9 +567,10 @@ class PostgresStoreService extends __1.StoreService {
         });
         return await this.kvsql(transaction).hincrbyfloat(jobKey, guid, amount);
     }
-    async setStateNX(jobId, appId, status) {
+    async setStateNX(jobId, appId, status, entity) {
         const hashKey = this.mintKey(key_1.KeyType.JOB_STATE, { appId, jobId });
-        const result = await this.kvsql().hsetnx(hashKey, ':', status?.toString() ?? '1');
+        const result = await this.kvsql().hsetnx(hashKey, ':', status?.toString() ?? '1', undefined, //multi
+        entity);
         return this.isSuccessful(result);
     }
     async getSchema(activityId, appVersion) {
@@ -1032,5 +1036,210 @@ class PostgresStoreService extends __1.StoreService {
         }
         return resolveRate(response, topic);
     }
+    /**
+     * Deploy time-aware notification triggers and functions
+     */
+    async deployTimeNotificationTriggers(appId) {
+        const schemaName = this.kvsql().safeName(appId);
+        const client = this.pgClient;
+        try {
+            // Read the SQL template and replace schema placeholder
+            const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+            const path = await Promise.resolve().then(() => __importStar(require('path')));
+            const sqlTemplate = fs.readFileSync(path.join(__dirname, 'time-notify.sql'), 'utf8');
+            const sql = sqlTemplate.replace(/{schema}/g, schemaName);
+            // Execute the entire SQL as one statement (functions contain $$ blocks with semicolons)
+            await client.query(sql);
+            this.logger.info('postgres-time-notifications-deployed', {
+                appId,
+                schemaName,
+                message: 'Time-aware notifications ENABLED - using LISTEN/NOTIFY instead of polling'
+            });
+        }
+        catch (error) {
+            this.logger.error('postgres-time-notifications-deploy-error', {
+                appId,
+                schemaName,
+                error: error.message
+            });
+            // Don't throw - fall back to polling mode
+        }
+    }
+    /**
+     * Enhanced time scout that uses LISTEN/NOTIFY to reduce polling
+     */
+    async startTimeScoutWithNotifications(timeEventCallback) {
+        const channelName = `time_hooks_${this.appId}`;
+        try {
+            // Set up LISTEN for time notifications
+            await this.pgClient.query(`LISTEN "${channelName}"`);
+            // Set up notification handler
+            this.pgClient.on('notification', (notification) => {
+                this.handleTimeNotification(notification, timeEventCallback);
+            });
+            this.logger.debug('postgres-time-scout-notifications-started', {
+                appId: this.appId,
+                channelName
+            });
+            // Start the enhanced time scout loop
+            await this.processTimeHooksWithNotifications(timeEventCallback);
+        }
+        catch (error) {
+            this.logger.error('postgres-time-scout-notifications-error', {
+                appId: this.appId,
+                error
+            });
+            // Fall back to regular polling mode
+            throw error;
+        }
+    }
+    /**
+     * Handle time notifications from PostgreSQL
+     */
+    async handleTimeNotification(notification, timeEventCallback) {
+        try {
+            const payload = JSON.parse(notification.payload);
+            const { type, app_id, next_awakening, ready_at } = payload;
+            if (app_id !== this.appId) {
+                return; // Not for this app
+            }
+            this.logger.debug('postgres-time-notification-received', {
+                type,
+                appId: app_id,
+                nextAwakening: next_awakening,
+                readyAt: ready_at
+            });
+            if (type === 'time_hooks_ready') {
+                // Process any ready time hooks immediately
+                await this.processReadyTimeHooks(timeEventCallback);
+            }
+            else if (type === 'time_schedule_updated') {
+                // Update our sleep timing if we're the time scout
+                await this.updateTimeScoutSleep(next_awakening);
+            }
+        }
+        catch (error) {
+            this.logger.error('postgres-time-notification-handle-error', {
+                notification,
+                error
+            });
+        }
+    }
+    /**
+     * Process time hooks that are ready to be awakened
+     */
+    async processReadyTimeHooks(timeEventCallback) {
+        let hasMoreTasks = true;
+        while (hasMoreTasks) {
+            const workListTask = await this.getNextTask();
+            if (Array.isArray(workListTask)) {
+                const [listKey, target, gId, activityId, type] = workListTask;
+                if (type === 'child') {
+                    // Skip child tasks - they're handled by ancestors
+                }
+                else if (type === 'delist') {
+                    // Delist the signal key
+                    const key = this.mintKey(key_1.KeyType.SIGNALS, { appId: this.appId });
+                    await this.delistSignalKey(key, target);
+                }
+                else {
+                    // Process the task
+                    await timeEventCallback(target, gId, activityId, type);
+                }
+            }
+            else if (workListTask === true) {
+                // A worklist was emptied, continue processing
+                continue;
+            }
+            else {
+                // No more tasks ready
+                hasMoreTasks = false;
+            }
+        }
+    }
+    /**
+     * Enhanced time scout process that uses notifications
+     */
+    async processTimeHooksWithNotifications(timeEventCallback) {
+        let currentSleepTimeout = null;
+        // Function to calculate next sleep duration
+        const calculateNextSleep = async () => {
+            const nextAwakeningTime = await this.getNextAwakeningTime();
+            if (nextAwakeningTime) {
+                const sleepMs = nextAwakeningTime - Date.now();
+                return Math.max(sleepMs, 0);
+            }
+            // Default sleep if no tasks scheduled
+            return enums_1.HMSH_FIDELITY_SECONDS * 1000;
+        };
+        // Main loop
+        while (true) {
+            try {
+                if (await this.shouldScout()) {
+                    // Process any ready tasks
+                    await this.processReadyTimeHooks(timeEventCallback);
+                    // Calculate next sleep
+                    const sleepMs = await calculateNextSleep();
+                    // Sleep with ability to be interrupted by notifications
+                    await new Promise((resolve) => {
+                        currentSleepTimeout = setTimeout(resolve, sleepMs);
+                    });
+                }
+                else {
+                    // Not the scout, sleep longer
+                    await (0, utils_1.sleepFor)(enums_1.HMSH_SCOUT_INTERVAL_SECONDS * 1000);
+                }
+            }
+            catch (error) {
+                this.logger.error('postgres-time-scout-loop-error', { error });
+                await (0, utils_1.sleepFor)(1000);
+            }
+        }
+    }
+    /**
+     * Get the next awakening time from the database
+     */
+    async getNextAwakeningTime() {
+        const schemaName = this.kvsql().safeName(this.appId);
+        const appKey = `${this.appId}:time_range`;
+        try {
+            const result = await this.pgClient.query(`SELECT ${schemaName}.get_next_awakening_time($1) as next_time`, [appKey]);
+            if (result.rows[0]?.next_time) {
+                return new Date(result.rows[0].next_time).getTime();
+            }
+            return null;
+        }
+        catch (error) {
+            this.logger.error('postgres-get-next-awakening-error', { error });
+            return null;
+        }
+    }
+    /**
+     * Update the time scout's sleep timing based on schedule changes
+     */
+    async updateTimeScoutSleep(nextAwakening) {
+        // This could be used to interrupt current sleep and recalculate
+        // For now, just log the schedule update
+        this.logger.debug('postgres-time-schedule-updated', {
+            nextAwakening,
+            currentTime: Date.now()
+        });
+    }
+    /**
+     * Enhanced shouldScout that can handle notifications
+     */
+    async shouldScout() {
+        const wasScout = this.isScout;
+        const isScout = wasScout || (this.isScout = await this.reserveScoutRole('time'));
+        if (isScout) {
+            if (!wasScout) {
+                setTimeout(() => {
+                    this.isScout = false;
+                }, enums_1.HMSH_SCOUT_INTERVAL_SECONDS * 1000);
+            }
+            return true;
+        }
+        return false;
+    }
 }
 exports.PostgresStoreService = PostgresStoreService;

package/build/services/store/providers/redis/_base.d.ts

@@ -75,7 +75,7 @@ declare abstract class RedisStoreBase<ClientProvider extends ProviderClient, Tra
      * `purposeful re-entry`.
      */
     collateSynthetic(jobId: string, guid: string, amount: number, transaction?: TransactionProvider): Promise<number>;
-    setStateNX(jobId: string, appId: string, status?: number): Promise<boolean>;
+    setStateNX(jobId: string, appId: string, status?: number, entity?: string): Promise<boolean>;
     getSchema(activityId: string, appVersion: AppVID): Promise<ActivityType>;
     getSchemas(appVersion: AppVID): Promise<Record<string, ActivityType>>;
     setSchemas(schemas: Record<string, ActivityType>, appVersion: AppVID): Promise<any>;

package/build/services/store/providers/redis/_base.js

@@ -539,7 +539,7 @@ class RedisStoreBase extends __1.StoreService {
         });
         return await (transaction || this.storeClient)[this.commands.hincrbyfloat](jobKey, guid, amount.toString());
     }
-    async setStateNX(jobId, appId, status) {
+    async setStateNX(jobId, appId, status, entity) {
         const hashKey = this.mintKey(key_1.KeyType.JOB_STATE, { appId, jobId });
         const result = await this.storeClient[this.commands.hsetnx](hashKey, ':', status?.toString() ?? '1');
         return this.isSuccessful(result);

package/build/services/task/index.d.ts

@@ -32,5 +32,17 @@ declare class TaskService {
     registerWebHook(topic: string, context: JobState, dad: string, expire: number, transaction?: ProviderTransaction): Promise<string>;
     processWebHookSignal(topic: string, data: Record<string, unknown>): Promise<[string, string, string, string] | undefined>;
     deleteWebHookSignal(topic: string, data: Record<string, unknown>): Promise<number>;
+    /**
+     * Enhanced processTimeHooks that uses notifications for PostgreSQL stores
+     */
+    processTimeHooksWithNotifications(timeEventCallback: (jobId: string, gId: string, activityId: string, type: WorkListTaskType) => Promise<void>): Promise<void>;
+    /**
+     * Check if this is a PostgreSQL store
+     */
+    private isPostgresStore;
+    /**
+     * Check if the store supports notifications
+     */
+    private supportsNotifications;
 }
 export { TaskService };

package/build/services/task/index.js

@@ -202,5 +202,52 @@ class TaskService {
             throw new Error('signaler.process:error: hook rule not found');
         }
     }
+    /**
+     * Enhanced processTimeHooks that uses notifications for PostgreSQL stores
+     */
+    async processTimeHooksWithNotifications(timeEventCallback) {
+        // Check if the store supports notifications
+        if (this.isPostgresStore() && this.supportsNotifications()) {
+            try {
+                this.logger.info('task-using-notification-mode', {
+                    appId: this.store.appId,
+                    message: 'Time scout using PostgreSQL LISTEN/NOTIFY mode for efficient task processing'
+                });
+                // Use the PostgreSQL store's notification-based approach
+                await this.store.startTimeScoutWithNotifications(timeEventCallback);
+            }
+            catch (error) {
+                this.logger.warn('task-notifications-fallback', {
+                    appId: this.store.appId,
+                    error: error.message,
+                    fallbackTo: 'polling',
+                    message: 'Notification mode failed - falling back to traditional polling'
+                });
+                // Fall back to regular polling
+                await this.processTimeHooks(timeEventCallback);
+            }
+        }
+        else {
+            this.logger.info('task-using-polling-mode', {
+                appId: this.store.appId,
+                storeType: this.store.constructor.name,
+                message: 'Time scout using traditional polling mode (notifications not available)'
+            });
+            // Use regular polling for non-PostgreSQL stores
+            await this.processTimeHooks(timeEventCallback);
+        }
+    }
+    /**
+     * Check if this is a PostgreSQL store
+     */
+    isPostgresStore() {
+        return this.store.constructor.name === 'PostgresStoreService';
+    }
+    /**
+     * Check if the store supports notifications
+     */
+    supportsNotifications() {
+        return typeof this.store.startTimeScoutWithNotifications === 'function';
+    }
 }
 exports.TaskService = TaskService;

package/build/types/job.d.ts

@@ -95,6 +95,13 @@ type ExtensionType = {
      * will be added after the job is resumed if relevant.
      */
     pending?: number;
+    /**
+     * Entity to organize the job in the database by type.
+     * This is useful for querying and filtering jobs by type
+     * as the <your-app-id>.jobs table is organized by entity.
+     * Add partial indexes to the entity column to speed up queries.
+     */
+    entity?: string;
 };
 /**
  * job_status semaphore

package/build/types/provider.d.ts

@@ -84,6 +84,7 @@ export interface SetOptions {
 export interface HSetOptions {
     nx?: boolean;
     ex?: number;
+    entity?: string;
 }
 export interface ZAddOptions {
     nx?: boolean;

package/index.ts

@@ -5,6 +5,7 @@ import { MemFlow } from './services/memflow';
 import { ClientService as Client } from './services/memflow/client';
 import { ConnectionService as Connection } from './services/memflow/connection';
 import { Search } from './services/memflow/search';
+import { Entity } from './services/memflow/entity';
 import { WorkerService as Worker } from './services/memflow/worker';
 import { WorkflowService as workflow } from './services/memflow/workflow';
 import { WorkflowHandleService as WorkflowHandle } from './services/memflow/handle';
@@ -21,8 +22,6 @@ 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';
 
-//const { Client, Connection, Search, Worker, workflow } = MemFlow;
-
 export {
   //Provider Connectors
   Connector, //factory
@@ -44,6 +43,7 @@ export {
   Connection,
   proxyActivities,
   Search,
+  Entity,
   Worker,
   workflow,
   WorkflowHandle,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
-  "homepage": "https://hotmesh.io/",
+  "homepage": "https://github.com/hotmeshio/sdk-typescript/",
   "publishConfig": {
     "access": "public"
   },
@@ -33,7 +33,8 @@
     "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:fatal": "NODE_ENV=test jest ./tests/memflow/fatal/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:goodbye": "NODE_ENV=test jest ./tests/memflow/goodbye/*.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:memflow:context": "NODE_ENV=test jest ./tests/memflow/context/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:entity": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/entity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:memflow:agent": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/agent/postgres.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug HMSH_IS_CLUSTER=true NODE_ENV=test jest ./tests/memflow/helloworld/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/*.test.ts --detectOpenHandles --forceExit --verbose",
     "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",

package/build/services/memflow/workflow/contextMethods.d.ts

@@ -1,14 +0,0 @@
-import { Context } from './common';
-/**
- * Returns a context session handle for interacting with the workflow's JSONB context storage.
- * @returns {Promise<Context>} A context session for workflow data.
- *
- * @example
- * ```typescript
- * const context = await workflow.context();
- * await context.set({ user: { id: 123 } });
- * await context.merge({ user: { name: "John" } });
- * const user = await context.get("user");
- * ```
- */
-export declare function context(): Promise<Context>;