@mastra/voice-aws-nova-sonic 0.2.1 → 0.2.2-alpha.1

package/LICENSE.md

@@ -1,10 +1,12 @@
 Portions of this software are licensed as follows:
 
-- All content that resides under any directory named "ee/" within this
+- All content that resides under any directory named `ee/` within this
   repository, including but not limited to:
-  - `packages/core/src/auth/ee/`
-  - `packages/server/src/server/auth/ee/`
-    is licensed under the license defined in `ee/LICENSE`.
+  - `@mastra/core/auth/ee`
+  - `@mastra/core/agent-builder/ee`
+  - `@mastra/editor/ee`
+
+  is licensed under the license defined in [`ee/LICENSE`](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).
 
 - All third-party components incorporated into the Mastra Software are
   licensed under the original license provided by the owner of the

package/README.md

@@ -2,97 +2,10 @@
 
 Mastra integration for AWS Nova 2 Sonic, providing real-time bidirectional speech-to-speech capabilities using Amazon Bedrock's bidirectional streaming API.
 
-## Features
-
-- **Real-time bidirectional streaming**: Continuous audio streaming in both directions
-- **Multilingual support**: Supports English, French, Italian, German, Spanish, Portuguese, and Hindi
-- **Polyglot voices**: Voices that can speak multiple languages within the same session
-- **Barge-in support**: Users can interrupt the assistant mid-speech; handled server-side by Nova Sonic
-- **Tool/function calling**: Support for agentic workflows and async tool execution
-- **Cross-modal input**: Support for both audio and text inputs in the same conversation
-- **Natural turn-taking**: Intelligent voice activity detection and turn management
-- **Robust error handling**: Comprehensive error handling with detailed error codes
-
 ## Installation
 
 ```bash
 npm install @mastra/voice-aws-nova-sonic
-# or
-pnpm add @mastra/voice-aws-nova-sonic
-# or
-yarn add @mastra/voice-aws-nova-sonic
-```
-
-## Prerequisites
-
-- Node.js >= 22.13.0
-- AWS account with access to Amazon Bedrock
-- AWS credentials configured (see [AWS Setup](#aws-setup))
-- Access to Nova 2 Sonic model in your AWS region
-
-## AWS Setup
-
-### 1. Enable Nova 2 Sonic in Amazon Bedrock
-
-1. Go to the [Amazon Bedrock Console](https://console.aws.amazon.com/bedrock/)
-2. Navigate to "Model access" in the left sidebar
-3. Request access to "Amazon Nova 2 Sonic" model
-4. Wait for approval (usually instant)
-
-### 2. Configure AWS Credentials
-
-You can configure AWS credentials in several ways:
-
-**Option 1: Environment Variables**
-
-```bash
-export AWS_ACCESS_KEY_ID=your-access-key-id
-export AWS_SECRET_ACCESS_KEY=your-secret-access-key
-export AWS_REGION=us-east-1
-```
-
-**Option 2: AWS Credentials File**
-
-```ini
-# ~/.aws/credentials
-[default]
-aws_access_key_id = your-access-key-id
-aws_secret_access_key = your-secret-access-key
-```
-
-**Option 3: IAM Role** (for EC2/Lambda)
-
-- Attach an IAM role with Bedrock permissions to your EC2 instance or Lambda function
-
-**Option 4: Explicit Credentials in Code**
-
-```typescript
-import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic';
-
-const voice = new NovaSonicVoice({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'your-access-key-id',
-    secretAccessKey: 'your-secret-access-key',
-  },
-});
-```
-
-### 3. IAM Permissions
-
-Your AWS credentials need the following IAM permissions:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithBidirectionalStream"],
-      "Resource": "arn:aws:bedrock:*::foundation-model/amazon.nova-2-sonic-v1:0"
-    }
-  ]
-}
 ```
 
 ## Usage
@@ -132,253 +45,14 @@ agent.voice.on('writing', ({ text, role, generationStage }) => {
 await agent.voice.send(microphoneStream);
 ```
 
-### Advanced Configuration
-
-```typescript
-import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic';
-
-const voice = new NovaSonicVoice({
-  region: 'us-east-1', // or 'us-west-2', 'ap-northeast-1'
-  model: 'amazon.nova-2-sonic-v1:0',
-  speaker: 'matthew', // or 'tiffany', 'amy', etc.
-  languageCode: 'en-US',
-  instructions: 'You are a helpful assistant.',
-  sessionConfig: {
-    tools: [
-      {
-        name: 'search',
-        description: 'Search the web',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            query: { type: 'string' },
-          },
-          required: ['query'],
-        },
-      },
-    ],
-    turnDetectionConfiguration: {
-      // HIGH = fastest (1.5s pause), MEDIUM = balanced (1.75s), LOW = slowest (2s)
-      endpointingSensitivity: 'MEDIUM',
-    },
-  },
-  debug: true,
-});
-
-await voice.connect();
-```
-
-### With Tools
-
-```typescript
-import { Agent } from '@mastra/core/agent';
-import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic';
-import { createTool } from '@mastra/core/tools';
-import { z } from 'zod';
-
-const weatherTool = createTool({
-  id: 'weather',
-  description: 'Get weather information',
-  inputSchema: z.object({
-    location: z.string(),
-  }),
-  execute: async ({ context }) => {
-    // Fetch weather data
-    return { temperature: 72, condition: 'sunny' };
-  },
-});
-
-const agent = new Agent({
-  name: 'Weather Agent',
-  instructions: 'You help users get weather information.',
-  model: 'openai/gpt-4o',
-  tools: {
-    weather: weatherTool,
-  },
-  voice: new NovaSonicVoice({
-    region: 'us-east-1',
-  }),
-});
-
-await agent.voice.connect();
-// Tools are automatically available to the voice model
-```
-
-### Cross-Modal Text Input
-
-Send text messages during an active voice session:
-
-```typescript
-// After connecting and starting audio streaming
-await agent.voice.speak('What is the weather in New York?');
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-new NovaSonicVoice(config?: NovaSonicVoiceConfig)
-```
-
-**Configuration Options:**
-
-- `region` (string, optional): AWS region. Default: `'us-east-1'`. Supported: `'us-east-1'`, `'us-west-2'`, `'ap-northeast-1'`
-- `model` (string, optional): Model ID. Default: `'amazon.nova-2-sonic-v1:0'`
-- `credentials` (Credentials, optional): AWS credentials. If not provided, uses default credential chain
-- `speaker` (string, optional): Voice name/identifier (e.g., `'matthew'`, `'tiffany'`, `'amy'`)
-- `languageCode` (string, optional): Language code (e.g., `'en-US'`, `'fr-FR'`)
-- `instructions` (string, optional): System instructions for the model
-- `tools` (array, optional): Tool definitions
-- `sessionConfig` (object, optional): Session configuration including `turnDetectionConfiguration`, `tools`, `inferenceConfiguration`
-- `debug` (boolean, optional): Enable debug logging. Default: `false`
-
-### Methods
-
-#### `connect(options?)`
-
-Establishes connection to AWS Bedrock. Must be called before using other methods.
-
-```typescript
-await voice.connect();
-```
-
-#### `speak(input, options?)`
-
-Send cross-modal text input during an active voice session. Nova Sonic processes it and responds with audio.
-
-```typescript
-await voice.speak('Hello, world!');
-```
-
-#### `listen(audioStream, options?)`
-
-Stream audio input for transcription. For Nova Sonic, this is equivalent to `send()`.
-
-```typescript
-await voice.listen(audioStream);
-```
-
-#### `send(audioData)`
-
-Stream audio data in real-time. Accepts a `NodeJS.ReadableStream` (PCM16 audio) or an `Int16Array`.
-
-```typescript
-// Stream from a ReadableStream
-await voice.send(audioStream);
-
-// Or with Int16Array
-const audioArray = new Int16Array([...]);
-await voice.send(audioArray);
-```
-
-#### `close()`
-
-Disconnect and cleanup resources.
-
-```typescript
-voice.close();
-```
-
-#### `on(event, callback)`
-
-Register an event listener.
-
-```typescript
-voice.on('speaking', ({ audio }) => {
-  // audio is a base64-encoded string of PCM audio
-});
-
-voice.on('writing', ({ text, role, generationStage }) => {
-  // generationStage: 'SPECULATIVE' (preview) or 'FINAL' (actual transcript)
-  console.log(`${role}: ${text}`);
-});
-
-voice.on('error', ({ message, code }) => {
-  console.error(`Error: ${message} (${code})`);
-});
-```
-
-#### `off(event, callback)`
-
-Remove an event listener.
-
-```typescript
-voice.off('speaking', callback);
-```
-
-### Events
-
-- **`speaker`**: Audio stream (`NodeJS.ReadableStream`) for the full response
-- **`speaking`**: Audio chunk `{ audio: string, audioData: Buffer, response_id?: string }`
-- **`writing`**: Text transcription `{ text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }`
-- **`error`**: Error event `{ message: string, code?: string, details?: unknown }`
-- **`toolCall`**: Tool invocation `{ name: string, args: Record<string, any>, id: string }`
-- **`turnComplete`**: Turn completion `{ timestamp: number }`
-- **`interrupt`**: Barge-in detected `{ type: string, timestamp: number }`
-- **`contentStart`**: Content block started (raw Nova Sonic event)
-- **`contentEnd`**: Content block ended (raw Nova Sonic event)
-- **`usage`**: Token usage `{ inputTokens: number, outputTokens: number, totalTokens: number }`
-
-## Supported Regions
-
-- `us-east-1` (US East - N. Virginia)
-- `us-west-2` (US West - Oregon)
-- `ap-northeast-1` (Asia Pacific - Tokyo)
-
-## Supported Languages
-
-- English (US, UK, India, Australia)
-- French
-- Italian
-- German
-- Spanish
-- Portuguese
-- Hindi
-
-## Error Handling
-
-The package provides error handling with specific error codes:
-
-```typescript
-import { NovaSonicError, NovaSonicErrorCode } from '@mastra/voice-aws-nova-sonic';
-
-voice.on('error', ({ message, code, details }) => {
-  if (code === NovaSonicErrorCode.CONNECTION_FAILED) {
-    // Handle connection error
-  } else if (code === NovaSonicErrorCode.CREDENTIALS_MISSING) {
-    // Handle credentials error
-  }
-});
-```
-
-## Troubleshooting
-
-### Connection Issues
-
-- Verify AWS credentials are configured correctly
-- Check that Nova 2 Sonic is enabled in your AWS Bedrock console
-- Ensure your IAM role/user has the required permissions
-- Verify the region supports Nova 2 Sonic
-
-### Audio Issues
-
-- Ensure audio format is compatible (PCM, 16-bit, 16kHz)
-- Check sample rate matches expected format
-- Verify audio stream is not empty
-
-### Authentication Issues
+## Documentation
 
-- Check AWS credentials are valid
-- Verify IAM permissions include Bedrock access
-- Ensure region is correct
+- [@mastra/voice-aws-nova-sonic documentation](https://mastra.ai/integrations/voice/aws-nova-sonic)
 
-## License
+## Changelog
 
-Apache-2.0
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/voice/aws-nova-sonic/CHANGELOG.md) for version history and release notes.
 
-## Links
+## Support
 
-- [Mastra Documentation](https://mastra.ai)
-- [AWS Nova 2 Sonic Documentation](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-conversational-speech.html)
-- [Amazon Bedrock Documentation](https://docs.aws.amazon.com/bedrock/)
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/_types/@internal_voice/dist/_types/@internal_core/dist/base/index.d.ts

@@ -1,4 +1,4 @@
-import { i as IMastraLogger, u as RegisteredLogger } from "../index-S1lgaKO7.js";
+import { i as IMastraLogger, u as RegisteredLogger } from "../index-Biaf3BmX.js";
 //#region src/base/MastraBase.d.ts
 declare class MastraBase {
   #private;

package/dist/_types/@internal_voice/dist/_types/@internal_core/dist/index-Biaf3BmX.d.ts

@@ -0,0 +1,319 @@
+import { Transform } from "stream";
+//#region src/logger/adapter.d.ts
+/**
+ * OpenTelemetry-compatible trace correlation fields, injected at the top
+ * level of a logger's native record.
+ *
+ * Field names are part of the platform contract (snake_case, W3C formats):
+ * external consumers (e.g. the Studio logs view reading Railway stdout)
+ * parse structured log lines and look for exactly these keys.
+ */
+interface TraceFields {
+  /** 32-char lowercase hex W3C trace id */
+  trace_id: string;
+  /**
+   * 16-char lowercase hex W3C span id.
+   *
+   * Optional, and omitted rather than emitted empty: the active span may be
+   * one observability never exports (an internal span, or one dropped by
+   * `excludeSpanTypes`), leaving no span id a consumer could look up. The
+   * trace is still addressable in that case, so the line keeps `trace_id` and
+   * drops only this field. Consumers must treat `span_id` as possibly absent.
+   */
+  span_id?: string;
+}
+/**
+ * Destination for log records derived from the logger's native record,
+ * exported to Mastra observability. Structurally compatible with
+ * `LoggerContext` from `@mastra/core/observability`.
+ */
+interface AdapterLogSink {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+}
+interface LoggerAdapterOptions {
+  /** Inject trace_id/span_id into the logger's native records. */
+  correlation: boolean;
+  /** Export records derived from the native record to Mastra observability. */
+  export: boolean;
+}
+/**
+ * Context handed to an adaptable logger by Mastra when observability is
+ * wired up. All members are safe to call on every log call (synchronous,
+ * never throw).
+ */
+interface LoggerAdapterContext {
+  /**
+   * Resolve correlation fields for the currently active span, or undefined
+   * when no span is active (in which case no trace fields are added).
+   */
+  resolveTraceFields: () => TraceFields | undefined;
+  /**
+   * Resolve the observability log sink at call time. Returns the
+   * span-correlated sink when a span is active, the global sink otherwise,
+   * and undefined when export is disabled or observability is not
+   * initialized. Records must still be written to the native destination
+   * regardless.
+   */
+  getLogSink: () => AdapterLogSink | undefined;
+  options: LoggerAdapterOptions;
+}
+/**
+ * Capability marker a logger implements to opt into native trace
+ * correlation and observability export. When a configured logger implements
+ * this, Mastra attaches observability directly instead of wrapping the
+ * logger in the deprecated `DualLogger`.
+ */
+interface AdaptableLogger extends IMastraLogger {
+  __attachObservability(ctx: LoggerAdapterContext): void;
+  /**
+   * Stable identity for the attachment target. Loggers whose adapter context
+   * lives in state shared across a root/child family (e.g. PinoLogger's
+   * mixin ref cell) return that shared object, so attaching any family
+   * member is recognized as re-attaching the whole family. Defaults to the
+   * logger instance itself when absent.
+   */
+  __observabilityAttachmentKey?(): object;
+}
+declare function isAdaptableLogger(logger: IMastraLogger): logger is AdaptableLogger;
+/**
+ * Export a tracked exception through the adapter sink, mirroring the
+ * DualLogger dual-write shape (`errorId`/`domain`/`category`/`details`/`cause`
+ * when present on a MastraError-like value). Never throws into the caller.
+ */
+declare function exportTrackedException(ctx: LoggerAdapterContext | undefined, error: Error, metadata?: Record<string, unknown>): void;
+/**
+ * Adapt IMastraLogger's variadic args into the structured `data` payload of
+ * an exported log record. Extracts the first plain object as data,
+ * serializes an Error arg, and collects remaining primitives under `args`
+ * so the derived record preserves all context from the native call.
+ */
+declare function buildLogRecordData(args: unknown[]): Record<string, unknown> | undefined;
+//#endregion
+//#region src/logger/index.d.ts
+declare const RegisteredLogger: {
+  readonly AGENT: 'AGENT';
+  readonly OBSERVABILITY: 'OBSERVABILITY';
+  readonly AUTH: 'AUTH';
+  readonly BROWSER: 'BROWSER';
+  readonly NETWORK: 'NETWORK';
+  readonly WORKFLOW: 'WORKFLOW';
+  readonly LLM: 'LLM';
+  readonly TTS: 'TTS';
+  readonly VOICE: 'VOICE';
+  readonly VECTOR: 'VECTOR';
+  readonly BUNDLER: 'BUNDLER';
+  readonly DEPLOYER: 'DEPLOYER';
+  readonly MEMORY: 'MEMORY';
+  readonly STORAGE: 'STORAGE';
+  readonly EMBEDDINGS: 'EMBEDDINGS';
+  readonly MCP_SERVER: 'MCP_SERVER';
+  readonly SERVER_CACHE: 'SERVER_CACHE';
+  readonly SERVER: 'SERVER';
+  readonly WORKSPACE: 'WORKSPACE';
+  readonly CHANNEL: 'CHANNEL';
+};
+type RegisteredLogger = (typeof RegisteredLogger)[keyof typeof RegisteredLogger];
+declare const LogLevel: {
+  readonly DEBUG: 'debug';
+  readonly INFO: 'info';
+  readonly WARN: 'warn';
+  readonly ERROR: 'error';
+  readonly NONE: 'silent';
+};
+type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+interface BaseLogMessage {
+  runId?: string;
+  msg: string;
+  level: LogLevel;
+  time: Date;
+  pid: number;
+  hostname: string;
+  name: string;
+}
+declare abstract class LoggerTransport extends Transform {
+  constructor(opts?: any);
+  listLogsByRunId(_args: {
+    runId: string;
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: BaseLogMessage[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+  listLogs(_args?: {
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    returnPaginationResults?: boolean;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: BaseLogMessage[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+}
+declare const createCustomTransport: (stream: Transform, listLogs?: LoggerTransport['listLogs'], listLogsByRunId?: LoggerTransport['listLogsByRunId']) => LoggerTransport;
+interface IMastraLogger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+  trackException(error: Error, metadata?: Record<string, unknown>): void;
+  getTransports(): Map<string, LoggerTransport>;
+  listLogs(_transportId: string, _params?: {
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: BaseLogMessage[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+  listLogsByRunId(_args: {
+    transportId: string;
+    runId: string;
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: BaseLogMessage[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+}
+declare abstract class MastraLogger implements IMastraLogger {
+  protected name: string;
+  protected level: LogLevel;
+  protected transports: Map<string, LoggerTransport>;
+  constructor(options?: {
+    name?: string;
+    level?: LogLevel;
+    transports?: Record<string, LoggerTransport>;
+  });
+  abstract debug(message: string, ...args: any[]): void;
+  abstract info(message: string, ...args: any[]): void;
+  abstract warn(message: string, ...args: any[]): void;
+  abstract error(message: string, ...args: any[]): void;
+  getTransports(): Map<string, LoggerTransport>;
+  trackException(_error: Error, _metadata?: Record<string, unknown>): void;
+  listLogs(transportId: string, params?: {
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: BaseLogMessage[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+  listLogsByRunId({ transportId, runId, fromDate, toDate, logLevel, filters, page, perPage }: {
+    transportId: string;
+    runId: string;
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: BaseLogMessage[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+}
+type LogFilterContext = {
+  component?: RegisteredLogger;
+  level: LogLevel;
+  message: string;
+  args: unknown[];
+};
+type LogFilter = (ctx: LogFilterContext) => boolean;
+interface ConsoleLoggerOptions {
+  name?: string;
+  level?: LogLevel;
+  component?: RegisteredLogger;
+  filter?: LogFilter;
+}
+declare class ConsoleLogger extends MastraLogger {
+  #private;
+  protected component?: RegisteredLogger;
+  protected filter?: LogFilter;
+  constructor(options?: ConsoleLoggerOptions);
+  /**
+   * Adapter hook (see `AdaptableLogger`): enables native trace correlation
+   * (trace_id/span_id appended to console output) and observability export
+   * derived from the same record. Called by Mastra during setup.
+   */
+  __attachObservability(ctx: LoggerAdapterContext): void;
+  child(componentOrBindings: RegisteredLogger | Record<string, unknown>): ConsoleLogger;
+  private shouldLog;
+  private prefix;
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+  trackException(error: Error, metadata?: Record<string, unknown>): void;
+  listLogs(_transportId: string, _params?: {
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: never[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+  listLogsByRunId(_args: {
+    transportId: string;
+    runId: string;
+    fromDate?: Date;
+    toDate?: Date;
+    logLevel?: LogLevel;
+    filters?: Record<string, any>;
+    page?: number;
+    perPage?: number;
+  }): Promise<{
+    logs: never[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+  }>;
+}
+//#endregion
+export { buildLogRecordData as _, LogFilter as a, LoggerTransport as c, createCustomTransport as d, AdaptableLogger as f, TraceFields as g, LoggerAdapterOptions as h, IMastraLogger as i, MastraLogger as l, LoggerAdapterContext as m, ConsoleLogger as n, LogFilterContext as o, AdapterLogSink as p, ConsoleLoggerOptions as r, LogLevel as s, BaseLogMessage as t, RegisteredLogger as u, exportTrackedException as v, isAdaptableLogger as y };
+//# sourceMappingURL=index-Biaf3BmX.d.ts.map