@memgrafter/flatagents 2.0.0 → 2.2.0

package/MACHINES.md

@@ -22,7 +22,7 @@
 ```yaml
 # profiles.yml — agents reference by name
 spec: flatprofiles
-spec_version: "2.0.0"
+spec_version: "2.2.0"
 data:
   model_profiles:
     fast: { provider: cerebras, name: zai-glm-4.6, temperature: 0.6 }

package/README.md

@@ -2,7 +2,7 @@
 
 Define LLM agents in YAML. Run them anywhere.
 
-**For LLM/machine readers:** see [MACHINES.md](./MACHINES.md) for comprehensive reference.
+**For LLM/machine readers:** see [MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md) for comprehensive reference.
 
 ## Why?
 
@@ -35,19 +35,19 @@ Use FlatAgent alone for simple tasks. Use FlatMachine when you need multi-step w
 
 | Example | What it demonstrates |
 |---------|---------------------|
-| [helloworld](./sdk/examples/helloworld/python) | Minimal setup — single agent, single state machine |
-| [writer_critic](./sdk/examples/writer_critic/python) | Multi-agent loop — writer drafts, critic reviews, iterates |
-| [story_writer](./sdk/examples/story_writer/python) | Multi-step creative workflow with chapter generation |
-| [human-in-the-loop](./sdk/examples/human-in-the-loop/python) | Pause execution for human approval via hooks |
-| [error_handling](./sdk/examples/error_handling/python) | Error recovery and retry patterns at state machine level |
-| [dynamic_agent](./sdk/examples/dynamic_agent/python) | On-the-fly agent generation from runtime context |
-| [character_card](./sdk/examples/character_card/python) | Loading agent config from character card format |
-| [mdap](./sdk/examples/mdap/python) | MDAP voting execution — multi-sample consensus |
-| [gepa_self_optimizer](./sdk/examples/gepa_self_optimizer/python) | Self-optimizing prompts via reflection and critique |
-| [research_paper_analysis](./sdk/examples/research_paper_analysis/python) | Document analysis with structured extraction |
-| [multi_paper_synthesizer](./sdk/examples/multi_paper_synthesizer/python) | Cross-document synthesis with dynamic machine launching |
-| [support_triage_json](./sdk/examples/support_triage_json/python) | JSON input/output with classification pipeline |
-| [parallelism](./sdk/examples/parallelism/python) | Parallel machines, dynamic foreach, fire-and-forget launches |
+| [helloworld](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/helloworld/python) | Minimal setup — single agent, single state machine |
+| [writer_critic](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/writer_critic/python) | Multi-agent loop — writer drafts, critic reviews, iterates |
+| [story_writer](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/story_writer/python) | Multi-step creative workflow with chapter generation |
+| [human-in-the-loop](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/human-in-the-loop/python) | Pause execution for human approval via hooks |
+| [error_handling](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/error_handling/python) | Error recovery and retry patterns at state machine level |
+| [dynamic_agent](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/dynamic_agent/python) | On-the-fly agent generation from runtime context |
+| [character_card](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/character_card/python) | Loading agent config from character card format |
+| [mdap](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/mdap/python) | MDAP voting execution — multi-sample consensus |
+| [gepa_self_optimizer](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/gepa_self_optimizer/python) | Self-optimizing prompts via reflection and critique |
+| [research_paper_analysis](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/research_paper_analysis/python) | Document analysis with structured extraction |
+| [multi_paper_synthesizer](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/multi_paper_synthesizer/python) | Cross-document synthesis with dynamic machine launching |
+| [support_triage_json](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/support_triage_json/python) | JSON input/output with classification pipeline |
+| [parallelism](https://github.com/memgrafter/flatagents/tree/main/sdk/examples/parallelism/python) | Parallel machines, dynamic foreach, fire-and-forget launches |
 
 ## Quick Start
 
@@ -167,7 +167,7 @@ Use `enum: [...]` to constrain string values.
 
 ## Multi-Agent Workflows
 
-For orchestration, use FlatMachine ([full docs in MACHINES.md](./MACHINES.md)):
+For orchestration, use FlatMachine ([full docs in MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md)):
 
 ```python
 from flatagents import FlatMachine
@@ -182,7 +182,7 @@ FlatMachine provides: state transitions, conditional branching, loops, retry wit
 
 - Checkpoint and restore
 - Python SDK (TypeScript SDK in progress)
-- [MACHINES.md](./MACHINES.md) — LLM-optimized reference docs
+- [MACHINES.md](https://github.com/memgrafter/flatagents/blob/main/MACHINES.md) — LLM-optimized reference docs
 - Decider agents and machines
 - On-the-fly agent and machine definitions
 - Webhook hooks for remote state machine handling
@@ -206,9 +206,9 @@ FlatMachine provides: state transitions, conditional branching, loops, retry wit
 ## Specs
 
 TypeScript definitions are the source of truth:
-- [`flatagent.d.ts`](./flatagent.d.ts)
-- [`flatmachine.d.ts`](./flatmachine.d.ts)
-- [`profiles.d.ts`](./profiles.d.ts)
+- [`flatagent.d.ts`](https://github.com/memgrafter/flatagents/blob/main/flatagent.d.ts)
+- [`flatmachine.d.ts`](https://github.com/memgrafter/flatagents/blob/main/flatmachine.d.ts)
+- [`profiles.d.ts`](https://github.com/memgrafter/flatagents/blob/main/profiles.d.ts)
 
 ## Python SDK
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memgrafter/flatagents",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "TypeScript SDK for FlatAgents - Declarative LLM orchestration with YAML",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/schemas/flatagent.d.ts

@@ -149,7 +149,7 @@
  * The profile field specifies which profile name to use as base.
  */
 
-export const SPEC_VERSION = "2.0.0";
+export const SPEC_VERSION = "2.2.0";
 
 export interface AgentWrapper {
   spec: "flatagent";

package/schemas/flatagent.slim.d.ts

@@ -1,4 +1,4 @@
-export const SPEC_VERSION = "2.0.0";
+export const SPEC_VERSION = "2.2.0";
 export interface AgentWrapper {
     spec: "flatagent";
     spec_version: string;

package/schemas/flatagents-runtime.d.ts

@@ -570,6 +570,26 @@ export interface MachineSnapshot {
     waiting_channel?: string;
 }
 
+export interface SnapshotRuntime {
+    /**
+     * Clone a persisted machine state under a new execution ID.
+     *
+     * Reference implementation (SDK-specific internals may vary):
+     * 1) Deep-copy the source snapshot
+     * 2) Set execution_id = new_execution_id
+     * 3) Set created_at = current UTC ISO timestamp
+     * 4) Set parent_execution_id = source.execution_id
+     * 5) Drop pending_launches (avoid duplicate child ownership)
+     * 6) Persist under new_execution_id via checkpoint manager/backend
+     * 7) Return the cloned snapshot
+     */
+    clone_snapshot(
+        snapshot: MachineSnapshot,
+        new_execution_id: string,
+        persistence: PersistenceBackend
+    ): Promise<MachineSnapshot>;
+}
+
 export interface LaunchIntent {
     execution_id: string;
     machine: string;
@@ -780,7 +800,7 @@ export interface BackendConfig {
     aws_region?: string;
 }
 
-export const SPEC_VERSION = "2.0.0";
+export const SPEC_VERSION = "2.2.0";
 
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";
@@ -795,6 +815,7 @@ export interface SDKRuntimeWrapper {
     machine_invoker?: MachineInvoker;
     backend_config?: BackendConfig;
     machine_snapshot?: MachineSnapshot;
+    snapshot_runtime?: SnapshotRuntime;
     registration_backend?: RegistrationBackend;
     work_backend?: WorkBackend;
     signal_backend?: SignalBackend;

package/schemas/flatagents-runtime.schema.json

@@ -11,7 +11,7 @@
         },
         "spec_version": {
           "type": "string",
-          "const": "2.0.0"
+          "const": "2.2.0"
         },
         "execution_lock": {
           "$ref": "#/definitions/ExecutionLock"
@@ -43,6 +43,9 @@
         "machine_snapshot": {
           "$ref": "#/definitions/MachineSnapshot"
         },
+        "snapshot_runtime": {
+          "$ref": "#/definitions/SnapshotRuntime"
+        },
         "registration_backend": {
           "$ref": "#/definitions/RegistrationBackend"
         },
@@ -320,6 +323,10 @@
       ],
       "additionalProperties": false
     },
+    "SnapshotRuntime": {
+      "type": "object",
+      "additionalProperties": false
+    },
     "RegistrationBackend": {
       "type": "object",
       "additionalProperties": false

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

@@ -168,6 +168,9 @@ export interface MachineSnapshot {
     pending_launches?: LaunchIntent[];
     waiting_channel?: string;
 }
+export interface SnapshotRuntime {
+    clone_snapshot(snapshot: MachineSnapshot, new_execution_id: string, persistence: PersistenceBackend): Promise<MachineSnapshot>;
+}
 export interface LaunchIntent {
     execution_id: string;
     machine: string;
@@ -249,7 +252,7 @@ export interface BackendConfig {
     dynamodb_table?: string;
     aws_region?: string;
 }
-export const SPEC_VERSION = "2.0.0";
+export const SPEC_VERSION = "2.2.0";
 export interface SDKRuntimeWrapper {
     spec: "flatagents-runtime";
     spec_version: typeof SPEC_VERSION;
@@ -263,6 +266,7 @@ export interface SDKRuntimeWrapper {
     machine_invoker?: MachineInvoker;
     backend_config?: BackendConfig;
     machine_snapshot?: MachineSnapshot;
+    snapshot_runtime?: SnapshotRuntime;
     registration_backend?: RegistrationBackend;
     work_backend?: WorkBackend;
     signal_backend?: SignalBackend;

package/schemas/flatmachine.d.ts

@@ -311,12 +311,15 @@
  * MACHINE SNAPSHOT:
  * -----------------
  * Wire format for checkpoints.
+ * context.machine    - Runtime-owned metadata (execution_id, step, state, cost/calls)
+ *                      Rebuilt from live machine state on each step/resume.
  * 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)
+ * config_hash         - Content-addressed machine config key for cross-SDK resume (v2.1.0)
  */
 
-export const SPEC_VERSION = "2.0.0";
+export const SPEC_VERSION = "2.2.0";
 
 export interface MachineWrapper {
   spec: "flatmachine";
@@ -325,10 +328,26 @@ export interface MachineWrapper {
   metadata?: Record<string, any>;
 }
 
+/** Runtime-owned metadata injected at context.machine */
+export interface MachineRuntimeMetadata {
+  execution_id: string;
+  machine_name: string;
+  parent_execution_id?: string;
+  spec_version: string;
+  step: number;
+  current_state: string;
+  total_api_calls: number;
+  total_cost: number;
+}
+
 export interface MachineData {
   name?: string;
   expression_engine?: "simple" | "cel";
-  context?: Record<string, any>;
+  /**
+   * Initial user context. Runtime reserves `context.machine` and overwrites
+   * it each step/resume with MachineRuntimeMetadata.
+   */
+  context?: Record<string, any> & { machine?: MachineRuntimeMetadata };
   agents?: Record<string, AgentRef>;
   machines?: Record<string, string | MachineWrapper>;
   states: Record<string, StateDefinition>;
@@ -427,7 +446,7 @@ export interface MachineSnapshot {
   machine_name: string;
   spec_version: string;
   current_state: string;
-  context: Record<string, any>;
+  context: Record<string, any> & { machine?: MachineRuntimeMetadata };
   step: number;
   created_at: string;
   event?: string;
@@ -443,6 +462,7 @@ export interface MachineSnapshot {
     tool_calls_count: number;
     loop_cost: number;
   };
+  config_hash?: string;
 }
 
 export interface PersistenceConfig {

package/schemas/flatmachine.schema.json

@@ -40,7 +40,13 @@
           ]
         },
         "context": {
-          "type": "object"
+          "type": "object",
+          "properties": {
+            "machine": {
+              "$ref": "#/definitions/MachineRuntimeMetadata"
+            }
+          },
+          "description": "Initial user context. Runtime reserves `context.machine` and overwrites it each step/resume with MachineRuntimeMetadata."
         },
         "agents": {
           "type": "object",
@@ -82,6 +88,46 @@
       ],
       "additionalProperties": false
     },
+    "MachineRuntimeMetadata": {
+      "type": "object",
+      "properties": {
+        "execution_id": {
+          "type": "string"
+        },
+        "machine_name": {
+          "type": "string"
+        },
+        "parent_execution_id": {
+          "type": "string"
+        },
+        "spec_version": {
+          "type": "string"
+        },
+        "step": {
+          "type": "number"
+        },
+        "current_state": {
+          "type": "string"
+        },
+        "total_api_calls": {
+          "type": "number"
+        },
+        "total_cost": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "execution_id",
+        "machine_name",
+        "spec_version",
+        "step",
+        "current_state",
+        "total_api_calls",
+        "total_cost"
+      ],
+      "additionalProperties": false,
+      "description": "Runtime-owned metadata injected at context.machine"
+    },
     "AgentRef": {
       "anyOf": [
         {

package/schemas/flatmachine.slim.d.ts

@@ -1,14 +1,26 @@
-export const SPEC_VERSION = "2.0.0";
+export const SPEC_VERSION = "2.2.0";
 export interface MachineWrapper {
     spec: "flatmachine";
     spec_version: string;
     data: MachineData;
     metadata?: Record<string, any>;
 }
+export interface MachineRuntimeMetadata {
+    execution_id: string;
+    machine_name: string;
+    parent_execution_id?: string;
+    spec_version: string;
+    step: number;
+    current_state: string;
+    total_api_calls: number;
+    total_cost: number;
+}
 export interface MachineData {
     name?: string;
     expression_engine?: "simple" | "cel";
-    context?: Record<string, any>;
+    context?: Record<string, any> & {
+        machine?: MachineRuntimeMetadata;
+    };
     agents?: Record<string, AgentRef>;
     machines?: Record<string, string | MachineWrapper>;
     states: Record<string, StateDefinition>;
@@ -93,7 +105,9 @@ export interface MachineSnapshot {
     machine_name: string;
     spec_version: string;
     current_state: string;
-    context: Record<string, any>;
+    context: Record<string, any> & {
+        machine?: MachineRuntimeMetadata;
+    };
     step: number;
     created_at: string;
     event?: string;
@@ -109,6 +123,7 @@ export interface MachineSnapshot {
         tool_calls_count: number;
         loop_cost: number;
     };
+    config_hash?: string;
 }
 export interface PersistenceConfig {
     enabled: boolean;

package/schemas/profiles.d.ts

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

package/schemas/profiles.slim.d.ts

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