@heddleagent/execution-host-client 6.0.0 → 6.2.0

package/spec/v1/fixtures/manifest.json

@@ -7,6 +7,12 @@
       "kind": "json-schema",
       "expected": "valid"
     },
+    {
+      "id": "valid-heartbeat-request",
+      "file": "valid-heartbeat-request.json",
+      "kind": "json-schema",
+      "expected": "valid"
+    },
     {
       "id": "request-authority-in-body",
       "file": "invalid-request-extra-field.json",
@@ -19,6 +25,12 @@
       "kind": "sse",
       "expected": "complete"
     },
+    {
+      "id": "valid-heartbeat-result",
+      "file": "valid-heartbeat-result.sse",
+      "kind": "sse",
+      "expected": "complete"
+    },
     {
       "id": "cancelled",
       "file": "cancelled.sse",

package/spec/v1/fixtures/valid-heartbeat-request.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "kind": "heartbeat-task",
+  "invocationId": "heartbeat-execution-001",
+  "taskId": "heartbeat-task-001",
+  "task": "Review the workspace for actionable changes.",
+  "checkpoint": {
+    "version": 1,
+    "createdAt": "2026-08-10T04:00:00.000Z",
+    "state": {
+      "runId": "prior-run-001"
+    }
+  },
+  "runContext": {
+    "currentDateTime": "2026-08-10T04:00:00.000Z",
+    "intervalMs": 60000,
+    "continuationMode": "operator",
+    "previousRunId": "prior-run-001"
+  },
+  "model": "openai:gpt-5.6",
+  "maxSteps": 24,
+  "deadlineAt": "2026-08-10T04:10:00.000Z"
+}

package/spec/v1/fixtures/valid-heartbeat-result.sse

@@ -0,0 +1,13 @@
+id: 0
+event: accepted
+data: {"schemaVersion":1,"invocationId":"heartbeat-execution-001","runId":"heartbeat-run-001","sequence":0,"timestamp":"2026-08-10T04:00:00.000Z","kind":"accepted"}
+
+id: 1
+event: activity
+data: {"schemaVersion":1,"invocationId":"heartbeat-execution-001","runId":"heartbeat-run-001","sequence":1,"timestamp":"2026-08-10T04:00:00.000Z","kind":"activity","activity":{"type":"heartbeat.decision","decision":"continue"}}
+
+id: 2
+event: result
+data: {"schemaVersion":1,"invocationId":"heartbeat-execution-001","runId":"heartbeat-run-001","sequence":2,"timestamp":"2026-08-10T04:00:00.000Z","kind":"result","result":{"decision":"continue","summary":"No operator action required.","checkpoint":{"version":1,"createdAt":"2026-08-10T04:00:00.000Z","state":{"runId":"heartbeat-run-001"}},"state":{"runId":"heartbeat-run-001","outcome":"done","summary":"No operator action required."}}}
+
+: fixture-clean-eof

package/spec/v1/openapi.json

@@ -10,9 +10,9 @@
   "paths": {
     "/invocations": {
       "post": {
-        "operationId": "streamConversationTurn",
-        "summary": "Run one hosted conversation turn",
-        "description": "Starts one conversation turn and holds one SSE response open until a terminal event or an ambiguous interruption. A clean HTTP EOF is required before a terminal frame may be committed as final.",
+        "operationId": "streamExecutionHostInvocation",
+        "summary": "Run one supported Execution Host workflow",
+        "description": "Starts one conversation turn or heartbeat task and holds one SSE response open until a terminal event or an ambiguous interruption. A clean HTTP EOF is required before a terminal frame may be committed as final.",
         "parameters": [
           {
             "name": "x-amzn-bedrock-agentcore-runtime-session-id",
@@ -77,7 +77,17 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ConversationTurnRequest"
+                "oneOf": [
+                  {
+                    "$ref": "#/components/schemas/ConversationTurnRequest"
+                  },
+                  {
+                    "$ref": "#/components/schemas/HeartbeatTaskRequest"
+                  }
+                ],
+                "discriminator": {
+                  "propertyName": "kind"
+                }
               }
             }
           }
@@ -267,6 +277,170 @@
         ],
         "additionalProperties": false
       },
+      "HeartbeatTaskRequest": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "kind": {
+            "type": "string",
+            "const": "heartbeat-task"
+          },
+          "invocationId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+          },
+          "taskId": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+          },
+          "task": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200000,
+            "x-heddle-trimmed": true
+          },
+          "checkpoint": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "$ref": "#/components/schemas/HeartbeatTaskRequest/$defs/__schema0"
+            }
+          },
+          "runContext": {
+            "type": "object",
+            "properties": {
+              "currentDateTime": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "intervalMs": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              "continuationMode": {
+                "type": "string",
+                "enum": [
+                  "operator",
+                  "agent"
+                ]
+              },
+              "nextRunAt": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "previousRunAt": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "previousRunId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              }
+            },
+            "required": [
+              "currentDateTime",
+              "intervalMs"
+            ],
+            "additionalProperties": false
+          },
+          "model": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "reasoningEffort": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "ultrahigh",
+              "max"
+            ]
+          },
+          "maxSteps": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 10000
+          },
+          "searchIgnoreDirs": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          },
+          "systemContext": {
+            "type": "string",
+            "maxLength": 200000
+          },
+          "deadlineAt": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "kind",
+          "invocationId",
+          "taskId",
+          "task",
+          "runContext"
+        ],
+        "additionalProperties": false,
+        "$defs": {
+          "__schema0": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/HeartbeatTaskRequest/$defs/__schema0"
+                }
+              },
+              {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/HeartbeatTaskRequest/$defs/__schema0"
+                }
+              }
+            ]
+          }
+        }
+      },
       "RuntimePublicResult": {
         "type": "object",
         "properties": {
@@ -617,6 +791,333 @@
           }
         ]
       },
+      "HeartbeatStreamEvent": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "schemaVersion": {
+                "type": "number",
+                "const": 1
+              },
+              "invocationId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "runId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "sequence": {
+                "type": "number",
+                "const": 0
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "kind": {
+                "type": "string",
+                "const": "accepted"
+              }
+            },
+            "required": [
+              "schemaVersion",
+              "invocationId",
+              "runId",
+              "sequence",
+              "timestamp",
+              "kind"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "schemaVersion": {
+                "type": "number",
+                "const": 1
+              },
+              "invocationId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "runId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "sequence": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "kind": {
+                "type": "string",
+                "const": "activity"
+              },
+              "activity": {
+                "$ref": "#/components/schemas/HeartbeatStreamEvent/$defs/__schema0"
+              }
+            },
+            "required": [
+              "schemaVersion",
+              "invocationId",
+              "runId",
+              "sequence",
+              "timestamp",
+              "kind",
+              "activity"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "schemaVersion": {
+                "type": "number",
+                "const": 1
+              },
+              "invocationId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "runId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "sequence": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "kind": {
+                "type": "string",
+                "const": "result"
+              },
+              "result": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/HeartbeatStreamEvent/$defs/__schema1"
+                }
+              }
+            },
+            "required": [
+              "schemaVersion",
+              "invocationId",
+              "runId",
+              "sequence",
+              "timestamp",
+              "kind",
+              "result"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "schemaVersion": {
+                "type": "number",
+                "const": 1
+              },
+              "invocationId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "runId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "sequence": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "kind": {
+                "type": "string",
+                "const": "cancelled"
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "schemaVersion",
+              "invocationId",
+              "runId",
+              "sequence",
+              "timestamp",
+              "kind",
+              "reason"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "schemaVersion": {
+                "type": "number",
+                "const": 1
+              },
+              "invocationId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "runId": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*$"
+              },
+              "sequence": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+              },
+              "kind": {
+                "type": "string",
+                "const": "error"
+              },
+              "error": {
+                "type": "object",
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "^[a-z0-9_]+$"
+                  },
+                  "message": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1600
+                  }
+                },
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "schemaVersion",
+              "invocationId",
+              "runId",
+              "sequence",
+              "timestamp",
+              "kind",
+              "error"
+            ],
+            "additionalProperties": false
+          }
+        ],
+        "$defs": {
+          "__schema0": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/HeartbeatStreamEvent/$defs/__schema0"
+                }
+              },
+              {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/HeartbeatStreamEvent/$defs/__schema0"
+                }
+              }
+            ]
+          },
+          "__schema1": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/HeartbeatStreamEvent/$defs/__schema1"
+                }
+              },
+              {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/HeartbeatStreamEvent/$defs/__schema1"
+                }
+              }
+            ]
+          }
+        }
+      },
       "ExecutionAssertionClaims": {
         "type": "object",
         "properties": {
@@ -659,7 +1160,10 @@
           },
           "workflow": {
             "type": "string",
-            "const": "conversation-turn"
+            "enum": [
+              "conversation-turn",
+              "heartbeat-task"
+            ]
           },
           "sub": {
             "type": "string",
@@ -748,7 +1252,10 @@
           },
           "workflow": {
             "type": "string",
-            "const": "conversation-turn"
+            "enum": [
+              "conversation-turn",
+              "heartbeat-task"
+            ]
           },
           "serverId": {
             "type": "string",