@bytexbyte/nxtlinq-ai-agent-web-development 0.1.1

package/dist/voice/useWsRealtimeAudio.js

@@ -0,0 +1,115 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { BrowserWsPcmPlayer } from './ws/BrowserWsPcmPlayer';
+import { BrowserWsPcmRecorder } from './ws/BrowserWsPcmRecorder';
+import { useVoiceSilenceCommit } from './useVoiceSilenceCommit';
+export function useWsRealtimeAudio(isCaptureActive, isVoiceActive, options) {
+    const playerRef = useRef(null);
+    const recorderRef = useRef(null);
+    const sessionRef = useRef(null);
+    const captureGenRef = useRef(0);
+    const isCaptureActiveRef = useRef(isCaptureActive);
+    isCaptureActiveRef.current = isCaptureActive;
+    const prevCaptureActiveRef = useRef(isCaptureActive);
+    const getSession = useCallback(() => sessionRef.current, []);
+    const muteAfterSilenceCommitRef = useRef(options.muteAfterSilenceCommit);
+    muteAfterSilenceCommitRef.current = options.muteAfterSilenceCommit;
+    const silence = useVoiceSilenceCommit(getSession, () => muteAfterSilenceCommitRef.current(), options.voiceStatus);
+    const silenceRef = useRef(silence);
+    silenceRef.current = silence;
+    const ensurePlayer = useCallback(async () => {
+        if (!playerRef.current) {
+            playerRef.current = new BrowserWsPcmPlayer();
+            playerRef.current.prewarm();
+        }
+        await playerRef.current.ensureRunning();
+    }, []);
+    const stopCapture = useCallback((commit) => {
+        captureGenRef.current += 1;
+        const s = silenceRef.current;
+        s.clearPoll();
+        // Commit before recorder.stop() — stop() must not clear the OpenAI input buffer first.
+        if (commit && !s.consumeSkipCommitOnMute()) {
+            s.tryCommit('manual');
+        }
+        recorderRef.current?.stop();
+    }, []);
+    const startCapture = useCallback(async () => {
+        const session = sessionRef.current;
+        if (!session)
+            return;
+        const gen = ++captureGenRef.current;
+        const s = silenceRef.current;
+        if (!recorderRef.current)
+            recorderRef.current = new BrowserWsPcmRecorder();
+        playerRef.current?.clearQueue();
+        recorderRef.current.bindSession(session);
+        recorderRef.current.setOnRms(s.onSpeechRms);
+        recorderRef.current.setShouldAppend(() => s.hasHadSpeech());
+        // Let mic-unmute state settle before getUserMedia (Berify beginMicCapture).
+        await new Promise((resolve) => {
+            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+        });
+        if (gen !== captureGenRef.current || !isCaptureActiveRef.current)
+            return;
+        s.resetTurn();
+        try {
+            await recorderRef.current.start();
+            if (gen !== captureGenRef.current || !isCaptureActiveRef.current) {
+                recorderRef.current.stop();
+                return;
+            }
+            s.startPoll();
+        }
+        catch (err) {
+            s.clearPoll();
+            console.error('[nxtlinq] mic capture start failed', err);
+        }
+    }, []);
+    const cleanup = useCallback(() => {
+        silenceRef.current.clearPoll();
+        recorderRef.current?.cleanup();
+        recorderRef.current = null;
+        playerRef.current?.cleanup();
+        playerRef.current = null;
+        sessionRef.current = null;
+    }, []);
+    const bindSession = useCallback((session, captureWhenUnmuted = false) => {
+        sessionRef.current = session;
+        recorderRef.current?.bindSession(session);
+        if (session && captureWhenUnmuted && isCaptureActiveRef.current) {
+            void startCapture();
+        }
+    }, [startCapture]);
+    const buildCallbacks = useCallback((overrides) => ({
+        onOpen: () => {
+            void ensurePlayer();
+            overrides?.onOpen?.();
+        },
+        onAudioDelta: (pcm16) => {
+            void ensurePlayer().then(() => playerRef.current?.addAudio(pcm16));
+            overrides?.onAudioDelta?.(pcm16);
+        },
+        onClose: (reason) => {
+            cleanup();
+            overrides?.onClose?.(reason);
+        },
+        onError: (err) => {
+            cleanup();
+            overrides?.onError?.(err);
+        },
+    }), [cleanup, ensurePlayer]);
+    useEffect(() => {
+        if (!isVoiceActive) {
+            prevCaptureActiveRef.current = false;
+            cleanup();
+            return;
+        }
+        const prev = prevCaptureActiveRef.current;
+        prevCaptureActiveRef.current = isCaptureActive;
+        if (isCaptureActive && !prev)
+            void startCapture();
+        else if (!isCaptureActive && prev)
+            stopCapture(true);
+    }, [isCaptureActive, isVoiceActive, startCapture, stopCapture, cleanup]);
+    return { bindSession, buildCallbacks, getOutputAudioLevel: () => playerRef.current?.getAudioLevel() ?? 0 };
+}

package/dist/voice/voiceMicConstants.d.ts

@@ -0,0 +1,4 @@
+import type { VoiceStatus } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+export declare const ASSISTANT_MIC_HOLD_STATUSES: ReadonlySet<VoiceStatus>;
+export declare const SPEAKER_ACTIVE_STATUSES: ReadonlySet<VoiceStatus>;
+//# sourceMappingURL=voiceMicConstants.d.ts.map

package/dist/voice/voiceMicConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceMicConstants.d.ts","sourceRoot":"","sources":["../../src/voice/voiceMicConstants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8CAA8C,CAAC;AAEhF,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,WAAW,CAK/D,CAAC;AAEH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,WAAW,CAG3D,CAAC"}

package/dist/voice/voiceMicConstants.js

@@ -0,0 +1,10 @@
+export const ASSISTANT_MIC_HOLD_STATUSES = new Set([
+    'transcribing',
+    'thinking',
+    'generating',
+    'speaking',
+]);
+export const SPEAKER_ACTIVE_STATUSES = new Set([
+    'generating',
+    'speaking',
+]);

package/dist/voice/ws/BrowserWsPcmPlayer.d.ts

@@ -0,0 +1,23 @@
+export declare class BrowserWsPcmPlayer {
+    private readonly sampleRate;
+    private readonly fadeSamples;
+    private audioContext;
+    private gainNode;
+    private analyserNode;
+    private analyserBuffer;
+    private readonly activeSources;
+    private queue;
+    private isPlaying;
+    private playHead;
+    private lastChunkRms;
+    private lastChunkAt;
+    ensureRunning(): Promise<void>;
+    prewarm(): void;
+    addAudio(pcm16: Int16Array | ArrayBuffer): void;
+    getAudioLevel(): number;
+    clearQueue(): void;
+    cleanup(): void;
+    private ensureContext;
+    private pipelineQueue;
+}
+//# sourceMappingURL=BrowserWsPcmPlayer.d.ts.map

package/dist/voice/ws/BrowserWsPcmPlayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserWsPcmPlayer.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/BrowserWsPcmPlayer.ts"],"names":[],"mappings":"AAeA,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmD;IAC/E,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IAElB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpC,OAAO,IAAI,IAAI;IAIf,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAqB/C,aAAa,IAAI,MAAM;IAgBvB,UAAU,IAAI,IAAI;IAWlB,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,aAAa;CA2BtB"}

package/dist/voice/ws/BrowserWsPcmPlayer.js

@@ -0,0 +1,138 @@
+import { WS_REALTIME_SAMPLE_RATE } from './wsRealtimeConstants';
+const LEVEL_SCALE = 3.2;
+const LOOKAHEAD_SECONDS = 0.02;
+const CROSSFADE_SECONDS = 0.04;
+function applyFade(buffer, fadeSamples) {
+    const fade = Math.min(fadeSamples, Math.floor(buffer.length / 2));
+    if (fade <= 0)
+        return;
+    for (let i = 0; i < fade; i += 1) {
+        buffer[i] *= i / fade;
+        buffer[buffer.length - 1 - i] *= (fade - i) / fade;
+    }
+}
+export class BrowserWsPcmPlayer {
+    constructor() {
+        this.sampleRate = WS_REALTIME_SAMPLE_RATE;
+        this.fadeSamples = Math.max(1, Math.floor(this.sampleRate * 0.01));
+        this.audioContext = null;
+        this.gainNode = null;
+        this.analyserNode = null;
+        this.analyserBuffer = null;
+        this.activeSources = new Set();
+        this.queue = [];
+        this.isPlaying = true;
+        this.playHead = 0;
+        this.lastChunkRms = 0;
+        this.lastChunkAt = 0;
+    }
+    async ensureRunning() {
+        const ctx = this.ensureContext();
+        if (ctx.state === 'suspended')
+            await ctx.resume();
+        this.isPlaying = true;
+    }
+    prewarm() {
+        this.ensureContext();
+    }
+    addAudio(pcm16) {
+        const ctx = this.ensureContext();
+        const int16 = pcm16 instanceof ArrayBuffer ? new Int16Array(pcm16) : pcm16;
+        if (int16.length === 0)
+            return;
+        const floats = new Float32Array(int16.length);
+        let sumSq = 0;
+        for (let i = 0; i < int16.length; i += 1) {
+            const sample = int16[i] / 32768;
+            floats[i] = Math.max(-1, Math.min(1, sample));
+            sumSq += sample * sample;
+        }
+        applyFade(floats, this.fadeSamples);
+        this.lastChunkRms = Math.min(1, Math.sqrt(sumSq / int16.length) * LEVEL_SCALE);
+        this.lastChunkAt = Date.now();
+        const buffer = ctx.createBuffer(1, floats.length, this.sampleRate);
+        buffer.getChannelData(0).set(floats);
+        this.queue.push(buffer);
+        this.isPlaying = true;
+        this.pipelineQueue();
+    }
+    getAudioLevel() {
+        const analyser = this.analyserNode;
+        const buf = this.analyserBuffer;
+        if (analyser && buf && this.activeSources.size > 0) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            analyser.getFloatTimeDomainData(buf);
+            let sumSq = 0;
+            for (let i = 0; i < buf.length; i += 1) {
+                const v = buf[i];
+                sumSq += v * v;
+            }
+            return Math.min(1, Math.sqrt(sumSq / buf.length) * LEVEL_SCALE);
+        }
+        return Date.now() - this.lastChunkAt < 500 ? this.lastChunkRms : 0;
+    }
+    clearQueue() {
+        for (const source of this.activeSources) {
+            try {
+                source.stop();
+            }
+            catch { /* noop */ }
+        }
+        this.activeSources.clear();
+        this.queue = [];
+        this.playHead = this.audioContext?.currentTime ?? 0;
+        this.lastChunkRms = 0;
+        this.lastChunkAt = 0;
+    }
+    cleanup() {
+        this.clearQueue();
+        this.isPlaying = false;
+        void this.audioContext?.close();
+        this.analyserNode = null;
+        this.analyserBuffer = null;
+        this.gainNode = null;
+        this.audioContext = null;
+    }
+    ensureContext() {
+        if (!this.audioContext) {
+            this.audioContext = new AudioContext({ sampleRate: this.sampleRate });
+            this.gainNode = this.audioContext.createGain();
+            this.analyserNode = this.audioContext.createAnalyser();
+            this.analyserNode.fftSize = 512;
+            this.analyserBuffer = new Float32Array(this.analyserNode.fftSize);
+            this.gainNode.connect(this.analyserNode);
+            this.analyserNode.connect(this.audioContext.destination);
+            this.playHead = this.audioContext.currentTime;
+        }
+        return this.audioContext;
+    }
+    pipelineQueue() {
+        const ctx = this.audioContext;
+        const gain = this.gainNode;
+        if (!ctx || !gain || !this.isPlaying)
+            return;
+        while (this.queue.length > 0) {
+            const audioBuffer = this.queue.shift();
+            if (!audioBuffer)
+                return;
+            const source = ctx.createBufferSource();
+            source.buffer = audioBuffer;
+            const perSourceGain = ctx.createGain();
+            source.connect(perSourceGain);
+            perSourceGain.connect(gain);
+            const now = ctx.currentTime;
+            const startAt = Math.max((this.playHead || now) - CROSSFADE_SECONDS * 0.75, now + LOOKAHEAD_SECONDS);
+            const duration = audioBuffer.duration;
+            const endAt = startAt + duration;
+            const fade = Math.min(CROSSFADE_SECONDS, duration / 2);
+            perSourceGain.gain.setValueAtTime(0, startAt);
+            perSourceGain.gain.linearRampToValueAtTime(1, startAt + fade);
+            perSourceGain.gain.setValueAtTime(1, endAt - fade);
+            perSourceGain.gain.linearRampToValueAtTime(0, endAt);
+            this.playHead = endAt;
+            this.activeSources.add(source);
+            source.start(startAt);
+            source.onended = () => this.activeSources.delete(source);
+        }
+    }
+}

package/dist/voice/ws/BrowserWsPcmRecorder.d.ts

@@ -0,0 +1,19 @@
+import type { VoiceSession } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+/** getUserMedia only on start() — Berify hold-to-talk aligned. */
+export declare class BrowserWsPcmRecorder {
+    private session;
+    private onRms?;
+    private stream;
+    private audioContext;
+    private processor;
+    private source;
+    private silentGain;
+    private shouldAppend?;
+    bindSession(session: VoiceSession | null): void;
+    setShouldAppend(handler: () => boolean): void;
+    setOnRms(handler: (rms: number) => void): void;
+    start(): Promise<void>;
+    stop(): void;
+    cleanup(): void;
+}
+//# sourceMappingURL=BrowserWsPcmRecorder.d.ts.map

package/dist/voice/ws/BrowserWsPcmRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserWsPcmRecorder.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/BrowserWsPcmRecorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAC;AAajF,kEAAkE;AAClE,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,KAAK,CAAC,CAAwB;IACtC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,MAAM,CAA2C;IACzD,OAAO,CAAC,UAAU,CAAyB;IAE3C,OAAO,CAAC,YAAY,CAAC,CAAgB;IAErC,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI;IAI/C,eAAe,CAAC,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI;IAI7C,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B,IAAI,IAAI,IAAI;IAeZ,OAAO,IAAI,IAAI;CAIhB"}

package/dist/voice/ws/BrowserWsPcmRecorder.js

@@ -0,0 +1,76 @@
+import { float32ToPcm16 } from './float32ToPcm16';
+import { WS_REALTIME_SAMPLE_RATE } from './wsRealtimeConstants';
+function computeRms(channel) {
+    let sum = 0;
+    for (let i = 0; i < channel.length; i += 1) {
+        const v = channel[i];
+        sum += v * v;
+    }
+    return channel.length > 0 ? Math.sqrt(sum / channel.length) : 0;
+}
+/** getUserMedia only on start() — Berify hold-to-talk aligned. */
+export class BrowserWsPcmRecorder {
+    constructor() {
+        this.session = null;
+        this.stream = null;
+        this.audioContext = null;
+        this.processor = null;
+        this.source = null;
+        this.silentGain = null;
+    }
+    bindSession(session) {
+        this.session = session;
+    }
+    setShouldAppend(handler) {
+        this.shouldAppend = handler;
+    }
+    setOnRms(handler) {
+        this.onRms = handler;
+    }
+    async start() {
+        if (this.processor)
+            return;
+        this.stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+        const ctx = new AudioContext({ sampleRate: WS_REALTIME_SAMPLE_RATE });
+        this.audioContext = ctx;
+        this.source = ctx.createMediaStreamSource(this.stream);
+        this.processor = ctx.createScriptProcessor(4096, 1, 1);
+        this.silentGain = ctx.createGain();
+        this.silentGain.gain.value = 0;
+        this.source.connect(this.processor);
+        this.processor.connect(this.silentGain);
+        this.silentGain.connect(ctx.destination);
+        this.processor.onaudioprocess = (event) => {
+            if (!this.session?.appendInputAudio)
+                return;
+            const channel = event.inputBuffer.getChannelData(0);
+            const rms = computeRms(channel);
+            this.onRms?.(rms);
+            // Berify: only stream PCM after RMS crosses speech threshold.
+            if (this.shouldAppend && !this.shouldAppend())
+                return;
+            this.session.appendInputAudio(float32ToPcm16(channel));
+        };
+        if (ctx.state === 'suspended') {
+            await ctx.resume();
+        }
+    }
+    stop() {
+        this.processor?.disconnect();
+        this.source?.disconnect();
+        this.silentGain?.disconnect();
+        this.processor = null;
+        this.source = null;
+        this.silentGain = null;
+        for (const track of this.stream?.getTracks() ?? []) {
+            track.stop();
+        }
+        this.stream = null;
+        void this.audioContext?.close();
+        this.audioContext = null;
+    }
+    cleanup() {
+        this.stop();
+        this.session = null;
+    }
+}

package/dist/voice/ws/float32ToPcm16.d.ts

@@ -0,0 +1,2 @@
+export declare function float32ToPcm16(input: Float32Array): Int16Array;
+//# sourceMappingURL=float32ToPcm16.d.ts.map

package/dist/voice/ws/float32ToPcm16.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"float32ToPcm16.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/float32ToPcm16.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,UAAU,CAO9D"}

package/dist/voice/ws/float32ToPcm16.js

@@ -0,0 +1,8 @@
+export function float32ToPcm16(input) {
+    const out = new Int16Array(input.length);
+    for (let i = 0; i < input.length; i += 1) {
+        const sample = Math.max(-1, Math.min(1, input[i]));
+        out[i] = sample < 0 ? sample * 0x8000 : sample * 0x7fff;
+    }
+    return out;
+}

package/dist/voice/ws/voiceSilenceConstants.d.ts

@@ -0,0 +1,5 @@
+export declare const MIC_SPEECH_RMS_THRESHOLD = 0.008;
+export declare const MIC_BARGE_IN_RMS_THRESHOLD = 0.045;
+export declare const MIC_SILENCE_COMMIT_MS = 400;
+export declare const MIC_SILENCE_POLL_MS = 100;
+//# sourceMappingURL=voiceSilenceConstants.d.ts.map

package/dist/voice/ws/voiceSilenceConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceSilenceConstants.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/voiceSilenceConstants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAC9C,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAChD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/voice/ws/voiceSilenceConstants.js

@@ -0,0 +1,4 @@
+export const MIC_SPEECH_RMS_THRESHOLD = 0.008;
+export const MIC_BARGE_IN_RMS_THRESHOLD = 0.045;
+export const MIC_SILENCE_COMMIT_MS = 400;
+export const MIC_SILENCE_POLL_MS = 100;

package/dist/voice/ws/wsRealtimeConstants.d.ts

@@ -0,0 +1,2 @@
+export declare const WS_REALTIME_SAMPLE_RATE = 24000;
+//# sourceMappingURL=wsRealtimeConstants.d.ts.map

package/dist/voice/ws/wsRealtimeConstants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsRealtimeConstants.d.ts","sourceRoot":"","sources":["../../../src/voice/ws/wsRealtimeConstants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,QAAQ,CAAC"}

package/dist/voice/ws/wsRealtimeConstants.js

@@ -0,0 +1 @@
+export const WS_REALTIME_SAMPLE_RATE = 24000;

package/dist/webAgentDefaults.d.ts

@@ -0,0 +1,9 @@
+import type { AgentConfig } from '@bytexbyte/nxtlinq-ai-agent-core-development';
+/** Browser SDK defaults — integrators do not pass these props. */
+export declare const WEB_AGENT_DEFAULTS: {
+    readonly voiceTransport: "webrtc";
+    readonly voiceMode: "realtime";
+    readonly defaultModel: "open-ai-stream";
+};
+export declare function applyWebAgentDefaults<C extends AgentConfig>(config: C): C;
+//# sourceMappingURL=webAgentDefaults.d.ts.map

package/dist/webAgentDefaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webAgentDefaults.d.ts","sourceRoot":"","sources":["../src/webAgentDefaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8CAA8C,CAAC;AAEhF,kEAAkE;AAClE,eAAO,MAAM,kBAAkB;;;;CAIU,CAAC;AAE1C,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEzE"}

package/dist/webAgentDefaults.js

@@ -0,0 +1,9 @@
+/** Browser SDK defaults — integrators do not pass these props. */
+export const WEB_AGENT_DEFAULTS = {
+    voiceTransport: 'webrtc',
+    voiceMode: 'realtime',
+    defaultModel: 'open-ai-stream',
+};
+export function applyWebAgentDefaults(config) {
+    return { ...WEB_AGENT_DEFAULTS, ...config };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@bytexbyte/nxtlinq-ai-agent-web-development",
+  "version": "0.1.1",
+  "description": "React Web headless SDK for nxtlinq AI Agent — hooks and browser ports",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "yarn build"
+  },
+  "keywords": [
+    "nxtlinq",
+    "ai-agent",
+    "react",
+    "web",
+    "sdk"
+  ],
+  "author": "ByteXByte",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/nxtlinqLLC/nxtlinq/_git/nxtlinq-AI-Agent-SDK",
+    "directory": "packages/ai-agent-web"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@bytexbyte/nxtlinq-ai-agent-core-development": "0.3.8",
+    "ethers": "^6.16.0",
+    "fast-json-stable-stringify": "^2.1.0",
+    "metakeep": "^2.2.8",
+    "microsoft-cognitiveservices-speech-sdk": "^1.45.0",
+    "universal-cookie": "^8.0.1"
+  },
+  "devDependencies": {
+    "@bytexbyte/nxtlinq-ai-agent-core-development": "workspace:^",
+    "@types/react": "^18.2.64",
+    "@types/react-dom": "^18.2.25",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.4.2"
+  }
+}

package/src/context/NxtlinqAgentContext.tsx

@@ -0,0 +1,79 @@
+import {
+  NxtlinqAgent,
+  type AgentConfig,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import {
+  createNxtlinqAgentWeb,
+  type CreateNxtlinqAgentWebOptions,
+} from '../createNxtlinqAgent';
+
+const NxtlinqAgentContext = createContext<NxtlinqAgent | null>(null);
+
+type WebAgentInternalProps =
+  | 'voiceTransport'
+  | 'voiceMode'
+  | 'defaultModel'
+  | 'enableWebRTC';
+
+export type NxtlinqAgentProviderProps = Omit<
+  CreateNxtlinqAgentWebOptions,
+  WebAgentInternalProps
+> & {
+  children: ReactNode;
+  resetOnIdentityChange?: boolean;
+};
+
+export function NxtlinqAgentProvider({
+  children,
+  resetOnIdentityChange = true,
+  ...options
+}: NxtlinqAgentProviderProps): React.ReactElement {
+  const agent = useMemo(
+    () => createNxtlinqAgentWeb(options),
+    [
+      options.serviceId,
+      options.apiKey,
+      options.apiSecret,
+      options.environment,
+      options.pseudoId,
+      options.externalId,
+      options.conversationId,
+      options.storage,
+      options.fetchImpl,
+      options.getTimezone,
+      options.webrtc,
+    ],
+  );
+
+  useEffect(() => {
+    if (!resetOnIdentityChange) return;
+    agent.setMessages([]);
+  }, [agent, resetOnIdentityChange, options.pseudoId, options.externalId, options.conversationId]);
+
+  useEffect(() => () => agent.destroy(), [agent]);
+
+  return (
+    <NxtlinqAgentContext.Provider value={agent}>
+      {children}
+    </NxtlinqAgentContext.Provider>
+  );
+}
+
+export function useNxtlinqAgentContext(): NxtlinqAgent {
+  const agent = useContext(NxtlinqAgentContext);
+  if (!agent) {
+    throw new Error(
+      'useNxtlinqAgentContext must be used within <NxtlinqAgentProvider>',
+    );
+  }
+  return agent;
+}
+
+export type { AgentConfig };

package/src/createNxtlinqAgent.ts

@@ -0,0 +1,36 @@
+import {
+  NxtlinqAgent,
+  type AgentConfig,
+  type PlatformPorts,
+} from '@bytexbyte/nxtlinq-ai-agent-core-development';
+import {
+  createWebPlatformPorts,
+  type CreateWebPlatformPortsOptions,
+} from './ports/createWebPlatformPorts';
+import { applyWebAgentDefaults } from './webAgentDefaults';
+
+export type CreateNxtlinqAgentWebOptions = AgentConfig & CreateWebPlatformPortsOptions;
+
+/**
+ * Create a platform-ready {@link NxtlinqAgent} for React Web custom UIs.
+ * Applies browser defaults (`voiceTransport: webrtc`, `defaultModel`).
+ */
+export function createNxtlinqAgentWeb(options: CreateNxtlinqAgentWebOptions): NxtlinqAgent {
+  const {
+    storage,
+    fetchImpl,
+    getTimezone,
+    webrtc,
+    enableWebRTC,
+    ...rawConfig
+  } = options;
+  const config = applyWebAgentDefaults(rawConfig);
+  const ports: PlatformPorts = createWebPlatformPorts({
+    storage,
+    fetchImpl,
+    getTimezone,
+    webrtc,
+    enableWebRTC,
+  });
+  return new NxtlinqAgent(config, ports);
+}