@m1kad0/hannah-proto 4.5.0 → 4.6.0

package/dist/v1/agent.d.ts

@@ -0,0 +1,433 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+import { EnumValues, StateType } from "./shared";
+import { CaptureMode, SampleType } from "./wakeword_capture";
+import { AgentWeatherUpdate } from "./weather";
+export declare const protobufPackage = "hannah.v1";
+export declare enum ResidentType {
+    RESIDENT_TYPE_UNSPECIFIED = 0,
+    ROOMIE = 1,
+    GUEST = 2,
+    PET = 3,
+    UNRECOGNIZED = -1
+}
+/**
+ * Which single presence aspect to set. The residents adapter's presence.{away,home,night}
+ * datapoints guard their own cross-consistency (e.g. setting "away" true automatically
+ * flips "home" false) — Hannah only needs to name the aspect it actually has an opinion
+ * about, instead of writing the whole combined presence.state value (hannah#309, root
+ * cause of hannah#299: two independent Hannah-side decisions, home/away presence fusion
+ * and an explicit asleep/awake trigger, collapsed onto one write and could clobber each
+ * other's information). SET_AWAKE has no direct presence.state equivalent — it only
+ * clears "night" and leaves "home" untouched, regardless of its current value.
+ */
+export declare enum ResidentPresenceAction {
+    RESIDENT_PRESENCE_ACTION_UNSPECIFIED = 0,
+    AWAY = 1,
+    HOME = 2,
+    ASLEEP = 3,
+    AWAKE = 4,
+    UNRECOGNIZED = -1
+}
+/** Sent by the HannahAgent ioBroker adapter over the AgentConnect stream. */
+export interface AgentMessage {
+    /** any ioBroker state changed */
+    stateUpdate?: AgentStateUpdate | undefined;
+    /** residents adapter presence changed */
+    residentUpdate?: AgentResident | undefined;
+    /** text command state changed */
+    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 */
+    askResident?: AgentAskResident | undefined;
+    /** full room catalog, independent of devices */
+    sendRooms?: AgentRoomSnapshot | undefined;
+    weatherUpdate?: AgentWeatherUpdate | undefined;
+}
+/**
+ * Adapter instructs Hannah to control satellites in a room or a specific satellite.
+ * room: room_id (enum ID segment) or "all" for all rooms.
+ * device_id: if non-empty, only the named satellite is targeted (volume/mute/capture only);
+ *            room is still required (used for room-scoped commands and as fallback).
+ *            For capture, device_id is mandatory — never room-broadcast.
+ */
+export interface AgentSatelliteControl {
+    room: string;
+    /** optional: target a specific satellite instead of the whole room */
+    deviceId: string;
+    /** set do-not-disturb */
+    dnd?: boolean | undefined;
+    /** mute/unmute microphone */
+    mute?: boolean | undefined;
+    /** set volume (0–100) */
+    volume?: number | undefined;
+    /** speak plain-text announcement (verbatim) */
+    announcement?: string | undefined;
+    /** speak SSML announcement */
+    announcementSsml?: string | undefined;
+    /** speak announcement, text rephrased by LLM first */
+    announcementRephrase?: string | undefined;
+    /** start/stop a Voice Collector capture on this satellite */
+    capture?: CaptureControl | undefined;
+}
+/**
+ * Start or stop a Voice Collector capture — the AgentSatelliteControl counterpart
+ * to CaptureCommand, routed to the satellite named by AgentSatelliteControl.device_id.
+ */
+export interface CaptureControl {
+    sampleType: SampleType | undefined;
+    captureMode: CaptureMode;
+    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.
+ */
+export interface AgentStateUpdate {
+    /** full ioBroker state ID, e.g. "javascript.0.virtualDevice.Licht.EG.Wohnzimmer.DeckeSeite.on" */
+    stateId: string;
+    /** JSON-encoded value: "true", "42", "\"text\"" */
+    value: string;
+    /** true = confirmed by device */
+    ack: boolean;
+    /** Unix timestamp in milliseconds */
+    ts: bigint;
+}
+/** The text-command state in ioBroker changed — treat as a SubmitText call. */
+export interface AgentTextCommand {
+    text: string;
+}
+/** Sent by Hannah Core over the AgentConnect stream. */
+export interface AgentCommand {
+    /** Hannah wants to control an ioBroker device */
+    setState?: AgentSetState | undefined;
+    /** Hannah needs additional states streamed */
+    watchMore?: AgentWatchMore | undefined;
+    /** Hannah wants to set a resident's presence state */
+    setResident?: AgentSetResident | undefined;
+    /** a satellite registered or disconnected */
+    satelliteUpdate?: AgentSatelliteUpdate | undefined;
+    /** Hannah's answer to a text command */
+    textAnswer?: AgentTextAnswer | undefined;
+    /** satellite firmware version update */
+    firmwareEvent?: AgentFirmwareEvent | undefined;
+    /** BLE tag location changed */
+    bleUpdate?: AgentBleUpdate | undefined;
+    /** satellite sensor reading */
+    sensorUpdate?: AgentSensorUpdate | undefined;
+    /** answer to an ask_resident request */
+    residentAnswered?: AgentResidentAnswered | undefined;
+    /** Hannah Core deleted a satellite — adapter must remove its object tree */
+    satelliteDeleted?: AgentSatelliteDeleted | undefined;
+    /** Hannah wants to set a resident's mood, independent of presence */
+    setResidentMood?: AgentSetResidentMood | undefined;
+}
+export interface AgentFirmwareEvent {
+    device: string;
+    version: string;
+    /** true = newer version pending, false = current version report */
+    updateAvailable: boolean;
+}
+/**
+ * Hannah instructs the adapter to set an ioBroker state.
+ * The adapter calls setForeignState(); the resulting ack=true AgentStateUpdate
+ * confirms execution back to Hannah.
+ */
+export interface AgentSetState {
+    /** ioBroker state ID to write */
+    stateId: string;
+    /** JSON-encoded value */
+    value: string;
+}
+/**
+ * Hannah requests additional state IDs to be included in the AgentStateUpdate stream.
+ * Used by the trigger engine at runtime when triggers reference arbitrary state IDs
+ * (e.g. unless.state: "0_userdata.0.feeded") that aren't covered by enum discovery.
+ */
+export interface AgentWatchMore {
+    stateIds: string[];
+}
+/**
+ * Hannah instructs the adapter to set a resident's presence state in the residents adapter.
+ * type determines whether the target path is .roomie./.guest./.pet.
+ */
+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.
+     */
+    action: ResidentPresenceAction;
+}
+/**
+ * Hannah instructs the adapter to set a resident's mood — separate command from
+ * AgentSetResident so it can fire independent of any presence change (e.g. when a
+ * Hannah User's linked mood changes without an arrival/departure).
+ */
+export interface AgentSetResidentMood {
+    /** e.g. "leonie", "hannah" */
+    residentId: string;
+    mood: number;
+    type: ResidentType;
+}
+/**
+ * Hannah notifies the adapter that a satellite registered or disconnected,
+ * or that a satellite's volume or mute state changed.
+ * The adapter updates hannah.<instance>.satellites.rooms.<room_id>.* states accordingly.
+ */
+export interface AgentSatelliteUpdate {
+    /** satellite device_id (== eFuse MAC since v0.34); adapter uses as ioBroker object-ID */
+    deviceId: string;
+    /** room_id: stable enum ID segment (e.g. "wohnzimmer"); adapter uses as ioBroker path segment */
+    room: string;
+    /** UDP address (empty if not applicable) */
+    address: string;
+    /** true = registered/online, false = gone/offline */
+    online: boolean;
+    /** current volume level (0–100); absent = no change */
+    volume?: number | undefined;
+    /** current mute state; absent = no change */
+    mute?: boolean | undefined;
+    /** human-readable name from Core DB (empty = fall back to device_id) */
+    displayName: string;
+    /** current do-not-disturb state; absent = no change */
+    dnd?: boolean | undefined;
+}
+/**
+ * Hannah Core deleted a satellite (RoomManager.delete_satellite()) — the adapter
+ * must remove the satellite's full object tree (and its sensor tree), mirroring
+ * the room cleanup AgentSatelliteUpdate already does for online/offline changes.
+ */
+export interface AgentSatelliteDeleted {
+    /** satellite device_id being deleted */
+    deviceId: string;
+    /** room_id the satellite was assigned to, for room-container cleanup */
+    room: string;
+}
+/**
+ * Hannah sends the answer to a text command back to the adapter.
+ * The adapter sets hannah.<instance>.textAnswer accordingly.
+ */
+export interface AgentTextAnswer {
+    /** plain-text answer */
+    text: string;
+    /** detected intent name */
+    intent: string;
+}
+/**
+ * A notification from the ioBroker adapter.
+ * direct=true: skip LLM, play text unchanged (severity ignored).
+ * direct=false: LLM reformulates text; severity controls tone ("alert"|"notify"|"info").
+ */
+export interface AgentNotification {
+    text: string;
+    direct: boolean;
+    /** "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).
+ */
+export interface AgentRoom {
+    /** enum ID segment, e.g. "wohnzimmer" */
+    roomId: string;
+    /** all display names from ioBroker enum, e.g. {"de": "Wohnzimmer", "en": "Living Room"} */
+    displayNames: {
+        [key: string]: string;
+    };
+}
+export interface AgentRoom_DisplayNamesEntry {
+    key: string;
+    value: string;
+}
+/**
+ * Full room catalog from the ioBroker adapter. Sent on AgentConnect and whenever
+ * enum.rooms.* changes, independent of AgentDeviceSnapshot.
+ */
+export interface AgentRoomSnapshot {
+    rooms: AgentRoom[];
+}
+/** A resident from the ioBroker adapter */
+export interface AgentResident {
+    roomieId: string;
+    name?: string | undefined;
+    type: ResidentType;
+    moodLevel?: number | undefined;
+    presenceState?: number | undefined;
+}
+/** a list with all known residents */
+export interface AgentResidentSnapshot {
+    residents: AgentResident[];
+}
+export interface AgentAskResident {
+    correlationId: string;
+    room: string;
+    question: string;
+}
+export interface AgentResidentAnswered {
+    correlationId: string;
+    answer: string;
+}
+/**
+ * Hannah notifies the adapter that a BLE tag's location has changed.
+ * The adapter creates/updates states under hannah.<instance>.ble.<label>.*.
+ * room and satellite are empty when the tag is no longer visible.
+ */
+export interface AgentBleUpdate {
+    /** human-readable tag name (from config, used as state path) */
+    label: string;
+    /** MAC address (lowercase, colon-separated) */
+    mac: string;
+    /** room name (empty = tag not visible / stale) */
+    room: string;
+    /** satellite device ID that last detected the tag */
+    satellite: string;
+    /** last known RSSI in dBm (0 when room is empty) */
+    rssi: number;
+}
+/**
+ * Hannah notifies the adapter of a satellite's sensor reading.
+ * The adapter creates/updates states under hannah.<instance>.satellites.<device>.sensors.*.
+ * gas_resistance is omitted (0.0) when not available (BMP280+AHT20 hardware).
+ * iaq/co2_equiv/voc_equiv are omitted (0.0) when BSEC2 is not calibrated yet.
+ */
+export interface AgentSensorUpdate {
+    /** satellite device ID */
+    device: string;
+    /** °C */
+    temperature: number;
+    /** hPa */
+    pressure: number;
+    /** % relative humidity (0 when not available) */
+    humidity: number;
+    /** IAQ 0–500 (BSEC2); 0 when not calibrated */
+    iaq: number;
+    /** 0=uncertain 1=low 2=medium 3=high */
+    iaqAccuracy: number;
+    /** CO₂ equivalent ppm (BSEC2); 0 when not available */
+    co2Equiv: number;
+    /** breath VOC equivalent ppm (BSEC2); 0 when not available */
+    vocEquiv: number;
+}
+export declare const AgentMessage: MessageFns<AgentMessage>;
+export declare const AgentSatelliteControl: MessageFns<AgentSatelliteControl>;
+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 AgentFirmwareEvent: MessageFns<AgentFirmwareEvent>;
+export declare const AgentSetState: MessageFns<AgentSetState>;
+export declare const AgentWatchMore: MessageFns<AgentWatchMore>;
+export declare const AgentSetResident: MessageFns<AgentSetResident>;
+export declare const AgentSetResidentMood: MessageFns<AgentSetResidentMood>;
+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>;
+export declare const AgentResident: MessageFns<AgentResident>;
+export declare const AgentResidentSnapshot: MessageFns<AgentResidentSnapshot>;
+export declare const AgentAskResident: MessageFns<AgentAskResident>;
+export declare const AgentResidentAnswered: MessageFns<AgentResidentAnswered>;
+export declare const AgentBleUpdate: MessageFns<AgentBleUpdate>;
+export declare const AgentSensorUpdate: MessageFns<AgentSensorUpdate>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | bigint | undefined;
+export type DeepPartial<T> = T extends bigint ? string | number | bigint : T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};