@pellux/goodvibes-contracts 1.9.0 → 1.10.0

package/artifacts/operator-openapi.json

@@ -2,8 +2,8 @@
   "openapi": "3.1.0",
   "info": {
     "title": "GoodVibes Operator API",
-    "version": "1.9.0",
-    "description": "Generated from the operator contract (packages/contracts/artifacts/operator-contract.json). 412 cataloged methods: 361 with dedicated REST bindings, 51 reachable only through the generic invoke endpoint. 97 methods lack typed SDK client IO and are marked with `x-typed-client-io: false` — they are represented honestly, never omitted. Regenerate with `bun run openapi:generate`; drift fails `contracts:check`."
+    "version": "1.10.0",
+    "description": "Generated from the operator contract (packages/contracts/artifacts/operator-contract.json). 415 cataloged methods: 364 with dedicated REST bindings, 51 reachable only through the generic invoke endpoint. 97 methods lack typed SDK client IO and are marked with `x-typed-client-io: false` — they are represented honestly, never omitted. Regenerate with `bun run openapi:generate`; drift fails `contracts:check`."
   },
   "servers": [
     {
@@ -30433,6 +30433,154 @@
         ]
       }
     },
+    "/api/ops/memory": {
+      "get": {
+        "operationId": "ops.memory.get",
+        "summary": "Get Memory Governance State",
+        "description": "The MemoryGovernor snapshot: the current memory-pressure tier and budget, resident set size and heap, per-cache footprints the governor can shrink, which deferrable background jobs are paused, and the leak-tripwire state. Read-only observability so operators can see the daemon shedding memory before it approaches OOM.",
+        "tags": [
+          "health"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "tier": {
+                      "type": "string",
+                      "enum": [
+                        "normal",
+                        "elevated",
+                        "high",
+                        "critical"
+                      ]
+                    },
+                    "budgetMb": {
+                      "type": "number"
+                    },
+                    "rssMb": {
+                      "type": "number"
+                    },
+                    "heapUsedMb": {
+                      "type": "number"
+                    },
+                    "heapTotalMb": {
+                      "type": "number"
+                    },
+                    "usedPct": {
+                      "type": "number"
+                    },
+                    "refusingExpensiveWork": {
+                      "type": "boolean"
+                    },
+                    "caches": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "entries": {
+                            "type": "number"
+                          },
+                          "estimatedBytes": {
+                            "type": "number"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "name",
+                          "entries"
+                        ],
+                        "additionalProperties": false
+                      }
+                    },
+                    "pausedJobs": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "tripwire": {
+                      "type": "object",
+                      "properties": {
+                        "armed": {
+                          "type": "boolean"
+                        },
+                        "sustainedSec": {
+                          "type": "number"
+                        },
+                        "rateMbPerSec": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "armed",
+                        "sustainedSec",
+                        "rateMbPerSec"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "thresholds": {
+                      "type": "object",
+                      "properties": {
+                        "elevatedPct": {
+                          "type": "number"
+                        },
+                        "highPct": {
+                          "type": "number"
+                        },
+                        "criticalPct": {
+                          "type": "number"
+                        }
+                      },
+                      "required": [
+                        "elevatedPct",
+                        "highPct",
+                        "criticalPct"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": [
+                    "tier",
+                    "budgetMb",
+                    "rssMb",
+                    "heapUsedMb",
+                    "usedPct",
+                    "refusingExpensiveWork",
+                    "caches",
+                    "pausedJobs",
+                    "tripwire",
+                    "thresholds"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "x-typed-client-io": true,
+        "x-access": "authenticated",
+        "x-transport": [
+          "http",
+          "ws"
+        ],
+        "x-scopes": [
+          "read:health"
+        ]
+      }
+    },
     "/api/power/keep-awake": {
       "post": {
         "operationId": "power.keepAwake.set",
@@ -30790,6 +30938,413 @@
         ]
       }
     },
+    "/api/voice/local/install": {
+      "post": {
+        "operationId": "voice.local.install",
+        "summary": "Install the Managed Local-Voice Runtime",
+        "description": "One-act setup: download + checksum-verify the piper TTS engine, a default voice, and (where a pinned goodvibes-built bundle exists) the whisper.cpp STT engine with its default model into the goodvibes-managed directory, then point the voice.local.* config keys at the managed install — never overwriting a key you already set to a custom value (skipped keys are reported). After this, local TTS works with zero further configuration. Downloads only when you ask; a failed or checksum-mismatched download keeps nothing.",
+        "tags": [
+          "health"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "provisioned": {
+                      "type": "boolean"
+                    },
+                    "platform": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "tts": {
+                      "type": "object",
+                      "properties": {
+                        "engine": {
+                          "type": "string"
+                        },
+                        "state": {
+                          "type": "string",
+                          "enum": [
+                            "provisioned",
+                            "unsupported-platform",
+                            "download-failed",
+                            "checksum-mismatch"
+                          ]
+                        },
+                        "binaryPath": {
+                          "type": "string"
+                        },
+                        "modelPath": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "engine",
+                        "state"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "stt": {
+                      "type": "object",
+                      "properties": {
+                        "engine": {
+                          "type": "string"
+                        },
+                        "state": {
+                          "type": "string",
+                          "enum": [
+                            "provisioned",
+                            "unsupported-platform",
+                            "download-failed",
+                            "checksum-mismatch",
+                            "bundle-unavailable",
+                            "sideload-mismatch"
+                          ]
+                        },
+                        "binaryPath": {
+                          "type": "string"
+                        },
+                        "modelPath": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "engine",
+                        "state"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "components": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string"
+                          },
+                          "state": {
+                            "type": "string",
+                            "enum": [
+                              "installed",
+                              "skipped",
+                              "failed"
+                            ]
+                          },
+                          "bytes": {
+                            "type": "number"
+                          },
+                          "error": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "state"
+                        ],
+                        "additionalProperties": false
+                      }
+                    },
+                    "configured": {
+                      "type": "object",
+                      "properties": {
+                        "set": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "key": {
+                                "type": "string"
+                              },
+                              "value": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "key",
+                              "value"
+                            ],
+                            "additionalProperties": false
+                          }
+                        },
+                        "skipped": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "key": {
+                                "type": "string"
+                              },
+                              "reason": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "key",
+                              "reason"
+                            ],
+                            "additionalProperties": false
+                          }
+                        }
+                      },
+                      "required": [
+                        "set",
+                        "skipped"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": [
+                    "provisioned",
+                    "platform",
+                    "tts",
+                    "stt",
+                    "components",
+                    "configured"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "x-typed-client-io": true,
+        "x-access": "authenticated",
+        "x-transport": [
+          "http",
+          "ws"
+        ],
+        "x-scopes": [
+          "write:config"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {},
+                "additionalProperties": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/voice/local/status": {
+      "get": {
+        "operationId": "voice.local.status",
+        "summary": "Get Managed Local-Voice Runtime State",
+        "description": "Whether the managed local voice runtime (piper TTS + a default voice) is installed: not-provisioned (with a size-labeled offer), partial, provisioned, or unsupported-platform. STT (whisper.cpp) reports its own managed state: goodvibes builds and pins the whisper.cpp bundle per platform (no official prebuilt exists; provisioning never compiles on your machine), so where a pinned bundle exists STT provisions like TTS, and elsewhere it reports unsupported honestly. While a voice.local.install run is active, the response also carries installInProgress — the live per-component progress (phase, byte sizes where known) of that run — so surfaces poll this read during the install to render real progress; the section is absent when no install is running. Read-only.",
+        "tags": [
+          "health"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "platform": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "state": {
+                      "type": "string",
+                      "enum": [
+                        "not-provisioned",
+                        "partial",
+                        "provisioned",
+                        "unsupported-platform"
+                      ]
+                    },
+                    "tts": {
+                      "type": "object",
+                      "properties": {
+                        "engine": {
+                          "type": "string"
+                        },
+                        "binaryPresent": {
+                          "type": "boolean"
+                        },
+                        "voicePresent": {
+                          "type": "boolean"
+                        },
+                        "binaryPath": {
+                          "type": "string"
+                        },
+                        "modelPath": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "engine",
+                        "binaryPresent",
+                        "voicePresent",
+                        "binaryPath",
+                        "modelPath"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "stt": {
+                      "type": "object",
+                      "properties": {
+                        "engine": {
+                          "type": "string"
+                        },
+                        "supported": {
+                          "type": "boolean"
+                        },
+                        "state": {
+                          "type": "string",
+                          "enum": [
+                            "not-provisioned",
+                            "partial",
+                            "provisioned",
+                            "unsupported-platform"
+                          ]
+                        },
+                        "binaryPresent": {
+                          "type": "boolean"
+                        },
+                        "modelPresent": {
+                          "type": "boolean"
+                        },
+                        "binaryPath": {
+                          "type": "string"
+                        },
+                        "modelPath": {
+                          "type": "string"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "engine",
+                        "supported",
+                        "state",
+                        "binaryPresent",
+                        "modelPresent",
+                        "binaryPath",
+                        "modelPath"
+                      ],
+                      "additionalProperties": false
+                    },
+                    "offerBytes": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "installInProgress": {
+                      "type": "object",
+                      "properties": {
+                        "startedAt": {
+                          "type": "number"
+                        },
+                        "components": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "component": {
+                                "type": "string"
+                              },
+                              "phase": {
+                                "type": "string",
+                                "enum": [
+                                  "skip",
+                                  "download",
+                                  "verify",
+                                  "extract",
+                                  "done",
+                                  "error"
+                                ]
+                              },
+                              "message": {
+                                "type": "string"
+                              },
+                              "bytesTotal": {
+                                "type": "number"
+                              },
+                              "bytesDone": {
+                                "type": "number"
+                              }
+                            },
+                            "required": [
+                              "component",
+                              "phase"
+                            ],
+                            "additionalProperties": false
+                          }
+                        }
+                      },
+                      "required": [
+                        "startedAt",
+                        "components"
+                      ],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": [
+                    "platform",
+                    "state",
+                    "tts",
+                    "stt",
+                    "offerBytes"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "x-typed-client-io": true,
+        "x-access": "authenticated",
+        "x-transport": [
+          "http",
+          "ws"
+        ],
+        "x-scopes": [
+          "read:health"
+        ]
+      }
+    },
     "/api/intelligence": {
       "get": {
         "operationId": "intelligence.snapshot",
@@ -91747,6 +92302,15 @@
       "inputSchemaCoverage": "typed",
       "outputSchemaCoverage": "typed"
     },
+    {
+      "id": "ops.memory.get",
+      "category": "health",
+      "access": "authenticated",
+      "rest": "GET /api/ops/memory",
+      "typedClientIo": true,
+      "inputSchemaCoverage": "typed",
+      "outputSchemaCoverage": "typed"
+    },
     {
       "id": "power.keepAwake.set",
       "category": "health",
@@ -91765,6 +92329,24 @@
       "inputSchemaCoverage": "typed",
       "outputSchemaCoverage": "typed"
     },
+    {
+      "id": "voice.local.install",
+      "category": "health",
+      "access": "authenticated",
+      "rest": "POST /api/voice/local/install",
+      "typedClientIo": true,
+      "inputSchemaCoverage": "typed",
+      "outputSchemaCoverage": "typed"
+    },
+    {
+      "id": "voice.local.status",
+      "category": "health",
+      "access": "authenticated",
+      "rest": "GET /api/voice/local/status",
+      "typedClientIo": true,
+      "inputSchemaCoverage": "typed",
+      "outputSchemaCoverage": "typed"
+    },
     {
       "id": "intelligence.snapshot",
       "category": "intelligence",

package/artifacts/python/homeassistant_operator_client.py

@@ -5,7 +5,7 @@ emitted from the operator contract by scripts/generate-homeassistant-client.ts.
 Covers only the REST subset HA consumes; the webhook, conversation stream,
 and surface health probe are not operator methods and stay hand-written.
 
-Contract product version: 1.9.0
+Contract product version: 1.10.0
 Consumed operator methods: 33
 """
 from __future__ import annotations
@@ -13,7 +13,7 @@ from __future__ import annotations
 from typing import Any, Literal, Mapping, NamedTuple, NotRequired, TypedDict
 
 #: Daemon contract version these types were generated against (the version pin).
-CONTRACT_VERSION: str = "1.9.0"
+CONTRACT_VERSION: str = "1.10.0"
 
 
 class OperatorRoute(NamedTuple):