@breadstone/archipel-mcp 0.0.51 → 0.0.53

package/data/packages/platform-intelligence/api/TypeAlias.IntelligenceRealtimeModelLoaders.md

@@ -0,0 +1,14 @@
+---
+title: 'Type Alias: IntelligenceRealtimeModelLoaders'
+generated: true
+editUrl: false
+---
+# Type Alias: IntelligenceRealtimeModelLoaders
+
+```ts
+type IntelligenceRealtimeModelLoaders = Partial<Record<IntelligenceProviderName, IntelligenceRealtimeModelLoader>>;
+```
+
+Defined in: providers/IntelligenceRealtimeModelLoaders.ts:13
+
+Maps configured intelligence providers to tree-shakable realtime model loaders.

package/data/packages/platform-intelligence/api/TypeAlias.IntelligenceRealtimeServerEvent.md

@@ -0,0 +1,159 @@
+---
+title: 'Type Alias: IntelligenceRealtimeServerEvent'
+generated: true
+editUrl: false
+---
+# Type Alias: IntelligenceRealtimeServerEvent
+
+```ts
+type IntelligenceRealtimeServerEvent = 
+  | {
+  raw: unknown;
+  sessionId?: string;
+  type: "session-created";
+}
+  | {
+  raw: unknown;
+  type: "session-updated";
+}
+  | {
+  itemId?: string;
+  raw: unknown;
+  type: "speech-started";
+}
+  | {
+  itemId?: string;
+  raw: unknown;
+  type: "speech-stopped";
+}
+  | {
+  itemId?: string;
+  previousItemId?: string;
+  raw: unknown;
+  type: "audio-committed";
+}
+  | {
+  item: unknown;
+  itemId: string;
+  raw: unknown;
+  type: "conversation-item-added";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  transcript: string;
+  type: "input-transcription-completed";
+}
+  | {
+  raw: unknown;
+  responseId: string;
+  type: "response-created";
+}
+  | {
+  raw: unknown;
+  responseId: string;
+  status: string;
+  type: "response-done";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "output-item-added";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "output-item-done";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "content-part-added";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "content-part-done";
+}
+  | {
+  delta: string;
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "audio-delta";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "audio-done";
+}
+  | {
+  delta: string;
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "audio-transcript-delta";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  transcript?: string;
+  type: "audio-transcript-done";
+}
+  | {
+  delta: string;
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "text-delta";
+}
+  | {
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  text?: string;
+  type: "text-done";
+}
+  | {
+  callId: string;
+  delta: string;
+  itemId: string;
+  raw: unknown;
+  responseId: string;
+  type: "function-call-arguments-delta";
+}
+  | {
+  arguments: string;
+  callId: string;
+  itemId: string;
+  name: string;
+  raw: unknown;
+  responseId: string;
+  type: "function-call-arguments-done";
+}
+  | {
+  code?: string;
+  message: string;
+  raw: unknown;
+  type: "error";
+}
+  | {
+  raw: unknown;
+  rawType: string;
+  type: "custom";
+};
+```
+
+Defined in: realtime/contracts/IntelligenceRealtimeServerEvent.ts:10
+
+Provider-neutral event emitted by a realtime model.
+
+The original provider event remains available through `raw` for audited
+provider-specific diagnostics without leaking provider contracts into the
+normal application flow.

package/data/packages/platform-intelligence/api/TypeAlias.IntelligenceRealtimeStatus.md

@@ -0,0 +1,14 @@
+---
+title: 'Type Alias: IntelligenceRealtimeStatus'
+generated: true
+editUrl: false
+---
+# Type Alias: IntelligenceRealtimeStatus
+
+```ts
+type IntelligenceRealtimeStatus = "idle" | "connecting" | "connected" | "closing" | "closed" | "error";
+```
+
+Defined in: realtime/contracts/IntelligenceRealtimeStatus.ts:6
+
+Describes the lifecycle state of an upstream realtime model connection.

package/data/packages/platform-intelligence/api/Variable.MIMO_API_KEY.md

@@ -9,6 +9,6 @@ editUrl: false
 const MIMO_API_KEY: IConfigKey<string>;
 ```
 
-Defined in: providers/mimo/env.ts:10
+Defined in: [providers/mimo/env.ts:10](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-intelligence/src/providers/mimo/env.ts#L10)
 
 MiMo-specific API key.

package/data/packages/platform-intelligence/api/Variable.MIMO_BASE_URL.md

@@ -9,6 +9,6 @@ editUrl: false
 const MIMO_BASE_URL: IConfigKey<string>;
 ```
 
-Defined in: providers/mimo/env.ts:13
+Defined in: [providers/mimo/env.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-intelligence/src/providers/mimo/env.ts#L13)
 
 MiMo-specific base URL.

package/data/packages/platform-intelligence/api/Variable.MIMO_CONFIG_ENTRIES.md

@@ -9,6 +9,6 @@ editUrl: false
 const MIMO_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, "module">>;
 ```
 
-Defined in: providers/mimo/env.ts:16
+Defined in: [providers/mimo/env.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-intelligence/src/providers/mimo/env.ts#L16)
 
 Configuration entries used by the MiMo intelligence provider.

package/data/packages/platform-intelligence/api/index.md

@@ -17,6 +17,10 @@ editUrl: false
 | [IntelligenceModule](Class.IntelligenceModule) | Core module exposing the shared intelligence infrastructure. |
 | [IntelligenceProviderAssetUploader](Class.IntelligenceProviderAssetUploader) | Uploads provider-managed files and skills for reuse in AI SDK calls. |
 | [IntelligenceProviderError](Class.IntelligenceProviderError) | Error thrown when an intelligence provider call fails. |
+| [IntelligenceRealtimeError](Class.IntelligenceRealtimeError) | Error raised by a realtime session, transport, or metering adapter. |
+| [IntelligenceRealtimeMeteringPort](Class.IntelligenceRealtimeMeteringPort) | Application port for idempotently persisting realtime billing and audit events. |
+| [IntelligenceRealtimeSessionFactory](Class.IntelligenceRealtimeSessionFactory) | Creates and owns server-side, provider-neutral realtime AI sessions. |
+| [IntelligenceRealtimeSessionPort](Class.IntelligenceRealtimeSessionPort) | Provider-neutral control surface for one realtime model connection. |
 | [IntelligenceStructuredGenerator](Class.IntelligenceStructuredGenerator) | Executes AI SDK structured-output generation. |
 | [IntelligenceTelemetryRegistry](Class.IntelligenceTelemetryRegistry) | Registers AI SDK telemetry integrations for the current process. |
 | [IntelligenceTextGenerator](Class.IntelligenceTextGenerator) | Executes text completions using the configured intelligence provider. |
@@ -31,6 +35,15 @@ editUrl: false
 | [IIntelligenceCompletionUsage](Interface.IIntelligenceCompletionUsage) | Captures usage telemetry returned by the intelligence provider. |
 | [IIntelligenceModuleOptions](Interface.IIntelligenceModuleOptions) | Options for configuring the intelligence module. |
 | [IIntelligenceProviderConfiguration](Interface.IIntelligenceProviderConfiguration) | Describes the resolved configuration for the intelligence provider. |
+| [IIntelligenceRealtimeAudioFormat](Interface.IIntelligenceRealtimeAudioFormat) | Provider-neutral audio format configuration. |
+| [IIntelligenceRealtimeCloseEvent](Interface.IIntelligenceRealtimeCloseEvent) | Describes why an upstream realtime connection closed. |
+| [IIntelligenceRealtimeModuleOptions](Interface.IIntelligenceRealtimeModuleOptions) | Module-level resilience and resource limits for realtime intelligence. |
+| [IIntelligenceRealtimeSessionConfiguration](Interface.IIntelligenceRealtimeSessionConfiguration) | Provider-neutral configuration for a realtime AI session. |
+| [IIntelligenceRealtimeSessionOptions](Interface.IIntelligenceRealtimeSessionOptions) | Options used to create one server-owned realtime model connection. |
+| [IIntelligenceRealtimeToolDefinition](Interface.IIntelligenceRealtimeToolDefinition) | Provider-neutral function definition exposed to a realtime model. |
+| [IIntelligenceRealtimeTranscriptionConfiguration](Interface.IIntelligenceRealtimeTranscriptionConfiguration) | Provider-neutral transcription configuration. |
+| [IIntelligenceRealtimeTurnDetectionConfiguration](Interface.IIntelligenceRealtimeTurnDetectionConfiguration) | Provider-neutral voice activity detection configuration. |
+| [IIntelligenceRealtimeUsage](Interface.IIntelligenceRealtimeUsage) | Normalized token usage reported by a realtime provider. |
 | [IIntelligenceTextCompletion](Interface.IIntelligenceTextCompletion) | Represents the normalized completion result produced by the intelligence provider. |
 | [IIntelligenceTextGenerationOptions](Interface.IIntelligenceTextGenerationOptions) | Options that can be supplied when generating text with the intelligence provider. |
 | [IIntelligenceTextGenerator](Interface.IIntelligenceTextGenerator) | Abstraction responsible for executing text completions using the configured provider. |
@@ -45,6 +58,13 @@ editUrl: false
 | [IntelligenceLanguageModelLoader](TypeAlias.IntelligenceLanguageModelLoader) | Represents a factory responsible for creating a configured language model instance. |
 | [IntelligenceLanguageModelLoaders](TypeAlias.IntelligenceLanguageModelLoaders) | Maps configured intelligence providers to their tree-shakable model loader. |
 | [IntelligenceProviderName](TypeAlias.IntelligenceProviderName) | Represents the union of supported intelligence provider identifiers. |
+| [IntelligenceRealtimeClientEvent](TypeAlias.IntelligenceRealtimeClientEvent) | Provider-neutral event sent from an application to a realtime model. |
+| [IntelligenceRealtimeMetadataValue](TypeAlias.IntelligenceRealtimeMetadataValue) | Serializable metadata copied into realtime metering events. |
+| [IntelligenceRealtimeMeteringEvent](TypeAlias.IntelligenceRealtimeMeteringEvent) | Durable metering event emitted by an Archipel realtime session. |
+| [IntelligenceRealtimeModelLoader](TypeAlias.IntelligenceRealtimeModelLoader) | Creates a configured Vercel AI SDK realtime model behind the Archipel facade. |
+| [IntelligenceRealtimeModelLoaders](TypeAlias.IntelligenceRealtimeModelLoaders) | Maps configured intelligence providers to tree-shakable realtime model loaders. |
+| [IntelligenceRealtimeServerEvent](TypeAlias.IntelligenceRealtimeServerEvent) | Provider-neutral event emitted by a realtime model. |
+| [IntelligenceRealtimeStatus](TypeAlias.IntelligenceRealtimeStatus) | Describes the lifecycle state of an upstream realtime model connection. |
 | [IntelligenceTextStream](TypeAlias.IntelligenceTextStream) | Native AI SDK streaming result returned by the intelligence text generator. |
 
 ## Variables
@@ -137,6 +157,9 @@ editUrl: false
 | [createProviderOptions](Function.createProviderOptions) | Creates the provider options object consumed by the AI SDK model factories. |
 | [loadAnthropicLanguageModel](Function.loadAnthropicLanguageModel) | Creates the Anthropic language model from the resolved provider configuration. |
 | [loadGoogleLanguageModel](Function.loadGoogleLanguageModel) | Creates the Google Gemini language model from the resolved provider configuration. |
+| [loadGoogleRealtimeModel](Function.loadGoogleRealtimeModel) | Creates a Google Gemini Live model exclusively through the Vercel AI SDK provider. |
 | [loadGrokLanguageModel](Function.loadGrokLanguageModel) | Creates the Grok language model through the native xAI provider. |
+| [loadGrokRealtimeModel](Function.loadGrokRealtimeModel) | Creates an xAI Grok voice model exclusively through the Vercel AI SDK provider. |
 | [loadMimoLanguageModel](Function.loadMimoLanguageModel) | Creates the Xiaomi MiMo language model from the resolved provider configuration. |
 | [loadOpenAILanguageModel](Function.loadOpenAILanguageModel) | Creates the OpenAI language model from the resolved provider configuration. |
+| [loadOpenAIRealtimeModel](Function.loadOpenAIRealtimeModel) | Creates an OpenAI realtime model exclusively through the Vercel AI SDK provider. |

package/data/packages/platform-intelligence/index.md

@@ -1,14 +1,14 @@
 ---
 title: platform-intelligence
-description: Multi-provider AI text generation, streaming, and tool calling.
+description: Multi-provider AI text generation, streaming, realtime voice, metering, and tool calling.
 order: 16
-tags: [intelligence, ai, openai, anthropic, google, grok, text-generation, streaming, tool-calling, health]
+tags: [intelligence, ai, openai, anthropic, google, grok, text-generation, streaming, realtime, voice, metering, tool-calling, health]
 package: '@breadstone/archipel-platform-intelligence'
 ---
 
 # platform-intelligence
 
-Multi-provider AI text generation library supporting OpenAI, Anthropic, Google Generative AI, and Grok. Tool orchestration is delegated to the AI SDK through native and provider-defined tool definitions, `toolChoice`, `activeTools`, and `stopWhen`. Advanced use cases can pass native AI SDK prompts, request-level models, provider options, headers, telemetry, output settings, and step hooks through the platform generator.
+Multi-provider AI library supporting text generation and server-owned realtime voice sessions through OpenAI, Anthropic, Google Generative AI, and Grok. Tool orchestration is delegated to the AI SDK through native and provider-defined tool definitions, `toolChoice`, `activeTools`, and `stopWhen`. Advanced use cases can pass native AI SDK prompts, request-level models, provider options, headers, telemetry, output settings, and step hooks through the platform generator.
 
 **Package:** `@breadstone/archipel-platform-intelligence`
 
@@ -35,6 +35,126 @@ export class AppModule {}
 
 ---
 
+## Realtime Voice
+
+Archipel owns the upstream provider WebSocket and exposes normalized audio,
+text, transcription, response, and tool events through
+`IntelligenceRealtimeSessionPort`. The consuming backend can place its normal
+authentication, authorization, tenant isolation, persistence, and client
+WebSocket in front of this port. Provider credentials and short-lived tokens
+never need to reach the browser.
+
+The complete application integration is documented in
+[AI Realtime Voice](/guides/ai-realtime-voice); the reusable ownership,
+durability, and recovery rules are documented in the
+[Realtime Session Pattern](/patterns/realtime-session-pattern).
+
+The implementation uses the experimental realtime model contract in Vercel AI
+SDK 7. OpenAI, Google, and xAI are loaded through Archipel provider subpaths;
+consuming applications do not import the official OpenAI SDK or make direct
+provider calls.
+
+```typescript
+import { Injectable, Module } from '@nestjs/common';
+import {
+  IntelligenceModule,
+  IntelligenceProviderNames,
+} from '@breadstone/archipel-platform-intelligence';
+import {
+  IntelligenceRealtimeMeteringPort,
+  IntelligenceRealtimeSessionFactory,
+  type IntelligenceRealtimeMeteringEvent,
+} from '@breadstone/archipel-platform-intelligence/realtime';
+import { loadOpenAIRealtimeModel } from '@breadstone/archipel-platform-intelligence/providers/openai';
+import { loadGoogleRealtimeModel } from '@breadstone/archipel-platform-intelligence/providers/google';
+import { loadGrokRealtimeModel } from '@breadstone/archipel-platform-intelligence/providers/grok';
+
+@Injectable()
+export class RealtimeMeteringAdapter extends IntelligenceRealtimeMeteringPort {
+  public async report(event: IntelligenceRealtimeMeteringEvent): Promise<void> {
+    await persistIdempotently(event.eventId, event);
+  }
+}
+
+@Module({
+  imports: [
+    IntelligenceModule.register({
+      validateOnModuleInit: false,
+      realtime: {
+        providerLoaders: {
+          [IntelligenceProviderNames.OpenAI]: loadOpenAIRealtimeModel,
+          [IntelligenceProviderNames.Google]: loadGoogleRealtimeModel,
+          [IntelligenceProviderNames.Grok]: loadGrokRealtimeModel,
+        },
+        meteringAdapter: RealtimeMeteringAdapter,
+        meteringIntervalMs: 30_000,
+      },
+    }),
+  ],
+})
+export class RealtimeModule {}
+
+@Injectable()
+export class RealtimeConsultationService {
+  public constructor(private readonly sessions: IntelligenceRealtimeSessionFactory) {}
+
+  public async open(consultationId: string): Promise<void> {
+    const session = await this.sessions.createSession({
+      sessionId: consultationId,
+      model: 'gpt-realtime',
+      sessionConfiguration: {
+        instructions: 'Transcribe the consultation and answer concisely.',
+        inputAudioFormat: { type: 'audio/pcm', rate: 24_000 },
+        inputAudioTranscription: {},
+        outputModalities: ['text', 'audio'],
+        turnDetection: { type: 'server-vad' },
+      },
+      onEvent: forwardToAuthenticatedClient,
+    });
+
+    await session.connect();
+  }
+}
+```
+
+| Provider | Archipel loader | Example model |
+| --- | --- | --- |
+| OpenAI | `loadOpenAIRealtimeModel` | `gpt-realtime` |
+| Google | `loadGoogleRealtimeModel` | `gemini-3.1-flash-live-preview` |
+| xAI / Grok | `loadGrokRealtimeModel` | `grok-voice-latest` |
+
+### Metering and audit
+
+The application-supplied `IntelligenceRealtimeMeteringPort` receives four
+idempotently identifiable event types:
+
+| Event | Meaning |
+| --- | --- |
+| `session-started` | One upstream provider connection opened |
+| `billing-interval` | Elapsed provider-independent usage, every 30 seconds by default and once more for the final partial interval |
+| `provider-usage` | Exact token and modality counts when present in the raw provider event |
+| `session-ended` | Connection duration and close reason |
+
+An application can debit its own token ledger and append its AI audit log in
+the same transaction keyed by `eventId`. Time-based charging remains available
+when a provider omits exact usage; exact token usage remains available for cost
+reconciliation when reported.
+
+### Failure and persistence rules
+
+- Provider token requests and WebSocket setup are capped at five seconds and
+  transient token creation is retried at most twice.
+- Inbound, outbound, metering, and WebSocket buffers are bounded.
+- Normalized events preserve provider wire order.
+- Nest shutdown closes all owned sessions and flushes metering.
+- Archipel does not silently reconnect a lost provider conversation because a
+  new connection has different conversational state.
+- The consuming application must persist audio chunks and transcript progress
+  durably before acknowledging them, then reconstruct context when it opens a
+  replacement provider session.
+
+---
+
 ## Provider Subpaths
 
 Import only the providers you need:
@@ -359,11 +479,12 @@ All errors are wrapped in `IntelligenceProviderError` with `provider`, `model`,
 
 ## Error Handling
 
-The library provides three domain error classes for different failure scenarios:
+The library provides domain error classes for different failure scenarios:
 
 | Error class                        | Code                          | When thrown                                                           |
 | ---------------------------------- | ----------------------------- | --------------------------------------------------------------------- |
 | `IntelligenceProviderError`        | `INTELLIGENCE_PROVIDER`       | Provider SDK failures during text generation                          |
+| `IntelligenceRealtimeError`        | Realtime phase metadata       | Configuration, token, connect, send, receive, metering, or close failures |
 | `IntelligenceValidationError`      | `INTELLIGENCE_VALIDATION`     | Invalid generation parameters (temperature, topP, maxOutputTokens)    |
 | `IntelligenceConfigurationError`   | `INTELLIGENCE_CONFIGURATION`  | Unsupported provider, missing API key, or missing provider loader     |
 
@@ -379,7 +500,12 @@ import {
 
 ## Lifecycle
 
-`IntelligenceTextGenerator` implements `OnModuleInit` and validates the provider configuration plus registered provider loader eagerly at startup. Missing API keys, unsupported providers, or missing loaders throw `IntelligenceConfigurationError` before the first request is processed.
+`IntelligenceTextGenerator` implements `OnModuleInit` and validates the provider configuration plus registered provider loader eagerly at startup. Missing API keys, unsupported providers, or missing loaders throw `IntelligenceConfigurationError` before the first request is processed. `IntelligenceRealtimeSessionFactory` implements `OnModuleDestroy`, closes all owned provider WebSockets, and flushes queued metering on shutdown.
+
+Set `validateOnModuleInit: false` for a realtime-only module because that option
+controls eager text-model initialization. When text and realtime are both
+used, register the language-model loaders and keep the default eager
+validation.
 
 ---
 
@@ -391,7 +517,7 @@ import {
 
 ## Health Check
 
-The `IntelligenceHealthIndicator` verifies that provider configuration can be resolved. If no text generator is available, it reports `disabled: true`. Import it from the `/health` subpath:
+The `IntelligenceHealthIndicator` verifies that provider configuration can be resolved and reports registered realtime providers plus active session count. If neither text nor realtime infrastructure is available, it reports `disabled: true`. Import it from the `/health` subpath:
 
 ```typescript
 import { IntelligenceModule, IntelligenceProviderNames } from '@breadstone/archipel-platform-intelligence';
@@ -414,7 +540,7 @@ export class AppModule {}
 
 | Key | Check | Dependencies |
 | --- | ----- | ------------ |
-| `intelligence` | `up` when provider configuration resolves, else `down` | `@Optional() IntelligenceTextGenerator` |
+| `intelligence` | `up` when provider configuration resolves, else `down`; includes realtime readiness when registered | `@Optional() IntelligenceTextGenerator`, `@Optional() IntelligenceRealtimeSessionFactory` |
 
 ---
 

package/data/patterns/index.md

@@ -19,3 +19,4 @@ These patterns document repeatable implementation shapes used across Archipel. U
 | [Repository Pattern](./repository-pattern) | `RepositoryBase` subclasses and Prisma delegate isolation. |
 | [Testing Pattern](./testing-pattern) | Vitest structure, mocks, and integration test conventions. |
 | [Bootstrap Pattern](./bootstrap-pattern) | Composable NestJS startup with `PlatformApplication` and `PlatformBootstrapStep`. |
+| [Realtime Session Pattern](./realtime-session-pattern) | Long-lived connection ownership, per-fragment durability, metering, backpressure, and recovery. |