@memgrafter/flatagents 0.9.0 → 2.0.0

package/MACHINES.md

@@ -22,7 +22,7 @@
 ```yaml
 # profiles.yml — agents reference by name
 spec: flatprofiles
-spec_version: "0.9.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,66 @@ 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.
+
+**Core machines**
+- **Checker**: `get_pool_state` → `calculate_spawn` → `spawn_workers`
+- **Worker**: `register_worker` → `claim_job` → process → `complete_job`/`fail_job` → `deregister_worker`
+- **Reaper**: `list_stale_workers` → `reap_stale_workers`
+
+`spawn_workers` expects `worker_config_path` in context (or override hooks to resolve it). Custom queues can compose the base hooks and add actions.
+
+```yaml
+context:
+  worker_config_path: "./job_worker.yml"
+states:
+  check_state: { action: get_pool_state }
+  calculate_spawn: { action: calculate_spawn }
+  spawn_workers: { action: spawn_workers }
+```
+
+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)
@@ -101,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 };