@m1kad0/hannah-proto 4.8.0 → 5.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Protobuf/gRPC schema definitions for the Hannah voice assistant ecosystem (Core, satellites, WebUI, ioBroker adapter, Telegram bot, and other consumers). This repo is the single source of truth for the wire protocol shared across all of them.
 
-The `.proto` files live under `hannah/`, one per functional area — satellite control, event streaming, the ioBroker agent bridge, user registry, timers, automations, and so on. Nothing here is application code, just schema.
+The `.proto` files live under `hannah/` (per API generation in `hannah/v2/` and `hannah/v1/`), one per functional area — satellite control, event streaming, the ioBroker agent bridge, user registry, timers, automations, and so on. Nothing here is application code, just schema.
 
 ## Distribution
 
@@ -16,26 +16,34 @@ Three independent, tag-triggered publish targets — pick whichever matches your
 
 Go has no separate package registry, so that tagged GitHub repo *is* the package — `go get` resolves it directly.
 
-## API generations: hannah.v1
+## API generations: hannah.v1 and hannah.v2
 
-The schema exists in two packages side by side:
+The schema lives in versioned packages side by side:
 
 | Package | Files | Status |
 |---|---|---|
-| `hannah.v1` | `hannah/v1/*.proto` | **current generation** — all changes go here |
-| `hannah` (unversioned) | `hannah/*.proto` | frozen (N−1), kept so older components keep working |
+| `hannah.v2` | `hannah/v2/*.proto` | **current generation (N)** — all changes go here |
+| `hannah.v1` | `hannah/v1/*.proto` | frozen (N−1), kept so older components keep working |
 
-Both carry the same services and messages, but under different gRPC method paths (`/hannah.v1.HannahService/...` vs `/hannah.HannahService/...`), so a server can serve both at once and gRPC routes each call to the right one. Hannah Core serves the current generation and the one before it (N and N−1, never more). Clients use the current generation and fall back to the previous one if Core answers `UNIMPLEMENTED` (Core too old).
+The unversioned `hannah` package is gone since `hannah.v2`: a generation older than N−1 is removed. Only `hannah/options.proto` (the `compat_version` extension) is left in `hannah/`, shared by both generations and not copied.
 
-A breaking change never happens inside a generation — it starts the next one (`hannah.v2`), and the oldest one is removed. `hannah/options.proto` (the `compat_version` extension) is shared by both packages, not copied. The API generation is independent of the package version: `hannah.v1` ships in 4.x.
+Both carry the same services, but under different gRPC method paths (`/hannah.v2.HannahService/...` vs `/hannah.v1.HannahService/...`), so a server can serve both at once and gRPC routes each call to the right one. Hannah Core serves the current generation and the one before it (N and N−1, never more). Clients use the current generation and fall back to the previous one if Core answers `UNIMPLEMENTED` (Core too old).
 
-| Language | Current generation | Previous generation |
+A breaking change never happens inside a generation — it starts the next one (`hannah.v3`), and the oldest one is removed. The API generation is independent of the package version: `hannah.v2` ships in 5.x, `hannah.v1` in 4.x and 5.x.
+
+| Language | Current generation (N) | Previous generation (N−1) |
 |---|---|---|
-| Python | `from hannah_proto.v1 import hannah_pb2` | `from hannah_proto import hannah_pb2` |
-| TypeScript | `import { v1 } from '@m1kad0/hannah-proto'` → `v1.agent.AgentMessage` | `import { agent } from '@m1kad0/hannah-proto'` |
-| Go | `github.com/NurPech/hannah-proto-go/v4/hannahv1` | `github.com/NurPech/hannah-proto-go/v4` |
+| Python | `from hannah_proto.v2 import hannah_pb2` | `from hannah_proto.v1 import hannah_pb2` |
+| TypeScript | `import { v2 } from '@m1kad0/hannah-proto'` → `v2.agent.AgentMessage` | `import { v1 } from '@m1kad0/hannah-proto'` |
+| Go | `github.com/NurPech/hannah-proto-go/v5/hannahv2` | `github.com/NurPech/hannah-proto-go/v5/hannahv1` |
+
+CI rejects any change under `hannah/` outside `hannah/v2/` (deletions are allowed — that is how an old generation leaves).
+
+### What `hannah.v2` changes against `hannah.v1`
 
-CI rejects any change under `hannah/` outside `hannah/v1/`.
+- **Typed device model** (`hannah/v2/device_model.proto`): Hannah defines fixed device classes (`DeviceClass`) with slots (`SlotKind`, `Slot`, `SlotValue`) and their scales and units. The ioBroker adapter maps ioBroker objects onto them, normalizes the values and writes slot commands (`SetSlot`) back to the real states; Hannah Core never sees ioBroker state IDs for devices. The agent stream carries `TypedDeviceSnapshot`, `SlotUpdate` and `DeviceAvailability` (adapter → Core) and `SetSlot` (Core → adapter); `GetDevices`/`ControlDevice` work on slots.
+- **Removed:** the state-based device model (`AgentDevice`, `AgentDeviceSnapshot`, `canonical_key`, `StateType`, `EnumValues`), `AgentSetResident.presence_state`, all `reserved` entries and all `compat_version` options (a new generation starts at the implicit `1`). `AgentStateUpdate`, `AgentSetState` and `AgentWatchMore` stay for arbitrary watched states.
+- **Field numbers** of a changed message are not reused with another meaning inside the same lineage (`DeviceInfo`, `ControlDeviceRequest`), so bytes of one generation are never silently misread as the other. Between the generations, methods whose messages differ need a real translator, not a byte bridge.
 
 ## Versioning: PROTO_VERSION
 

package/dist/compat_interceptor.js

@@ -7,7 +7,7 @@ Object.defineProperty(exports, "DEFAULT_COMPAT_VERSION", { enumerable: true, get
 exports.COMPAT_VERSION_METADATA_KEY = "x-compat-version";
 /** `methodPath` is the full gRPC path (e.g. "/hannah.v1.HannahService/SubmitText"),
  * matching the keys gen-compat-versions.js writes into REQUIRED_COMPAT_VERSIONS —
- * the bare name would be ambiguous between hannah and hannah.v1. */
+ * the bare name would be ambiguous between hannah.v1 and hannah.v2. */
 function getRequiredCompatVersion(methodPath) {
     return compat_versions_1.REQUIRED_COMPAT_VERSIONS[methodPath] ?? compat_versions_1.DEFAULT_COMPAT_VERSION;
 }

package/dist/compat_versions.js

@@ -4,94 +4,6 @@ exports.REQUIRED_COMPAT_VERSIONS = exports.DEFAULT_COMPAT_VERSION = void 0;
 // Generated by scripts/gen-compat-versions.js — do not edit by hand.
 exports.DEFAULT_COMPAT_VERSION = 1;
 exports.REQUIRED_COMPAT_VERSIONS = {
-    "/hannah.HannahService/GetUsers": 1,
-    "/hannah.HannahService/GetUser": 1,
-    "/hannah.HannahService/LinkAccount": 1,
-    "/hannah.HannahService/UnlinkAccount": 1,
-    "/hannah.HannahService/CreateLinkToken": 1,
-    "/hannah.HannahService/SetTrustLevel": 1,
-    "/hannah.HannahService/SetSystemMessages": 1,
-    "/hannah.HannahService/SetAutomation": 1,
-    "/hannah.HannahService/Login": 1,
-    "/hannah.HannahService/CreateUser": 1,
-    "/hannah.HannahService/UpdateUser": 1,
-    "/hannah.HannahService/DeleteUser": 1,
-    "/hannah.HannahService/GetResidents": 1,
-    "/hannah.HannahService/GetDevices": 1,
-    "/hannah.HannahService/ControlDevice": 1,
-    "/hannah.HannahService/SubmitText": 1,
-    "/hannah.HannahService/SubmitVoice": 1,
-    "/hannah.HannahService/Announce": 1,
-    "/hannah.HannahService/Notify": 1,
-    "/hannah.HannahService/GetSatellites": 1,
-    "/hannah.HannahService/SetSatelliteRoom": 1,
-    "/hannah.HannahService/SetSatelliteDisplayName": 1,
-    "/hannah.HannahService/SetSatelliteOwner": 1,
-    "/hannah.HannahService/SetSatelliteSmalltalkFollowup": 1,
-    "/hannah.HannahService/DeleteSatellite": 1,
-    "/hannah.HannahService/GetRooms": 1,
-    "/hannah.HannahService/GetGroups": 1,
-    "/hannah.HannahService/CreateGroup": 1,
-    "/hannah.HannahService/UpdateGroup": 1,
-    "/hannah.HannahService/DeleteGroup": 1,
-    "/hannah.HannahService/SetGroupSatellites": 1,
-    "/hannah.HannahService/GetTriggers": 1,
-    "/hannah.HannahService/CreateTrigger": 2,
-    "/hannah.HannahService/UpdateTrigger": 2,
-    "/hannah.HannahService/DeleteTrigger": 1,
-    "/hannah.HannahService/GetAlarms": 1,
-    "/hannah.HannahService/CreateAlarm": 1,
-    "/hannah.HannahService/UpdateAlarm": 1,
-    "/hannah.HannahService/DeleteAlarm": 1,
-    "/hannah.HannahService/GetSettings": 1,
-    "/hannah.HannahService/UpdateConfig": 1,
-    "/hannah.HannahService/GetBleTags": 1,
-    "/hannah.HannahService/CreateBleTag": 1,
-    "/hannah.HannahService/UpdateBleTag": 1,
-    "/hannah.HannahService/DeleteBleTag": 1,
-    "/hannah.HannahService/GetPresenceSources": 1,
-    "/hannah.HannahService/CreatePresenceSource": 1,
-    "/hannah.HannahService/UpdatePresenceSource": 1,
-    "/hannah.HannahService/DeletePresenceSource": 1,
-    "/hannah.HannahService/GetCars": 1,
-    "/hannah.HannahService/CreateCar": 1,
-    "/hannah.HannahService/UpdateCar": 1,
-    "/hannah.HannahService/DeleteCar": 1,
-    "/hannah.HannahService/GetCarState": 1,
-    "/hannah.HannahService/GetAllCarStates": 1,
-    "/hannah.HannahService/SubscribeEvents": 1,
-    "/hannah.HannahService/TriggerFirmwareUpdate": 1,
-    "/hannah.HannahService/TriggerSatelliteRestart": 1,
-    "/hannah.HannahService/RequestSatelliteCapture": 1,
-    "/hannah.HannahService/ReleaseSatelliteCapture": 1,
-    "/hannah.HannahService/StreamSatelliteAudio": 1,
-    "/hannah.HannahService/TriggerPlink": 1,
-    "/hannah.HannahService/CollectorConnect": 2,
-    "/hannah.HannahService/TriggerCollectorCapture": 2,
-    "/hannah.HannahService/RegisterProxy": 1,
-    "/hannah.HannahService/SubmitSatelliteAudio": 3,
-    "/hannah.HannahService/NotifySatelliteRegistered": 1,
-    "/hannah.HannahService/NotifySatelliteGone": 1,
-    "/hannah.HannahService/ProvisionSatellite": 1,
-    "/hannah.HannahService/StartVoiceEnrollment": 1,
-    "/hannah.HannahService/EnrollVoiceprint": 1,
-    "/hannah.HannahService/TimerConnect": 1,
-    "/hannah.HannahService/GetTimers": 1,
-    "/hannah.HannahService/DeleteTimer": 1,
-    "/hannah.HannahService/AgentConnect": 1,
-    "/hannah.HannahService/AutomationConnect": 1,
-    "/hannah.HannahService/ChannelConnect": 1,
-    "/hannah.HannahService/GetChannels": 1,
-    "/hannah.HannahService/SubscribeInfrastructure": 1,
-    "/hannah.HannahService/LogCollectorConnect": 1,
-    "/hannah.HannahService/ListActivityLog": 1,
-    "/hannah.HannahService/StreamActivityAudio": 1,
-    "/hannah.HannahService/CreateMessage": 1,
-    "/hannah.HannahService/ListMessages": 1,
-    "/hannah.HannahService/DeleteMessage": 1,
-    "/hannah.LogService/Ship": 1,
-    "/hannah.LogService/GetSources": 1,
-    "/hannah.LogService/Export": 1,
     "/hannah.v1.HannahService/GetUsers": 1,
     "/hannah.v1.HannahService/GetUser": 1,
     "/hannah.v1.HannahService/LinkAccount": 1,
@@ -179,5 +91,93 @@ exports.REQUIRED_COMPAT_VERSIONS = {
     "/hannah.v1.HannahService/DeleteMessage": 1,
     "/hannah.v1.LogService/Ship": 1,
     "/hannah.v1.LogService/GetSources": 1,
-    "/hannah.v1.LogService/Export": 1
+    "/hannah.v1.LogService/Export": 1,
+    "/hannah.v2.HannahService/GetUsers": 1,
+    "/hannah.v2.HannahService/GetUser": 1,
+    "/hannah.v2.HannahService/LinkAccount": 1,
+    "/hannah.v2.HannahService/UnlinkAccount": 1,
+    "/hannah.v2.HannahService/CreateLinkToken": 1,
+    "/hannah.v2.HannahService/SetTrustLevel": 1,
+    "/hannah.v2.HannahService/SetSystemMessages": 1,
+    "/hannah.v2.HannahService/SetAutomation": 1,
+    "/hannah.v2.HannahService/Login": 1,
+    "/hannah.v2.HannahService/CreateUser": 1,
+    "/hannah.v2.HannahService/UpdateUser": 1,
+    "/hannah.v2.HannahService/DeleteUser": 1,
+    "/hannah.v2.HannahService/GetResidents": 1,
+    "/hannah.v2.HannahService/GetDevices": 1,
+    "/hannah.v2.HannahService/ControlDevice": 1,
+    "/hannah.v2.HannahService/SubmitText": 1,
+    "/hannah.v2.HannahService/SubmitVoice": 1,
+    "/hannah.v2.HannahService/Announce": 1,
+    "/hannah.v2.HannahService/Notify": 1,
+    "/hannah.v2.HannahService/GetSatellites": 1,
+    "/hannah.v2.HannahService/SetSatelliteRoom": 1,
+    "/hannah.v2.HannahService/SetSatelliteDisplayName": 1,
+    "/hannah.v2.HannahService/SetSatelliteOwner": 1,
+    "/hannah.v2.HannahService/SetSatelliteSmalltalkFollowup": 1,
+    "/hannah.v2.HannahService/DeleteSatellite": 1,
+    "/hannah.v2.HannahService/GetRooms": 1,
+    "/hannah.v2.HannahService/GetGroups": 1,
+    "/hannah.v2.HannahService/CreateGroup": 1,
+    "/hannah.v2.HannahService/UpdateGroup": 1,
+    "/hannah.v2.HannahService/DeleteGroup": 1,
+    "/hannah.v2.HannahService/SetGroupSatellites": 1,
+    "/hannah.v2.HannahService/GetTriggers": 1,
+    "/hannah.v2.HannahService/CreateTrigger": 1,
+    "/hannah.v2.HannahService/UpdateTrigger": 1,
+    "/hannah.v2.HannahService/DeleteTrigger": 1,
+    "/hannah.v2.HannahService/GetAlarms": 1,
+    "/hannah.v2.HannahService/CreateAlarm": 1,
+    "/hannah.v2.HannahService/UpdateAlarm": 1,
+    "/hannah.v2.HannahService/DeleteAlarm": 1,
+    "/hannah.v2.HannahService/GetSettings": 1,
+    "/hannah.v2.HannahService/UpdateConfig": 1,
+    "/hannah.v2.HannahService/GetBleTags": 1,
+    "/hannah.v2.HannahService/CreateBleTag": 1,
+    "/hannah.v2.HannahService/UpdateBleTag": 1,
+    "/hannah.v2.HannahService/DeleteBleTag": 1,
+    "/hannah.v2.HannahService/GetPresenceSources": 1,
+    "/hannah.v2.HannahService/CreatePresenceSource": 1,
+    "/hannah.v2.HannahService/UpdatePresenceSource": 1,
+    "/hannah.v2.HannahService/DeletePresenceSource": 1,
+    "/hannah.v2.HannahService/GetCars": 1,
+    "/hannah.v2.HannahService/CreateCar": 1,
+    "/hannah.v2.HannahService/UpdateCar": 1,
+    "/hannah.v2.HannahService/DeleteCar": 1,
+    "/hannah.v2.HannahService/GetCarState": 1,
+    "/hannah.v2.HannahService/GetAllCarStates": 1,
+    "/hannah.v2.HannahService/SubscribeEvents": 1,
+    "/hannah.v2.HannahService/TriggerFirmwareUpdate": 1,
+    "/hannah.v2.HannahService/TriggerSatelliteRestart": 1,
+    "/hannah.v2.HannahService/RequestSatelliteCapture": 1,
+    "/hannah.v2.HannahService/ReleaseSatelliteCapture": 1,
+    "/hannah.v2.HannahService/StreamSatelliteAudio": 1,
+    "/hannah.v2.HannahService/TriggerPlink": 1,
+    "/hannah.v2.HannahService/CollectorConnect": 1,
+    "/hannah.v2.HannahService/TriggerCollectorCapture": 1,
+    "/hannah.v2.HannahService/RegisterProxy": 1,
+    "/hannah.v2.HannahService/SubmitSatelliteAudio": 1,
+    "/hannah.v2.HannahService/NotifySatelliteRegistered": 1,
+    "/hannah.v2.HannahService/NotifySatelliteGone": 1,
+    "/hannah.v2.HannahService/ProvisionSatellite": 1,
+    "/hannah.v2.HannahService/StartVoiceEnrollment": 1,
+    "/hannah.v2.HannahService/EnrollVoiceprint": 1,
+    "/hannah.v2.HannahService/TimerConnect": 1,
+    "/hannah.v2.HannahService/GetTimers": 1,
+    "/hannah.v2.HannahService/DeleteTimer": 1,
+    "/hannah.v2.HannahService/AgentConnect": 1,
+    "/hannah.v2.HannahService/AutomationConnect": 1,
+    "/hannah.v2.HannahService/ChannelConnect": 1,
+    "/hannah.v2.HannahService/GetChannels": 1,
+    "/hannah.v2.HannahService/SubscribeInfrastructure": 1,
+    "/hannah.v2.HannahService/LogCollectorConnect": 1,
+    "/hannah.v2.HannahService/ListActivityLog": 1,
+    "/hannah.v2.HannahService/StreamActivityAudio": 1,
+    "/hannah.v2.HannahService/CreateMessage": 1,
+    "/hannah.v2.HannahService/ListMessages": 1,
+    "/hannah.v2.HannahService/DeleteMessage": 1,
+    "/hannah.v2.LogService/Ship": 1,
+    "/hannah.v2.LogService/GetSources": 1,
+    "/hannah.v2.LogService/Export": 1
 };

package/dist/index.d.ts

@@ -1,27 +1,6 @@
 export * from './version';
-export * as activity_log from './activity_log';
-export * as agent from './agent';
-export * as automation from './automation';
-export * as car_state from './car_state';
-export * as channel from './channel';
 export * as compat_interceptor from './compat_interceptor';
 export * as compat_versions from './compat_versions';
-export * as control from './control';
-export * as device_control_menu from './device_control_menu';
-export * as event_stream from './event_stream';
-export * as hannah from './hannah';
-export * as infrastructure from './infrastructure';
-export * as logging from './logging';
-export * as messages from './messages';
 export * as options from './options';
-export * as satellite from './satellite';
-export * as satellite_provisioning from './satellite_provisioning';
-export * as satellite_proxy from './satellite_proxy';
-export * as shared from './shared';
-export * as speaker_enrollment from './speaker_enrollment';
-export * as timer_admin from './timer_admin';
-export * as timer_service from './timer_service';
-export * as user_registry from './user_registry';
-export * as wakeword_capture from './wakeword_capture';
-export * as weather from './weather';
 export * as v1 from './v1';
+export * as v2 from './v2';

package/dist/index.js

@@ -36,31 +36,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.v1 = exports.weather = exports.wakeword_capture = exports.user_registry = exports.timer_service = exports.timer_admin = exports.speaker_enrollment = exports.shared = exports.satellite_proxy = exports.satellite_provisioning = exports.satellite = exports.options = exports.messages = exports.logging = exports.infrastructure = exports.hannah = exports.event_stream = exports.device_control_menu = exports.control = exports.compat_versions = exports.compat_interceptor = exports.channel = exports.car_state = exports.automation = exports.agent = exports.activity_log = void 0;
+exports.v2 = exports.v1 = exports.options = exports.compat_versions = exports.compat_interceptor = void 0;
 __exportStar(require("./version"), exports);
-exports.activity_log = __importStar(require("./activity_log"));
-exports.agent = __importStar(require("./agent"));
-exports.automation = __importStar(require("./automation"));
-exports.car_state = __importStar(require("./car_state"));
-exports.channel = __importStar(require("./channel"));
 exports.compat_interceptor = __importStar(require("./compat_interceptor"));
 exports.compat_versions = __importStar(require("./compat_versions"));
-exports.control = __importStar(require("./control"));
-exports.device_control_menu = __importStar(require("./device_control_menu"));
-exports.event_stream = __importStar(require("./event_stream"));
-exports.hannah = __importStar(require("./hannah"));
-exports.infrastructure = __importStar(require("./infrastructure"));
-exports.logging = __importStar(require("./logging"));
-exports.messages = __importStar(require("./messages"));
 exports.options = __importStar(require("./options"));
-exports.satellite = __importStar(require("./satellite"));
-exports.satellite_provisioning = __importStar(require("./satellite_provisioning"));
-exports.satellite_proxy = __importStar(require("./satellite_proxy"));
-exports.shared = __importStar(require("./shared"));
-exports.speaker_enrollment = __importStar(require("./speaker_enrollment"));
-exports.timer_admin = __importStar(require("./timer_admin"));
-exports.timer_service = __importStar(require("./timer_service"));
-exports.user_registry = __importStar(require("./user_registry"));
-exports.wakeword_capture = __importStar(require("./wakeword_capture"));
-exports.weather = __importStar(require("./weather"));
 exports.v1 = __importStar(require("./v1"));
+exports.v2 = __importStar(require("./v2"));

package/dist/{activity_log.d.ts → v2/activity_log.d.ts}

@@ -1,5 +1,5 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
-export declare const protobufPackage = "hannah";
+export declare const protobufPackage = "hannah.v2";
 export interface ActivityLogEntry {
     id: bigint;
     ts: string;

package/dist/{activity_log.js → v2/activity_log.js}

@@ -3,12 +3,12 @@
 // versions:
 //   protoc-gen-ts_proto  v2.12.1
 //   protoc               unknown
-// source: hannah/activity_log.proto
+// source: hannah/v2/activity_log.proto
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ActivityAudioChunk = exports.StreamActivityAudioRequest = exports.ListActivityLogResponse = exports.ListActivityLogRequest = exports.ActivityLogEntry = exports.protobufPackage = void 0;
 /* eslint-disable */
 const wire_1 = require("@bufbuild/protobuf/wire");
-exports.protobufPackage = "hannah";
+exports.protobufPackage = "hannah.v2";
 function createBaseActivityLogEntry() {
     return {
         id: 0n,

package/dist/{agent.d.ts → v2/agent.d.ts}

@@ -1,8 +1,8 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
-import { EnumValues, StateType } from "./shared";
+import { DeviceAvailability, SetSlot, SlotUpdate, TypedDeviceSnapshot } from "./device_model";
 import { CaptureMode, SampleType } from "./wakeword_capture";
 import { AgentWeatherUpdate } from "./weather";
-export declare const protobufPackage = "hannah";
+export declare const protobufPackage = "hannah.v2";
 export declare enum ResidentType {
     RESIDENT_TYPE_UNSPECIFIED = 0,
     ROOMIE = 1,
@@ -30,7 +30,7 @@ export declare enum ResidentPresenceAction {
 }
 /** Sent by the HannahAgent ioBroker adapter over the AgentConnect stream. */
 export interface AgentMessage {
-    /** any ioBroker state changed */
+    /** a watched ioBroker state changed (AgentWatchMore) */
     stateUpdate?: AgentStateUpdate | undefined;
     /** residents adapter presence changed */
     residentUpdate?: AgentResident | undefined;
@@ -38,8 +38,6 @@ export interface AgentMessage {
     textCommand?: AgentTextCommand | undefined;
     /** satellite control command */
     satelliteControl?: AgentSatelliteControl | undefined;
-    /** initial snapshot with all states */
-    sendSnapshot?: AgentDeviceSnapshot | undefined;
     /** initial snapshot with all residents */
     sendResidents?: AgentResidentSnapshot | undefined;
     /** ask Resident via Hannah */
@@ -47,6 +45,23 @@ export interface AgentMessage {
     /** full room catalog, independent of devices */
     sendRooms?: AgentRoomSnapshot | undefined;
     weatherUpdate?: AgentWeatherUpdate | undefined;
+    /**
+     * Typed device model (device_model.proto). The adapter maps ioBroker objects
+     * onto device classes and slots; Core never sees ioBroker state IDs for devices.
+     */
+    typedSnapshot?: TypedDeviceSnapshot | undefined;
+    /** a slot of a device changed */
+    slotUpdate?: SlotUpdate | undefined;
+    /** a device became (un)reachable */
+    deviceAvailability?: DeviceAvailability | undefined;
+    /**
+     * Set = the adapter asks Core to reply with an AgentAck carrying the same
+     * ack_id, listing the fields of this message Core's schema did not know.
+     * Unset = no ack. A Core too old for AgentAck ignores this field and never
+     * replies, so the adapter must treat a missing ack (after a timeout) as
+     * "not supported" (hannah-proto#16).
+     */
+    ackId?: bigint | undefined;
 }
 /**
  * Adapter instructs Hannah to control satellites in a room or a specific satellite.
@@ -84,12 +99,14 @@ export interface CaptureControl {
     stop: boolean;
 }
 /**
- * An ioBroker state change event. ack=true means the device confirmed the value
- * (as opposed to ack=false which is the "desired" value). Hannah uses this to
- * verify that a SetState command was executed successfully.
+ * A state change event for a state Hannah asked to watch (AgentWatchMore), e.g. the
+ * trigger engine's conditions. Devices are not reported this way, they use SlotUpdate.
+ * ack=true means the device confirmed the value (as opposed to ack=false which is the
+ * "desired" value). Hannah uses this to verify that a SetState command was executed
+ * successfully.
  */
 export interface AgentStateUpdate {
-    /** full ioBroker state ID, e.g. "javascript.0.virtualDevice.Licht.EG.Wohnzimmer.DeckeSeite.on" */
+    /** full ioBroker state ID, e.g. "0_userdata.0.feeded" */
     stateId: string;
     /** JSON-encoded value: "true", "42", "\"text\"" */
     value: string;
@@ -104,7 +121,7 @@ export interface AgentTextCommand {
 }
 /** Sent by Hannah Core over the AgentConnect stream. */
 export interface AgentCommand {
-    /** Hannah wants to control an ioBroker device */
+    /** Hannah wants to write an arbitrary ioBroker state (trigger actions) */
     setState?: AgentSetState | undefined;
     /** Hannah needs additional states streamed */
     watchMore?: AgentWatchMore | undefined;
@@ -126,6 +143,33 @@ export interface AgentCommand {
     satelliteDeleted?: AgentSatelliteDeleted | undefined;
     /** Hannah wants to set a resident's mood, independent of presence */
     setResidentMood?: AgentSetResidentMood | undefined;
+    /** reply to an AgentMessage that set ack_id */
+    ack?: AgentAck | undefined;
+    /** Hannah wants to control a slot of a typed device */
+    setSlot?: SetSlot | undefined;
+}
+/**
+ * Core's reply to an AgentMessage that set ack_id: which fields of that
+ * message (including nested messages) Core's schema did not know and
+ * therefore dropped. Empty unknown_fields = every field was known.
+ * Core guarantees that every field it does not report is also evaluated,
+ * so a security-relevant field never reads as supported without being
+ * enforced (hannah-proto#16).
+ */
+export interface AgentAck {
+    ackId: bigint;
+    unknownFields: UnknownFields[];
+}
+/**
+ * Unknown field numbers, aggregated per message type — a snapshot with many
+ * devices yields one entry for hannah.v2.TypedDevice, not one per device.
+ * An unknown oneof payload shows up as a field number on the enclosing message.
+ */
+export interface UnknownFields {
+    /** fully qualified name, e.g. "hannah.v2.TypedDevice" */
+    messageType: string;
+    /** deduplicated */
+    fieldNumbers: number[];
 }
 export interface AgentFirmwareEvent {
     device: string;
@@ -159,21 +203,10 @@ export interface AgentWatchMore {
 export interface AgentSetResident {
     /** e.g. "leonie", "hannah" */
     residentId: string;
-    /**
-     * Legacy absolute presence value (0=absent, 1=home, 2=night) — writes the combined
-     * presence.state, which cross-clobbers whichever of home/away/night Hannah didn't
-     * intend to change. Superseded by `action`; kept only for adapters older than
-     * compat_version 2, which don't understand `action` yet and ignore it entirely.
-     * Senders should populate both until those adapters are no longer in use.
-     *
-     * @deprecated
-     */
-    presenceState: number;
     type: ResidentType;
     /**
-     * Preferred over `presence_state`: sets only the single presence.{away,home,night}
-     * flag this action corresponds to, letting the residents adapter's own consistency
-     * guard handle the rest.
+     * Sets only the single presence.{away,home,night} flag this action corresponds to,
+     * letting the residents adapter's own consistency guard handle the rest.
      */
     action: ResidentPresenceAction;
 }
@@ -243,67 +276,11 @@ export interface AgentNotification {
     /** "alert" | "notify" | "info" — only used when direct=false */
     severity: string;
 }
-export interface AgentStateValue {
-    value: string;
-    ack: boolean;
-}
-/** A device from the ioBroker adapter */
-export interface AgentDevice {
-    stateId: string;
-    floor: string;
-    /** room_id: stable enum ID segment, e.g. "wohnzimmer" or "living_room" */
-    room: string;
-    device: string;
-    deviceType: string;
-    functions: string[];
-    value: AgentStateValue | undefined;
-    /** all display names from ioBroker enum, e.g. {"de": "Wohnzimmer", "en": "Living Room"} */
-    roomNames: {
-        [key: string]: string;
-    };
-    /** derived from ioBroker's common.type/role/states */
-    stateType: StateType;
-    /** only set when state_type is ENUM or COLOR */
-    enumValues: EnumValues | undefined;
-    /** derived from ioBroker's common.write */
-    writable: boolean;
-    /**
-     * Grouping ID for the device this state belongs to (the adapter's own
-     * `deviceId`, one path segment up from state_id) — lets Core group sibling
-     * states without guessing from state_id's path depth. Empty = adapter hasn't
-     * been updated yet; Core falls back to its own path-depth heuristic (hannah#257).
-     */
-    deviceId: string;
-    /**
-     * Semantic role of this specific state (e.g. "on", "level", "color", "current",
-     * "expected"), resolved by the adapter from the state's ioBroker common.role —
-     * same per-state basis as device_type, not aggregated across sibling states
-     * (a thermostat's "current" and "expected" states have different roles but
-     * belong to one device). Empty = adapter hasn't been updated yet or role is
-     * unresolvable; Core falls back to its iobroker.state_names default table
-     * (hannah#256, hannah#257).
-     */
-    canonicalKey: string;
-    /**
-     * Whether this device's actuator uses the inverted convention (0%=open,
-     * 100%=closed) instead of Hannah's default (0%=closed, 100%=open), e.g.
-     * some Homematic/KNX shutter/awning actuators. Unset = unknown/no override,
-     * not `false` (hannah-proto#4).
-     */
-    inverted?: boolean | undefined;
-}
-export interface AgentDevice_RoomNamesEntry {
-    key: string;
-    value: string;
-}
-/** a list with all known devices from the ioBroker adapter */
-export interface AgentDeviceSnapshot {
-    devices: AgentDevice[];
-}
 /**
  * A room from the ioBroker adapter's enum.rooms.* catalog — independent of devices,
  * so rooms without any device yet are still known to Hannah (e.g. before the first
- * satellite is provisioned into a brand-new room).
+ * satellite is provisioned into a brand-new room). TypedDevice.room refers to
+ * room_id, the display names live here only.
  */
 export interface AgentRoom {
     /** enum ID segment, e.g. "wohnzimmer" */
@@ -319,7 +296,7 @@ export interface AgentRoom_DisplayNamesEntry {
 }
 /**
  * Full room catalog from the ioBroker adapter. Sent on AgentConnect and whenever
- * enum.rooms.* changes, independent of AgentDeviceSnapshot.
+ * enum.rooms.* changes, independent of TypedDeviceSnapshot.
  */
 export interface AgentRoomSnapshot {
     rooms: AgentRoom[];
@@ -392,6 +369,8 @@ export declare const CaptureControl: MessageFns<CaptureControl>;
 export declare const AgentStateUpdate: MessageFns<AgentStateUpdate>;
 export declare const AgentTextCommand: MessageFns<AgentTextCommand>;
 export declare const AgentCommand: MessageFns<AgentCommand>;
+export declare const AgentAck: MessageFns<AgentAck>;
+export declare const UnknownFields: MessageFns<UnknownFields>;
 export declare const AgentFirmwareEvent: MessageFns<AgentFirmwareEvent>;
 export declare const AgentSetState: MessageFns<AgentSetState>;
 export declare const AgentWatchMore: MessageFns<AgentWatchMore>;
@@ -401,10 +380,6 @@ export declare const AgentSatelliteUpdate: MessageFns<AgentSatelliteUpdate>;
 export declare const AgentSatelliteDeleted: MessageFns<AgentSatelliteDeleted>;
 export declare const AgentTextAnswer: MessageFns<AgentTextAnswer>;
 export declare const AgentNotification: MessageFns<AgentNotification>;
-export declare const AgentStateValue: MessageFns<AgentStateValue>;
-export declare const AgentDevice: MessageFns<AgentDevice>;
-export declare const AgentDevice_RoomNamesEntry: MessageFns<AgentDevice_RoomNamesEntry>;
-export declare const AgentDeviceSnapshot: MessageFns<AgentDeviceSnapshot>;
 export declare const AgentRoom: MessageFns<AgentRoom>;
 export declare const AgentRoom_DisplayNamesEntry: MessageFns<AgentRoom_DisplayNamesEntry>;
 export declare const AgentRoomSnapshot: MessageFns<AgentRoomSnapshot>;