@memgrafter/flatagents 0.10.0 → 2.0.0

package/schemas/flatagents-runtime.slim.d.ts

@@ -7,6 +7,11 @@ export interface PersistenceBackend {
     load(key: string): Promise<MachineSnapshot | null>;
     delete(key: string): Promise<void>;
     list(prefix: string): Promise<string[]>;
+    listExecutionIds?(options?: {
+        event?: string;
+        waiting_channel?: string;
+    }): Promise<string[]>;
+    deleteExecution?(execution_id: string): Promise<void>;
 }
 export interface ResultBackend {
     write(uri: string, data: any): Promise<void>;
@@ -17,8 +22,65 @@ export interface ResultBackend {
     exists(uri: string): Promise<boolean>;
     delete(uri: string): Promise<void>;
 }
+export interface AgentResult {
+    output?: Record<string, any> | null;
+    content?: string | null;
+    raw?: any;
+    usage?: UsageInfo | null;
+    cost?: CostInfo | number | null;
+    metadata?: Record<string, any> | null;
+    finish_reason?: string | null;
+    error?: AgentError | null;
+    rate_limit?: RateLimitState | null;
+    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 {
+    code?: string;
+    type?: string;
+    message: string;
+    status_code?: number;
+    retryable?: boolean;
+}
+export interface RateLimitState {
+    limited: boolean;
+    retry_after?: number;
+    windows?: RateLimitWindow[];
+}
+export interface RateLimitWindow {
+    name: string;
+    resource: string;
+    remaining?: number;
+    limit?: number;
+    resets_in?: number;
+    reset_at?: number;
+}
+export interface ProviderData {
+    provider?: string;
+    model?: string;
+    request_id?: string;
+    raw_headers?: Record<string, string>;
+    [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<T>(fn: () => Promise<T>): Promise<T>;
+    execute(executor: AgentExecutor, input: Record<string, any>, context?: Record<string, any>): Promise<AgentResult>;
 }
 export interface ExecutionConfig {
     type: "default" | "retry" | "parallel" | "mdap_voting";
@@ -37,6 +99,15 @@ export interface MachineHooks {
     onError?(state: string, error: Error, context: Record<string, any>): string | null | Promise<string | null>;
     onAction?(action: string, context: Record<string, any>): Record<string, any> | Promise<Record<string, any>>;
 }
+export interface HooksRegistry {
+    register(name: string, factory: HooksFactory): void;
+    resolve(ref: HooksRef): MachineHooks;
+    has(name: string): boolean;
+}
+export type HooksFactory = {
+    new (args?: Record<string, any>): MachineHooks;
+} | ((args?: Record<string, any>) => MachineHooks);
+import { HooksRef, HooksRefConfig } from "./flatmachine";
 export interface LLMBackend {
     totalCost: number;
     totalApiCalls: number;
@@ -95,6 +166,7 @@ export interface MachineSnapshot {
     total_cost?: number;
     parent_execution_id?: string;
     pending_launches?: LaunchIntent[];
+    waiting_channel?: string;
 }
 export interface LaunchIntent {
     execution_id: string;
@@ -149,15 +221,35 @@ export interface WorkItem {
     attempts: number;
     max_retries: number;
 }
+export interface SignalBackend {
+    send(channel: string, data: any): Promise<string>;
+    consume(channel: string): Promise<Signal | null>;
+    peek(channel: string): Promise<Signal[]>;
+    channels(): Promise<string[]>;
+}
+export interface Signal {
+    id: string;
+    channel: string;
+    data: any;
+    created_at: string;
+}
+export interface TriggerBackend {
+    notify(channel: string): Promise<void>;
+}
 export interface BackendConfig {
-    persistence?: "memory" | "local" | "redis" | "postgres" | "s3";
-    locking?: "none" | "local" | "redis" | "consul";
-    results?: "memory" | "redis";
-    registration?: "memory" | "sqlite" | "redis";
-    work?: "memory" | "sqlite" | "redis";
+    persistence?: "memory" | "local" | "sqlite" | "redis" | "postgres" | "s3" | "dynamodb";
+    locking?: "none" | "local" | "sqlite" | "redis" | "consul" | "dynamodb";
+    results?: "memory" | "redis" | "dynamodb";
+    registration?: "memory" | "sqlite" | "redis" | "dynamodb";
+    work?: "memory" | "sqlite" | "redis" | "dynamodb";
+    signal?: "memory" | "sqlite" | "redis" | "dynamodb";
+    trigger?: "none" | "file" | "socket";
     sqlite_path?: string;
+    trigger_path?: string;
+    dynamodb_table?: string;
+    aws_region?: string;
 }
-export const SPEC_VERSION = "0.10.0";
+export const SPEC_VERSION = "2.0.0";
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";
     spec_version: typeof SPEC_VERSION;
@@ -166,10 +258,13 @@ 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/flatmachine.d.ts

@@ -26,7 +26,7 @@
  * name               - Machine identifier
  * expression_engine  - "simple" (default) or "cel"
  * context            - Initial context values (Jinja2 templates)
- * agents             - Map of agent name to config file path or inline config
+ * agents             - Map of agent name to AgentRef (path, inline config, or typed adapter ref)
  * machines           - Map of machine name to config file path or inline config
  * states             - Map of state name to state definition
  * settings           - Optional settings (hooks, etc.)
@@ -39,6 +39,7 @@
  * execution         - Execution type config: {type: "retry", backoffs: [...], jitter: 0.1}
  * on_error          - Error handling: "error_state" or {default: "...", ErrorType: "..."}
  * action            - Hook action to execute
+ * wait_for          - Channel to wait for external signal (Jinja2 template)
  * input             - Input mapping (Jinja2 templates)
  * output_to_context - Map agent output to context (Jinja2 templates)
  * output            - Final output (for final states)
@@ -55,6 +56,10 @@
  * launch            - Machine(s) to start fire-and-forget
  * launch_input      - Input for launched machines
  *
+ * EXTERNAL SIGNALS (v1.2.0):
+ * --------------------------
+ * wait_for          - Channel name (Jinja2 template) to wait for external signal
+ *
  * NOTE: Only `machine` supports parallel invocation (string[]), not `agent`.
  * Machines are self-healing with checkpoint/resume and error handling.
  * Agents are raw LLM calls that can fail without recovery. Wrap agents in
@@ -203,6 +208,35 @@
  *       transitions:
  *         - to: continue_immediately
  *
+ * WAIT_FOR (EXTERNAL SIGNAL) EXAMPLE:
+ * ------------------------------------
+ * Machine checkpoints and exits. Nothing running. Dispatcher resumes
+ * the machine when a signal arrives on the named channel.
+ * Signal data is available as output.* in output_to_context templates.
+ *
+ *   states:
+ *     wait_for_approval:
+ *       wait_for: "approval/{{ context.task_id }}"
+ *       timeout: 86400
+ *       output_to_context:
+ *         approved: "{{ output.approved }}"
+ *         reviewer: "{{ output.reviewer }}"
+ *       transitions:
+ *         - condition: "context.approved"
+ *           to: continue_work
+ *         - to: rejected
+ *
+ * QUOTA-GATED EXAMPLE:
+ * --------------------
+ *
+ *   states:
+ *     wait_for_quota:
+ *       wait_for: "quota/openai"
+ *       output_to_context:
+ *         quota_token: "{{ output }}"
+ *       transitions:
+ *         - to: call_api
+ *
  * PERSISTENCE (v0.2.0):
  * --------------------
  * MachineSnapshot    - Wire format for checkpoints (execution_id, state, context, step)
@@ -249,14 +283,40 @@
  * Launch intent for outbox pattern.
  * Recorded in checkpoint before launching to ensure exactly-once semantics.
  *
+ * HOOKS CONFIG:
+ * -------------
+ * Hooks are referenced by name and resolved via a runtime HooksRegistry.
+ * This keeps machine configs language-agnostic — the same YAML works with
+ * Python, JavaScript, Rust, or any other SDK.
+ *
+ * String shorthand:
+ *   hooks: "my-hooks"
+ *
+ * With constructor args:
+ *   hooks:
+ *     name: "my-hooks"
+ *     args:
+ *       working_dir: "."
+ *
+ * Composite (multiple hooks):
+ *   hooks:
+ *     - "logging"
+ *     - name: "my-hooks"
+ *       args: { working_dir: "." }
+ *
+ * The SDK's HooksRegistry maps names to implementations.
+ * Built-in hooks (e.g., "logging", "webhook") are pre-registered.
+ * Custom hooks are registered by the runner before machine execution.
+ *
  * MACHINE SNAPSHOT:
  * -----------------
  * Wire format for checkpoints.
  * parent_execution_id - Lineage tracking (v0.4.0)
  * pending_launches    - Outbox pattern (v0.4.0)
+ * waiting_channel     - Signal channel this machine is blocked on (v1.2.0)
  */
 
-export const SPEC_VERSION = "0.10.0";
+export const SPEC_VERSION = "2.0.0";
 
 export interface MachineWrapper {
   spec: "flatmachine";
@@ -269,41 +329,26 @@ export interface MachineData {
   name?: string;
   expression_engine?: "simple" | "cel";
   context?: Record<string, any>;
-  agents?: Record<string, string | AgentWrapper>;
+  agents?: Record<string, AgentRef>;
   machines?: Record<string, string | MachineWrapper>;
   states: Record<string, StateDefinition>;
   settings?: MachineSettings;
   persistence?: PersistenceConfig;
-  hooks?: HooksConfig;
+  hooks?: HooksRef;
 }
 
-/**
- * Configuration for loading hooks from file or module.
- *
- * File-based (preferred for self-contained skills):
- *   hooks:
- *     file: "./hooks.py"
- *     class: "MyHooks"
- *     args:
- *       working_dir: "."
- *
- * Module-based (for installed packages):
- *   hooks:
- *     module: "mypackage.hooks"
- *     class: "MyHooks"
- *     args:
- *       api_key: "{{ input.api_key }}"
- *
- * Fields:
- *   file   - Path to Python file containing hooks class (relative to machine.yml)
- *   module - Python module path to import
- *   class  - Class name to instantiate (required)
- *   args   - Arguments to pass to hooks constructor
- */
-export interface HooksConfig {
-  file?: string;
-  module?: string;
-  class: string;
+export interface AgentRefConfig {
+  type: string;
+  ref?: string;
+  config?: Record<string, any>;
+}
+
+export type AgentRef = string | AgentWrapper | AgentRefConfig;
+
+export type HooksRef = string | HooksRefConfig | Array<string | HooksRefConfig>;
+
+export interface HooksRefConfig {
+  name: string;
   args?: Record<string, any>;
 }
 
@@ -320,11 +365,12 @@ export interface StateDefinition {
   action?: string;
   execution?: ExecutionConfig;
   on_error?: string | Record<string, string>;
+  wait_for?: string;
   input?: Record<string, any>;
   output_to_context?: Record<string, any>;
   output?: Record<string, any>;
   transitions?: Transition[];
-  tool_loop?: boolean;
+  tool_loop?: boolean | ToolLoopStateConfig;
   sampling?: "single" | "multi";
   foreach?: string;
   as?: string;
@@ -335,6 +381,16 @@ export interface StateDefinition {
   launch_input?: Record<string, any>;
 }
 
+export interface ToolLoopStateConfig {
+  max_tool_calls?: number;     // Total tool calls before forced stop. Default: 50
+  max_turns?: number;          // LLM call rounds before forced stop. Default: 20
+  allowed_tools?: string[];    // Whitelist (if set, only these execute)
+  denied_tools?: string[];     // Blacklist (takes precedence over allowed)
+  tool_timeout?: number;       // Per-tool execution timeout in seconds. Default: 30
+  total_timeout?: number;      // Total loop timeout in seconds. Default: 600
+  max_cost?: number;           // Cost limit in dollars
+}
+
 export interface MachineInput {
   name: string;
   input?: Record<string, any>;
@@ -380,6 +436,13 @@ export interface MachineSnapshot {
   total_cost?: number;
   parent_execution_id?: string;
   pending_launches?: LaunchIntent[];
+  waiting_channel?: string;
+  tool_loop_state?: {
+    chain: Array<Record<string, any>>;
+    turns: number;
+    tool_calls_count: number;
+    loop_cost: number;
+  };
 }
 
 export interface PersistenceConfig {

package/schemas/flatmachine.schema.json

@@ -45,14 +45,7 @@
         "agents": {
           "type": "object",
           "additionalProperties": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "$ref": "#/definitions/AgentWrapper"
-              }
-            ]
+            "$ref": "#/definitions/AgentRef"
           }
         },
         "machines": {
@@ -81,7 +74,7 @@
           "$ref": "#/definitions/PersistenceConfig"
         },
         "hooks": {
-          "$ref": "#/definitions/HooksConfig"
+          "$ref": "#/definitions/HooksRef"
         }
       },
       "required": [
@@ -89,6 +82,19 @@
       ],
       "additionalProperties": false
     },
+    "AgentRef": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "$ref": "#/definitions/AgentWrapper"
+        },
+        {
+          "$ref": "#/definitions/AgentRefConfig"
+        }
+      ]
+    },
     "AgentWrapper": {
       "type": "object",
       "properties": {
@@ -146,6 +152,12 @@
         },
         "mcp": {
           "$ref": "#/definitions/MCPConfig"
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ToolDefinition"
+          }
         }
       },
       "required": [
@@ -354,6 +366,56 @@
       },
       "additionalProperties": false
     },
+    "ToolDefinition": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "function"
+        },
+        "function": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "description": {
+              "type": "string"
+            },
+            "parameters": {
+              "type": "object"
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "type",
+        "function"
+      ],
+      "additionalProperties": false
+    },
+    "AgentRefConfig": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "ref": {
+          "type": "string"
+        },
+        "config": {
+          "type": "object"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false
+    },
     "StateDefinition": {
       "type": "object",
       "properties": {
@@ -405,6 +467,9 @@
             }
           ]
         },
+        "wait_for": {
+          "type": "string"
+        },
         "input": {
           "type": "object"
         },
@@ -421,7 +486,14 @@
           }
         },
         "tool_loop": {
-          "type": "boolean"
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/definitions/ToolLoopStateConfig"
+            }
+          ]
         },
         "sampling": {
           "type": "string",
@@ -534,6 +606,39 @@
       ],
       "additionalProperties": false
     },
+    "ToolLoopStateConfig": {
+      "type": "object",
+      "properties": {
+        "max_tool_calls": {
+          "type": "number"
+        },
+        "max_turns": {
+          "type": "number"
+        },
+        "allowed_tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "denied_tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tool_timeout": {
+          "type": "number"
+        },
+        "total_timeout": {
+          "type": "number"
+        },
+        "max_cost": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    },
     "MachineSettings": {
       "type": "object",
       "properties": {
@@ -570,16 +675,33 @@
         "backend"
       ]
     },
-    "HooksConfig": {
-      "type": "object",
-      "properties": {
-        "file": {
+    "HooksRef": {
+      "anyOf": [
+        {
           "type": "string"
         },
-        "module": {
-          "type": "string"
+        {
+          "$ref": "#/definitions/HooksRefConfig"
         },
-        "class": {
+        {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "$ref": "#/definitions/HooksRefConfig"
+              }
+            ]
+          }
+        }
+      ]
+    },
+    "HooksRefConfig": {
+      "type": "object",
+      "properties": {
+        "name": {
           "type": "string"
         },
         "args": {
@@ -587,10 +709,9 @@
         }
       },
       "required": [
-        "class"
+        "name"
       ],
-      "additionalProperties": false,
-      "description": "Configuration for loading hooks from file or module.\n\nFile-based (preferred for self-contained skills):   hooks:     file: \"./hooks.py\"     class: \"MyHooks\"     args:       working_dir: \".\"\n\nModule-based (for installed packages):   hooks:     module: \"mypackage.hooks\"     class: \"MyHooks\"     args:       api_key: \"{{ input.api_key }}\"\n\nFields:   file   - Path to Python file containing hooks class (relative to machine.yml)   module - Python module path to import   class  - Class name to instantiate (required)   args   - Arguments to pass to hooks constructor"
+      "additionalProperties": false
     }
   }
 }

package/schemas/flatmachine.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "0.10.0";
+export const SPEC_VERSION = "2.0.0";
 export interface MachineWrapper {
     spec: "flatmachine";
     spec_version: string;
@@ -9,17 +9,22 @@ export interface MachineData {
     name?: string;
     expression_engine?: "simple" | "cel";
     context?: Record<string, any>;
-    agents?: Record<string, string | AgentWrapper>;
+    agents?: Record<string, AgentRef>;
     machines?: Record<string, string | MachineWrapper>;
     states: Record<string, StateDefinition>;
     settings?: MachineSettings;
     persistence?: PersistenceConfig;
-    hooks?: HooksConfig;
+    hooks?: HooksRef;
 }
-export interface HooksConfig {
-    file?: string;
-    module?: string;
-    class: string;
+export interface AgentRefConfig {
+    type: string;
+    ref?: string;
+    config?: Record<string, any>;
+}
+export type AgentRef = string | AgentWrapper | AgentRefConfig;
+export type HooksRef = string | HooksRefConfig | Array<string | HooksRefConfig>;
+export interface HooksRefConfig {
+    name: string;
     args?: Record<string, any>;
 }
 export interface MachineSettings {
@@ -34,11 +39,12 @@ export interface StateDefinition {
     action?: string;
     execution?: ExecutionConfig;
     on_error?: string | Record<string, string>;
+    wait_for?: string;
     input?: Record<string, any>;
     output_to_context?: Record<string, any>;
     output?: Record<string, any>;
     transitions?: Transition[];
-    tool_loop?: boolean;
+    tool_loop?: boolean | ToolLoopStateConfig;
     sampling?: "single" | "multi";
     foreach?: string;
     as?: string;
@@ -48,6 +54,15 @@ export interface StateDefinition {
     launch?: string | string[];
     launch_input?: Record<string, any>;
 }
+export interface ToolLoopStateConfig {
+    max_tool_calls?: number;
+    max_turns?: number;
+    allowed_tools?: string[];
+    denied_tools?: string[];
+    tool_timeout?: number;
+    total_timeout?: number;
+    max_cost?: number;
+}
 export interface MachineInput {
     name: string;
     input?: Record<string, any>;
@@ -87,6 +102,13 @@ export interface MachineSnapshot {
     total_cost?: number;
     parent_execution_id?: string;
     pending_launches?: LaunchIntent[];
+    waiting_channel?: string;
+    tool_loop_state?: {
+        chain: Array<Record<string, any>>;
+        turns: number;
+        tool_calls_count: number;
+        loop_cost: number;
+    };
 }
 export interface PersistenceConfig {
     enabled: boolean;

package/schemas/profiles.d.ts

@@ -108,7 +108,7 @@
  * stream            - Enable streaming responses (default: false)
  */
 
-export const SPEC_VERSION = "0.10.0";
+export const SPEC_VERSION = "2.0.0";
 
 export interface ProfilesWrapper {
   spec: "flatprofiles";

package/schemas/profiles.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "0.10.0";
+export const SPEC_VERSION = "2.0.0";
 export interface ProfilesWrapper {
     spec: "flatprofiles";
     spec_version: string;