@mininglamp-oss/octo-runtime-client 0.0.0-stage → 1.1.11

package/schema/kernel-client.behavior.json

@@ -0,0 +1,56 @@
+{
+  "revision": 1,
+  "ipcVersion": 1,
+  "limits": {
+    "connections": 32,
+    "invocations": 128,
+    "controlConcurrency": 4,
+    "lookupConcurrency": 4,
+    "requestBytes": 33554432,
+    "lineBytes": 42008576,
+    "readChunkBytes": 65536
+  },
+  "timeoutsMs": {
+    "connect": 5000,
+    "unary": 5000,
+    "invokeAck": 30000,
+    "recovery": 10000
+  },
+  "repairDelaysMs": [100, 250, 500],
+  "terminalStates": ["completed", "failed", "cancelled", "lost"],
+  "retryableErrors": ["CONNECTION_CLOSED", "KERNEL_UNAVAILABLE", "KERNEL_TIMEOUT"],
+  "lookupFields": [
+    "run_id",
+    "invocation_id",
+    "agent_session_id",
+    "session_generation",
+    "protocol_mode"
+  ],
+  "receiptFields": [
+    "run_id",
+    "invocation_id",
+    "stream_id",
+    "agent_session_id",
+    "session_generation",
+    "protocol_mode",
+    "protocol"
+  ],
+  "identityInputFields": {
+    "run_id": "runId",
+    "invocation_id": "invocationId",
+    "agent_session_id": "sessionId",
+    "session_generation": "sessionGeneration",
+    "protocol_mode": "protocol_mode"
+  },
+  "defaults": {
+    "session_generation": 0,
+    "protocol_mode": "native"
+  },
+  "lifecycle": {
+    "admission": ["admitting", "accepted", "acceptance_unknown", "unobserved"],
+    "cancellation": ["none", "requested", "acknowledged", "unknown"]
+  },
+  "ownership": "attached",
+  "closeCancelsRun": false,
+  "replayInvoke": false
+}

package/schema/kernel-ipc-fixtures.json

@@ -0,0 +1,53 @@
+{
+  "ipc_version": 1,
+  "cases": [
+    {
+      "name": "status",
+      "request": { "jsonrpc": "2.0", "id": "status-1", "method": "status", "params": {} },
+      "valid": true,
+      "result_definition": "KernelStatus"
+    },
+    {
+      "name": "list",
+      "request": { "jsonrpc": "2.0", "id": "list-1", "method": "adapter.list", "params": {} },
+      "valid": true
+    },
+    {
+      "name": "missing-run",
+      "request": {
+        "jsonrpc": "2.0",
+        "id": "get-1",
+        "method": "agent_run.get",
+        "params": {
+          "key": {
+            "run_id": "r1",
+            "invocation_id": "i1",
+            "agent_session_id": "s1",
+            "session_generation": 0,
+            "protocol_mode": "native"
+          }
+        }
+      },
+      "valid": true,
+      "error_code": "RUN_NOT_AVAILABLE"
+    },
+    {
+      "name": "numeric-id",
+      "request": { "jsonrpc": "2.0", "id": 1, "method": "status", "params": {} },
+      "valid": false,
+      "error_code": "INVALID_REQUEST"
+    },
+    {
+      "name": "unknown-params",
+      "request": {
+        "jsonrpc": "2.0",
+        "id": "bad-1",
+        "method": "status",
+        "params": { "extra": true }
+      },
+      "valid": false,
+      "error_code": "INVALID_PARAMS"
+    },
+    { "name": "batch", "request": [], "valid": false, "error_code": "INVALID_REQUEST" }
+  ]
+}

package/schema/kernel-ipc.schema.json

@@ -0,0 +1,538 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:mininglamp-oss:octo-runtime:kernel-ipc:v1",
+  "title": "Kernel IPC v1",
+  "description": "One UTF-8 LF-terminated JSON-RPC request per local connection. No batches. Closing a connection never cancels execution. Source sequence numbers belong to the Kernel instance. Receipts and events retain the original Run protocol identities.",
+  "definitions": {
+    "Request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "id", "method", "params"],
+      "properties": {
+        "jsonrpc": {
+          "const": "2.0"
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "x-octo-max-utf8-bytes": 128
+        },
+        "method": {
+          "enum": [
+            "status",
+            "adapter.list",
+            "agent_run.invoke",
+            "agent_run.get",
+            "agent_run.subscribe",
+            "agent_run.cancel",
+            "agent_run.respond",
+            "agent_run.native.respond"
+          ]
+        },
+        "params": {
+          "type": "object"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "status"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/EmptyParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "adapter.list"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/EmptyParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "agent_run.invoke"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/InvokeParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "agent_run.get"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/GetParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "agent_run.subscribe"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/SubscribeParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "agent_run.cancel"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/CancelParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "agent_run.respond"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/RespondParams"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "method": {
+                "const": "agent_run.native.respond"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "params": {
+                "$ref": "#/definitions/RespondNativeParams"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "EmptyParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [],
+      "properties": {}
+    },
+    "EmptyResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [],
+      "properties": {}
+    },
+    "InvokeParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input"],
+      "properties": {
+        "input": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/InvokeInputWire"
+        },
+        "executionEnvOverrides": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/ContextEnvsPayload"
+        },
+        "kernel_instance_id": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "GetParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key"],
+      "properties": {
+        "key": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelLookupKey"
+        },
+        "kernel_instance_id": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "SubscribeParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "after_seq"],
+      "properties": {
+        "ref": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelRunRef"
+        },
+        "after_seq": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "CancelParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref"],
+      "properties": {
+        "ref": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelRunRef"
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "RespondParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "response"],
+      "properties": {
+        "ref": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelRunRef"
+        },
+        "response": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/InteractionResponseWire"
+        }
+      }
+    },
+    "RespondNativeParams": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ref", "response"],
+      "properties": {
+        "ref": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelRunRef"
+        },
+        "response": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/NativeInteractionResponse"
+        }
+      }
+    },
+    "InvokeResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kernel_instance_id", "receipt"],
+      "properties": {
+        "kernel_instance_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "receipt": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/HostRunReceipt"
+        }
+      }
+    },
+    "CancelResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["accepted"],
+      "properties": {
+        "accepted": {
+          "type": "boolean"
+        }
+      }
+    },
+    "SuccessResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "id", "result"],
+      "properties": {
+        "jsonrpc": {
+          "const": "2.0"
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "result": {}
+      }
+    },
+    "ErrorResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "id", "error"],
+      "properties": {
+        "jsonrpc": {
+          "const": "2.0"
+        },
+        "id": {
+          "type": ["string", "null"]
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["code", "message", "data"],
+          "properties": {
+            "code": {
+              "type": "integer"
+            },
+            "message": {
+              "type": "string"
+            },
+            "data": {
+              "type": "object",
+              "additionalProperties": true,
+              "required": ["code"],
+              "properties": {
+                "code": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "EventNotification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "method", "params"],
+      "properties": {
+        "jsonrpc": {
+          "const": "2.0"
+        },
+        "method": {
+          "const": "agent_run.event"
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kernel_instance_id", "run_id", "stream_id", "seq", "event"],
+          "properties": {
+            "kernel_instance_id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "run_id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "stream_id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "seq": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            },
+            "event": {
+              "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/HostFrame"
+            }
+          }
+        }
+      }
+    },
+    "StreamErrorNotification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "method", "params"],
+      "properties": {
+        "jsonrpc": {
+          "const": "2.0"
+        },
+        "method": {
+          "const": "agent_run.stream_error"
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "kernel_instance_id"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "minLength": 1
+            },
+            "kernel_instance_id": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
+    "KnownBusinessErrorCode": {
+      "enum": [
+        "KERNEL_UNAVAILABLE",
+        "KERNEL_INSTANCE_CHANGED",
+        "RUN_IDENTITY_MISMATCH",
+        "RUN_NOT_AVAILABLE",
+        "RUN_ALREADY_ACCEPTED",
+        "RUN_CAPACITY_EXHAUSTED",
+        "STREAM_GAP",
+        "STREAM_EXPIRED",
+        "STREAM_CURSOR_INVALID",
+        "STREAM_SUBSCRIBER_LIMIT",
+        "ACCEPTANCE_UNKNOWN",
+        "OPERATION_OUTCOME_UNKNOWN",
+        "CLIENT_CLOSED",
+        "WORKER_LOST",
+        "WORKER_RESTART_EXHAUSTED",
+        "INVOKE_REQUEST_TOO_LARGE",
+        "HOST_FRAME_TOO_LARGE"
+      ]
+    },
+    "BusinessErrorCode": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Open error namespace; preserve unknown codes and data."
+    }
+  },
+  "$ref": "#/definitions/Request",
+  "x-octo-methods": [
+    {
+      "method": "status",
+      "name": "Status",
+      "params": {
+        "$ref": "#/definitions/EmptyParams"
+      },
+      "result": {
+        "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelStatus"
+      },
+      "stream": false,
+      "sideEffect": false
+    },
+    {
+      "method": "adapter.list",
+      "name": "List",
+      "params": {
+        "$ref": "#/definitions/EmptyParams"
+      },
+      "result": {
+        "type": "array",
+        "items": {
+          "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/HostedAdapterMetadataWire"
+        }
+      },
+      "stream": false,
+      "sideEffect": false
+    },
+    {
+      "method": "agent_run.invoke",
+      "name": "Submit",
+      "params": {
+        "$ref": "#/definitions/InvokeParams"
+      },
+      "result": {
+        "$ref": "#/definitions/InvokeResult"
+      },
+      "stream": false,
+      "sideEffect": true
+    },
+    {
+      "method": "agent_run.get",
+      "name": "Get",
+      "params": {
+        "$ref": "#/definitions/GetParams"
+      },
+      "result": {
+        "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelRunSnapshot"
+      },
+      "stream": false,
+      "sideEffect": false
+    },
+    {
+      "method": "agent_run.subscribe",
+      "name": "Subscribe",
+      "params": {
+        "$ref": "#/definitions/SubscribeParams"
+      },
+      "result": {
+        "$ref": "urn:mininglamp-oss:octo-runtime:protocol-schema#/definitions/KernelRunSnapshot"
+      },
+      "stream": true,
+      "sideEffect": false
+    },
+    {
+      "method": "agent_run.cancel",
+      "name": "Cancel",
+      "params": {
+        "$ref": "#/definitions/CancelParams"
+      },
+      "result": {
+        "$ref": "#/definitions/CancelResult"
+      },
+      "stream": false,
+      "sideEffect": true
+    },
+    {
+      "method": "agent_run.respond",
+      "name": "Respond",
+      "params": {
+        "$ref": "#/definitions/RespondParams"
+      },
+      "result": {
+        "$ref": "#/definitions/EmptyResult"
+      },
+      "stream": false,
+      "sideEffect": true
+    },
+    {
+      "method": "agent_run.native.respond",
+      "name": "RespondNative",
+      "params": {
+        "$ref": "#/definitions/RespondNativeParams"
+      },
+      "result": {
+        "$ref": "#/definitions/EmptyResult"
+      },
+      "stream": false,
+      "sideEffect": true
+    }
+  ]
+}