@hotmeshio/hotmesh 0.5.0 → 0.5.1

package/README.md

@@ -1,44 +1,52 @@
 # HotMesh
 
-**Permanent-Memory Workflows & AI Agents**
+**🧠 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** is a Temporal-style workflow engine that runs natively on PostgreSQL — with a powerful twist: every workflow maintains permanent, state that persists independently of the workflow itself.
+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.
 
-This means:
+Use HotMesh to:
 
-* Any number of lightweight, thread-safe **hook workers** can attach to the same workflow record at any time.
-* These hooks can safely **read and write** to shared state.
-* The result is a **durable execution model** with **evolving memory**, ideal for **human-in-the-loop processes** and **AI agents that learn over time**.
+* **Store Evolving State** – Retain memory/state between executions
+* **Coordinate Distributed Work** – Safely allow multiple workers to act on shared state
+* **Track and Replay** – Full audit history and replay support by default
 
 ---
 
 ## Table of Contents
 
-1. 🚀 Quick Start
-2. 🧠 How Permanent Memory Works
-3. 🔌 Hooks & Entity API
-4. 🤖 Building Durable AI Agents
-5. 🔬 Advanced Patterns & Recipes
-6. 📚 Documentation & Links
+1. [Quick Start](#-quick-start)
+2. [Permanent Memory Architecture](#-permanent-memory-architecture)
+3. [Durable AI Agents](#-durable-ai-agents)
+4. [Building Pipelines with State](#-building-pipelines-with-state)
+5. [Documentation & Links](#-documentation--links)
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
+
+### Prerequisites
+
+* PostgreSQL (or Supabase)
+* Node.js 16+
 
 ### Install
+
 ```bash
 npm install @hotmeshio/hotmesh
 ```
 
-### Start a workflow
-```typescript
-// index.ts
+### Connect to a Database
+
+HotMesh leverages Temporal.io's developer-friendly syntax for authoring workers, workflows, and clients. The `init` and `start` methods should look familiar.
+
+```ts
 import { MemFlow } from '@hotmeshio/hotmesh';
 import { Client as Postgres } from 'pg';
 
 async function main() {
+  // MemFlow will auto-provision the database upon init
   const mf = await MemFlow.init({
     appId: 'my-app',
     engine: {
@@ -49,13 +57,13 @@ async function main() {
     }
   });
 
-  // Kick off a workflow
+  // Start a workflow with an assigned ID and arguments
   const handle = await mf.workflow.start({
-    entity: 'user',
-    workflowName: 'userExample',
-    workflowId: 'jane@hotmesh.com',
-    args: ['Jane'],
-    taskQueue: 'entityqueue'
+    entity: 'research-agent',
+    workflowName: 'researchAgent',
+    workflowId: 'agent-session-jane-001',
+    args: ['What are the long-term impacts of renewable energy subsidies?'],
+    taskQueue: 'agents'
   });
 
   console.log('Result:', await handle.result());
@@ -64,168 +72,53 @@ async function main() {
 main().catch(console.error);
 ```
 
----
-
-## 🧠 How Permanent Memory Works
-
-* **Entity = persistent JSON record** – each workflow's memory is stored as a JSONB row in your Postgres database
-* **Atomic operations** (`set`, `merge`, `append`, `increment`, `toggle`, `delete`, …)
-* **Transactional** – every update participates in the workflow/DB transaction
-* **Time-travel-safe** – full replay compatibility; side-effect detector guarantees determinism
-* **Hook-friendly** – any worker with the record ID can attach and mutate its slice of the JSON
-* **Index-friendly** - entity data is stored as JSONB; add partial indexes for improved query analysis.
+### System Benefits
 
-**Example: Adding a Partial Index for Specific Entity Types**
-```sql
--- Create a partial index for 'user' entities with specific entity values
-CREATE INDEX idx_user_premium ON your_app.jobs (id)
-WHERE entity = 'user' AND (context->>'isPremium')::boolean = true;
-```
-This index will only be used for queries that match both conditions, making lookups for premium users much faster.
+* **No Setup Required** – Tables and indexes are provisioned automatically
+* **Shared State** – Every worker shares access to the same entity memory
+* **Coordination by Design** – PostgreSQL handles consistency and isolation
+* **Tenant Isolation** – Each app maintains its own schema
+* **Scalable Defaults** – Partitioned tables and index support included
 
 ---
 
-## 🔌 Hooks & Entity API – Full Example
-
-HotMesh hooks are powerful because they can be called both internally (from within a workflow) and externally (from outside, even after the workflow completes). This means you can:
-
-* Start a workflow that sets up initial state
-* Have the workflow call some hooks internally
-* Let the workflow complete
-* Continue to update the workflow's entity state from the outside via hooks
-* Build long-running processes that evolve over time
-
-Here's a complete example showing both internal and external hook usage:
-
-```typescript
-import { MemFlow } from '@hotmeshio/hotmesh';
-
-/* ------------ Main workflow ------------ */
-export async function userExample(name: string): Promise<any> {
-  //the entity method provides transactional, replayable access to shared job state 
-  const entity = await MemFlow.workflow.entity();
-
-  //create the initial entity (even arrays are supported)
-  await entity.set({
-    user: { name },
-    hooks: {},
-    metrics: { count: 0 }
-  });
-
-  // Call one hook internally
-  const result1 = await MemFlow.workflow.execHook({
-    taskQueue: 'entityqueue',
-    workflowName: 'hook1',
-    args: [name, 'hook1'],
-    signalId: 'hook1-complete'
-  });
-
-  // merge the result
-  await entity.merge({ hooks: { r1: result1 } });
-  await entity.increment('metrics.count', 1);
-
-  return "The main has completed; the db record persists and can be hydrated; hook in from the outside!";
-}
-
-/* ------------ Hook 1 (hooks have access to methods like sleepFor) ------------ */
-export async function hook1(name: string, kind: string): Promise<any> {
-  await MemFlow.workflow.sleepFor('2 seconds');
-  const res = { kind, processed: true, at: Date.now() };
-  await MemFlow.workflow.signal('hook1-complete', res);
-}
-
-/* ------------ Hook 2 (hooks can access shared job entity) ------------ */
-export async function hook2(name: string, kind: string): Promise<void> {
-  const entity = await MemFlow.workflow.entity();
-  await entity.merge({ user: { lastSeen: new Date().toISOString() } });
-  await MemFlow.workflow.signal('hook2-complete', { ok: true });
-}
-
-/* ------------ Worker/Hook Registration ------------ */
-async function startWorker() {
-  const mf = await MemFlow.init({
-    appId: 'my-app',
-    engine: {
-      connection: {
-        class: Postgres,
-        options: { connectionString: process.env.DATABASE_URL }
-      }
-    }
-  });
+## Permanent Memory Architecture
 
-  const worker = await mf.worker.create({
-    taskQueue: 'entityqueue',
-    workflow: example
-  });
+Every workflow in HotMesh is backed by an "entity": a versioned, JSONB record that tracks its memory and state transitions.
 
-  await mf.worker.create({
-    taskQueue: 'entityqueue',
-    workflow: hook1
-  });
+* **Entities** – Represent long-lived state for a workflow or agent
+* **Commands** – Modify state with methods like `set`, `merge`, `append`, `increment`
+* **Consistency** – All updates are transactional with Postgres
+* **Replay Safety** – Protects against duplicated side effects during re-execution
+* **Partial Indexing** – Optimized querying of fields within large JSON structures
 
-  await mf.worker.create({
-    taskQueue: 'entityqueue',
-    workflow: hook2
-  });
+### Example: Partial Index for Premium Users
 
-  console.log('Workers and hooks started and listening...');
-}
+```sql
+-- Index only those user entities that are marked as premium
+CREATE INDEX idx_user_premium ON your_app.jobs (id)
+WHERE entity = 'user' AND (context->>'isPremium')::boolean = true;
 ```
 
-### The Power of External Hooks
-
-One of HotMesh's most powerful features is that workflow entities remain accessible even after the main workflow completes. By providing the original workflow ID, any authorized client can:
-
-* Hook into existing workflow entities
-* Update state and trigger new processing
-* Build evolving, long-running processes
-* Enable human-in-the-loop workflows
-* Create AI agents that learn over time
-
-Here's how to hook into an existing workflow from the outside:
-
-```typescript
-/* ------------ External Hook Example ------------ */
-async function externalHookExample() {
-  const client = new MemFlow.Client({
-    appId: 'my-app',
-    engine: {
-      connection: {
-        class: Postgres,
-        options: { connectionString: process.env.DATABASE_URL }
-      }
-    }
-  });
-
-  // Start hook2 externally by providing the original workflow ID
-  await client.workflow.hook({
-    workflowId: 'jane@hotmesh.com', //id of the target workflow
-    taskQueue: 'entityqueue',
-    workflowName: 'hook2',
-    args: [name, 'external-hook']
-  });
-}
-```
+This index improves performance for filtered queries while reducing index size.
 
 ---
 
-## 🤖 Building Durable AI Agents
+## Durable AI Agents
+
+Agents often require memory—context that persists between invocations, spans multiple perspectives, or outlives a single process. HotMesh supports that natively.
 
-HotMesh's permanent memory enables a revolutionary approach to AI agents: **perspective-oriented intelligence**. Instead of monolithic agents, you build **multi-faceted agents** where:
+The following example builds a "research agent" that runs sub-flows and self-reflects on the results.
 
-* **Entity state** = the agent's living, evolving context
-* **Hooks** = different perspectives that operate on that context
-* **Child workflows** = specialized co-agents with their own entity types
-* **Shared memory** = enables rich self-reflection and multi-agent collaboration
+### Research Agent Example
 
-### Example: A Research Agent with Multiple Perspectives
+#### Main Coordinator Agent
 
-```typescript
-/* ------------ Main Research Agent ------------ */
+```ts
 export async function researchAgent(query: string): Promise<any> {
   const entity = await MemFlow.workflow.entity();
-  
-  // Initialize agent context
+
+  // Set up shared memory for this agent session
   await entity.set({
     query,
     findings: [],
@@ -234,20 +127,20 @@ export async function researchAgent(query: string): Promise<any> {
     status: 'researching'
   });
 
-  // Spawn perspective hooks that operate on shared context
-  const optimisticView = MemFlow.workflow.execHook({
-    taskQueue: 'perspectives',
+  // Launch perspective hooks in parallel (no need to await here)
+  const optimistic = MemFlow.workflow.execHook({
+    taskQueue: 'agents',
     workflowName: 'optimisticPerspective',
     args: [query]
   });
 
-  const skepticalView = MemFlow.workflow.execHook({
-    taskQueue: 'perspectives', 
+  const skeptical = MemFlow.workflow.execHook({
+    taskQueue: 'agents',
     workflowName: 'skepticalPerspective',
     args: [query]
   });
 
-  // Spawn a fact-checker child agent with its own entity type
+  // Launch a child workflow with its own isolated entity/state
   const factChecker = await MemFlow.workflow.execChild({
     entity: 'fact-checker',
     workflowName: 'factCheckAgent',
@@ -256,121 +149,221 @@ export async function researchAgent(query: string): Promise<any> {
     taskQueue: 'agents'
   });
 
-  // Wait for all perspectives to contribute
-  await Promise.all([optimisticView, skepticalView, factChecker]);
+  // Wait for all views to complete before analyzing
+  await Promise.all([optimistic, skeptical, factChecker]);
 
-  // Self-reflection: analyze conflicting perspectives
+  // Final synthesis: aggregate and compare all perspectives
   await MemFlow.workflow.execHook({
     taskQueue: 'perspectives',
     workflowName: 'synthesizePerspectives',
     args: []
   });
 
-  const finalContext = await entity.get();
-  return finalContext;
+  return await entity.get();
 }
+```
+
+#### Hooks: Perspectives
 
-/* ------------ Optimistic Perspective Hook ------------ */
-export async function optimisticPerspective(query: string): Promise<void> {
+```ts
+// Optimistic hook looks for affirming evidence
+export async function optimisticPerspective(query: string, config: {signal: string}): Promise<void> {
   const entity = await MemFlow.workflow.entity();
-  
-  // Optimistic perspective: look for supporting evidence
   const findings = await searchForSupportingEvidence(query);
-  
-  await entity.merge({
-    perspectives: {
-      optimistic: {
-        findings,
-        confidence: 0.8,
-        bias: 'Tends to emphasize positive evidence'
-      }
-    }
-  });
+  await entity.merge({ perspectives: { optimistic: { findings, confidence: 0.8 }}});
+  //signal the caller to notify all done
+  await MemFlow.workflow.signal(config.signal, {});
 }
 
-/* ------------ Skeptical Perspective Hook ------------ */
-export async function skepticalPerspective(query: string): Promise<void> {
+// Skeptical hook seeks out contradictions and counterpoints
+export async function skepticalPerspective(query: string, config: {signal: string}): Promise<void> {
   const entity = await MemFlow.workflow.entity();
-  
-  // Skeptical perspective: challenge assumptions
   const counterEvidence = await searchForCounterEvidence(query);
-  
-  await entity.merge({
-    perspectives: {
-      skeptical: {
-        counterEvidence,
-        confidence: 0.6,
-        bias: 'Challenges assumptions and seeks contradictory evidence'
-      }
-    }
-  });
+  await entity.merge({ perspectives: { skeptical: { counterEvidence, confidence: 0.6 }}});
+  await MemFlow.workflow.signal(config.signal, {});
 }
+```
+
+#### Child Agent: Fact Checker
 
-/* ------------ Fact-Checker Child Agent ------------ */
+```ts
+// A dedicated child agent with its own entity type and context
 export async function factCheckAgent(query: string): Promise<any> {
-  // This child has its own entity type for specialized fact-checking context
   const entity = await MemFlow.workflow.entity();
-  
-  await entity.set({
-    query,
-    sources: [],
-    verifications: [],
-    credibilityScore: 0
-  });
+  await entity.set({ query, sources: [], verifications: [] });
 
-  // Fact-checker can spawn its own specialized hooks
   await MemFlow.workflow.execHook({
-    taskQueue: 'verification',
+    taskQueue: 'agents',
     workflowName: 'verifySourceCredibility',
     args: [query]
   });
 
   return await entity.get();
 }
+```
 
-/* ------------ Synthesis Perspective Hook ------------ */
-export async function synthesizePerspectives(): Promise<void> {
+#### Synthesis
+
+```ts
+// Synthesis hook aggregates different viewpoints
+export async function synthesizePerspectives(config: {signal: string}): Promise<void> {
   const entity = await MemFlow.workflow.entity();
   const context = await entity.get();
-  
-  // Analyze conflicting perspectives and synthesize
-  const synthesis = await analyzePerspectives(context.perspectives);
-  
+
+  const result = await analyzePerspectives(context.perspectives);
+
   await entity.merge({
     perspectives: {
       synthesis: {
-        finalAssessment: synthesis,
-        confidence: calculateConfidence(context.perspectives),
-        reasoning: 'Balanced analysis of optimistic and skeptical viewpoints'
+        finalAssessment: result,
+        confidence: calculateConfidence(context.perspectives)
       }
     },
     status: 'completed'
   });
+  await MemFlow.workflow.signal(config.signal, {});
 }
 ```
 
-### The Power of Perspective-Oriented Agents
+---
+
+## Building Pipelines with State
 
-This approach enables agents that can:
+HotMesh treats pipelines as long-lived records, not ephemeral jobs. Every pipeline run is stateful, resumable, and traceable.
 
-* **Question themselves** – different hooks challenge each other's assumptions
-* **Spawn specialized co-agents** – child workflows with their own entity types tackle specific domains
-* **Maintain rich context** – all perspectives contribute to a shared, evolving knowledge base
-* **Scale horizontally** – each perspective can run on different workers
-* **Learn continuously** – entity state accumulates insights across all interactions
-* **Self-reflect** – synthesis hooks analyze conflicting perspectives and improve decision-making
+### Setup a Data Pipeline
+
+```ts
+export async function dataPipeline(source: string): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
 
-Because every perspective operates on the same durable entity, agents can pause, restart, and evolve their world-model indefinitely while maintaining coherent, multi-faceted intelligence.
+  // 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();
+  
+  // Simulate data cleaning
+  await entity.merge({
+    status: 'cleaning',
+    lastCleanedAt: new Date().toISOString()
+  });
+
+  // Add to changelog
+  await entity.append('changeLog', {
+    action: 'clean',
+    timestamp: new Date().toISOString()
+  });
+
+  // Signal completion if called via execHook
+  if (signalInfo?.signal) {
+    await MemFlow.workflow.signal(signalInfo.signal, { 
+      status: 'cleaned',
+      timestamp: new Date().toISOString()
+    });
+  }
+}
+
+/**
+ * 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()
+  });
+
+  // Add to changelog
+  await entity.append('changeLog', {
+    action: 'schedule_refresh',
+    timestamp: new Date().toISOString(),
+    nextRefresh: new Date().toISOString()
+  });
+
+  // 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',
+    taskQueue: 'pipeline',
+    workflowName: 'runPipeline',
+    args: []
+  });
+}
+```
 
 ---
 
-## 📚 Documentation & Links
+## Documentation & Links
 
-* SDK API – [https://hotmeshio.github.io/sdk-typescript](https://hotmeshio.github.io/sdk-typescript)
-* Examples – [https://github.com/hotmeshio/samples-typescript](https://github.com/hotmeshio/samples-typescript)
+* SDK Reference – [hotmeshio.github.io/sdk-typescript](https://hotmeshio.github.io/sdk-typescript)
+* Examples – [github.com/hotmeshio/samples-typescript](https://github.com/hotmeshio/samples-typescript)
 
 ---
 
 ## License
 
-Apache 2.0 – see `LICENSE` for details.
+Apache 2.0 – See `LICENSE` for details.

package/build/modules/errors.d.ts

@@ -15,6 +15,7 @@ declare class MemFlowWaitForError extends Error {
     workflowId: string;
     index: number;
     workflowDimension: string;
+    type: string;
     constructor(params: MemFlowWaitForErrorType);
 }
 declare class MemFlowProxyError extends Error {
@@ -31,6 +32,7 @@ declare class MemFlowProxyError extends Error {
     workflowDimension: string;
     workflowId: string;
     workflowTopic: string;
+    type: string;
     constructor(params: MemFlowProxyErrorType);
 }
 declare class MemFlowChildError extends Error {
@@ -50,6 +52,7 @@ declare class MemFlowChildError extends Error {
     parentWorkflowId: string;
     workflowId: string;
     workflowTopic: string;
+    type: string;
     constructor(params: MemFlowChildErrorType);
 }
 declare class MemFlowWaitForAllError extends Error {
@@ -62,6 +65,7 @@ declare class MemFlowWaitForAllError extends Error {
     parentWorkflowId: string;
     workflowId: string;
     workflowTopic: string;
+    type: string;
     constructor(params: MemFlowWaitForAllErrorType);
 }
 declare class MemFlowSleepError extends Error {
@@ -70,22 +74,27 @@ declare class MemFlowSleepError extends Error {
     duration: number;
     index: number;
     workflowDimension: string;
+    type: string;
     constructor(params: MemFlowSleepErrorType);
 }
 declare class MemFlowTimeoutError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stack?: string);
 }
 declare class MemFlowMaxedError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stackTrace?: string);
 }
 declare class MemFlowFatalError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stackTrace?: string);
 }
 declare class MemFlowRetryError extends Error {
     code: number;
+    type: string;
     constructor(message: string, stackTrace?: string);
 }
 declare class MapDataError extends Error {

package/build/modules/errors.js

@@ -19,6 +19,7 @@ exports.SetStateError = SetStateError;
 class MemFlowWaitForError extends Error {
     constructor(params) {
         super(`WaitFor Interruption`);
+        this.type = 'MemFlowWaitForError';
         this.signalId = params.signalId;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
@@ -29,6 +30,7 @@ exports.MemFlowWaitForError = MemFlowWaitForError;
 class MemFlowProxyError extends Error {
     constructor(params) {
         super(`ProxyActivity Interruption`);
+        this.type = 'MemFlowProxyError';
         this.arguments = params.arguments;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
@@ -48,6 +50,7 @@ exports.MemFlowProxyError = MemFlowProxyError;
 class MemFlowChildError extends Error {
     constructor(params) {
         super(`ExecChild Interruption`);
+        this.type = 'MemFlowChildError';
         this.arguments = params.arguments;
         this.workflowId = params.workflowId;
         this.workflowTopic = params.workflowTopic;
@@ -70,6 +73,7 @@ exports.MemFlowChildError = MemFlowChildError;
 class MemFlowWaitForAllError extends Error {
     constructor(params) {
         super(`Collation Interruption`);
+        this.type = 'MemFlowWaitForAllError';
         this.items = params.items;
         this.size = params.size;
         this.workflowId = params.workflowId;
@@ -85,6 +89,7 @@ exports.MemFlowWaitForAllError = MemFlowWaitForAllError;
 class MemFlowSleepError extends Error {
     constructor(params) {
         super(`SleepFor Interruption`);
+        this.type = 'MemFlowSleepError';
         this.duration = params.duration;
         this.workflowId = params.workflowId;
         this.index = params.index;
@@ -96,6 +101,7 @@ exports.MemFlowSleepError = MemFlowSleepError;
 class MemFlowTimeoutError extends Error {
     constructor(message, stack) {
         super(message);
+        this.type = 'MemFlowTimeoutError';
         if (this.stack) {
             this.stack = stack;
         }
@@ -106,6 +112,7 @@ exports.MemFlowTimeoutError = MemFlowTimeoutError;
 class MemFlowMaxedError extends Error {
     constructor(message, stackTrace) {
         super(message);
+        this.type = 'MemFlowMaxedError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
@@ -116,6 +123,7 @@ exports.MemFlowMaxedError = MemFlowMaxedError;
 class MemFlowFatalError extends Error {
     constructor(message, stackTrace) {
         super(message);
+        this.type = 'MemFlowFatalError';
         if (stackTrace) {
             this.stack = stackTrace;
         }
@@ -126,6 +134,7 @@ exports.MemFlowFatalError = MemFlowFatalError;
 class MemFlowRetryError extends Error {
     constructor(message, stackTrace) {
         super(message);
+        this.type = 'MemFlowRetryError';
         if (stackTrace) {
             this.stack = stackTrace;
         }

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.5.0",
+    "version": "0.5.1",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

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

@@ -6,6 +6,7 @@ import { Entity } from './entity';
 import { WorkerService } from './worker';
 import { WorkflowService } from './workflow';
 import { WorkflowHandleService } from './handle';
+import { didInterrupt } from './workflow/interruption';
 /**
  * The MemFlow service is a collection of services that
  * emulate Temporal's capabilities, but instead are
@@ -106,6 +107,13 @@ declare class MemFlowClass {
      * including: `execChild`, `waitFor`, `sleep`, etc
      */
     static workflow: typeof WorkflowService;
+    /**
+     * Checks if an error is a HotMesh reserved error type that indicates
+     * a workflow interruption rather than a true error condition.
+     *
+     * @see {@link utils/interruption.didInterrupt} for detailed documentation
+     */
+    static didInterrupt: typeof didInterrupt;
     /**
      * Shutdown everything. All connections, workers, and clients will be closed.
      * Include in your signal handlers to ensure a clean shutdown.

package/build/services/memflow/index.js

@@ -9,6 +9,7 @@ const entity_1 = require("./entity");
 const worker_1 = require("./worker");
 const workflow_1 = require("./workflow");
 const handle_1 = require("./handle");
+const interruption_1 = require("./workflow/interruption");
 /**
  * The MemFlow service is a collection of services that
  * emulate Temporal's capabilities, but instead are
@@ -120,3 +121,10 @@ MemFlowClass.Worker = worker_1.WorkerService;
  * including: `execChild`, `waitFor`, `sleep`, etc
  */
 MemFlowClass.workflow = workflow_1.WorkflowService;
+/**
+ * Checks if an error is a HotMesh reserved error type that indicates
+ * a workflow interruption rather than a true error condition.
+ *
+ * @see {@link utils/interruption.didInterrupt} for detailed documentation
+ */
+MemFlowClass.didInterrupt = interruption_1.didInterrupt;

package/build/services/memflow/worker.js

@@ -322,6 +322,31 @@ class WorkerService {
                 const workflowResponse = await storage_1.asyncLocalStorage.run(context, async () => {
                     return await workflowFunction.apply(this, workflowInput.arguments);
                 });
+                //if the embedded function has a try/catch, it can interrup the throw
+                // throw here to interrupt the workflow if the embedded function caught and suppressed
+                if (interruptionRegistry.length > 0) {
+                    const payload = interruptionRegistry[0];
+                    switch (payload.type) {
+                        case 'MemFlowWaitForError':
+                            throw new errors_1.MemFlowWaitForError(payload);
+                        case 'MemFlowProxyError':
+                            throw new errors_1.MemFlowProxyError(payload);
+                        case 'MemFlowChildError':
+                            throw new errors_1.MemFlowChildError(payload);
+                        case 'MemFlowSleepError':
+                            throw new errors_1.MemFlowSleepError(payload);
+                        case 'MemFlowTimeoutError':
+                            throw new errors_1.MemFlowTimeoutError(payload.message, payload.stack);
+                        case 'MemFlowMaxedError':
+                            throw new errors_1.MemFlowMaxedError(payload.message, payload.stack);
+                        case 'MemFlowFatalError':
+                            throw new errors_1.MemFlowFatalError(payload.message, payload.stack);
+                        case 'MemFlowRetryError':
+                            throw new errors_1.MemFlowRetryError(payload.message, payload.stack);
+                        default:
+                            throw new errors_1.MemFlowRetryError(`Unknown interruption type: ${payload.type}`);
+                    }
+                }
                 return {
                     code: 200,
                     status: stream_1.StreamStatus.SUCCESS,

package/build/services/memflow/workflow/execChild.js

@@ -82,6 +82,7 @@ async function execChild(options) {
     const interruptionMessage = getChildInterruptPayload(context, options, execIndex);
     interruptionRegistry.push({
         code: common_1.HMSH_CODE_MEMFLOW_CHILD,
+        type: 'MemFlowChildError',
         ...interruptionMessage,
     });
     await (0, common_1.sleepImmediate)();

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

@@ -3,8 +3,8 @@ import { HookOptions } from './common';
  * Extended hook options that include signal configuration
  */
 export interface ExecHookOptions extends HookOptions {
-    /** Signal ID to send after hook execution */
-    signalId: string;
+    /** Signal ID to send after hook execution; if not provided, a random one will be generated */
+    signalId?: string;
 }
 /**
  * Executes a hook function and awaits the signal response.

package/build/services/memflow/workflow/execHook.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.execHook = void 0;
 const hook_1 = require("./hook");
 const waitFor_1 = require("./waitFor");
+const interruption_1 = require("./interruption");
 /**
  * Executes a hook function and awaits the signal response.
  * This is a convenience method that combines `hook()` and `waitFor()` operations.
@@ -60,14 +61,23 @@ const waitFor_1 = require("./waitFor");
  * ```
  */
 async function execHook(options) {
-    // Create hook options with signal field added to args
-    const hookOptions = {
-        ...options,
-        args: [...options.args, { signal: options.signalId }]
-    };
-    // Execute the hook with the signal information
-    await (0, hook_1.hook)(hookOptions);
-    // Wait for the signal response and return it
-    return await (0, waitFor_1.waitFor)(options.signalId);
+    try {
+        if (!options.signalId) {
+            options.signalId = 'memflow-hook-' + crypto.randomUUID();
+        }
+        const hookOptions = {
+            ...options,
+            args: [...options.args, { signal: options.signalId, $memflow: true }]
+        };
+        // Execute the hook with the signal information
+        await (0, hook_1.hook)(hookOptions);
+        // Wait for the signal response and return it
+        return await (0, waitFor_1.waitFor)(options.signalId);
+    }
+    catch (error) {
+        if ((0, interruption_1.didInterrupt)(error)) {
+            throw error;
+        }
+    }
 }
 exports.execHook = execHook;

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

@@ -0,0 +1,26 @@
+/**
+ * Checks if an error is a HotMesh reserved error type that indicates
+ * a workflow interruption rather than a true error condition.
+ *
+ * When this returns true, you can safely return from your workflow function.
+ * The workflow engine will handle the interruption automatically.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someWorkflowOperation();
+ * } catch (error) {
+ *   // Check if this is a HotMesh interruption
+ *   if (didInterrupt(error)) {
+ *     // Rethrow the error if HotMesh interruption
+ *     throw error;
+ *   }
+ *   // Handle actual error
+ *   console.error('Workflow failed:', error);
+ * }
+ * ```
+ *
+ * @param error - The error to check
+ * @returns true if the error is a HotMesh interruption
+ */
+export declare function didInterrupt(error: Error): boolean;

package/build/services/memflow/workflow/interruption.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didInterrupt = void 0;
+const errors_1 = require("../../../modules/errors");
+/**
+ * Checks if an error is a HotMesh reserved error type that indicates
+ * a workflow interruption rather than a true error condition.
+ *
+ * When this returns true, you can safely return from your workflow function.
+ * The workflow engine will handle the interruption automatically.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await someWorkflowOperation();
+ * } catch (error) {
+ *   // Check if this is a HotMesh interruption
+ *   if (didInterrupt(error)) {
+ *     // Rethrow the error if HotMesh interruption
+ *     throw error;
+ *   }
+ *   // Handle actual error
+ *   console.error('Workflow failed:', error);
+ * }
+ * ```
+ *
+ * @param error - The error to check
+ * @returns true if the error is a HotMesh interruption
+ */
+function didInterrupt(error) {
+    return (error instanceof errors_1.MemFlowChildError ||
+        error instanceof errors_1.MemFlowFatalError ||
+        error instanceof errors_1.MemFlowMaxedError ||
+        error instanceof errors_1.MemFlowProxyError ||
+        error instanceof errors_1.MemFlowRetryError ||
+        error instanceof errors_1.MemFlowSleepError ||
+        error instanceof errors_1.MemFlowTimeoutError ||
+        error instanceof errors_1.MemFlowWaitForError ||
+        error instanceof errors_1.MemFlowWaitForAllError);
+}
+exports.didInterrupt = didInterrupt;

package/build/services/memflow/workflow/proxyActivities.js

@@ -67,6 +67,7 @@ function wrapActivity(activityName, options) {
         const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, args, options);
         interruptionRegistry.push({
             code: common_1.HMSH_CODE_MEMFLOW_PROXY,
+            type: 'MemFlowProxyError',
             ...interruptionMessage,
         });
         await (0, common_1.sleepImmediate)();

package/build/services/memflow/workflow/sleepFor.js

@@ -43,6 +43,7 @@ async function sleepFor(duration) {
     };
     interruptionRegistry.push({
         code: common_1.HMSH_CODE_MEMFLOW_SLEEP,
+        type: 'MemFlowSleepError',
         ...interruptionMessage,
     });
     await (0, common_1.sleepImmediate)();

package/build/services/memflow/workflow/waitFor.js

@@ -45,11 +45,10 @@ async function waitFor(signalId) {
         signalId,
         index: execIndex,
         workflowDimension,
-    };
-    interruptionRegistry.push({
+        type: 'MemFlowWaitForError',
         code: common_1.HMSH_CODE_MEMFLOW_WAIT,
-        ...interruptionMessage,
-    });
+    };
+    interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();
     throw new common_1.MemFlowWaitForError(interruptionMessage);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",