@etazio/agent-sdk 0.1.0

package/types/shared/web.d.ts

@@ -0,0 +1,297 @@
+import { z } from 'zod';
+/**
+ * Phase 7f – Web-Anzeige am Fernseher: ein Chromium auf dem Server (Renderer-Dienst) zeigt eine Webseite,
+ * sein Bild geht als `web:frame` an die Clients in Sichtweite. Zwei Ziele:
+ * - **Ad-hoc-URL** (`TvState.url` bei `source: 'web'`) – flüchtiges Profil, jedes Mitglied darf bedienen,
+ * - **Kanal** (`TvState.web` = Kanal-Id, mehrere durch Komma für die Rotation) – benannt, persistentes Profil,
+ *   Anmeldung bleibt erhalten; anlegen/ändern/bedienen verlangt `office.edit`.
+ *
+ * Bedienung ist echte Browser-Bedienung: wer die Steuerung übernimmt (exklusiv, `controlTtlMs`), schickt
+ * Maus-, Tastatur- und Radereignisse per `web:input` an die Seite (CDP `Input.dispatch*`).
+ */
+export declare const WEB_LIMITS: {
+    readonly maxUrl: 1024;
+    readonly maxName: 60;
+    readonly maxCss: 4096;
+    /** Kanäle je Workspace */
+    readonly maxChannels: 12;
+    /** Kanäle gleichzeitig offen je Renderer-Instanz */
+    readonly maxContexts: 3;
+    /** Bildabstand im Standbildmodus (Sekunden) */
+    readonly minRefresh: 2;
+    readonly maxRefresh: 300;
+    readonly defaultRefresh: 10;
+    /** Sichtfenster des Server-Browsers */
+    readonly minViewport: 480;
+    readonly maxViewport: 2560;
+    readonly defaultViewport: {
+        readonly w: 1280;
+        readonly h: 720;
+    };
+    /** Zoom der Seite */
+    readonly minZoom: 0.25;
+    readonly maxZoom: 3;
+    /** Steuerung: Dauer der exklusiven Übernahme ohne Eingabe (ms) */
+    readonly controlTtlMs: number;
+    /** Eingabeereignisse je Sekunde und Teilnehmer */
+    readonly inputPerSecond: 60;
+    /** Zeichen, die auf einmal eingefügt werden dürfen (Zwischenablage) */
+    readonly maxPaste: 8192;
+    /** Ohne Zuschauer: pausieren nach … ms, Seite schließen nach … ms */
+    readonly idlePauseMs: 60000;
+    readonly idleCloseMs: number;
+    /** Bildgröße (Bytes, base64) */
+    readonly maxFrameBytes: 1500000;
+    /** Rotation mehrerer Kanäle: Sekunden je Kanal */
+    readonly minRotate: 10;
+    readonly maxRotate: 3600;
+    /** Bildrate im Bewegtbildmodus */
+    readonly maxLiveFps: 10;
+};
+export declare const WEB_MODES: readonly ['still', 'live'];
+export type WebMode = (typeof WEB_MODES)[number];
+export interface WebChannelDto {
+    id: string;
+    name: string;
+    url: string;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    mode: WebMode;
+    refreshSeconds: number;
+    zoom: number;
+    scroll?: {
+        x: number;
+        y: number;
+    };
+    css?: string;
+    /** Anmeldung im Profil hinterlegt (Cookies im Volume) */
+    hasProfile: boolean;
+    /** Feste Kopfzeilen/Basic-Auth hinterlegt (Werte selbst werden nie ausgeliefert) */
+    hasAuth: boolean;
+    createdBy: string | null;
+    updatedAt: string;
+    lastLoginAt: string | null;
+}
+/** Zielbeschreibung einer Web-Anzeige: Kanal-Id oder Ad-hoc-Adresse */
+export interface WebTarget {
+    /** `channel:<id>` oder `url:<adresse>` – Schlüssel für Abo, Frames und Steuerung */
+    key: string;
+    channelId?: string;
+    url?: string;
+}
+export declare const webKey: {
+    channel: (id: string) => string;
+    url: (u: string) => string;
+};
+/** Kanal-Ids einer Web-Anzeige (Rotation: durch Komma getrennt) */
+export declare function webChannelIds(web: string | undefined): string[];
+/**
+ * Aktuelles Ziel einer Web-Anzeige zur Serverzeit `now`. Mehrere Kanäle rotieren mit `rotate` Sekunden
+ * (synchron über `at`, wie die Diashow); ohne Kanal gilt die Ad-hoc-Adresse.
+ */
+export declare function webTarget(state: {
+    web?: string;
+    url?: string;
+    rotate?: number;
+    at?: number;
+}, now?: number): WebTarget | null;
+/** Nur https (und `http` bleibt der serverseitigen Allowlist vorbehalten) – Vorprüfung im Client */
+export declare function isWebUrl(u: string): boolean;
+/** Eingabe des Nutzers zu einer Adresse ergänzen: „example.com/x“ → „https://example.com/x“ */
+export declare function normalizeWebUrl(input: string): string | null;
+/** Anzeigename einer Web-Anzeige (Kanalname setzt der Client ein) */
+export declare function webLabel(title: string | null | undefined, url: string | null | undefined): string;
+export declare const WEB_BUTTONS: readonly ['left', 'right', 'middle'];
+export declare const webInputEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"mouse">;
+    type: z.ZodEnum<{
+        click: "click";
+        down: "down";
+        move: "move";
+        up: "up";
+    }>;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    button: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        middle: "middle";
+        right: "right";
+    }>>;
+    clickCount: z.ZodOptional<z.ZodNumber>;
+    modifiers: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"wheel">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    dx: z.ZodNumber;
+    dy: z.ZodNumber;
+    modifiers: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"key">;
+    type: z.ZodEnum<{
+        char: "char";
+        down: "down";
+        up: "up";
+    }>;
+    key: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    modifiers: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>], "kind">;
+export type WebInputEvent = z.infer<typeof webInputEventSchema>;
+export declare const webNavigateSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        back: "back";
+        forward: "forward";
+        home: "home";
+        reload: "reload";
+        url: "url";
+    }>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WebNavigate = z.infer<typeof webNavigateSchema>;
+export interface WebWatchPayload {
+    placementId: string;
+    /** false = Abo beenden */
+    watch: boolean;
+}
+export interface WebFramePayload {
+    placementId: string;
+    /** Ziel-Schlüssel (Kanal oder Adresse) – Frames alter Ziele lassen sich so verwerfen */
+    key: string;
+    seq: number;
+    /** JPEG/PNG als base64 (ohne data:-Präfix) */
+    data: string;
+    mime: string;
+    w: number;
+    h: number;
+}
+export type WebPhase = 'starting' | 'loading' | 'ready' | 'blocked' | 'error' | 'login' | 'stopped';
+export interface WebStatusPayload {
+    placementId: string;
+    key: string;
+    phase: WebPhase;
+    /** Adresse, auf der die Seite gerade steht (Mitglieder; Gäste bekommen null) */
+    url: string | null;
+    title: string | null;
+    canGoBack: boolean;
+    canGoForward: boolean;
+    /** Teilnehmer mit der Steuerung (null = frei) */
+    controller: string | null;
+    controllerName: string | null;
+    /** Fehlertext für die Zwischenanzeige */
+    message?: string;
+}
+export interface WebControlPayload {
+    placementId: string;
+    key: string;
+    controller: string | null;
+    controllerName: string | null;
+    /** Serverzeit, zu der die Übernahme ohne Eingabe abläuft */
+    until: number | null;
+}
+export declare const webWatchSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    watch: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const webControlSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    take: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const webInputSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"mouse">;
+        type: z.ZodEnum<{
+            click: "click";
+            down: "down";
+            move: "move";
+            up: "up";
+        }>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        button: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            middle: "middle";
+            right: "right";
+        }>>;
+        clickCount: z.ZodOptional<z.ZodNumber>;
+        modifiers: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"wheel">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        dx: z.ZodNumber;
+        dy: z.ZodNumber;
+        modifiers: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"key">;
+        type: z.ZodEnum<{
+            char: "char";
+            down: "down";
+            up: "up";
+        }>;
+        key: z.ZodString;
+        code: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        modifiers: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export declare const webNavigateRequestSchema: z.ZodIntersection<z.ZodObject<{
+    placementId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodEnum<{
+        back: "back";
+        forward: "forward";
+        home: "home";
+        reload: "reload";
+        url: "url";
+    }>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/**
+ * Sichtfeld an die Anzeigefläche des Steuernden angleichen. Ohne das rendert der Server-Browser
+ * immer im Kanal-Sichtfeld (Standard 1280×720) und das Bild wird im Fenster hochskaliert – die
+ * Seite wirkt dann herangezoomt und unscharf. Gilt nur, solange jemand steuert; danach stellt der
+ * Dienst das Kanal-Sichtfeld wieder her, damit der Fernseher sein gewohntes Bild behält.
+ */
+export declare const webResizeSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, z.core.$strip>;
+export type WebResizePayload = z.infer<typeof webResizeSchema>;
+export declare const webChannelInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodString;
+    viewport: z.ZodOptional<z.ZodObject<{
+        w: z.ZodNumber;
+        h: z.ZodNumber;
+    }, z.core.$strip>>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        live: "live";
+        still: "still";
+    }>>;
+    refreshSeconds: z.ZodOptional<z.ZodNumber>;
+    zoom: z.ZodOptional<z.ZodNumber>;
+    scroll: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    css: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    basicAuth: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        user: z.ZodString;
+        password: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type WebChannelInput = z.infer<typeof webChannelInputSchema>;
+export declare const webChannelIdSchema: z.ZodString;

package/types/speech.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sprache zu Text und Text zu Sprache (SPA-83).
+ *
+ * Die Schnittstellen stehen bewusst vor der Umsetzung: welcher Anbieter erkennt und spricht, ist die
+ * Sache des Agenten-Betreibers – das Office liefert nur den Ton. Wer einen anderen Dienst nutzt,
+ * schreibt zwei kleine Funktionen und lässt alles andere unverändert.
+ *
+ * Mitgeliefert ist OpenAI, weil es mit einem einzigen Schlüssel beides kann und ohne zusätzliches
+ * Paket auskommt: Erkennung über `/v1/audio/transcriptions`, Stimme über `/v1/audio/speech` mit
+ * rohem PCM – das lässt sich beim Eintreffen abspielen, statt auf die fertige Datei zu warten.
+ */
+export interface SttAdapter {
+    /** Eine abgeschlossene Äußerung erkennen. Leerer String = nichts Verwertbares. */
+    transcribe(pcm: Int16Array, sampleRate: number, signal?: AbortSignal): Promise<string>;
+}
+export interface TtsAdapter {
+    /** Abtastrate des gelieferten PCM-Stroms */
+    readonly sampleRate: number;
+    /**
+     * Text sprechen. Liefert 16-bit-PCM in Stücken, sobald sie da sind – wer auf die ganze Datei
+     * wartet, wartet eine Sekunde zu lang, und genau die entscheidet, ob es lebendig wirkt.
+     */
+    speak(text: string, signal?: AbortSignal): AsyncIterable<Int16Array>;
+}
+export interface OpenAiSpeechOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Erkennungsmodell (`gpt-4o-mini-transcribe` ist schnell, `whisper-1` günstig) */
+    sttModel?: string;
+    /** Sprachmodell für die Stimme */
+    ttsModel?: string;
+    /** Stimme des Agenten – gehört langfristig ins Agenten-Profil (SPA-83, offene Frage 5) */
+    voice?: string;
+    /** Erwartete Sprache als ISO-Code; spart der Erkennung das Raten und damit Zeit */
+    language?: string;
+    timeoutMs?: number;
+}
+export declare function openAiStt(options: OpenAiSpeechOptions): SttAdapter;
+export declare function openAiTts(options: OpenAiSpeechOptions): TtsAdapter;

package/types/version.d.ts

@@ -0,0 +1,2 @@
+/** Version dieses SDK – muss zu `package.json` passen (geprüft in `scripts/build.mjs` und `test/dist.test.mjs`). */
+export declare const SDK_VERSION = "0.1.0";

package/types/voice.d.ts

@@ -0,0 +1,61 @@
+import type { AgentVoicePayload } from './shared/index.js';
+import type { SttAdapter, TtsAdapter } from './speech.js';
+import type { EtazioAgent } from './index.js';
+export interface VoiceReplyContext {
+    /** Was der Mensch gesagt hat */
+    text: string;
+    session: AgentVoicePayload;
+    /** Bricht ab, sobald der Mensch dazwischenredet oder das Gespräch endet – an jede Modellanfrage weiterreichen */
+    signal: AbortSignal;
+}
+export interface EtazioVoiceOptions {
+    stt: SttAdapter;
+    tts: TtsAdapter;
+    /**
+     * Antwort auf eine Äußerung. Leerer String = nichts sagen.
+     * Das ist die einzige Stelle, an der das eigene Modell hängt – alles davor und danach ist Mechanik.
+     */
+    reply(ctx: VoiceReplyContext): Promise<string>;
+    /**
+     * Untertitel im Chat: was der Agent sagt, soll mitlesbar sein (SPA-83). Standard: an.
+     * Was der Mensch sagt, wird bewusst **nicht** geschrieben – das wäre eine Aufzeichnung, und die
+     * gehört ausdrücklich freigegeben, nicht nebenbei angeschaltet.
+     */
+    subtitles?: boolean;
+    /** Stille bis zum Satzende (ms) */
+    silenceMs?: number;
+    /** Wie laut es sein muss, damit es als Rede gilt (0…1) */
+    threshold?: number;
+    onError?(err: Error): void;
+    onTranscript?(text: string, session: AgentVoicePayload): void;
+}
+export declare class EtazioVoice {
+    private readonly agent;
+    private readonly options;
+    private readonly live;
+    private started;
+    constructor(agent: EtazioAgent, options: EtazioVoiceOptions);
+    /** An die Sprachereignisse des Agenten hängen. Ab hier laufen Gespräche von selbst. */
+    start(): this;
+    /** Laufende Gespräche (für Diagnose und geordnetes Herunterfahren). */
+    get sessions(): AgentVoicePayload[];
+    stop(): Promise<void>;
+    private open;
+    /** Ton des Menschen lesen, in Äußerungen schneiden und beantworten. */
+    private listen;
+    /** Ein Gesprächszug: verstehen → antworten → sprechen. Jeder Schritt kann unterbrochen werden. */
+    private turn;
+    /** Text sprechen: Blöcke gehen raus, sobald sie da sind – wer die ganze Datei abwartet, wartet zu lang. */
+    private say;
+    /**
+     * Barge-in: der Mensch redet dazwischen. Der laufende Zug wird abgebrochen **und** die schon in
+     * LiveKit liegende Warteschlange geleert – ohne das Zweite redet der Agent noch sekundenlang weiter.
+     */
+    private bargeIn;
+    private state;
+    private close;
+    private closeAll;
+    private fail;
+}
+/** Kurzform: Sprachschleife an einen verbundenen Agenten hängen. */
+export declare function attachVoice(agent: EtazioAgent, options: EtazioVoiceOptions): EtazioVoice;