@agentuity/core 1.0.1 → 1.0.2

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Package Overview
 
-Core utilities and shared types for the Agentuity framework. This package provides foundational types, schemas, and utilities used across all Agentuity packages.
+Core utilities and shared types for the Agentuity framework. This package provides foundational types, schemas, error handling, and service interfaces used across all Agentuity packages.
 
 ## Commands
 
@@ -15,17 +15,85 @@ Core utilities and shared types for the Agentuity framework. This package provid
 - **Runtime**: Browser and Node/Bun compatible, no runtime-specific code. Must work in all JavaScript environments
 - **Build target**: ESNext with TypeScript declaration files
 - **Exports**: All public APIs exported from `src/index.ts`
-- **No dependencies**: This is a foundational package with zero runtime dependencies
+- **No runtime dependencies**: This is a foundational package with zero runtime dependencies
 
 ## Structure
 
 ```text
 src/
 ├── index.ts              # Main entry point, exports all modules
-├── json.ts               # JSON utilities
-├── standard_schema.ts    # Standard schema interfaces
-├── typehelper.ts         # TypeScript utility types
-└── services/             # Storage service interfaces
+├── error.ts              # RichError, StructuredError, isStructuredError
+├── json.ts               # safeStringify utility
+├── logger.ts             # Logger interface and LogLevel type
+├── standard_schema.ts    # StandardSchemaV1 interface
+├── string.ts             # toCamelCase, toPascalCase utilities
+├── typehelper.ts         # InferInput, InferOutput type utilities
+├── workbench-config.ts   # Workbench configuration encoding/decoding
+└── services/
+    ├── _util.ts          # buildUrl, toServiceException, toPayload, fromResponse
+    ├── adapter.ts        # FetchAdapter, FetchRequest/Response types
+    ├── exception.ts      # ServiceException class
+    ├── evalrun.ts        # Eval run event types and schemas
+    ├── keyvalue.ts       # KeyValueStorage interface and KeyValueStorageService
+    ├── queue.ts          # QueueService interface and QueueStorageService
+    ├── sandbox.ts        # Sandbox and Snapshot service interfaces
+    ├── session.ts        # Session event types and schemas
+    ├── stream.ts         # StreamStorage interface and StreamStorageService
+    └── vector.ts         # VectorStorage interface and VectorStorageService
+```
+
+## Key Exports
+
+### Error Handling
+
+```typescript
+import { RichError, StructuredError, isStructuredError } from '@agentuity/core';
+
+// StructuredError - error with code and metadata
+throw new StructuredError('NOT_FOUND', 'User not found', { userId: '123' });
+
+// RichError - error with rich formatting
+throw new RichError('Operation failed', { cause: originalError });
+
+// Type guard
+if (isStructuredError(error)) {
+	console.log(error.code, error.metadata);
+}
+```
+
+### Type Utilities
+
+```typescript
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@agentuity/core';
+
+// Infer schema input/output types (works with Zod, Valibot, ArkType, etc.)
+type Input = InferInput<typeof mySchema>;
+type Output = InferOutput<typeof mySchema>;
+```
+
+### Service Interfaces
+
+```typescript
+import {
+	KeyValueStorageService,
+	VectorStorageService,
+	StreamStorageService,
+	QueueStorageService,
+} from '@agentuity/core';
+
+// All storage services follow the same pattern:
+// - Interface defines the contract
+// - *Service class provides default implementation with FetchAdapter
+```
+
+### String Utilities
+
+```typescript
+import { toCamelCase, toPascalCase, safeStringify } from '@agentuity/core';
+
+toCamelCase('hello-world'); // 'helloWorld'
+toPascalCase('hello-world'); // 'HelloWorld'
+safeStringify(circularObject); // Safe JSON stringification
 ```
 
 ## Code Style
@@ -42,10 +110,10 @@ src/
 - **Type-only exports** - Many exports are `type` or `interface` only
 - **Standard Schema compatibility** - Follow StandardSchemaV1 spec for validation interfaces
 - **No side effects** - All exports must be pure (no global mutations)
+- **Service pattern** - Storage services take a FetchAdapter for HTTP abstraction
 
 ## Testing
 
-- No test framework configured yet
 - When adding tests, use Bun's built-in test runner: `bun test`
 - When running tests, prefer using a subagent (Task tool) to avoid context bloat from test output
 

package/dist/index.d.ts

@@ -15,4 +15,5 @@ export type { StandardSchemaV1 } from './standard_schema';
 export { toCamelCase, toPascalCase } from './string';
 export type { InferInput, InferOutput } from './typehelper';
 export { WorkbenchConfigError, WorkbenchNotFoundError, encodeWorkbenchConfig, decodeWorkbenchConfig, getWorkbenchConfig, type WorkbenchConfig, } from './workbench-config';
+export type { SDPDescription, ICECandidate, SignalMessage, SignalMsg, WebRTCConnectionState, WebRTCDisconnectReason, DataChannelConfig, DataChannelMessage, DataChannelState, WebRTCSignalingCallbacks, ConnectionQualitySummary, RecordingOptions, RecordingHandle, RecordingState, TrackSource, } from './webrtc';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAExE,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAevC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAWN,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEN,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,iCAAiC,GAGjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAON,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAkBN,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAIN,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEN,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,iCAAiC,GAGjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EA2CN,YAAY,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKzF,oBAAoB;AACpB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAKrD,oBAAoB;AACpB,OAAO,EACN,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,GAElB,MAAM,oBAAoB,CAAC;AAE5B,4EAA4E"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAExE,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAevC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAWN,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEN,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,iCAAiC,GAGjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAON,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAkBN,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAIN,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEN,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,iCAAiC,GAGjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EA2CN,YAAY,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKzF,oBAAoB;AACpB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAKrD,oBAAoB;AACpB,OAAO,EACN,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,GAElB,MAAM,oBAAoB,CAAC;AAqB5B,4EAA4E"}

package/dist/services/_util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_util.d.ts","sourceRoot":"","sources":["../../src/services/_util.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,QAAQ,GACpB,MAAM,MAAM,EACZ,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,QAAQ,eAAe,KACrB,MAWF,CAAC;AAEF,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC,CA2EhD;AAMD,wBAAsB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CA0CtE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBpE"}
+{"version":3,"file":"_util.d.ts","sourceRoot":"","sources":["../../src/services/_util.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,QAAQ,GACpB,MAAM,MAAM,EACZ,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,QAAQ,eAAe,KACrB,MAWF,CAAC;AAEF,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAoFhD;AAMD,wBAAsB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CA0CtE;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBpE"}

package/dist/services/_util.js

@@ -24,6 +24,14 @@ export async function toServiceException(method, url, response) {
                 statusCode: response.status,
                 sessionId,
             });
+        case 402:
+            return new ServiceException({
+                message: 'This action requires a paid plan. Please upgrade your account at https://app.agentuity.com/billing to continue.',
+                method,
+                url,
+                statusCode: response.status,
+                sessionId,
+            });
         case 404:
             return new ServiceException({
                 message: 'Not Found',

package/dist/services/_util.js.map

@@ -1 +1 @@
-{"version":3,"file":"_util.js","sourceRoot":"","sources":["../../src/services/_util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,CAAC,MAAM,QAAQ,GAAG,CACvB,IAAY,EACZ,IAAY,EACZ,OAAgB,EAChB,KAAuB,EACd,EAAE;IACX,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAChD,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC;IACzC,IAAI,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QAC5D,GAAG,IAAI,OAAO,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACX,GAAG,IAAI,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,MAAkB,EAClB,GAAW,EACX,QAAkB;IAElB,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACvD,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QACzB,KAAK,GAAG,CAAC;QACT,KAAK,GAAG;YACP,OAAO,IAAI,gBAAgB,CAAC;gBAC3B,OAAO,EAAE,cAAc;gBACvB,MAAM;gBACN,GAAG;gBACH,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,SAAS;aACT,CAAC,CAAC;QACJ,KAAK,GAAG;YACP,OAAO,IAAI,gBAAgB,CAAC;gBAC3B,OAAO,EAAE,WAAW;gBACpB,MAAM;gBACN,GAAG;gBACH,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,SAAS;aACT,CAAC,CAAC;QACJ,QAAQ;IACT,CAAC;IACD,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChD,IAAI,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyC,CAAC;YAChF,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBACnB,OAAO,IAAI,gBAAgB,CAAC;oBAC3B,OAAO,EAAE,OAAO,CAAC,KAAK;oBACtB,MAAM;oBACN,GAAG;oBACH,UAAU,EAAE,QAAQ,CAAC,MAAM;oBAC3B,SAAS;iBACT,CAAC,CAAC;YACJ,CAAC;YACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACrB,OAAO,IAAI,gBAAgB,CAAC;oBAC3B,OAAO,EAAE,OAAO,CAAC,OAAO;oBACxB,MAAM;oBACN,GAAG;oBACH,UAAU,EAAE,QAAQ,CAAC,MAAM;oBAC3B,SAAS;iBACT,CAAC,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,gBAAgB,CAAC;gBAC3B,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBAChC,MAAM;gBACN,GAAG;gBACH,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,SAAS;aACT,CAAC,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACR,kBAAkB;QACnB,CAAC;IACF,CAAC;IACD,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,IAAI,gBAAgB,CAAC;YAC3B,OAAO,EAAE,IAAI;YACb,MAAM;YACN,GAAG;YACH,UAAU,EAAE,QAAQ,CAAC,MAAM;YAC3B,SAAS;SACT,CAAC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACR,kBAAkB;IACnB,CAAC;IAED,OAAO,IAAI,gBAAgB,CAAC;QAC3B,OAAO,EAAE,QAAQ,CAAC,UAAU;QAC5B,MAAM;QACN,GAAG;QACH,UAAU,EAAE,QAAQ,CAAC,MAAM;QAC3B,SAAS;KACT,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AACrD,MAAM,eAAe,GAAG,YAAY,CAAC;AACrC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAa;IAC5C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;IAC9B,CAAC;IACD,QAAQ,OAAO,IAAI,EAAE,CAAC;QACrB,KAAK,QAAQ;YACZ,IACC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC;gBAChE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,EAC/D,CAAC;gBACF,IAAI,CAAC;oBACJ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACjB,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;gBAChC,CAAC;gBAAC,MAAM,CAAC;oBACR,kBAAkB;gBACnB,CAAC;YACF,CAAC;YACD,OAAO,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QAChC,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACZ,0CAA0C;YAC1C,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC,CAAC;QAChD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACf,IAAI,IAAI,YAAY,WAAW,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,IAAI,YAAY,UAAU,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,MAAqB,EAAE,iBAAiB,CAAC,CAAC;YACxD,CAAC;YACD,IAAI,IAAI,YAAY,cAAc,EAAE,CAAC;gBACpC,OAAO,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;YAClC,CAAC;YACD,IAAI,IAAI,YAAY,OAAO,EAAE,CAAC;gBAC7B,OAAO,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC;YAC9B,CAAC;YACD,IAAI,IAAI,YAAY,QAAQ,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;YAC1B,CAAC;YACD,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC,CAAC;QAC/C,CAAC;IACF,CAAC;IACD,OAAO,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,QAAkB;IACvD,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAClE,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;IAEjD,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;IACrC,CAAC;IAED,IAAI,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,uEAAuE;QACvE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC;gBACJ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACR,2BAA2B;YAC5B,CAAC;QACF,CAAC;QACD,OAAO,IAAS,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAM,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"_util.js","sourceRoot":"","sources":["../../src/services/_util.ts"],"names":[],"mappings":"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"}

package/dist/webrtc.d.ts

@@ -0,0 +1,243 @@
+/**
+ * WebRTC signaling types shared between server and client.
+ */
+/**
+ * SDP (Session Description Protocol) description for WebRTC negotiation.
+ */
+export interface SDPDescription {
+    type: 'offer' | 'answer' | 'pranswer' | 'rollback';
+    sdp?: string;
+}
+/**
+ * ICE (Interactive Connectivity Establishment) candidate for NAT traversal.
+ */
+export interface ICECandidate {
+    candidate?: string;
+    sdpMid?: string | null;
+    sdpMLineIndex?: number | null;
+    usernameFragment?: string | null;
+}
+/**
+ * Signaling message protocol for WebRTC peer communication.
+ *
+ * Message types:
+ * - `join`: Client requests to join a room
+ * - `joined`: Server confirms join with peer ID and existing peers
+ * - `peer-joined`: Server notifies when another peer joins the room
+ * - `peer-left`: Server notifies when a peer leaves the room
+ * - `sdp`: SDP offer/answer exchange between peers
+ * - `ice`: ICE candidate exchange between peers
+ * - `error`: Error message from server
+ */
+export type SignalMessage = {
+    t: 'join';
+    roomId: string;
+} | {
+    t: 'joined';
+    peerId: string;
+    roomId: string;
+    peers: string[];
+} | {
+    t: 'peer-joined';
+    peerId: string;
+} | {
+    t: 'peer-left';
+    peerId: string;
+} | {
+    t: 'sdp';
+    from: string;
+    to?: string;
+    description: SDPDescription;
+} | {
+    t: 'ice';
+    from: string;
+    to?: string;
+    candidate: ICECandidate;
+} | {
+    t: 'error';
+    message: string;
+};
+/**
+ * @deprecated Use `SignalMessage` instead. Alias for backwards compatibility.
+ */
+export type SignalMsg = SignalMessage;
+/**
+ * WebRTC connection states for the frontend state machine.
+ *
+ * State transitions:
+ * - idle → connecting: connect() called
+ * - connecting → signaling: WebSocket opened, joined room
+ * - connecting → idle: error or cancel
+ * - signaling → negotiating: peer joined, SDP exchange started
+ * - signaling → idle: hangup or WebSocket closed
+ * - negotiating → connected: ICE complete, media flowing
+ * - negotiating → signaling: peer left during negotiation
+ * - negotiating → idle: error or hangup
+ * - connected → negotiating: renegotiation needed
+ * - connected → signaling: peer left
+ * - connected → idle: hangup or WebSocket closed
+ */
+export type WebRTCConnectionState = 'idle' | 'connecting' | 'signaling' | 'negotiating' | 'connected';
+/**
+ * Reasons for disconnection.
+ */
+export type WebRTCDisconnectReason = 'hangup' | 'error' | 'peer-left' | 'timeout';
+/**
+ * Configuration for creating a data channel.
+ */
+export interface DataChannelConfig {
+    /** Unique label for the channel */
+    label: string;
+    /** Whether messages are ordered (default: true) */
+    ordered?: boolean;
+    /** Maximum retransmit time in milliseconds */
+    maxPacketLifeTime?: number;
+    /** Maximum number of retransmissions */
+    maxRetransmits?: number;
+    /** Sub-protocol name */
+    protocol?: string;
+}
+/**
+ * Message types for data channel communication.
+ */
+export type DataChannelMessage = {
+    type: 'string';
+    data: string;
+} | {
+    type: 'binary';
+    data: ArrayBuffer;
+} | {
+    type: 'json';
+    data: unknown;
+};
+/**
+ * Data channel state.
+ */
+export type DataChannelState = 'connecting' | 'open' | 'closing' | 'closed';
+/**
+ * Normalized connection quality summary.
+ * Derived from RTCPeerConnection.getStats() for easy consumption.
+ */
+export interface ConnectionQualitySummary {
+    /** Round-trip time in milliseconds */
+    rtt?: number;
+    /** Packet loss percentage (0-100) */
+    packetLossPercent?: number;
+    /** Jitter in milliseconds (audio) */
+    jitter?: number;
+    /** Current bitrate in bits per second */
+    bitrate?: {
+        audio?: {
+            inbound?: number;
+            outbound?: number;
+        };
+        video?: {
+            inbound?: number;
+            outbound?: number;
+        };
+    };
+    /** Video metrics */
+    video?: {
+        framesPerSecond?: number;
+        framesDropped?: number;
+        frameWidth?: number;
+        frameHeight?: number;
+    };
+    /** ICE candidate pair info */
+    candidatePair?: {
+        localType?: string;
+        remoteType?: string;
+        protocol?: string;
+        usingRelay?: boolean;
+    };
+    /** Timestamp when stats were collected */
+    timestamp: number;
+}
+/**
+ * Recording options for MediaRecorder.
+ */
+export interface RecordingOptions {
+    /** MIME type for recording (default: 'video/webm;codecs=vp9,opus' or 'audio/webm;codecs=opus') */
+    mimeType?: string;
+    /** Audio bits per second */
+    audioBitsPerSecond?: number;
+    /** Video bits per second */
+    videoBitsPerSecond?: number;
+}
+/**
+ * Recording handle for controlling an active recording.
+ */
+export interface RecordingHandle {
+    /** Stop recording and get the blob */
+    stop(): Promise<Blob>;
+    /** Pause recording */
+    pause(): void;
+    /** Resume recording */
+    resume(): void;
+    /** Current recording state */
+    readonly state: RecordingState;
+}
+/**
+ * Recording state.
+ */
+export type RecordingState = 'inactive' | 'recording' | 'paused';
+/**
+ * Abstract track source interface for custom media sources.
+ * Implementations can provide camera, screen share, or custom tracks.
+ *
+ * Note: This interface is implemented in @agentuity/frontend where
+ * browser APIs (MediaStream) are available.
+ */
+export interface TrackSource {
+    /** Get the media stream from this source (returns browser MediaStream) */
+    getStream(): Promise<unknown>;
+    /** Stop the source and release resources */
+    stop(): void;
+    /** Source type identifier */
+    readonly type: 'user-media' | 'display-media' | 'custom';
+}
+/**
+ * Callbacks for WebRTC signaling server events.
+ * All callbacks are optional - only subscribe to events you care about.
+ */
+export interface WebRTCSignalingCallbacks {
+    /**
+     * Called when a new room is created.
+     * @param roomId - The room ID
+     */
+    onRoomCreated?: (roomId: string) => void;
+    /**
+     * Called when a room is destroyed (last peer left).
+     * @param roomId - The room ID
+     */
+    onRoomDestroyed?: (roomId: string) => void;
+    /**
+     * Called when a peer joins a room.
+     * @param peerId - The peer's ID
+     * @param roomId - The room ID
+     */
+    onPeerJoin?: (peerId: string, roomId: string) => void;
+    /**
+     * Called when a peer leaves a room.
+     * @param peerId - The peer's ID
+     * @param roomId - The room ID
+     * @param reason - Why the peer left
+     */
+    onPeerLeave?: (peerId: string, roomId: string, reason: 'disconnect' | 'kicked') => void;
+    /**
+     * Called when a signaling message is relayed.
+     * @param type - Message type ('sdp' or 'ice')
+     * @param from - Sender peer ID
+     * @param to - Target peer ID (undefined for broadcast)
+     * @param roomId - The room ID
+     */
+    onMessage?: (type: 'sdp' | 'ice', from: string, to: string | undefined, roomId: string) => void;
+    /**
+     * Called when an error occurs.
+     * @param error - The error that occurred
+     * @param peerId - The peer ID if applicable
+     * @param roomId - The room ID if applicable
+     */
+    onError?: (error: Error, peerId?: string, roomId?: string) => void;
+}
+//# sourceMappingURL=webrtc.d.ts.map

package/dist/webrtc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webrtc.d.ts","sourceRoot":"","sources":["../src/webrtc.ts"],"names":[],"mappings":"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"}

package/dist/webrtc.js

@@ -0,0 +1,5 @@
+/**
+ * WebRTC signaling types shared between server and client.
+ */
+export {};
+//# sourceMappingURL=webrtc.js.map

package/dist/webrtc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webrtc.js","sourceRoot":"","sources":["../src/webrtc.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/core",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -37,7 +37,7 @@
 		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "1.0.1",
+		"@agentuity/test-utils": "1.0.2",
 		"@types/bun": "latest",
 		"bun-types": "latest",
 		"esbuild": "^0.25.0",

package/src/env.d.ts

@@ -0,0 +1,229 @@
+/**
+ * SDK Environment Variable Type Definitions
+ *
+ * This file augments NodeJS.ProcessEnv with all Agentuity SDK environment variables.
+ * All variables are optional (may or may not be set at runtime).
+ */
+
+declare global {
+	namespace NodeJS {
+		interface ProcessEnv {
+			// ============================================================================
+			// Authentication & Secrets
+			// ============================================================================
+
+			/**
+			 * SDK authentication key for Agentuity services.
+			 * Used by the runtime to authenticate API requests.
+			 */
+			AGENTUITY_SDK_KEY?: string;
+
+			/**
+			 * Auth secret for session signing and encryption.
+			 * Falls back to BETTER_AUTH_SECRET if not set.
+			 */
+			AGENTUITY_AUTH_SECRET?: string;
+
+			/**
+			 * Cloud base URL for authentication.
+			 * Fallback chain: AGENTUITY_BASE_URL → BETTER_AUTH_URL
+			 */
+			AGENTUITY_CLOUD_BASE_URL?: string;
+
+			/** Base URL fallback for cloud services */
+			AGENTUITY_BASE_URL?: string;
+
+			/** User ID for authentication context */
+			AGENTUITY_USER_ID?: string;
+
+			// ============================================================================
+			// Service URLs & Endpoints
+			// ============================================================================
+
+			/**
+			 * Region identifier for service URL construction.
+			 * Values: 'usc' (US Central), 'local', etc.
+			 */
+			AGENTUITY_REGION?: string;
+
+			/** Transport service URL for agent communication */
+			AGENTUITY_TRANSPORT_URL?: string;
+
+			/** Catalyst service URL for AI model access */
+			AGENTUITY_CATALYST_URL?: string;
+
+			/** Key-value storage service URL */
+			AGENTUITY_KEYVALUE_URL?: string;
+
+			/** Vector storage service URL */
+			AGENTUITY_VECTOR_URL?: string;
+
+			/** Sandbox execution service URL */
+			AGENTUITY_SANDBOX_URL?: string;
+
+			/** Stream storage service URL */
+			AGENTUITY_STREAM_URL?: string;
+
+			/** OpenTelemetry Protocol endpoint URL */
+			AGENTUITY_OTLP_URL?: string;
+
+			/** AI Gateway URL for model routing */
+			AGENTUITY_AIGATEWAY_URL?: string;
+
+			/** Main API URL for Agentuity services */
+			AGENTUITY_API_URL?: string;
+
+			/** App/dashboard URL */
+			AGENTUITY_APP_URL?: string;
+
+			// ============================================================================
+			// Logging & Observability
+			// ============================================================================
+
+			/**
+			 * Log level for application logging.
+			 * Values: 'trace', 'debug', 'info', 'warn', 'error'
+			 */
+			AGENTUITY_LOG_LEVEL?: string;
+
+			/**
+			 * SDK-specific log level (overrides AGENTUITY_LOG_LEVEL for SDK internals).
+			 * Values: 'trace', 'debug', 'info', 'warn', 'error'
+			 */
+			AGENTUITY_SDK_LOG_LEVEL?: string;
+
+			/** Enable OpenTelemetry debug output to console */
+			AGENTUITY_DEBUG_OTEL_CONSOLE?: string;
+
+			/**
+			 * Bearer token for OTLP authentication.
+			 * Falls back to AGENTUITY_SDK_KEY if not set.
+			 */
+			AGENTUITY_OTLP_BEARER_TOKEN?: string;
+
+			/** Directory for cloud telemetry export */
+			AGENTUITY_CLOUD_EXPORT_DIR?: string;
+
+			/** Log level for Gravity logging subsystem */
+			AGENTUITY_GRAVITY_LOG_LEVEL?: string;
+
+			/** File path for clean/structured log output */
+			AGENTUITY_CLEAN_LOGS_FILE?: string;
+
+			/** Internal session ID for request correlation */
+			AGENTUITY_INTERNAL_SESSION_ID?: string;
+
+			// ============================================================================
+			// Build & Runtime Configuration
+			// ============================================================================
+
+			/**
+			 * Environment name for the application.
+			 * Falls back to NODE_ENV if not set.
+			 */
+			AGENTUITY_ENVIRONMENT?: string;
+
+			/** Node.js environment (development, production, test) */
+			NODE_ENV?: string;
+
+			/** Enable SDK development mode with additional debugging */
+			AGENTUITY_SDK_DEV_MODE?: string;
+
+			/**
+			 * Flag indicating code is running inside the Agentuity agent runtime.
+			 * Set automatically by the runtime.
+			 */
+			AGENTUITY_RUNTIME?: string;
+
+			/** Environment shorthand (dev, staging, prod) */
+			AGENTUITY_ENV?: string;
+
+			/** HTTP server port */
+			PORT?: string;
+
+			/** Agentuity-specific server port (overrides PORT) */
+			AGENTUITY_PORT?: string;
+
+			/** Vite development server port */
+			VITE_PORT?: string;
+
+			/** Development mode flag */
+			DEV?: string;
+
+			// ============================================================================
+			// Cloud Deployment & Metadata
+			// ============================================================================
+
+			/** SDK version deployed to cloud */
+			AGENTUITY_CLOUD_SDK_VERSION?: string;
+
+			/** CLI version used for deployment */
+			AGENTUITY_CLI_VERSION?: string;
+
+			/** Organization ID in Agentuity Cloud */
+			AGENTUITY_CLOUD_ORG_ID?: string;
+
+			/** Project ID in Agentuity Cloud */
+			AGENTUITY_CLOUD_PROJECT_ID?: string;
+
+			/** Deployment ID in Agentuity Cloud */
+			AGENTUITY_CLOUD_DEPLOYMENT_ID?: string;
+
+			/**
+			 * Cloud domains configuration.
+			 * JSON array of domain strings.
+			 */
+			AGENTUITY_CLOUD_DOMAINS?: string;
+
+			/** Local project directory path */
+			AGENTUITY_PROJECT_DIR?: string;
+
+			/** Configuration profile name */
+			AGENTUITY_PROFILE?: string;
+
+			/** Deployment name/identifier */
+			AGENTUITY_DEPLOYMENT?: string;
+
+			// ============================================================================
+			// Database
+			// ============================================================================
+
+			/**
+			 * Database connection URL.
+			 * Standard connection string format: protocol://user:pass@host:port/db
+			 */
+			DATABASE_URL?: string;
+
+			// ============================================================================
+			// Development & Testing
+			// ============================================================================
+
+			/** CI environment flag (set in CI/CD pipelines) */
+			CI?: string;
+
+			/**
+			 * Sandbox ID when running in an Agentuity sandbox environment.
+			 * Set automatically by the sandbox runtime.
+			 */
+			AGENTUITY_SANDBOX_ID?: string;
+
+			// ============================================================================
+			// Third-Party & System
+			// ============================================================================
+
+			/** S3-compatible endpoint URL */
+			S3_ENDPOINT?: string;
+
+			/** AWS endpoint URL override */
+			AWS_ENDPOINT?: string;
+
+			/**
+			 * Trusted domains for authentication.
+			 * Comma-separated list of domain patterns.
+			 */
+			AUTH_TRUSTED_DOMAINS?: string;
+		}
+	}
+}
+
+export {};

package/src/index.ts

@@ -162,4 +162,23 @@ export {
 	type WorkbenchConfig,
 } from './workbench-config';
 
+// webrtc.ts exports
+export type {
+	SDPDescription,
+	ICECandidate,
+	SignalMessage,
+	SignalMsg,
+	WebRTCConnectionState,
+	WebRTCDisconnectReason,
+	DataChannelConfig,
+	DataChannelMessage,
+	DataChannelState,
+	WebRTCSignalingCallbacks,
+	ConnectionQualitySummary,
+	RecordingOptions,
+	RecordingHandle,
+	RecordingState,
+	TrackSource,
+} from './webrtc';
+
 // Client code moved to @agentuity/frontend for better bundler compatibility

package/src/services/_util.ts

@@ -36,6 +36,15 @@ export async function toServiceException(
 				statusCode: response.status,
 				sessionId,
 			});
+		case 402:
+			return new ServiceException({
+				message:
+					'This action requires a paid plan. Please upgrade your account at https://app.agentuity.com/billing to continue.',
+				method,
+				url,
+				statusCode: response.status,
+				sessionId,
+			});
 		case 404:
 			return new ServiceException({
 				message: 'Not Found',

package/src/webrtc.ts

@@ -0,0 +1,259 @@
+/**
+ * WebRTC signaling types shared between server and client.
+ */
+
+// =============================================================================
+// Signaling Protocol Types
+// =============================================================================
+
+/**
+ * SDP (Session Description Protocol) description for WebRTC negotiation.
+ */
+export interface SDPDescription {
+	type: 'offer' | 'answer' | 'pranswer' | 'rollback';
+	sdp?: string;
+}
+
+/**
+ * ICE (Interactive Connectivity Establishment) candidate for NAT traversal.
+ */
+export interface ICECandidate {
+	candidate?: string;
+	sdpMid?: string | null;
+	sdpMLineIndex?: number | null;
+	usernameFragment?: string | null;
+}
+
+/**
+ * Signaling message protocol for WebRTC peer communication.
+ *
+ * Message types:
+ * - `join`: Client requests to join a room
+ * - `joined`: Server confirms join with peer ID and existing peers
+ * - `peer-joined`: Server notifies when another peer joins the room
+ * - `peer-left`: Server notifies when a peer leaves the room
+ * - `sdp`: SDP offer/answer exchange between peers
+ * - `ice`: ICE candidate exchange between peers
+ * - `error`: Error message from server
+ */
+export type SignalMessage =
+	| { t: 'join'; roomId: string }
+	| { t: 'joined'; peerId: string; roomId: string; peers: string[] }
+	| { t: 'peer-joined'; peerId: string }
+	| { t: 'peer-left'; peerId: string }
+	| { t: 'sdp'; from: string; to?: string; description: SDPDescription }
+	| { t: 'ice'; from: string; to?: string; candidate: ICECandidate }
+	| { t: 'error'; message: string };
+
+/**
+ * @deprecated Use `SignalMessage` instead. Alias for backwards compatibility.
+ */
+export type SignalMsg = SignalMessage;
+
+// =============================================================================
+// Frontend State Machine Types
+// =============================================================================
+
+/**
+ * WebRTC connection states for the frontend state machine.
+ *
+ * State transitions:
+ * - idle → connecting: connect() called
+ * - connecting → signaling: WebSocket opened, joined room
+ * - connecting → idle: error or cancel
+ * - signaling → negotiating: peer joined, SDP exchange started
+ * - signaling → idle: hangup or WebSocket closed
+ * - negotiating → connected: ICE complete, media flowing
+ * - negotiating → signaling: peer left during negotiation
+ * - negotiating → idle: error or hangup
+ * - connected → negotiating: renegotiation needed
+ * - connected → signaling: peer left
+ * - connected → idle: hangup or WebSocket closed
+ */
+export type WebRTCConnectionState =
+	| 'idle'
+	| 'connecting'
+	| 'signaling'
+	| 'negotiating'
+	| 'connected';
+
+/**
+ * Reasons for disconnection.
+ */
+export type WebRTCDisconnectReason = 'hangup' | 'error' | 'peer-left' | 'timeout';
+
+// =============================================================================
+// Data Channel Types
+// =============================================================================
+
+/**
+ * Configuration for creating a data channel.
+ */
+export interface DataChannelConfig {
+	/** Unique label for the channel */
+	label: string;
+	/** Whether messages are ordered (default: true) */
+	ordered?: boolean;
+	/** Maximum retransmit time in milliseconds */
+	maxPacketLifeTime?: number;
+	/** Maximum number of retransmissions */
+	maxRetransmits?: number;
+	/** Sub-protocol name */
+	protocol?: string;
+}
+
+/**
+ * Message types for data channel communication.
+ */
+export type DataChannelMessage =
+	| { type: 'string'; data: string }
+	| { type: 'binary'; data: ArrayBuffer }
+	| { type: 'json'; data: unknown };
+
+/**
+ * Data channel state.
+ */
+export type DataChannelState = 'connecting' | 'open' | 'closing' | 'closed';
+
+// =============================================================================
+// Connection Quality / Stats Types
+// =============================================================================
+
+/**
+ * Normalized connection quality summary.
+ * Derived from RTCPeerConnection.getStats() for easy consumption.
+ */
+export interface ConnectionQualitySummary {
+	/** Round-trip time in milliseconds */
+	rtt?: number;
+	/** Packet loss percentage (0-100) */
+	packetLossPercent?: number;
+	/** Jitter in milliseconds (audio) */
+	jitter?: number;
+	/** Current bitrate in bits per second */
+	bitrate?: {
+		audio?: { inbound?: number; outbound?: number };
+		video?: { inbound?: number; outbound?: number };
+	};
+	/** Video metrics */
+	video?: {
+		framesPerSecond?: number;
+		framesDropped?: number;
+		frameWidth?: number;
+		frameHeight?: number;
+	};
+	/** ICE candidate pair info */
+	candidatePair?: {
+		localType?: string;
+		remoteType?: string;
+		protocol?: string;
+		usingRelay?: boolean;
+	};
+	/** Timestamp when stats were collected */
+	timestamp: number;
+}
+
+/**
+ * Recording options for MediaRecorder.
+ */
+export interface RecordingOptions {
+	/** MIME type for recording (default: 'video/webm;codecs=vp9,opus' or 'audio/webm;codecs=opus') */
+	mimeType?: string;
+	/** Audio bits per second */
+	audioBitsPerSecond?: number;
+	/** Video bits per second */
+	videoBitsPerSecond?: number;
+}
+
+/**
+ * Recording handle for controlling an active recording.
+ */
+export interface RecordingHandle {
+	/** Stop recording and get the blob */
+	stop(): Promise<Blob>;
+	/** Pause recording */
+	pause(): void;
+	/** Resume recording */
+	resume(): void;
+	/** Current recording state */
+	readonly state: RecordingState;
+}
+
+/**
+ * Recording state.
+ */
+export type RecordingState = 'inactive' | 'recording' | 'paused';
+
+// =============================================================================
+// Track Source Types
+// =============================================================================
+
+/**
+ * Abstract track source interface for custom media sources.
+ * Implementations can provide camera, screen share, or custom tracks.
+ *
+ * Note: This interface is implemented in @agentuity/frontend where
+ * browser APIs (MediaStream) are available.
+ */
+export interface TrackSource {
+	/** Get the media stream from this source (returns browser MediaStream) */
+	getStream(): Promise<unknown>;
+	/** Stop the source and release resources */
+	stop(): void;
+	/** Source type identifier */
+	readonly type: 'user-media' | 'display-media' | 'custom';
+}
+
+// =============================================================================
+// Backend Signaling Callbacks
+// =============================================================================
+
+/**
+ * Callbacks for WebRTC signaling server events.
+ * All callbacks are optional - only subscribe to events you care about.
+ */
+export interface WebRTCSignalingCallbacks {
+	/**
+	 * Called when a new room is created.
+	 * @param roomId - The room ID
+	 */
+	onRoomCreated?: (roomId: string) => void;
+
+	/**
+	 * Called when a room is destroyed (last peer left).
+	 * @param roomId - The room ID
+	 */
+	onRoomDestroyed?: (roomId: string) => void;
+
+	/**
+	 * Called when a peer joins a room.
+	 * @param peerId - The peer's ID
+	 * @param roomId - The room ID
+	 */
+	onPeerJoin?: (peerId: string, roomId: string) => void;
+
+	/**
+	 * Called when a peer leaves a room.
+	 * @param peerId - The peer's ID
+	 * @param roomId - The room ID
+	 * @param reason - Why the peer left
+	 */
+	onPeerLeave?: (peerId: string, roomId: string, reason: 'disconnect' | 'kicked') => void;
+
+	/**
+	 * Called when a signaling message is relayed.
+	 * @param type - Message type ('sdp' or 'ice')
+	 * @param from - Sender peer ID
+	 * @param to - Target peer ID (undefined for broadcast)
+	 * @param roomId - The room ID
+	 */
+	onMessage?: (type: 'sdp' | 'ice', from: string, to: string | undefined, roomId: string) => void;
+
+	/**
+	 * Called when an error occurs.
+	 * @param error - The error that occurred
+	 * @param peerId - The peer ID if applicable
+	 * @param roomId - The room ID if applicable
+	 */
+	onError?: (error: Error, peerId?: string, roomId?: string) => void;
+}