@breadstone/archipel-mcp 0.0.52 → 0.0.54

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](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-intelligence/src/realtime/contracts/IntelligenceRealtimeServerEvent.ts#L10)
+
+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](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-intelligence/src/realtime/contracts/IntelligenceRealtimeStatus.ts#L6)
+
+Describes the lifecycle state of an upstream realtime model connection.

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

@@ -9,14 +9,21 @@ editUrl: false
 
 | Class | Description |
 | ------ | ------ |
+| [DefaultIntelligencePromptPolicyAdapter](Class.DefaultIntelligencePromptPolicyAdapter) | Default prompt policy that supports native settings and automatic model selection. |
 | [IntelligenceAgentFactory](Class.IntelligenceAgentFactory) | Creates AI SDK 7 tool-loop agents with platform-registered tools merged in. |
 | [IntelligenceConfigurationError](Class.IntelligenceConfigurationError) | Error thrown when an intelligence provider configuration is invalid or missing. |
 | [IntelligenceEmbeddingGenerator](Class.IntelligenceEmbeddingGenerator) | Executes AI SDK embedding operations. |
 | [IntelligenceHealthIndicator](Class.IntelligenceHealthIndicator) | Health indicator for the intelligence infrastructure. Verifies that the intelligence provider configuration can be resolved. |
 | [IntelligenceMediaGenerator](Class.IntelligenceMediaGenerator) | Executes AI SDK media generation and understanding operations. |
 | [IntelligenceModule](Class.IntelligenceModule) | Core module exposing the shared intelligence infrastructure. |
+| [IntelligencePromptExecutor](Class.IntelligencePromptExecutor) | Validates and executes reusable intelligence prompt invocations. |
+| [IntelligencePromptPolicyPort](Class.IntelligencePromptPolicyPort) | Resolves provider-neutral prompt requirements into effective generation settings. |
 | [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. |
@@ -30,7 +37,24 @@ editUrl: false
 | ------ | ------ |
 | [IIntelligenceCompletionUsage](Interface.IIntelligenceCompletionUsage) | Captures usage telemetry returned by the intelligence provider. |
 | [IIntelligenceModuleOptions](Interface.IIntelligenceModuleOptions) | Options for configuring the intelligence module. |
+| [IIntelligencePromptDefinition](Interface.IIntelligencePromptDefinition) | Reusable, immutable definition of an intelligence prompt. |
+| [IIntelligencePromptEffectivePolicy](Interface.IIntelligencePromptEffectivePolicy) | Effective settings resolved for one prompt execution. |
+| [IIntelligencePromptExecutionContext](Interface.IIntelligencePromptExecutionContext) | Application context made available to prompt policy adapters. |
+| [IIntelligencePromptExecutionPolicy](Interface.IIntelligencePromptExecutionPolicy) | Native settings and provider-neutral requirements declared by an intelligence prompt. |
+| [IIntelligencePromptExecutionResult](Interface.IIntelligencePromptExecutionResult) | Normalized result of an intelligence prompt execution. |
+| [IIntelligencePromptInvocation](Interface.IIntelligencePromptInvocation) | Bound prompt definition ready for execution. |
+| [IIntelligencePromptPolicyRequest](Interface.IIntelligencePromptPolicyRequest) | Policy resolution request for one prompt invocation. |
+| [IIntelligencePromptRenderContext](Interface.IIntelligencePromptRenderContext) | Input exposed to pure prompt rendering functions. |
 | [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. |
@@ -42,9 +66,24 @@ editUrl: false
 
 | Type Alias | Description |
 | ------ | ------ |
+| [IIntelligencePromptModelRequirement](TypeAlias.IIntelligencePromptModelRequirement) | Model selection requested by a reusable intelligence prompt. |
 | [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. |
+| [IntelligencePromptCapability](TypeAlias.IntelligencePromptCapability) | Provider-neutral capability required by an intelligence prompt. |
+| [IntelligencePromptDefinitionConfiguration](TypeAlias.IntelligencePromptDefinitionConfiguration) | Configuration accepted by [intelligencePrompt](Function.intelligencePrompt). |
+| [IntelligencePromptGenerationOptions](TypeAlias.IntelligencePromptGenerationOptions) | Native generation settings that can be stored on a prompt definition. |
+| [IntelligencePromptLatency](TypeAlias.IntelligencePromptLatency) | Latency profile requested by an intelligence prompt. |
+| [IntelligencePromptMode](TypeAlias.IntelligencePromptMode) | Supported execution modes for reusable intelligence prompts. |
+| [IntelligencePromptQuality](TypeAlias.IntelligencePromptQuality) | Provider-neutral model quality requested by an intelligence prompt. |
+| [IntelligencePromptReasoning](TypeAlias.IntelligencePromptReasoning) | Provider-neutral reasoning effort requested by an intelligence prompt. |
 | [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
@@ -135,8 +174,12 @@ editUrl: false
 | [createOpenAIWebSearchPreviewTool](Function.createOpenAIWebSearchPreviewTool) | Creates an OpenAI web-search-preview tool registration. |
 | [createOpenAIWebSearchTool](Function.createOpenAIWebSearchTool) | Creates an OpenAI web-search tool registration. |
 | [createProviderOptions](Function.createProviderOptions) | Creates the provider options object consumed by the AI SDK model factories. |
+| [intelligencePrompt](Function.intelligencePrompt) | Creates a reusable intelligence prompt definition. |
 | [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,204 @@ export class AppModule {}
 
 ---
 
+## Reusable Prompts
+
+Use `intelligencePrompt()` to keep a prompt's identity, version, schemas,
+instructions, messages, and execution requirements in one pure definition.
+Bind already prepared feature data with `.with(...)` and execute the resulting
+invocation through the NestJS `IntelligencePromptExecutor`.
+
+For a guided first implementation, see
+[Intelligence Prompts Warm-up](/guides/intelligence-prompts-warm-up).
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { z } from 'zod';
+import {
+  intelligencePrompt,
+  IntelligencePromptExecutor,
+} from '@breadstone/archipel-platform-intelligence';
+
+const DuplicateDetectionPrompt = intelligencePrompt({
+  name: 'crm.duplicate-detection',
+  version: 1,
+  mode: 'object',
+  inputSchema: z.object({
+    sourceId: z.number().int(),
+    candidateIds: z.array(z.number().int()),
+  }),
+  outputSchema: z.object({
+    scores: z.array(z.object({
+      id: z.number().int(),
+      score: z.number().min(0).max(100),
+    })),
+  }),
+  system: () => [
+    'Score duplicate candidates using only the supplied fields.',
+    'Do not infer facts from missing data.',
+  ],
+  messages: ({ input }) => [
+    { role: 'user', content: JSON.stringify(input) },
+  ],
+  execution: {
+    options: { temperature: 0, maxOutputTokens: 800 },
+    model: { strategy: 'automatic' },
+    requiredCapabilities: ['structuredOutput'],
+  },
+});
+
+export function duplicateDetectionPrompt(sourceId: number, candidateIds: ReadonlyArray<number>) {
+  return DuplicateDetectionPrompt.with({ sourceId, candidateIds });
+}
+
+@Injectable()
+export class DuplicateDetectionService {
+  public constructor(private readonly prompts: IntelligencePromptExecutor) {}
+
+  public async score(sourceId: number, candidateIds: ReadonlyArray<number>) {
+    const execution = await this.prompts.execute(
+      duplicateDetectionPrompt(sourceId, candidateIds),
+    );
+
+    return execution.output.scores;
+  }
+}
+```
+
+The schemas use the AI SDK `FlexibleSchema` contract. Object mode requires an
+output schema and uses AI SDK 7 `Output.object()`; text mode has no output
+schema and returns a string. Input and completed object output are validated at
+runtime.
+
+Native AI SDK settings work with the default policy. Applications that declare
+provider-neutral quality, reasoning, latency, preferred models, or fixed model
+identifiers register an `IntelligencePromptPolicyPort` adapter through
+`IntelligenceModule.register({ promptPolicyAdapter })`. Execution results
+contain requested and effective policy, provider, model, usage, reasoning, and
+invocation metadata for application-owned billing and auditing.
+
+---
+
+## 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 +557,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 +578,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 +595,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 +618,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. |