@memgrafter/flatagents 0.9.0 → 2.0.0

package/schemas/flatagents-runtime.d.ts

@@ -15,10 +15,12 @@
  *   - MachineHooks: Base interface (MUST)
  *   - RegistrationBackend: SQLiteRegistrationBackend (MUST), MemoryRegistrationBackend (SHOULD)
  *   - WorkBackend: SQLiteWorkBackend (MUST), MemoryWorkBackend (SHOULD)
+ *   - SignalBackend: MemorySignalBackend (MUST), SQLiteSignalBackend (SHOULD)
+ *   - TriggerBackend: NoOpTrigger (MUST), FileTrigger (SHOULD)
  *
  * OPTIONAL IMPLEMENTATIONS:
  * -------------------------
- *   - Distributed backends (Redis, Postgres, etc.)
+ *   - Distributed backends (Redis, Postgres, DynamoDB, etc.)
  *   - LLMBackend (SDK may use native provider SDKs)
  *
  * EXECUTION LOCKING:
@@ -68,10 +70,30 @@
  * Extension points for machine execution.
  * All methods are optional and can be sync or async.
  *
+ * SDKs MUST provide:
+ *   - HooksRegistry: Name-based registry for resolving hooks from config
+ *
  * SDKs SHOULD provide:
  *   - WebhookHooks: Send events to HTTP endpoint
  *   - CompositeHooks: Combine multiple hook implementations
  *
+ * HOOKS REGISTRY:
+ * ---------------
+ * Maps hook names (strings) to implementations. Machine configs reference
+ * hooks by name; the SDK's HooksRegistry resolves them at runtime.
+ *
+ * This decouples machine configs from any specific language or file path,
+ * enabling the same YAML to work across Python, JavaScript, Rust, etc.
+ *
+ * SDKs MUST provide:
+ *   - HooksRegistry with register(), resolve(), has()
+ *
+ * Built-in registrations (when available in the SDK):
+ *   - "logging": LoggingHooks
+ *   - "webhook": WebhookHooks (args: { url, timeout?, api_key? })
+ *   - "metrics": MetricsHooks
+ *   - "distributed-worker": DistributedWorkerHooks
+ *
  * LLM BACKEND (OPTIONAL):
  * -----------------------
  * Abstraction over LLM providers.
@@ -87,6 +109,83 @@
  * Interface for invoking peer machines.
  * Used internally by FlatMachine for `machine:` and `launch:` states.
  *
+ * AGENT RESULT:
+ * --------------
+ * Universal result contract for agent execution across all backends.
+ * All fields are optional and use structured data (no classes) for
+ * cross-language and cross-process/network compatibility.
+ *
+ * REGISTRATION BACKEND:
+ * ---------------------
+ * Worker lifecycle management for distributed execution.
+ *
+ * SDKs MUST provide:
+ *   - SQLiteRegistrationBackend: For local deployments
+ *
+ * SDKs SHOULD provide:
+ *   - MemoryRegistrationBackend: For testing
+ *
+ * Implementation notes:
+ *   - Time units: Python reference SDK uses seconds for all interval values
+ *   - Stale threshold: SDKs SHOULD default to 2× heartbeat_interval if not specified
+ *
+ * WORK BACKEND:
+ * -------------
+ * Work distribution via named pools with atomic claim.
+ *
+ * SDKs MUST provide:
+ *   - SQLiteWorkBackend: For local deployments
+ *
+ * SDKs SHOULD provide:
+ *   - MemoryWorkBackend: For testing
+ *
+ * Implementation notes:
+ *   - Atomic claim: SDKs MUST ensure no two workers can claim the same job
+ *   - Test requirements: Include concurrent claim race condition tests
+ *
+ * SIGNAL BACKEND:
+ * ---------------
+ * Durable signal storage for cross-process machine activation.
+ *
+ * Signals are named-channel messages that wake checkpointed machines.
+ * A machine paused at a `wait_for` state checkpoints with a `waiting_channel`
+ * tag and exits (no process running). When a signal arrives on that channel,
+ * a dispatcher finds matching checkpoints and resumes them.
+ *
+ * Signal data becomes the `wait_for` state's output — accessible via
+ * output.* in output_to_context templates. No new template syntax needed.
+ *
+ * Channel semantics:
+ *   - Addressed: "approval/task-001" → one waiting machine
+ *   - Broadcast: "quota/openai"      → N waiting machines (dispatcher controls limit)
+ *
+ * SDKs MUST provide:
+ *   - MemorySignalBackend: For testing and single-process use
+ *
+ * SDKs SHOULD provide:
+ *   - SQLiteSignalBackend: For durable local use
+ *
+ * TRIGGER BACKEND:
+ * ----------------
+ * Process activation when signals or work arrive.
+ * The OS-native equivalent of Lambda triggers / DynamoDB Streams.
+ *
+ * Called after SignalBackend.send() or WorkPool.push() to wake
+ * a dispatcher process. The dispatcher then queries for matching
+ * checkpoints and resumes machines.
+ *
+ * Deployment mapping:
+ *   - NoOpTrigger:  Consumer already running (polling/in-process)
+ *   - FileTrigger:  Touch file → launchd WatchPaths (macOS) / systemd PathChanged (Linux)
+ *   - SocketTrigger: UDS notify → in-host low-latency wake (optional)
+ *   - DynamoDB:     Implicit via Streams → Lambda (no application code)
+ *
+ * SDKs MUST provide:
+ *   - NoOpTrigger: For in-process and polling consumers
+ *
+ * SDKs SHOULD provide:
+ *   - FileTrigger: For OS-level activation with zero running processes
+ *
  * BACKEND CONFIGURATION:
  * ----------------------
  * Backend configuration for machine settings.
@@ -146,6 +245,24 @@ export interface PersistenceBackend {
      * @returns Array of matching keys, sorted lexicographically
      */
     list(prefix: string): Promise<string[]>;
+
+    /**
+     * List execution IDs, optionally filtered by latest checkpoint state.
+     *
+     * @param options.event - Filter by latest checkpoint event (e.g., "machine_end")
+     * @param options.waiting_channel - Filter by waiting_channel metadata
+     * @returns Array of matching execution IDs
+     */
+    listExecutionIds?(options?: {
+        event?: string;
+        waiting_channel?: string;
+    }): Promise<string[]>;
+
+    /**
+     * Delete all checkpoint data for an execution.
+     * Safe to call if execution doesn't exist.
+     */
+    deleteExecution?(execution_id: string): Promise<void>;
 }
 
 export interface ResultBackend {
@@ -181,14 +298,126 @@ export interface ResultBackend {
     delete(uri: string): Promise<void>;
 }
 
+export interface AgentResult {
+    // Content
+    output?: Record<string, any> | null;
+    content?: string | null;
+    raw?: any;  // In-process only, not serialized across boundaries
+    
+    // Metrics
+    usage?: UsageInfo | null;
+    cost?: CostInfo | number | null;  // number for backwards compatibility
+    metadata?: Record<string, any> | null;
+    
+    // Completion status
+    /** Known values: "stop", "length", "tool_use", "error", "content_filter", "aborted" */
+    finish_reason?: string | null;
+    
+    // Error info (null/undefined = success)
+    error?: AgentError | null;
+    
+    // Rate limit state (normalized for orchestration)
+    rate_limit?: RateLimitState | null;
+    
+    // Provider-specific data (includes raw_headers when available)
+    provider_data?: ProviderData | null;
+}
+
+export interface UsageInfo {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
+}
+
+export interface CostInfo {
+    input?: number;
+    output?: number;
+    cache_read?: number;
+    cache_write?: number;
+    total?: number;
+}
+
+export interface AgentError {
+    /** 
+     * Known values: "rate_limit", "timeout", "server_error", "invalid_request",
+     * "auth_error", "content_filter", "context_length", "model_unavailable"
+     * Custom codes allowed for extension.
+     */
+    code?: string;
+    
+    /** Original error type name (e.g., "RateLimitError", "TimeoutError") */
+    type?: string;
+    
+    /** Human-readable error message */
+    message: string;
+    
+    /** HTTP status code if applicable */
+    status_code?: number;
+    
+    /** Whether retry might succeed */
+    retryable?: boolean;
+}
+
+export interface RateLimitState {
+    /** Is any limit exhausted? */
+    limited: boolean;
+    
+    /** Recommended wait time in seconds */
+    retry_after?: number;
+    
+    /** Per-window breakdown for smart orchestration */
+    windows?: RateLimitWindow[];
+}
+
+export interface RateLimitWindow {
+    /** Identifier: "requests_per_minute", "tokens_per_day", etc. */
+    name: string;
+    
+    /** Known values: "requests", "tokens", "input_tokens", "output_tokens" */
+    resource: string;
+    
+    /** Current remaining in this window */
+    remaining?: number;
+    
+    /** Maximum for this window */
+    limit?: number;
+    
+    /** Seconds until this window resets */
+    resets_in?: number;
+    
+    /** Unix timestamp when this window resets */
+    reset_at?: number;
+}
+
+export interface ProviderData {
+    /** Provider name (e.g., "openai", "anthropic", "cerebras") */
+    provider?: string;
+    
+    /** Model identifier */
+    model?: string;
+    
+    /** Provider's request ID for debugging/support */
+    request_id?: string;
+    
+    /** Raw HTTP headers from response (when backend exposes them) */
+    raw_headers?: Record<string, string>;
+    
+    /** Any other provider-specific data */
+    [key: string]: any;
+}
+
+export interface AgentExecutor {
+    execute(input: Record<string, any>, context?: Record<string, any>): Promise<AgentResult>;
+    metadata?: Record<string, any>;
+}
+
 export interface ExecutionType {
     /**
-     * Execute a function with this strategy.
-     *
-     * @param fn - The async function to execute (typically agent.call)
-     * @returns The result(s) according to strategy
+     * Execute an agent with this strategy.
      */
-    execute<T>(fn: () => Promise<T>): Promise<T>;
+    execute(executor: AgentExecutor, input: Record<string, any>, context?: Record<string, any>): Promise<AgentResult>;
 }
 
 export interface ExecutionConfig {
@@ -227,6 +456,37 @@ export interface MachineHooks {
     onAction?(action: string, context: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
 }
 
+export interface HooksRegistry {
+    /**
+     * Register a hooks implementation by name.
+     * @param name - Hook name referenced in machine config (e.g., "my-hooks")
+     * @param factory - Class constructor or factory function
+     */
+    register(name: string, factory: HooksFactory): void;
+
+    /**
+     * Resolve a HooksRef from machine config into a MachineHooks instance.
+     * - String: lookup by name, no args
+     * - HooksRefConfig: lookup by name, pass args to factory
+     * - Array: resolve each entry, combine with CompositeHooks
+     * @throws Error if name is not registered
+     */
+    resolve(ref: HooksRef): MachineHooks;
+
+    /** Check if a name is registered. */
+    has(name: string): boolean;
+}
+
+/**
+ * Factory for creating MachineHooks instances.
+ * Can be a class constructor or a function.
+ */
+export type HooksFactory =
+    | { new (args?: Record<string, any>): MachineHooks }
+    | ((args?: Record<string, any>) => MachineHooks);
+
+import { HooksRef, HooksRefConfig } from "./flatmachine";
+
 export interface LLMBackend {
     /** Total cost accumulated across all calls. */
     totalCost: number;
@@ -307,6 +567,7 @@ export interface MachineSnapshot {
     total_cost?: number;
     parent_execution_id?: string;
     pending_launches?: LaunchIntent[];
+    waiting_channel?: string;
 }
 
 export interface LaunchIntent {
@@ -316,21 +577,6 @@ export interface LaunchIntent {
     launched: boolean;
 }
 
-/**
- * REGISTRATION BACKEND:
- * ---------------------
- * Worker lifecycle management for distributed execution.
- *
- * SDKs MUST provide:
- *   - SQLiteRegistrationBackend: For local deployments
- *
- * SDKs SHOULD provide:
- *   - MemoryRegistrationBackend: For testing
- *
- * Implementation notes:
- *   - Time units: Python reference SDK uses seconds for all interval values
- *   - Stale threshold: SDKs SHOULD default to 2× heartbeat_interval if not specified
- */
 export interface RegistrationBackend {
     /**
      * Register a new worker.
@@ -388,21 +634,6 @@ export interface WorkerFilter {
     stale_threshold_seconds?: number;  // Filter workers with old heartbeats
 }
 
-/**
- * WORK BACKEND:
- * -------------
- * Work distribution via named pools with atomic claim.
- *
- * SDKs MUST provide:
- *   - SQLiteWorkBackend: For local deployments
- *
- * SDKs SHOULD provide:
- *   - MemoryWorkBackend: For testing
- *
- * Implementation notes:
- *   - Atomic claim: SDKs MUST ensure no two workers can claim the same job
- *   - Test requirements: Include concurrent claim race condition tests
- */
 export interface WorkBackend {
     /**
      * Get a named work pool.
@@ -468,32 +699,89 @@ export interface WorkItem {
 // - "done": Successfully completed
 // - "poisoned": Failed max_retries times, will not be retried
 
+export interface SignalBackend {
+    /**
+     * Send a signal to a named channel.
+     * @param channel - Channel name (e.g., "approval/task-001", "quota/openai")
+     * @param data - Signal payload (JSON-serializable)
+     * @returns Signal ID
+     */
+    send(channel: string, data: any): Promise<string>;
+
+    /**
+     * Atomically consume the next signal on a channel.
+     * Removes the signal from storage.
+     * @returns Signal or null if none pending
+     */
+    consume(channel: string): Promise<Signal | null>;
+
+    /**
+     * Peek at pending signals without consuming.
+     * @returns Array of pending signals on this channel
+     */
+    peek(channel: string): Promise<Signal[]>;
+
+    /**
+     * List channels that have pending signals.
+     * Used by dispatcher to find actionable channels.
+     */
+    channels(): Promise<string[]>;
+}
+
+export interface Signal {
+    id: string;
+    channel: string;
+    data: any;
+    created_at: string;
+}
+
+export interface TriggerBackend {
+    /**
+     * Signal that activity occurred on a channel.
+     * Implementation touches a file, writes to a socket, or no-ops.
+     *
+     * @param channel - Channel name
+     */
+    notify(channel: string): Promise<void>;
+}
+
 export interface BackendConfig {
     /** Checkpoint storage. Default: memory */
-    persistence?: "memory" | "local" | "redis" | "postgres" | "s3";
+    persistence?: "memory" | "local" | "sqlite" | "redis" | "postgres" | "s3" | "dynamodb";
 
     /** Execution locking. Default: none */
-    locking?: "none" | "local" | "redis" | "consul";
+    locking?: "none" | "local" | "sqlite" | "redis" | "consul" | "dynamodb";
 
     /** Inter-machine results. Default: memory */
-    results?: "memory" | "redis";
+    results?: "memory" | "redis" | "dynamodb";
 
     /** Worker registration. Default: memory */
-    registration?: "memory" | "sqlite" | "redis";
+    registration?: "memory" | "sqlite" | "redis" | "dynamodb";
 
     /** Work pool. Default: memory */
-    work?: "memory" | "sqlite" | "redis";
+    work?: "memory" | "sqlite" | "redis" | "dynamodb";
+
+    /** Signal storage. Default: memory */
+    signal?: "memory" | "sqlite" | "redis" | "dynamodb";
 
-    /** Path for sqlite backends (registration and work share this) */
+    /** Trigger activation. Default: none */
+    trigger?: "none" | "file" | "socket";
+
+    /** Path for sqlite backends (registration, work, and signals share this) */
     sqlite_path?: string;
+
+    /** Base path for file triggers (default: /tmp/flatmachines) */
+    trigger_path?: string;
+
+    /** DynamoDB table name (single-table design) */
+    dynamodb_table?: string;
+
+    /** AWS region for DynamoDB */
+    aws_region?: string;
 }
 
-export const SPEC_VERSION = "0.9.0";
+export const SPEC_VERSION = "2.0.0";
 
-/**
- * Wrapper interface for JSON schema generation.
- * Groups all runtime interfaces that SDKs must implement.
- */
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";
     spec_version: typeof SPEC_VERSION;
@@ -502,11 +790,14 @@ export interface SDKRuntimeWrapper {
     result_backend?: ResultBackend;
     execution_config?: ExecutionConfig;
     machine_hooks?: MachineHooks;
+    hooks_registry?: HooksRegistry;
     llm_backend?: LLMBackend;
     machine_invoker?: MachineInvoker;
     backend_config?: BackendConfig;
     machine_snapshot?: MachineSnapshot;
     registration_backend?: RegistrationBackend;
     work_backend?: WorkBackend;
+    signal_backend?: SignalBackend;
+    trigger_backend?: TriggerBackend;
 }
 

package/schemas/flatagents-runtime.schema.json

@@ -11,7 +11,7 @@
         },
         "spec_version": {
           "type": "string",
-          "const": "0.9.0"
+          "const": "2.0.0"
         },
         "execution_lock": {
           "$ref": "#/definitions/ExecutionLock"
@@ -28,6 +28,9 @@
         "machine_hooks": {
           "$ref": "#/definitions/MachineHooks"
         },
+        "hooks_registry": {
+          "$ref": "#/definitions/HooksRegistry"
+        },
         "llm_backend": {
           "$ref": "#/definitions/LLMBackend"
         },
@@ -45,19 +48,24 @@
         },
         "work_backend": {
           "$ref": "#/definitions/WorkBackend"
+        },
+        "signal_backend": {
+          "$ref": "#/definitions/SignalBackend"
+        },
+        "trigger_backend": {
+          "$ref": "#/definitions/TriggerBackend"
         }
       },
       "required": [
         "spec",
         "spec_version"
       ],
-      "additionalProperties": false,
-      "description": "Wrapper interface for JSON schema generation. Groups all runtime interfaces that SDKs must implement."
+      "additionalProperties": false
     },
     "ExecutionLock": {
       "type": "object",
       "additionalProperties": false,
-      "description": "FlatAgents Runtime Interface Spec ==================================\n\nThis file defines the runtime interfaces that SDKs MUST implement to be considered compliant. These are NOT configuration schemas (see flatagent.d.ts and flatmachine.d.ts for those).\n\nREQUIRED IMPLEMENTATIONS:\n-------------------------   - ExecutionLock: NoOpLock (MUST), LocalFileLock (SHOULD)   - PersistenceBackend: MemoryBackend (MUST), LocalFileBackend (SHOULD)   - ResultBackend: InMemoryResultBackend (MUST)   - ExecutionType: Default, Retry, Parallel, MDAPVoting (MUST)   - MachineHooks: Base interface (MUST)   - RegistrationBackend: SQLiteRegistrationBackend (MUST), MemoryRegistrationBackend (SHOULD)   - WorkBackend: SQLiteWorkBackend (MUST), MemoryWorkBackend (SHOULD)\n\nOPTIONAL IMPLEMENTATIONS:\n-------------------------   - Distributed backends (Redis, Postgres, etc.)   - LLMBackend (SDK may use native provider SDKs)\n\nEXECUTION LOCKING:\n------------------ Prevents concurrent execution of the same machine instance.\n\nSDKs MUST provide:   - NoOpLock: For when locking is handled externally or disabled\n\nSDKs SHOULD provide:   - LocalFileLock: For single-node deployments using fcntl/flock\n\nDistributed deployments should implement Redis/Consul/etcd locks.\n\nPERSISTENCE BACKEND:\n-------------------- Storage backend for machine checkpoints.\n\nSDKs MUST provide:   - MemoryBackend: For testing and ephemeral runs\n\nSDKs SHOULD provide:   - LocalFileBackend: For durable local storage with atomic writes\n\nRESULT BACKEND:\n--------------- Inter-machine communication via URI-addressed results.\n\nURI format: flatagents://{execution_id}/{path}   - path is typically \"result\" or \"checkpoint\"\n\nSDKs MUST provide:   - InMemoryResultBackend: For single-process execution\n\nEXECUTION TYPES:\n---------------- Execution strategy for agent calls.\n\nSDKs MUST implement all four types:   - default: Single call, no retry   - retry: Configurable backoffs with jitter   - parallel: Run N samples, return all successes   - mdap_voting: Multi-sample with consensus voting\n\nMACHINE HOOKS:\n-------------- Extension points for machine execution. All methods are optional and can be sync or async.\n\nSDKs SHOULD provide:   - WebhookHooks: Send events to HTTP endpoint   - CompositeHooks: Combine multiple hook implementations\n\nLLM BACKEND (OPTIONAL):\n----------------------- Abstraction over LLM providers.\n\nThis interface is OPTIONAL - SDKs may use provider SDKs directly. Useful for:   - Unified retry/monitoring across providers   - Provider-agnostic code   - Testing with mock backends\n\nMACHINE INVOKER:\n---------------- Interface for invoking peer machines. Used internally by FlatMachine for `machine:` and `launch:` states.\n\nBACKEND CONFIGURATION:\n---------------------- Backend configuration for machine settings.\n\nExample in YAML:   settings:     backends:       persistence: local       locking: none       results: memory"
+      "description": "FlatAgents Runtime Interface Spec ==================================\n\nThis file defines the runtime interfaces that SDKs MUST implement to be considered compliant. These are NOT configuration schemas (see flatagent.d.ts and flatmachine.d.ts for those).\n\nREQUIRED IMPLEMENTATIONS:\n-------------------------   - ExecutionLock: NoOpLock (MUST), LocalFileLock (SHOULD)   - PersistenceBackend: MemoryBackend (MUST), LocalFileBackend (SHOULD)   - ResultBackend: InMemoryResultBackend (MUST)   - ExecutionType: Default, Retry, Parallel, MDAPVoting (MUST)   - MachineHooks: Base interface (MUST)   - RegistrationBackend: SQLiteRegistrationBackend (MUST), MemoryRegistrationBackend (SHOULD)   - WorkBackend: SQLiteWorkBackend (MUST), MemoryWorkBackend (SHOULD)   - SignalBackend: MemorySignalBackend (MUST), SQLiteSignalBackend (SHOULD)   - TriggerBackend: NoOpTrigger (MUST), FileTrigger (SHOULD)\n\nOPTIONAL IMPLEMENTATIONS:\n-------------------------   - Distributed backends (Redis, Postgres, DynamoDB, etc.)   - LLMBackend (SDK may use native provider SDKs)\n\nEXECUTION LOCKING:\n------------------ Prevents concurrent execution of the same machine instance.\n\nSDKs MUST provide:   - NoOpLock: For when locking is handled externally or disabled\n\nSDKs SHOULD provide:   - LocalFileLock: For single-node deployments using fcntl/flock\n\nDistributed deployments should implement Redis/Consul/etcd locks.\n\nPERSISTENCE BACKEND:\n-------------------- Storage backend for machine checkpoints.\n\nSDKs MUST provide:   - MemoryBackend: For testing and ephemeral runs\n\nSDKs SHOULD provide:   - LocalFileBackend: For durable local storage with atomic writes\n\nRESULT BACKEND:\n--------------- Inter-machine communication via URI-addressed results.\n\nURI format: flatagents://{execution_id}/{path}   - path is typically \"result\" or \"checkpoint\"\n\nSDKs MUST provide:   - InMemoryResultBackend: For single-process execution\n\nEXECUTION TYPES:\n---------------- Execution strategy for agent calls.\n\nSDKs MUST implement all four types:   - default: Single call, no retry   - retry: Configurable backoffs with jitter   - parallel: Run N samples, return all successes   - mdap_voting: Multi-sample with consensus voting\n\nMACHINE HOOKS:\n-------------- Extension points for machine execution. All methods are optional and can be sync or async.\n\nSDKs MUST provide:   - HooksRegistry: Name-based registry for resolving hooks from config\n\nSDKs SHOULD provide:   - WebhookHooks: Send events to HTTP endpoint   - CompositeHooks: Combine multiple hook implementations\n\nHOOKS REGISTRY:\n--------------- Maps hook names (strings) to implementations. Machine configs reference hooks by name; the SDK's HooksRegistry resolves them at runtime.\n\nThis decouples machine configs from any specific language or file path, enabling the same YAML to work across Python, JavaScript, Rust, etc.\n\nSDKs MUST provide:   - HooksRegistry with register(), resolve(), has()\n\nBuilt-in registrations (when available in the SDK):   - \"logging\": LoggingHooks   - \"webhook\": WebhookHooks (args: { url, timeout?, api_key? })   - \"metrics\": MetricsHooks   - \"distributed-worker\": DistributedWorkerHooks\n\nLLM BACKEND (OPTIONAL):\n----------------------- Abstraction over LLM providers.\n\nThis interface is OPTIONAL - SDKs may use provider SDKs directly. Useful for:   - Unified retry/monitoring across providers   - Provider-agnostic code   - Testing with mock backends\n\nMACHINE INVOKER:\n---------------- Interface for invoking peer machines. Used internally by FlatMachine for `machine:` and `launch:` states.\n\nAGENT RESULT:\n-------------- Universal result contract for agent execution across all backends. All fields are optional and use structured data (no classes) for cross-language and cross-process/network compatibility.\n\nREGISTRATION BACKEND:\n--------------------- Worker lifecycle management for distributed execution.\n\nSDKs MUST provide:   - SQLiteRegistrationBackend: For local deployments\n\nSDKs SHOULD provide:   - MemoryRegistrationBackend: For testing\n\nImplementation notes:   - Time units: Python reference SDK uses seconds for all interval values   - Stale threshold: SDKs SHOULD default to 2× heartbeat_interval if not specified\n\nWORK BACKEND:\n------------- Work distribution via named pools with atomic claim.\n\nSDKs MUST provide:   - SQLiteWorkBackend: For local deployments\n\nSDKs SHOULD provide:   - MemoryWorkBackend: For testing\n\nImplementation notes:   - Atomic claim: SDKs MUST ensure no two workers can claim the same job   - Test requirements: Include concurrent claim race condition tests\n\nSIGNAL BACKEND:\n--------------- Durable signal storage for cross-process machine activation.\n\nSignals are named-channel messages that wake checkpointed machines. A machine paused at a `wait_for` state checkpoints with a `waiting_channel` tag and exits (no process running). When a signal arrives on that channel, a dispatcher finds matching checkpoints and resumes them.\n\nSignal data becomes the `wait_for` state's output — accessible via output.* in output_to_context templates. No new template syntax needed.\n\nChannel semantics:   - Addressed: \"approval/task-001\" → one waiting machine   - Broadcast: \"quota/openai\"      → N waiting machines (dispatcher controls limit)\n\nSDKs MUST provide:   - MemorySignalBackend: For testing and single-process use\n\nSDKs SHOULD provide:   - SQLiteSignalBackend: For durable local use\n\nTRIGGER BACKEND:\n---------------- Process activation when signals or work arrive. The OS-native equivalent of Lambda triggers / DynamoDB Streams.\n\nCalled after SignalBackend.send() or WorkPool.push() to wake a dispatcher process. The dispatcher then queries for matching checkpoints and resumes machines.\n\nDeployment mapping:   - NoOpTrigger:  Consumer already running (polling/in-process)   - FileTrigger:  Touch file → launchd WatchPaths (macOS) / systemd PathChanged (Linux)   - SocketTrigger: UDS notify → in-host low-latency wake (optional)   - DynamoDB:     Implicit via Streams → Lambda (no application code)\n\nSDKs MUST provide:   - NoOpTrigger: For in-process and polling consumers\n\nSDKs SHOULD provide:   - FileTrigger: For OS-level activation with zero running processes\n\nBACKEND CONFIGURATION:\n---------------------- Backend configuration for machine settings.\n\nExample in YAML:   settings:     backends:       persistence: local       locking: none       results: memory"
     },
     "PersistenceBackend": {
       "type": "object",
@@ -107,6 +115,10 @@
       "type": "object",
       "additionalProperties": false
     },
+    "HooksRegistry": {
+      "type": "object",
+      "additionalProperties": false
+    },
     "LLMBackend": {
       "type": "object",
       "properties": {
@@ -137,9 +149,11 @@
           "enum": [
             "memory",
             "local",
+            "sqlite",
             "redis",
             "postgres",
-            "s3"
+            "s3",
+            "dynamodb"
           ],
           "description": "Checkpoint storage. Default: memory"
         },
@@ -148,8 +162,10 @@
           "enum": [
             "none",
             "local",
+            "sqlite",
             "redis",
-            "consul"
+            "consul",
+            "dynamodb"
           ],
           "description": "Execution locking. Default: none"
         },
@@ -157,7 +173,8 @@
           "type": "string",
           "enum": [
             "memory",
-            "redis"
+            "redis",
+            "dynamodb"
           ],
           "description": "Inter-machine results. Default: memory"
         },
@@ -166,7 +183,8 @@
           "enum": [
             "memory",
             "sqlite",
-            "redis"
+            "redis",
+            "dynamodb"
           ],
           "description": "Worker registration. Default: memory"
         },
@@ -175,13 +193,45 @@
           "enum": [
             "memory",
             "sqlite",
-            "redis"
+            "redis",
+            "dynamodb"
           ],
           "description": "Work pool. Default: memory"
         },
+        "signal": {
+          "type": "string",
+          "enum": [
+            "memory",
+            "sqlite",
+            "redis",
+            "dynamodb"
+          ],
+          "description": "Signal storage. Default: memory"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": [
+            "none",
+            "file",
+            "socket"
+          ],
+          "description": "Trigger activation. Default: none"
+        },
         "sqlite_path": {
           "type": "string",
-          "description": "Path for sqlite backends (registration and work share this)"
+          "description": "Path for sqlite backends (registration, work, and signals share this)"
+        },
+        "trigger_path": {
+          "type": "string",
+          "description": "Base path for file triggers (default: /tmp/flatmachines)"
+        },
+        "dynamodb_table": {
+          "type": "string",
+          "description": "DynamoDB table name (single-table design)"
+        },
+        "aws_region": {
+          "type": "string",
+          "description": "AWS region for DynamoDB"
         }
       },
       "additionalProperties": false
@@ -230,6 +280,9 @@
           "items": {
             "$ref": "#/definitions/LaunchIntent"
           }
+        },
+        "waiting_channel": {
+          "type": "string"
         }
       },
       "required": [
@@ -269,13 +322,19 @@
     },
     "RegistrationBackend": {
       "type": "object",
-      "additionalProperties": false,
-      "description": "REGISTRATION BACKEND:\n--------------------- Worker lifecycle management for distributed execution.\n\nSDKs MUST provide:   - SQLiteRegistrationBackend: For local deployments\n\nSDKs SHOULD provide:   - MemoryRegistrationBackend: For testing\n\nImplementation notes:   - Time units: Python reference SDK uses seconds for all interval values   - Stale threshold: SDKs SHOULD default to 2× heartbeat_interval if not specified"
+      "additionalProperties": false
     },
     "WorkBackend": {
       "type": "object",
-      "additionalProperties": false,
-      "description": "WORK BACKEND:\n------------- Work distribution via named pools with atomic claim.\n\nSDKs MUST provide:   - SQLiteWorkBackend: For local deployments\n\nSDKs SHOULD provide:   - MemoryWorkBackend: For testing\n\nImplementation notes:   - Atomic claim: SDKs MUST ensure no two workers can claim the same job   - Test requirements: Include concurrent claim race condition tests"
+      "additionalProperties": false
+    },
+    "SignalBackend": {
+      "type": "object",
+      "additionalProperties": false
+    },
+    "TriggerBackend": {
+      "type": "object",
+      "additionalProperties": false
     }
   }
 }