@etazio/agent-sdk 0.1.0

package/types/shared/agents.d.ts

@@ -0,0 +1,689 @@
+import { z } from 'zod';
+import { type AvatarProfile } from './avatar.js';
+/**
+ * KI-Agenten als Teilnehmer im Office (SPA-66, `specs/agents-spec.md`).
+ *
+ * Ein Agent ist ein Client wie der Browser: dieselben Socket-Ereignisse, eigene Identität, eigener
+ * Berechtigungsumfang. Die Rollenmatrix (`roles.ts`) bleibt für Menschen – Agenten haben eine eigene,
+ * additive Scope-Liste, die serverseitig an genau einer Stelle geprüft wird (`World.mayDo`).
+ */
+/** Versionierter Protokollname; Breaking Changes nur über eine neue Version. */
+export declare const AGENT_PROTOCOL = "agent-protocol/v1";
+/** Erkennbares Präfix des Agent-Tokens (wie `sk-`-Muster anderer Dienste). */
+export declare const AGENT_TOKEN_PREFIX = "hag_";
+export declare const AGENT_SCOPES: readonly ['office.read', 'world.presence', 'world.move', 'world.seat', 'world.react', 'chat.read', 'chat.write', 'object.state', 'object.action', 'board.write', 'tv.control', 'zone.knock', 'meeting.audio', 'voice.listen', 'voice.speak', 'tools.use'];
+export type AgentScope = (typeof AGENT_SCOPES)[number];
+/** Beschreibung je Scope – Admin-UI und Doku lesen dieselbe Tabelle. */
+export declare const AGENT_SCOPE_LABELS: Record<AgentScope, string>;
+/** Vorschlag für neue Agenten: sehen, gehen, reden – alles Weitere wird bewusst vergeben. */
+export declare const AGENT_DEFAULT_SCOPES: AgentScope[];
+export declare function hasScope(scopes: readonly AgentScope[] | null | undefined, scope: AgentScope): boolean;
+export declare const AGENT_LIMITS: {
+    /** Agenten je Workspace */
+    readonly perWorkspace: 10;
+    /** Gleichzeitige Verbindungen je Agent */
+    readonly connections: 4;
+    /** Chat-Nachrichten je Minute */
+    readonly chatPerMinute: 30;
+    /** Bewegungsbefehle (`agent:goTo`) je Minute */
+    readonly goToPerMinute: 20;
+    /** Objektzustände je Sekunde */
+    readonly statePerSecond: 10;
+    /** Objektaktionen je Sekunde */
+    readonly actionsPerSecond: 5;
+    /** Reaktionen je Sekunde */
+    readonly reactPerSecond: 2;
+    /** Ereignisse insgesamt je Sekunde (harte Klammer über allem) */
+    readonly eventsPerSecond: 40;
+    /** So oft darf ein Agent gedrosselt werden, bevor die Verbindung fällt */
+    readonly throttleStrikes: 5;
+    /** Ohne Lebenszeichen gilt eine Verbindung als hängend (ms) */
+    readonly idleMs: number;
+    readonly maxName: 60;
+    readonly maxDescription: 400;
+    /** Zonen, auf die ein Agent hören kann */
+    readonly maxZones: 20;
+    /** Gleichzeitige Sprachsitzungen je Agent */
+    readonly voiceSessions: 3;
+    /** Gleichzeitige Sprachsitzungen je Workspace (über alle Agenten) */
+    readonly voiceSessionsPerWorkspace: 6;
+    /** Gesprochene Sekunden je Minute und Agent – darüber wird gedrosselt */
+    readonly voiceSecondsPerMinute: 45;
+    /** Stille im Gespräch, nach der der Server die Sitzung beendet (ms) */
+    readonly voiceIdleMs: 45000;
+    /** Harte Obergrenze für eine einzelne Sprachsitzung (ms) */
+    readonly voiceMaxSessionMs: number;
+    /** Zustandsmeldungen des Agenten je Sekunde (`agent:voice:state`) */
+    readonly voiceStatePerSecond: 10;
+    /** Externe Werkzeugaufrufe je Minute und Agent */
+    readonly toolCallsPerMinute: 20;
+    /** Aufrufe desselben externen Werkzeugs je Minute und Agent */
+    readonly toolCallsPerToolPerMinute: 10;
+    /** Verbindungen, die ein Workspace verwalten darf */
+    readonly connectionsPerWorkspace: 20;
+};
+/** Grund einer Drosselung – der Agent bekommt ihn als `agent:throttled`. */
+export type AgentThrottleReason = 'chat' | 'goto' | 'state' | 'action' | 'react' | 'events' | 'voice' | 'tool';
+export declare const AGENT_CAPABILITIES: readonly ['chat', 'voice', 'board', 'tv', 'move'];
+export type AgentCapability = (typeof AGENT_CAPABILITIES)[number];
+/** Wie ein Mensch den Agenten erreicht (alle Wege erzeugen `agent:address`). */
+export interface AgentAddressing {
+    /** `@Name` im Chat */
+    mention: boolean;
+    /** Hingehen und `E` drücken */
+    proximity: boolean;
+    /** Betreten einer dieser Zonen meldet den Ankömmling */
+    zones: string[];
+    /** Ansprache am eigenen Arbeitsplatz */
+    desk: boolean;
+}
+export type AgentOperator = 'intern' | 'extern';
+export type AgentStatus = 'active' | 'disabled';
+export declare const AGENT_CONNECTION_KINDS: readonly ['mcp-http', 'notion', 'google'];
+export type AgentConnectionKind = (typeof AGENT_CONNECTION_KINDS)[number];
+export declare const AGENT_CONNECTION_KIND_LABELS: Record<AgentConnectionKind, string>;
+export declare const AGENT_TOOL_ACCESS: readonly ['read', 'read-write'];
+export type AgentToolAccess = (typeof AGENT_TOOL_ACCESS)[number];
+export declare const AGENT_CONNECTION_AUTH: readonly ['none', 'token', 'oauth'];
+export type AgentConnectionAuth = (typeof AGENT_CONNECTION_AUTH)[number];
+export interface AgentToolSummary {
+    name: string;
+    title: string | null;
+    description: string | null;
+    /** Ohne ausdrücklichen readOnly-Hinweis gilt ein Werkzeug vorsichtshalber als schreibend. */
+    readOnly: boolean;
+}
+export interface AgentConnectionDto {
+    id: string;
+    workspaceId: string;
+    kind: AgentConnectionKind;
+    auth: AgentConnectionAuth;
+    name: string;
+    url: string;
+    status: 'active' | 'disabled';
+    hasCredentials: boolean;
+    oauthConnected: boolean;
+    tools: AgentToolSummary[];
+    lastCheckedAt: string | null;
+    lastUsedAt: string | null;
+    lastError: string | null;
+    createdAt: string;
+}
+/** Installierbarer Remote-Server aus der offiziellen MCP Registry. */
+export interface AgentMarketplaceItem {
+    /** Stabiler Registry-Name, z. B. `com.notion/mcp`. */
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    auth: AgentConnectionAuth;
+    version: string;
+    websiteUrl: string | null;
+    repositoryUrl: string | null;
+}
+export interface AgentToolGrant {
+    connectionId: string;
+    access: AgentToolAccess;
+    /** Leer bedeutet: alle Werkzeuge der Verbindung, unter Beachtung von `access`. */
+    tools: string[];
+}
+export interface AgentDto {
+    id: string;
+    workspaceId: string;
+    name: string;
+    description: string;
+    operator: AgentOperator;
+    endpointUrl: string | null;
+    scopes: AgentScope[];
+    capabilities: AgentCapability[];
+    toolGrants: AgentToolGrant[];
+    addressing: AgentAddressing;
+    avatar: AvatarProfile;
+    homeDeskId: string | null;
+    status: AgentStatus;
+    /** Sichtbarer Anfang des Tokens (`hag_ab12cd34…`) – nie das Token selbst */
+    tokenPrefix: string;
+    tokenRotatedAt: string | null;
+    lastSeenAt: string | null;
+    lastError: string | null;
+    /** Verbindungen gerade offen */
+    online: boolean;
+    createdAt: string;
+}
+/** Antwort beim Anlegen/Rotieren: das Token ist genau hier einmal sichtbar. */
+export interface AgentSecretDto {
+    agent: AgentDto;
+    token: string;
+}
+export declare const agentNameSchema: z.ZodString;
+export declare const agentScopeSchema: z.ZodEnum<{
+    "board.write": "board.write";
+    "chat.read": "chat.read";
+    "chat.write": "chat.write";
+    "meeting.audio": "meeting.audio";
+    "object.action": "object.action";
+    "object.state": "object.state";
+    "office.read": "office.read";
+    "tools.use": "tools.use";
+    "tv.control": "tv.control";
+    "voice.listen": "voice.listen";
+    "voice.speak": "voice.speak";
+    "world.move": "world.move";
+    "world.presence": "world.presence";
+    "world.react": "world.react";
+    "world.seat": "world.seat";
+    "zone.knock": "zone.knock";
+}>;
+export declare const agentCapabilitySchema: z.ZodEnum<{
+    board: "board";
+    chat: "chat";
+    move: "move";
+    tv: "tv";
+    voice: "voice";
+}>;
+export declare const agentIdSchema: z.ZodString;
+export declare const agentAddressingSchema: z.ZodObject<{
+    mention: z.ZodDefault<z.ZodBoolean>;
+    proximity: z.ZodDefault<z.ZodBoolean>;
+    zones: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    desk: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Fremdagenten dürfen nur https-Endpunkte hinterlegen (reserviert für die Webhook-Zustellung). */
+export declare const agentEndpointSchema: z.ZodString;
+export declare const createAgentSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    operator: z.ZodDefault<z.ZodEnum<{
+        extern: "extern";
+        intern: "intern";
+    }>>;
+    endpointUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "board.write": "board.write";
+        "chat.read": "chat.read";
+        "chat.write": "chat.write";
+        "meeting.audio": "meeting.audio";
+        "object.action": "object.action";
+        "object.state": "object.state";
+        "office.read": "office.read";
+        "tools.use": "tools.use";
+        "tv.control": "tv.control";
+        "voice.listen": "voice.listen";
+        "voice.speak": "voice.speak";
+        "world.move": "world.move";
+        "world.presence": "world.presence";
+        "world.react": "world.react";
+        "world.seat": "world.seat";
+        "zone.knock": "zone.knock";
+    }>>>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        board: "board";
+        chat: "chat";
+        move: "move";
+        tv: "tv";
+        voice: "voice";
+    }>>>;
+    addressing: z.ZodPrefault<z.ZodObject<{
+        mention: z.ZodDefault<z.ZodBoolean>;
+        proximity: z.ZodDefault<z.ZodBoolean>;
+        zones: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        desk: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    avatar: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        rigVersion: z.ZodDefault<z.ZodLiteral<2>>;
+        body: z.ZodDefault<z.ZodEnum<{
+            broad: "broad";
+            slim: "slim";
+            standard: "standard";
+        }>>;
+        height: z.ZodDefault<z.ZodEnum<{
+            medium: "medium";
+            short: "short";
+            tall: "tall";
+        }>>;
+        hair: z.ZodDefault<z.ZodEnum<{
+            bun: "bun";
+            long: "long";
+            none: "none";
+            short: "short";
+        }>>;
+        top: z.ZodDefault<z.ZodEnum<{
+            hoodie: "hoodie";
+            longsleeve: "longsleeve";
+            tshirt: "tshirt";
+        }>>;
+        accessories: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            cap: "cap";
+            glasses: "glasses";
+            headphones: "headphones";
+        }>>>;
+        colors: z.ZodPrefault<z.ZodObject<{
+            skin: z.ZodDefault<z.ZodString>;
+            hair: z.ZodDefault<z.ZodString>;
+            shirt: z.ZodDefault<z.ZodString>;
+            pants: z.ZodDefault<z.ZodString>;
+            shoes: z.ZodDefault<z.ZodString>;
+            accent: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodTransform<{
+        rigVersion: 2;
+        body: "broad" | "slim" | "standard";
+        height: "medium" | "short" | "tall";
+        hair: "bun" | "long" | "none" | "short";
+        top: "hoodie" | "longsleeve" | "tshirt";
+        colors: {
+            skin: string;
+            hair: string;
+            shirt: string;
+            pants: string;
+            shoes: string;
+            accent: string;
+        };
+        accessories: ("cap" | "glasses" | "headphones")[];
+    }, {
+        rigVersion: 2;
+        body: "broad" | "slim" | "standard";
+        height: "medium" | "short" | "tall";
+        hair: "bun" | "long" | "none" | "short";
+        top: "hoodie" | "longsleeve" | "tshirt";
+        accessories: ("cap" | "glasses" | "headphones")[];
+        colors: {
+            skin: string;
+            hair: string;
+            shirt: string;
+            pants: string;
+            shoes: string;
+            accent: string;
+        };
+    }>>>;
+    homeDeskId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type CreateAgentInput = z.output<typeof createAgentSchema>;
+export declare const updateAgentSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodDefault<z.ZodString>>;
+    operator: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        extern: "extern";
+        intern: "intern";
+    }>>>;
+    endpointUrl: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
+    scopes: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "board.write": "board.write";
+        "chat.read": "chat.read";
+        "chat.write": "chat.write";
+        "meeting.audio": "meeting.audio";
+        "object.action": "object.action";
+        "object.state": "object.state";
+        "office.read": "office.read";
+        "tools.use": "tools.use";
+        "tv.control": "tv.control";
+        "voice.listen": "voice.listen";
+        "voice.speak": "voice.speak";
+        "world.move": "world.move";
+        "world.presence": "world.presence";
+        "world.react": "world.react";
+        "world.seat": "world.seat";
+        "zone.knock": "zone.knock";
+    }>>>>;
+    capabilities: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        board: "board";
+        chat: "chat";
+        move: "move";
+        tv: "tv";
+        voice: "voice";
+    }>>>>;
+    addressing: z.ZodOptional<z.ZodPrefault<z.ZodObject<{
+        mention: z.ZodDefault<z.ZodBoolean>;
+        proximity: z.ZodDefault<z.ZodBoolean>;
+        zones: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        desk: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    avatar: z.ZodOptional<z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        rigVersion: z.ZodDefault<z.ZodLiteral<2>>;
+        body: z.ZodDefault<z.ZodEnum<{
+            broad: "broad";
+            slim: "slim";
+            standard: "standard";
+        }>>;
+        height: z.ZodDefault<z.ZodEnum<{
+            medium: "medium";
+            short: "short";
+            tall: "tall";
+        }>>;
+        hair: z.ZodDefault<z.ZodEnum<{
+            bun: "bun";
+            long: "long";
+            none: "none";
+            short: "short";
+        }>>;
+        top: z.ZodDefault<z.ZodEnum<{
+            hoodie: "hoodie";
+            longsleeve: "longsleeve";
+            tshirt: "tshirt";
+        }>>;
+        accessories: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            cap: "cap";
+            glasses: "glasses";
+            headphones: "headphones";
+        }>>>;
+        colors: z.ZodPrefault<z.ZodObject<{
+            skin: z.ZodDefault<z.ZodString>;
+            hair: z.ZodDefault<z.ZodString>;
+            shirt: z.ZodDefault<z.ZodString>;
+            pants: z.ZodDefault<z.ZodString>;
+            shoes: z.ZodDefault<z.ZodString>;
+            accent: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodTransform<{
+        rigVersion: 2;
+        body: "broad" | "slim" | "standard";
+        height: "medium" | "short" | "tall";
+        hair: "bun" | "long" | "none" | "short";
+        top: "hoodie" | "longsleeve" | "tshirt";
+        colors: {
+            skin: string;
+            hair: string;
+            shirt: string;
+            pants: string;
+            shoes: string;
+            accent: string;
+        };
+        accessories: ("cap" | "glasses" | "headphones")[];
+    }, {
+        rigVersion: 2;
+        body: "broad" | "slim" | "standard";
+        height: "medium" | "short" | "tall";
+        hair: "bun" | "long" | "none" | "short";
+        top: "hoodie" | "longsleeve" | "tshirt";
+        accessories: ("cap" | "glasses" | "headphones")[];
+        colors: {
+            skin: string;
+            hair: string;
+            shirt: string;
+            pants: string;
+            shoes: string;
+            accent: string;
+        };
+    }>>>>;
+    homeDeskId: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>;
+}, z.core.$strip>;
+export type UpdateAgentInput = z.output<typeof updateAgentSchema>;
+export declare const workspaceAgentSettingsSchema: z.ZodObject<{
+    externalAgentsDisabled: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const createAgentConnectionSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<{
+        google: "google";
+        "mcp-http": "mcp-http";
+        notion: "notion";
+    }>>;
+    name: z.ZodString;
+    url: z.ZodString;
+    auth: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        oauth: "oauth";
+        token: "token";
+    }>>;
+    token: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>;
+}, z.core.$strip>;
+export type CreateAgentConnectionInput = z.output<typeof createAgentConnectionSchema>;
+export declare const updateAgentConnectionSchema: z.ZodObject<{
+    kind: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        google: "google";
+        "mcp-http": "mcp-http";
+        notion: "notion";
+    }>>>;
+    name: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    auth: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        oauth: "oauth";
+        token: "token";
+    }>>>;
+    token: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    headers: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    status: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>>;
+}, z.core.$strip>;
+export type UpdateAgentConnectionInput = z.output<typeof updateAgentConnectionSchema>;
+export declare const agentToolGrantSchema: z.ZodObject<{
+    access: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        "read-write": "read-write";
+    }>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AgentToolGrantInput = z.output<typeof agentToolGrantSchema>;
+export declare const agentHelloSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"agent-protocol/v1">;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        board: "board";
+        chat: "chat";
+        move: "move";
+        tv: "tv";
+        voice: "voice";
+    }>>>;
+    client: z.ZodPrefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        version: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    participantId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentHelloInput = z.output<typeof agentHelloSchema>;
+/** Ziel eines Laufbefehls: Punkt, Zone oder ein anderer Teilnehmer. */
+export declare const agentGoToSchema: z.ZodUnion<readonly [z.ZodObject<{
+    x: z.ZodNumber;
+    z: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    zoneId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    participantId: z.ZodString;
+}, z.core.$strip>]>;
+export type AgentGoToInput = z.output<typeof agentGoToSchema>;
+export declare const agentMeetingTokenSchema: z.ZodObject<{
+    target: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"office">, z.ZodString]>>;
+}, z.core.$strip>;
+/** Mensch spricht einen Agenten an (Browser → Server) – Hingehen + `E` oder Personen-Menü. */
+export declare const agentInvokeSchema: z.ZodObject<{
+    agentParticipantId: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    voice: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Beschreibung der Welt im Handshake – so viel, dass ein Agent ohne Repo-Kenntnis handeln kann. */
+export interface AgentWorldDigest {
+    workspaceId: string;
+    workspaceName: string;
+    officeId: string;
+    revisionId: string;
+    zones: Array<{
+        id: string;
+        name: string;
+        private: boolean;
+        capacity: number | null;
+        center: [number, number];
+    }>;
+    objects: Array<{
+        placementId: string;
+        asset: string;
+        kind: string;
+        label: string;
+        position: [number, number];
+        action: string | null;
+    }>;
+    seats: Array<{
+        id: string;
+        x: number;
+        z: number;
+        taken: boolean;
+    }>;
+    participants: Array<{
+        id: string;
+        name: string;
+        kind: 'user' | 'agent';
+        zoneId: string | null;
+        x: number;
+        z: number;
+    }>;
+    conversations: string[];
+}
+export interface AgentHelloResult {
+    protocol: typeof AGENT_PROTOCOL;
+    agent: {
+        id: string;
+        name: string;
+        operator: AgentOperator;
+    };
+    scopes: AgentScope[];
+    limits: typeof AGENT_LIMITS;
+    participantId: string;
+    reconnected: boolean;
+    world: AgentWorldDigest;
+}
+/** Ereignis „jemand spricht dich an“ – der eine Kanal für alle vier Ansprachewege. */
+export interface AgentAddressPayload {
+    /**
+     * `mention` = @Name im Chat, `talk` = hingehen + E, `zone.enter` = Zone betreten,
+     * `desk` = am Arbeitsplatz, `card.decision` = jemand hat eine Bestätigungs-Karte entschieden (SPA-117)
+     */
+    kind: 'mention' | 'talk' | 'zone.enter' | 'desk' | 'card.decision';
+    from: {
+        participantId: string | null;
+        userId: string;
+        displayName: string;
+    };
+    /** Konversation, in der eine Antwort landen sollte (`room:office`, `room:<zone>`, `dm:a:b`) */
+    conv: string;
+    text: string | null;
+    zoneId: string | null;
+    at: number;
+    /** Nur bei `card.decision`: welche Karte, welche Aktion und wann entschieden wurde (SPA-117) */
+    decision?: {
+        messageId: string;
+        blockId: string;
+        actionId: string;
+        actionLabel: string;
+        at: string;
+    };
+}
+export interface AgentThrottledPayload {
+    reason: AgentThrottleReason;
+    /** Wie oft dieser Agent in dieser Verbindung schon gedrosselt wurde */
+    strikes: number;
+    /** Verbindung wird nach diesem Ereignis getrennt */
+    disconnecting: boolean;
+    message: string;
+}
+export interface AgentRevokedPayload {
+    reason: 'disabled' | 'token_rotated' | 'deleted' | 'workspace_disabled';
+    message: string;
+}
+/** Kennzeichnung eines Agenten am Teilnehmer (UI: Badge, Karte, Teilnehmerliste, Chat). */
+export interface AgentBadge {
+    agentId: string;
+    operator: AgentOperator;
+    description: string;
+}
+/** Autor einer Chat-Nachricht: Mensch oder Agent (Nachrichten tragen die Art mit). */
+export type AuthorKind = 'user' | 'agent';
+/**
+ * Sprachschleife im Raum: der Mensch geht hin, drückt `E` und redet – Sprache zu Text beim
+ * Agenten-Betreiber, Antwort als eigene Audiospur im selben LiveKit-Raum.
+ *
+ * Der Server hält dabei nur den **Gesprächszustand**: wer spricht mit wem, seit wann, in welchem
+ * Raum. Ton fließt nie über die API. Damit gilt unverändert, was in Phase 5 für Menschen gilt –
+ * wer den Raum nicht betreten darf, bekommt kein Token, und ohne offene Sitzung hört ein Agent nichts.
+ */
+/** Was der Agent gerade tut – die UI macht daraus die Anzeige am Avatar. */
+export declare const AGENT_VOICE_STATES: readonly ['idle', 'listening', 'thinking', 'speaking'];
+export type AgentVoiceState = (typeof AGENT_VOICE_STATES)[number];
+/** Warum eine Sprachsitzung endete. */
+export type AgentVoiceEndReason = 
+/** Der Mensch hat `E` noch einmal gedrückt */
+'closed'
+/** Reichweite verlassen */
+ | 'away'
+/** Zone gewechselt – anderer Raum, anderes Gespräch */
+ | 'zone'
+/** Zu lange still */
+ | 'idle'
+/** Obergrenze der Sitzungsdauer erreicht */
+ | 'expired'
+/** Einer von beiden ist weg (Verbindung, Welt, Workspace) */
+ | 'gone'
+/** Budget erschöpft */
+ | 'throttled';
+/**
+ * Ereignis an den Agenten: ein Gespräch wird eröffnet oder beendet (`agent:voice`).
+ *
+ * Bei `open` holt sich der Agent mit `agent:meetingToken` (Ziel `target`) sein LiveKit-Token und
+ * abonniert **nur** die Spur von `human.identity` – mehr darf er nicht hören.
+ */
+export interface AgentVoicePayload {
+    kind: 'open' | 'close';
+    sessionId: string;
+    /** LiveKit-Raum, in dem das Gespräch läuft */
+    room: string;
+    /** Ziel für `agent:meetingToken` (`office` oder Zonen-ID) */
+    target: string;
+    /** Der Mensch am anderen Ende; `identity` ist seine LiveKit-Identität (= Teilnehmer-ID) */
+    human: {
+        participantId: string;
+        userId: string;
+        displayName: string;
+        identity: string;
+    };
+    /** Konversation für Untertitel (`chat:send`) */
+    conv: string;
+    zoneId: string | null;
+    /** Nur bei `close` */
+    reason: AgentVoiceEndReason | null;
+    at: number;
+}
+/** Der Agent meldet, was er gerade tut (`agent:voice:state`). */
+export declare const agentVoiceStateSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    state: z.ZodEnum<{
+        idle: "idle";
+        listening: "listening";
+        speaking: "speaking";
+        thinking: "thinking";
+    }>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentVoiceStateInput = z.output<typeof agentVoiceStateSchema>;
+/** Der Mensch beendet das Gespräch (`voice:close`, Browser → Server). */
+export declare const voiceCloseSchema: z.ZodObject<{
+    agentParticipantId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Gesprächszustand für die Oberfläche (`voice:session`, Server → alle im Workspace).
+ *
+ * `active: false` heißt: das Gespräch ist zu Ende. Die Anzeige am Avatar hängt an genau diesem
+ * Ereignis – es gibt keinen zweiten Weg, auf dem ein Sprechzustand in die UI kommt.
+ */
+export interface VoiceSessionPayload {
+    sessionId: string;
+    agentParticipantId: string;
+    agentId: string;
+    humanParticipantId: string;
+    active: boolean;
+    /** Zustand des Agenten in diesem Gespräch */
+    state: AgentVoiceState;
+    reason: AgentVoiceEndReason | null;
+    since: number;
+    at: number;
+}
+/** Erwähnungen `@Name` aus einem Nachrichtentext ziehen (Groß-/Kleinschreibung egal, Namen mit Leerzeichen). */
+export declare function findMentions(text: string, names: readonly string[]): string[];