Monorepo setup with task runners, testing lib and API consistency tools

.eslintrc

@@ -0,0 +1,27 @@
+{
+  "plugins": ["@typescript-eslint/eslint-plugin", "eslint-plugin-tsdoc"],
+  "extends": [
+    "turbo",
+    "prettier",
+    "plugin:prettier/recommended",
+    "plugin:@typescript-eslint/recommended",
+  ],
+  "env": {
+    "node": true,
+  },
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "ecmaFeatures": {},
+  },
+  "settings": {},
+  "rules": {
+    "tsdoc/syntax": "warn",
+    "space-before-function-parens": 0,
+    "@typescript-eslint/no-unused-vars": "error",
+    "import/export": 0,
+    "@typescript-eslint/ban-ts-comment": "warn",
+    "@typescript-eslint/no-empty-interface": "warn",
+    "@typescript-eslint/consistent-type-imports": "warn",
+    "@typescript-eslint/no-explicit-any": "warn",
+  },
+}

.github/workflows/build.yml

@@ -3,52 +3,33 @@
 # SPDX-License-Identifier: Apache-2.0
 
 name: agents CI
-on: [push, pull_request]
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
 
 jobs:
-  lint:
-    name: Lint
+  test:
+    name: Test and build
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: REUSE-3.0 compliance check
         uses: fsfe/reuse-action@v3
       - uses: pnpm/action-setup@v2
         with:
-          version: 8
+          version: 9
       - name: Setup node
         uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: pnpm
       - name: Install dependencies
         run: pnpm install
-      - name: ESLint
-        run: |
-          cd agents
-          pnpm lint
-          cd ../plugins/elevenlabs
-          pnpm lint
-
-  build:
-    name: Build
-    runs-on: ubuntu-latest
-    needs: lint
-    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v2
-        with:
-          version: 8
-      - name: Setup node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: pnpm
-      - name: Install dependencies
-        run: pnpm install
-      - name: pnpm build
-        run: |
-          cd agents
-          pnpm build
-          cd ../plugins/elevenlabs
-          pnpm build
+      - name: Lint
+        run: pnpm lint
+      - name: Prettier
+        run: pnpm format:check
+      - name: Build
+        run: pnpm build

.gitignore

@@ -173,3 +173,9 @@ dist
 
 # Finder (MacOS) folder config
 .DS_Store
+
+# turbo 
+.turbo
+
+# API extractor
+temp

.prettierignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+pnpm-lock.yaml

.prettierrc

@@ -8,4 +8,5 @@
   "importOrderSeparation": false,
   "importOrderSortSpecifiers": true,
   "importOrderParserPlugins": ["typescript"],
+  "plugins": ["@trivago/prettier-plugin-sort-imports"]
 }

.reuse/dep5

@@ -4,16 +4,16 @@ Upstream-Contact: LiveKit, Inc. <https://livekit.io>
 Source: https://livekit.io
 
 # trivial files
-Files: .gitignore flake.lock
+Files: .gitignore flake.lock .prettierignore package.json
 Copyright: 2024 LiveKit, Inc.
 License: Apache-2.0
 
 # global project files
-Files: .prettierrc eslint.config.mjs pnpm-lock.yaml pnpm-workspace.yaml
+Files: .prettierrc eslint.config.mjs .eslintrc pnpm-lock.yaml pnpm-workspace.yaml api-extractor-shared.json turbo.json tsconfig.json vitest.workspace.ts
 Copyright: 2024 LiveKit, Inc.
 License: Apache-2.0
 
 # sub-project files
-Files: agents/package.json examples/package.json plugins/elevenlabs/package.json agents/tsconfig.json plugins/elevenlabs/tsconfig.json examples/tsconfig.json
+Files: agents/package.json agents/api-extractor.json examples/package.json plugins/elevenlabs/package.json plugins/elevenlabs/api-extractor agents/tsconfig.json plugins/elevenlabs/tsconfig.json examples/tsconfig.json
 Copyright: 2024 LiveKit, Inc.
 License: Apache-2.0

agents/api-extractor.json

@@ -0,0 +1,20 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  /**
+   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
+   * standard settings to be shared across multiple projects.
+   *
+   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
+   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
+   * resolved using NodeJS require().
+   *
+   * SUPPORTED TOKENS: none
+   * DEFAULT VALUE: ""
+   */
+  "extends": "../api-extractor-shared.json",
+  "mainEntryPointFilePath": "./dist/index.d.ts"
+}

agents/package.json

@@ -8,15 +8,13 @@
   "type": "module",
   "scripts": {
     "build": "tsc",
-    "lint": "eslint src"
+    "lint": "eslint -f unix \"src/**/*.ts\"",
+    "api:check": "api-extractor run --typescript-compiler-folder ../node_modules/typescript",
+    "api:update": "api-extractor run --local --typescript-compiler-folder ../node_modules/typescript --verbose"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "@types/ws": "^8.5.10",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
-    "typescript-eslint": "^7.4.0"
+    "@microsoft/api-extractor": "^7.35.0",
+    "@types/ws": "^8.5.10"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

agents/src/cli.ts

@@ -1,12 +1,11 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { version } from './version.js';
-import { Option, Command } from 'commander';
-import { WorkerOptions, Worker } from './worker.js';
-import { EventEmitter } from 'events';
+import { Command, Option } from 'commander';
+import type { EventEmitter } from 'events';
 import { log } from './log.js';
+import { version } from './version.js';
+import { Worker, type WorkerOptions } from './worker.js';
 
 type CliArgs = {
   opts: WorkerOptions;

agents/src/http_server.ts

@@ -1,8 +1,7 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { createServer, ServerResponse, Server, IncomingMessage } from 'http';
+import { type IncomingMessage, type Server, type ServerResponse, createServer } from 'http';
 
 const healthCheck = async (res: ServerResponse) => {
   res.writeHead(200);

agents/src/index.ts

@@ -1,6 +1,9 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import * as cli from './cli.js';
+import * as stt from './stt/index.js';
+import * as tts from './tts/index.js';
 
 export * from './vad.js';
 export * from './plugin.js';
@@ -10,6 +13,5 @@ export * from './job_request.js';
 export * from './worker.js';
 export * from './utils.js';
 export * from './log.js';
-export * as cli from './cli.js';
-export * as stt from './stt/index.js';
-export * as tts from './tts/index.js';
+
+export { cli, stt, tts };

agents/src/ipc/job_main.ts

@@ -1,14 +1,13 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { IPC_MESSAGE, JobMainArgs, Message, Ping } from './protocol.js';
+import { type JobAssignment, ServerMessage } from '@livekit/protocol';
 import { Room } from '@livekit/rtc-node';
+import { type ChildProcess, fork } from 'child_process';
 import { EventEmitter, once } from 'events';
 import { JobContext } from '../job_context.js';
 import { log } from '../log.js';
-import { ChildProcess, fork } from 'child_process';
-import { JobAssignment, ServerMessage } from '@livekit/protocol';
+import { IPC_MESSAGE, type JobMainArgs, type Message, type Ping } from './protocol.js';
 
 export const runJob = (args: JobMainArgs): ChildProcess => {
   return fork(__filename, [args.raw, args.entry, args.fallbackURL]);

agents/src/ipc/job_process.ts

@@ -1,15 +1,20 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { Job } from '@livekit/protocol';
-import { IPC_MESSAGE, JobMainArgs, Message, Pong, StartJobResponse } from './protocol.js';
-import { runJob } from './job_main.js';
+import type { Job } from '@livekit/protocol';
+import type { ChildProcess } from 'child_process';
 import { once } from 'events';
+import type { Logger } from 'pino';
+import type { AcceptData } from '../job_request.js';
 import { log } from '../log.js';
-import { Logger } from 'pino';
-import { AcceptData } from '../job_request.js';
-import { ChildProcess } from 'child_process';
+import { runJob } from './job_main.js';
+import {
+  IPC_MESSAGE,
+  type JobMainArgs,
+  type Message,
+  type Pong,
+  type StartJobResponse,
+} from './protocol.js';
 
 const START_TIMEOUT = 90 * 1000;
 const PING_INTERVAL = 5 * 1000;
@@ -21,9 +26,9 @@ export class JobProcess {
   args: JobMainArgs;
   logger: Logger;
   process?: ChildProcess;
-  startTimeout?: Timer;
-  pongTimeout?: Timer;
-  pingInterval?: Timer;
+  startTimeout?: ReturnType<typeof setTimeout>;
+  pongTimeout?: ReturnType<typeof setTimeout>;
+  pingInterval?: ReturnType<typeof setInterval>;
 
   constructor(job: Job, acceptData: AcceptData, raw: string, fallbackURL: string) {
     this.#job = job;
@@ -80,8 +85,7 @@ export class JobProcess {
         if (delay > HIGH_PING_THRESHOLD) {
           this.logger.warn(`job is unresponsive (${delay}ms delay)`);
         }
-        // @ts-expect-error: this actually works fine types/bun doesn't have a typedecl for it yet
-        this.pongTimeout.refresh();
+        this.pongTimeout?.refresh();
       } else if (msg.type === IPC_MESSAGE.UserExit || msg.type === IPC_MESSAGE.ShutdownResponse) {
         this.logger.info('job exiting');
         this.clear();

agents/src/job_context.ts

@@ -1,10 +1,9 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { Room, LocalParticipant, RemoteParticipant } from '@livekit/rtc-node';
-import { Job } from '@livekit/protocol';
-import { EventEmitter } from 'events';
+import type { Job } from '@livekit/protocol';
+import type { LocalParticipant, RemoteParticipant, Room } from '@livekit/rtc-node';
+import type { EventEmitter } from 'events';
 
 export class JobContext {
   #job: Job;

agents/src/job_request.ts

@@ -1,10 +1,9 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { Job, ParticipantInfo, Room } from '@livekit/protocol';
-import { log } from './log.js';
+import type { Job, ParticipantInfo, Room } from '@livekit/protocol';
 import { EventEmitter } from 'events';
+import { log } from './log.js';
 
 class AnsweredError extends Error {
   constructor() {

agents/src/log.ts

@@ -1,8 +1,7 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import pino from 'pino';
+import { pino } from 'pino';
 
 export const log = pino({
   transport: {

agents/src/stt/stream_adapter.ts

@@ -1,11 +1,10 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
+import type { AudioFrame } from '@livekit/rtc-node';
+import { type AudioBuffer, mergeFrames } from '../utils.js';
+import { VADEventType, type VADStream } from '../vad.js';
 import { STT, SpeechEvent, SpeechEventType, SpeechStream } from './stt.js';
-import { VADEventType, VADStream } from '../vad.js';
-import { AudioFrame } from '@livekit/rtc-node';
-import { AudioBuffer, mergeFrames } from '../utils.js';
 
 export class StreamAdapterWrapper extends SpeechStream {
   closed: boolean;

agents/src/stt/stt.ts

@@ -1,9 +1,8 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
-import { AudioFrame } from '@livekit/rtc-node';
-import { AudioBuffer } from '../utils.js';
+import type { AudioFrame } from '@livekit/rtc-node';
+import type { AudioBuffer } from '../utils.js';
 
 export enum SpeechEventType {
   START_OF_SPEECH = 0,

agents/src/tts/index.ts

@@ -1,12 +1,21 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import { StreamAdapter, StreamAdapterWrapper } from './stream_adapter.js';
+import {
+  SynthesisEvent,
+  SynthesisEventType,
+  SynthesizeStream,
+  type SynthesizedAudio,
+  TTS,
+} from './tts.js';
 
 export {
   TTS,
   SynthesisEvent,
   SynthesisEventType,
   SynthesizedAudio,
   SynthesizeStream,
-} from './tts.js';
-export { StreamAdapter, StreamAdapterWrapper } from './stream_adapter.js';
+  StreamAdapter,
+  StreamAdapterWrapper,
+};

agents/src/tts/stream_adapter.ts

@@ -1,15 +1,14 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-
+import type { SentenceStream, SentenceTokenizer } from '../tokenize.js';
 import {
-  TTS,
   SynthesisEvent,
   SynthesisEventType,
-  SynthesizedAudio,
   SynthesizeStream,
+  type SynthesizedAudio,
+  TTS,
 } from './tts.js';
-import { SentenceStream, SentenceTokenizer } from '../tokenize.js';
 
 export class StreamAdapterWrapper extends SynthesizeStream {
   closed: boolean;