@memgrafter/flatagents 0.10.0 → 2.0.0

package/MACHINES.md

@@ -22,7 +22,7 @@
 ```yaml
 # profiles.yml — agents reference by name
 spec: flatprofiles
-spec_version: "0.10.0"
+spec_version: "2.0.0"
 data:
   model_profiles:
     fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }
@@ -34,6 +34,13 @@ data:
 Agent model field: `"fast"` | `{ profile: "fast", temperature: 0.9 }` | `{ provider: x, name: y }`
 Resolution: default → profile → overrides → override
 
+## Agent References
+
+`data.agents` values may be:
+- String path to a flatagent config
+- Inline flatagent config (`spec: flatagent`)
+- Typed adapter ref: `{ type: "flatagent" | "smolagents" | "pi-agent", ref?: "...", config?: {...} }`
+
 ## State Fields
 
 | Field | Purpose |
@@ -49,6 +56,7 @@ Resolution: default → profile → overrides → override
 | `on_error` | State name or `{ default: x, ErrorType: y }` |
 | `transitions` | `[{ condition: "expr", to: state }, { to: default }]` |
 | `mode` | `settled` (all) / `any` (first) for parallel |
+| `wait_for` | Channel to wait for external signal (Jinja2 template) |
 | `timeout` | Seconds (0=forever) |
 
 ## Patterns
@@ -80,6 +88,19 @@ launch: background_task
 launch_input: { data: "{{ context.data }}" }
 ```
 
+**Wait for signal** (checkpoint, exit, resume on signal):
+```yaml
+wait_for_approval:
+  wait_for: "approval/{{ context.task_id }}"
+  timeout: 86400
+  output_to_context:
+    approved: "{{ output.approved }}"
+  transitions:
+    - condition: "context.approved"
+      to: continue
+    - to: rejected
+```
+
 ## Distributed Worker Pattern
 
 Use hook actions (e.g., `DistributedWorkerHooks`) with a `RegistrationBackend` + `WorkBackend` to build worker pools.
@@ -102,6 +123,31 @@ states:
 
 See `sdk/examples/distributed_worker/` for a full example.
 
+## Signals & Triggers
+
+Machine pauses at `wait_for` state → checkpoints with `waiting_channel` → process exits. Nothing running.
+
+**Signal delivery**: External process writes signal → trigger fires → dispatcher resumes matching machines.
+
+```
+send("approval/task-001", {approved: true})
+  → SQLite INSERT + touch trigger file
+  → launchd/systemd starts dispatcher
+  → dispatcher queries checkpoints WHERE waiting_channel = "approval/task-001"
+  → resumes machine from checkpoint, signal data as output.*
+```
+
+**Channel semantics**:
+- Addressed: `"approval/{{ context.task_id }}"` → one waiter
+- Broadcast: `"quota/openai"` → N waiters (dispatcher controls limit)
+
+**10,000 waiting machines** = 10,000 rows in SQLite. Zero processes, zero memory.
+
+**Trigger backends**: `none` (polling), `file` (launchd/systemd — nothing running), `socket` (UDS, in-process).
+DynamoDB Streams is implicit (no trigger code needed).
+
+**Signal backends**: `memory` (testing), `sqlite` (local durable), `dynamodb` (AWS).
+
 ## Context Variables
 
 `context.*` (all states), `input.*` (initial), `output.*` (in output_to_context), `item`/`as` (foreach)
@@ -123,3 +169,12 @@ class MyHooks(MachineHooks):
 persistence: { enabled: true, backend: local }  # local | memory
 ```
 Resume: `machine.execute(resume_from=execution_id)`
+
+## SDKs
+
+### Python SDKs
+- **flatagents** (agents): `pip install flatagents[litellm]`
+- **flatmachines** (orchestration): `pip install flatmachines[flatagents]`
+
+### JavaScript SDK
+A single JS SDK lives under [`sdk/js`](./sdk/js). It follows the same specs but is not yet split into separate FlatAgents/FlatMachines packages.

package/dist/index.d.mts

@@ -1,3 +1,39 @@
+declare class WebhookHooks implements MachineHooks {
+    private url;
+    constructor(url: string);
+    private send;
+    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
+    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
+    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
+    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
+    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
+}
+declare class CompositeHooks implements MachineHooks {
+    private hooks;
+    constructor(hooks: MachineHooks[]);
+    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
+    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
+    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
+    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
+    onTransition(from: string, to: string, context: Record<string, any>): Promise<string>;
+    onError(state: string, error: Error, context: Record<string, any>): Promise<string | null>;
+    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
+}
+/**
+ * Name-based registry for resolving hooks from machine config.
+ *
+ * Machine configs reference hooks by name (e.g., hooks: "my-hooks").
+ * The registry maps names to factory classes/functions and resolves
+ * them at runtime, keeping configs language-agnostic.
+ */
+declare class HooksRegistry {
+    private factories;
+    register(name: string, factory: HooksFactory): void;
+    has(name: string): boolean;
+    resolve(ref: HooksRef): MachineHooks;
+    private resolveSingle;
+}
+
 /**
  * Model configuration for an agent.
  * Can be inline config, profile reference, or profile with overrides.
@@ -200,9 +236,18 @@ interface ResultBackend {
     exists(uri: string): Promise<boolean>;
     delete(uri: string): Promise<void>;
 }
+type HooksRef = string | HooksRefConfig | Array<string | HooksRefConfig>;
+interface HooksRefConfig {
+    name: string;
+    args?: Record<string, any>;
+}
+type HooksFactory = {
+    new (args?: Record<string, any>): MachineHooks;
+} | ((args?: Record<string, any>) => MachineHooks);
 interface MachineOptions {
     config: MachineConfig | string;
     hooks?: MachineHooks;
+    hooksRegistry?: HooksRegistry;
     persistence?: PersistenceBackend;
     resultBackend?: ResultBackend;
     executionLock?: ExecutionLock;
@@ -409,6 +454,7 @@ declare class FlatMachine {
     private context;
     private input;
     private hooks?;
+    private _hooksRegistry;
     private checkpointManager?;
     private resultBackend?;
     private executionLock;
@@ -420,6 +466,8 @@ declare class FlatMachine {
     private currentState?;
     private currentStep;
     constructor(options: MachineOptions);
+    get hooksRegistry(): HooksRegistry;
+    private resolveHooks;
     execute(input?: Record<string, any>, resumeSnapshot?: MachineSnapshot): Promise<any>;
     private executeInternal;
     resume(executionId: string): Promise<any>;
@@ -574,28 +622,6 @@ declare class MDAPVotingExecution implements ExecutionType {
 }
 declare function getExecutionType(config?: ExecutionConfig): ExecutionType;
 
-declare class WebhookHooks implements MachineHooks {
-    private url;
-    constructor(url: string);
-    private send;
-    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
-    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
-    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
-    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
-    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
-}
-declare class CompositeHooks implements MachineHooks {
-    private hooks;
-    constructor(hooks: MachineHooks[]);
-    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
-    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
-    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
-    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
-    onTransition(from: string, to: string, context: Record<string, any>): Promise<string>;
-    onError(state: string, error: Error, context: Record<string, any>): Promise<string | null>;
-    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
-}
-
 declare class MemoryBackend implements PersistenceBackend {
     private store;
     save(key: string, snapshot: MachineSnapshot): Promise<void>;
@@ -670,4 +696,4 @@ declare class LocalFileLock implements ExecutionLock {
     release(key: string): Promise<void>;
 }
 
-export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type LLMBackend, type LLMBackendConfig, type LLMOptions, LocalFileBackend, LocalFileLock, type MCPServer, MCPToolProvider, MDAPVotingExecution, type MachineConfig, type MachineHooks, type MachineOptions, type MachineSnapshot, MemoryBackend, type Message, MockLLMBackend, type MockResponse, type ModelConfig, type ModelProfileConfig, NoOpLock, ParallelExecution, type PersistenceBackend, ProfileManager, type ProfiledModelConfig, type ProfilesConfig, type ResultBackend, RetryExecution, type State, type TemplateAllowlist, type ToolCall, type ToolDefinition, type ToolFilter, VercelAIBackend, WebhookHooks, evaluate, getExecutionType, inMemoryResultBackend, resolveModelConfig, setTemplateAllowlist };
+export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type HooksFactory, type HooksRef, type HooksRefConfig, HooksRegistry, type LLMBackend, type LLMBackendConfig, type LLMOptions, LocalFileBackend, LocalFileLock, type MCPServer, MCPToolProvider, MDAPVotingExecution, type MachineConfig, type MachineHooks, type MachineOptions, type MachineSnapshot, MemoryBackend, type Message, MockLLMBackend, type MockResponse, type ModelConfig, type ModelProfileConfig, NoOpLock, ParallelExecution, type PersistenceBackend, ProfileManager, type ProfiledModelConfig, type ProfilesConfig, type ResultBackend, RetryExecution, type State, type TemplateAllowlist, type ToolCall, type ToolDefinition, type ToolFilter, VercelAIBackend, WebhookHooks, evaluate, getExecutionType, inMemoryResultBackend, resolveModelConfig, setTemplateAllowlist };

package/dist/index.d.ts

@@ -1,3 +1,39 @@
+declare class WebhookHooks implements MachineHooks {
+    private url;
+    constructor(url: string);
+    private send;
+    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
+    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
+    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
+    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
+    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
+}
+declare class CompositeHooks implements MachineHooks {
+    private hooks;
+    constructor(hooks: MachineHooks[]);
+    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
+    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
+    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
+    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
+    onTransition(from: string, to: string, context: Record<string, any>): Promise<string>;
+    onError(state: string, error: Error, context: Record<string, any>): Promise<string | null>;
+    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
+}
+/**
+ * Name-based registry for resolving hooks from machine config.
+ *
+ * Machine configs reference hooks by name (e.g., hooks: "my-hooks").
+ * The registry maps names to factory classes/functions and resolves
+ * them at runtime, keeping configs language-agnostic.
+ */
+declare class HooksRegistry {
+    private factories;
+    register(name: string, factory: HooksFactory): void;
+    has(name: string): boolean;
+    resolve(ref: HooksRef): MachineHooks;
+    private resolveSingle;
+}
+
 /**
  * Model configuration for an agent.
  * Can be inline config, profile reference, or profile with overrides.
@@ -200,9 +236,18 @@ interface ResultBackend {
     exists(uri: string): Promise<boolean>;
     delete(uri: string): Promise<void>;
 }
+type HooksRef = string | HooksRefConfig | Array<string | HooksRefConfig>;
+interface HooksRefConfig {
+    name: string;
+    args?: Record<string, any>;
+}
+type HooksFactory = {
+    new (args?: Record<string, any>): MachineHooks;
+} | ((args?: Record<string, any>) => MachineHooks);
 interface MachineOptions {
     config: MachineConfig | string;
     hooks?: MachineHooks;
+    hooksRegistry?: HooksRegistry;
     persistence?: PersistenceBackend;
     resultBackend?: ResultBackend;
     executionLock?: ExecutionLock;
@@ -409,6 +454,7 @@ declare class FlatMachine {
     private context;
     private input;
     private hooks?;
+    private _hooksRegistry;
     private checkpointManager?;
     private resultBackend?;
     private executionLock;
@@ -420,6 +466,8 @@ declare class FlatMachine {
     private currentState?;
     private currentStep;
     constructor(options: MachineOptions);
+    get hooksRegistry(): HooksRegistry;
+    private resolveHooks;
     execute(input?: Record<string, any>, resumeSnapshot?: MachineSnapshot): Promise<any>;
     private executeInternal;
     resume(executionId: string): Promise<any>;
@@ -574,28 +622,6 @@ declare class MDAPVotingExecution implements ExecutionType {
 }
 declare function getExecutionType(config?: ExecutionConfig): ExecutionType;
 
-declare class WebhookHooks implements MachineHooks {
-    private url;
-    constructor(url: string);
-    private send;
-    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
-    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
-    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
-    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
-    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
-}
-declare class CompositeHooks implements MachineHooks {
-    private hooks;
-    constructor(hooks: MachineHooks[]);
-    onMachineStart(context: Record<string, any>): Promise<Record<string, any>>;
-    onMachineEnd(context: Record<string, any>, output: any): Promise<any>;
-    onStateEnter(state: string, context: Record<string, any>): Promise<Record<string, any>>;
-    onStateExit(state: string, context: Record<string, any>, output: any): Promise<any>;
-    onTransition(from: string, to: string, context: Record<string, any>): Promise<string>;
-    onError(state: string, error: Error, context: Record<string, any>): Promise<string | null>;
-    onAction(action: string, context: Record<string, any>): Promise<Record<string, any>>;
-}
-
 declare class MemoryBackend implements PersistenceBackend {
     private store;
     save(key: string, snapshot: MachineSnapshot): Promise<void>;
@@ -670,4 +696,4 @@ declare class LocalFileLock implements ExecutionLock {
     release(key: string): Promise<void>;
 }
 
-export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type LLMBackend, type LLMBackendConfig, type LLMOptions, LocalFileBackend, LocalFileLock, type MCPServer, MCPToolProvider, MDAPVotingExecution, type MachineConfig, type MachineHooks, type MachineOptions, type MachineSnapshot, MemoryBackend, type Message, MockLLMBackend, type MockResponse, type ModelConfig, type ModelProfileConfig, NoOpLock, ParallelExecution, type PersistenceBackend, ProfileManager, type ProfiledModelConfig, type ProfilesConfig, type ResultBackend, RetryExecution, type State, type TemplateAllowlist, type ToolCall, type ToolDefinition, type ToolFilter, VercelAIBackend, WebhookHooks, evaluate, getExecutionType, inMemoryResultBackend, resolveModelConfig, setTemplateAllowlist };
+export { type AgentConfig, type AgentOptions, type BackendConfig, CheckpointManager, CompositeHooks, DefaultExecution, type ExecutionConfig, type ExecutionLock, type ExecutionType, FlatAgent, FlatMachine, type HooksFactory, type HooksRef, type HooksRefConfig, HooksRegistry, type LLMBackend, type LLMBackendConfig, type LLMOptions, LocalFileBackend, LocalFileLock, type MCPServer, MCPToolProvider, MDAPVotingExecution, type MachineConfig, type MachineHooks, type MachineOptions, type MachineSnapshot, MemoryBackend, type Message, MockLLMBackend, type MockResponse, type ModelConfig, type ModelProfileConfig, NoOpLock, ParallelExecution, type PersistenceBackend, ProfileManager, type ProfiledModelConfig, type ProfilesConfig, type ResultBackend, RetryExecution, type State, type TemplateAllowlist, type ToolCall, type ToolDefinition, type ToolFilter, VercelAIBackend, WebhookHooks, evaluate, getExecutionType, inMemoryResultBackend, resolveModelConfig, setTemplateAllowlist };

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   DefaultExecution: () => DefaultExecution,
   FlatAgent: () => FlatAgent,
   FlatMachine: () => FlatMachine,
+  HooksRegistry: () => HooksRegistry,
   LocalFileBackend: () => LocalFileBackend,
   LocalFileLock: () => LocalFileLock,
   MCPToolProvider: () => MCPToolProvider,
@@ -1006,6 +1007,179 @@ var LocalFileLock = class {
   }
 };
 
+// src/hooks.ts
+var WebhookHooks = class {
+  constructor(url) {
+    this.url = url;
+  }
+  async send(event, data) {
+    try {
+      const body = JSON.stringify({ event, ...data, timestamp: (/* @__PURE__ */ new Date()).toISOString() }, (key, value) => {
+        if (typeof value === "object" && value !== null) {
+          const seen = /* @__PURE__ */ new WeakSet();
+          return JSON.parse(JSON.stringify(value, (k, v) => {
+            if (typeof v === "object" && v !== null) {
+              if (seen.has(v)) return "[Circular]";
+              seen.add(v);
+            }
+            return v;
+          }));
+        }
+        return value;
+      });
+      await fetch(this.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body
+      });
+    } catch {
+    }
+  }
+  async onMachineStart(context) {
+    await this.send("machine_start", { context });
+    return context;
+  }
+  async onMachineEnd(context, output) {
+    await this.send("machine_end", { context, output });
+    return output;
+  }
+  async onStateEnter(state, context) {
+    await this.send("state_enter", { state, context });
+    return context;
+  }
+  async onStateExit(state, context, output) {
+    await this.send("state_exit", { state, context, output });
+    return output;
+  }
+  async onAction(action, context) {
+    await this.send("action", { action, context });
+    return context;
+  }
+};
+var CompositeHooks = class {
+  constructor(hooks) {
+    this.hooks = hooks;
+  }
+  async onMachineStart(context) {
+    let result = context;
+    for (const hook of this.hooks) {
+      if (hook.onMachineStart) {
+        try {
+          result = await hook.onMachineStart(result);
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+  async onMachineEnd(context, output) {
+    let result = output;
+    for (const hook of this.hooks) {
+      if (hook.onMachineEnd) {
+        try {
+          result = await hook.onMachineEnd(context, result);
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+  async onStateEnter(state, context) {
+    let result = context;
+    for (const hook of this.hooks) {
+      if (hook.onStateEnter) {
+        try {
+          result = await hook.onStateEnter(state, result);
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+  async onStateExit(state, context, output) {
+    let result = output;
+    for (const hook of this.hooks) {
+      if (hook.onStateExit) {
+        try {
+          result = await hook.onStateExit(state, context, result);
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+  async onTransition(from, to, context) {
+    let result = to;
+    for (const hook of this.hooks) {
+      if (hook.onTransition) {
+        try {
+          result = await hook.onTransition(from, result, context);
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+  async onError(state, error, context) {
+    let result = null;
+    for (const hook of this.hooks) {
+      if (hook.onError) {
+        try {
+          const hookResult = await hook.onError(state, error, context);
+          if (hookResult !== null) result = hookResult;
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+  async onAction(action, context) {
+    let result = context;
+    for (const hook of this.hooks) {
+      if (hook.onAction) {
+        try {
+          result = await hook.onAction(action, result);
+        } catch {
+        }
+      }
+    }
+    return result;
+  }
+};
+var HooksRegistry = class {
+  constructor() {
+    this.factories = /* @__PURE__ */ new Map();
+  }
+  register(name, factory) {
+    this.factories.set(name, factory);
+  }
+  has(name) {
+    return this.factories.has(name);
+  }
+  resolve(ref) {
+    if (Array.isArray(ref)) {
+      const hooks = ref.map((entry) => this.resolveSingle(entry));
+      return new CompositeHooks(hooks);
+    }
+    return this.resolveSingle(ref);
+  }
+  resolveSingle(ref) {
+    const name = typeof ref === "string" ? ref : ref.name;
+    const args = typeof ref === "string" ? void 0 : ref.args;
+    const factory = this.factories.get(name);
+    if (!factory) {
+      throw new Error(
+        `No hooks registered for name '${name}'. Registered: [${[...this.factories.keys()].join(", ")}]`
+      );
+    }
+    try {
+      return new factory(args);
+    } catch {
+      return factory(args);
+    }
+  }
+};
+
 // src/flatmachine.ts
 var FlatMachine = class _FlatMachine {
   constructor(options) {
@@ -1017,7 +1191,8 @@ var FlatMachine = class _FlatMachine {
     this.pendingLaunches = [];
     this.currentStep = 0;
     this.config = typeof options.config === "string" ? yaml3.parse((0, import_fs5.readFileSync)(options.config, "utf-8")) : options.config;
-    this.hooks = options.hooks;
+    this._hooksRegistry = options.hooksRegistry ?? new HooksRegistry();
+    this.hooks = this.resolveHooks(options.hooks);
     this.configDir = options.configDir ?? process.cwd();
     this.profilesFile = this.resolveProfilesFile(options.profilesFile);
     this.executionId = options.executionId ?? this.executionId;
@@ -1040,6 +1215,15 @@ var FlatMachine = class _FlatMachine {
       this.checkpointEvents = new Set(events);
     }
   }
+  get hooksRegistry() {
+    return this._hooksRegistry;
+  }
+  resolveHooks(explicit) {
+    if (explicit) return explicit;
+    const hooksConfig = this.config.data.hooks;
+    if (!hooksConfig) return void 0;
+    return this._hooksRegistry.resolve(hooksConfig);
+  }
   async execute(input, resumeSnapshot) {
     if (this.config.data.expression_engine === "cel") {
       throw new Error("expression_engine 'cel' is not supported in the JS SDK yet");
@@ -1323,7 +1507,7 @@ var FlatMachine = class _FlatMachine {
       config: resolved.config,
       configDir: resolved.configDir,
       resultBackend: this.resultBackend,
-      hooks: this.hooks,
+      hooksRegistry: this._hooksRegistry,
       executionId: overrides?.executionId,
       parentExecutionId: overrides?.parentExecutionId,
       profilesFile: this.profilesFile
@@ -1533,146 +1717,6 @@ var FlatMachine = class _FlatMachine {
     return { [firstKey]: results[firstKey] };
   }
 };
-
-// src/hooks.ts
-var WebhookHooks = class {
-  constructor(url) {
-    this.url = url;
-  }
-  async send(event, data) {
-    try {
-      const body = JSON.stringify({ event, ...data, timestamp: (/* @__PURE__ */ new Date()).toISOString() }, (key, value) => {
-        if (typeof value === "object" && value !== null) {
-          const seen = /* @__PURE__ */ new WeakSet();
-          return JSON.parse(JSON.stringify(value, (k, v) => {
-            if (typeof v === "object" && v !== null) {
-              if (seen.has(v)) return "[Circular]";
-              seen.add(v);
-            }
-            return v;
-          }));
-        }
-        return value;
-      });
-      await fetch(this.url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body
-      });
-    } catch {
-    }
-  }
-  async onMachineStart(context) {
-    await this.send("machine_start", { context });
-    return context;
-  }
-  async onMachineEnd(context, output) {
-    await this.send("machine_end", { context, output });
-    return output;
-  }
-  async onStateEnter(state, context) {
-    await this.send("state_enter", { state, context });
-    return context;
-  }
-  async onStateExit(state, context, output) {
-    await this.send("state_exit", { state, context, output });
-    return output;
-  }
-  async onAction(action, context) {
-    await this.send("action", { action, context });
-    return context;
-  }
-};
-var CompositeHooks = class {
-  constructor(hooks) {
-    this.hooks = hooks;
-  }
-  async onMachineStart(context) {
-    let result = context;
-    for (const hook of this.hooks) {
-      if (hook.onMachineStart) {
-        try {
-          result = await hook.onMachineStart(result);
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-  async onMachineEnd(context, output) {
-    let result = output;
-    for (const hook of this.hooks) {
-      if (hook.onMachineEnd) {
-        try {
-          result = await hook.onMachineEnd(context, result);
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-  async onStateEnter(state, context) {
-    let result = context;
-    for (const hook of this.hooks) {
-      if (hook.onStateEnter) {
-        try {
-          result = await hook.onStateEnter(state, result);
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-  async onStateExit(state, context, output) {
-    let result = output;
-    for (const hook of this.hooks) {
-      if (hook.onStateExit) {
-        try {
-          result = await hook.onStateExit(state, context, result);
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-  async onTransition(from, to, context) {
-    let result = to;
-    for (const hook of this.hooks) {
-      if (hook.onTransition) {
-        try {
-          result = await hook.onTransition(from, result, context);
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-  async onError(state, error, context) {
-    let result = null;
-    for (const hook of this.hooks) {
-      if (hook.onError) {
-        try {
-          const hookResult = await hook.onError(state, error, context);
-          if (hookResult !== null) result = hookResult;
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-  async onAction(action, context) {
-    let result = context;
-    for (const hook of this.hooks) {
-      if (hook.onAction) {
-        try {
-          result = await hook.onAction(action, result);
-        } catch {
-        }
-      }
-    }
-    return result;
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CheckpointManager,
@@ -1680,6 +1724,7 @@ var CompositeHooks = class {
   DefaultExecution,
   FlatAgent,
   FlatMachine,
+  HooksRegistry,
   LocalFileBackend,
   LocalFileLock,
   MCPToolProvider,