@breadstone/archipel-mcp 0.0.52 → 0.0.53

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. |

package/data/patterns/realtime-session-pattern.md

@@ -0,0 +1,309 @@
+---
+title: Realtime Session Pattern
+description: Ownership, durability, metering, backpressure, and recovery rules for long-lived bidirectional provider sessions.
+order: 11
+---
+
+# Archipel Realtime Session Pattern
+
+## Overview
+
+A realtime session is a long-lived, bidirectional connection to an external
+provider. Unlike a normal request, it can outlive access-token refreshes,
+client network changes, deployments, and individual HTTP transactions. Its
+correctness therefore depends on explicit ownership, durable checkpoints,
+bounded queues, idempotent accounting, and visible reconnects.
+
+`platform-intelligence` applies this pattern to live AI audio and text through
+`IntelligenceRealtimeSessionFactory` and
+`IntelligenceRealtimeSessionPort`. The same rules apply to other long-lived
+provider streams.
+
+---
+
+## Canonical Topology
+
+```mermaid
+flowchart LR
+  Client[Client capture and playback]
+  ClientQueue[Local durable chunk queue]
+  Gateway[Authenticated application gateway]
+  DomainStore[Durable domain state]
+  Metering[Idempotent ledger and audit adapter]
+  SessionPort[Provider-neutral session port]
+  Upstream[External realtime provider]
+
+  Client --> ClientQueue
+  ClientQueue <--> Gateway
+  Gateway <--> DomainStore
+  Gateway <--> SessionPort
+  SessionPort --> Metering
+  SessionPort <--> Upstream
+```
+
+The platform library owns the upstream provider connection. The application
+owns the client-facing transport and all business state. The client owns media
+capture and the last local copy of data not yet acknowledged by the
+application.
+
+---
+
+## Invariant 1: Separate Logical and Physical Identity
+
+Never use one identifier for both the durable conversation and a provider
+socket.
+
+| Identity | Changes on reconnect | Used for |
+| --- | --- | --- |
+| Logical session ID | No | Authorization, domain persistence, customer-visible history |
+| Connection ID | Yes | Provider attempt, metering idempotency, diagnostics, close history |
+
+One logical session may have many sequential provider connections. Every
+connection start and end must remain visible in the audit trail.
+
+In `platform-intelligence`, these identities are `sessionId` and
+`connectionId`.
+
+---
+
+## Invariant 2: One Owner Per Active Connection
+
+An upstream WebSocket and its event queues live in one process. All commands
+for that connection must reach the owning process and execute in order.
+
+Acceptable cluster strategies include:
+
+- sticky client routing for the active gateway connection;
+- a distributed ownership record mapping connection ID to pod;
+- a dedicated realtime worker selected before the client begins streaming.
+
+The in-memory factory registry is a process-local lifecycle mechanism, not a
+distributed session store. Durable business state must never depend on it.
+
+---
+
+## Invariant 3: Persist Small Units While Streaming
+
+Durability must not turn realtime media into a deferred upload. Split the
+stream into small ordered fragments and persist each fragment before it is
+acknowledged.
+
+```mermaid
+sequenceDiagram
+  participant Capture as Client capture
+  participant Local as Local durable queue
+  participant Gateway as Application gateway
+  participant Store as Durable application store
+  participant Port as Realtime session port
+  participant Provider as Provider
+
+  Capture->>Local: Write chunk (chunkId, sequence, audio)
+  Local->>Gateway: Send chunk
+  Gateway->>Store: Insert idempotently
+  Store-->>Gateway: Durable
+  Gateway->>Port: appendAudio(audio)
+  Port->>Provider: Forward immediately
+  Port-->>Gateway: Accepted
+  Gateway-->>Local: Acknowledge chunkId
+  Local->>Local: Remove acknowledged chunk
+```
+
+The local write protects against a browser or network failure. The application
+write protects against gateway restarts and provides the source for recovery.
+The provider call remains live because this happens per fragment rather than
+after the complete recording.
+
+### Chunk-envelope rules
+
+- The application envelope contains a stable `chunkId` and monotonic
+  `sequence`.
+- Persistence uses `(logicalSessionId, chunkId)` as an idempotency key.
+- The durable record distinguishes `pending` from `forwarded`. A duplicate of
+  a forwarded chunk is acknowledged without another upstream write; a pending
+  chunk still needs forwarding.
+- Gaps stop acknowledgement until the application's ordering policy resolves
+  them.
+- The provider-neutral port receives only the media payload required by the
+  upstream contract.
+- Chunk size, capture cadence, and audio format are negotiated by the
+  application and selected provider.
+
+There is an unavoidable ambiguity if a process dies after the provider accepts
+a fragment but before the application marks it forwarded. Most realtime
+provider audio-append operations have no application idempotency key. Do not
+claim exactly-once provider delivery; retain the durable recording and make
+connection recovery explicit instead.
+
+---
+
+## Invariant 4: Preserve Wire Order, Bound Every Queue
+
+Inbound provider events and outbound client commands must be serialized per
+connection. Concurrent callbacks may otherwise reorder transcript deltas,
+tool calls, response cancellation, or audio commits.
+
+Every queue also needs a finite capacity:
+
+| Queue or buffer | Overflow policy |
+| --- | --- |
+| Client local queue | Stop capture or warn before storage exhaustion |
+| Client-to-application frames | Apply socket backpressure and stop acknowledgement |
+| Application persistence queue | Reject or pause the client; never grow without limit |
+| Provider outbound queue | Fail the command with a retryability signal |
+| Provider inbound queue | Close the connection when ordering can no longer be guaranteed |
+| Metering queue | Close or degrade according to the application's billing safety policy |
+| WebSocket buffered bytes | Reject additional writes until the socket drains |
+
+`platform-intelligence` serializes provider events and enforces per-session
+event and byte limits. These limits do not replace tenant quotas or client
+gateway limits.
+
+---
+
+## Invariant 5: Meter Through an Idempotent Application Port
+
+Long-lived streams cannot rely on request interceptors for complete usage
+accounting. Emit durable lifecycle and interval events through an application
+port instead.
+
+Each event must contain:
+
+- a stable event ID;
+- logical session and physical connection IDs;
+- provider and model;
+- occurrence time;
+- bounded correlation metadata;
+- event-specific interval, usage, or close data.
+
+The adapter uses the event ID as a unique key and commits the usage event,
+commercial ledger change, and AI audit record in one transaction.
+
+```mermaid
+flowchart LR
+  Event[Metering event with eventId]
+  Unique[Insert with unique eventId]
+  Debit[Debit credit ledger]
+  Audit[Append AI audit record]
+  Commit[Commit transaction]
+
+  Event --> Unique
+  Unique --> Debit
+  Debit --> Audit
+  Audit --> Commit
+```
+
+Use provider-independent intervals for predictable commercial charging and
+provider-reported token dimensions for reconciliation. Do not charge both
+sources for the same work unless that is an explicit pricing rule.
+
+The adapter should normally write to a local database transaction or outbox.
+Calling a slow remote billing API directly increases queue pressure and makes
+shutdown flushes unreliable.
+
+---
+
+## Invariant 6: Reconnect Is a New Connection
+
+Do not silently reconnect a stateful provider session. A replacement socket
+does not necessarily contain the same model conversation, input buffer, tool
+state, or response state.
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Connecting: connect
+  Connecting --> Connected: socket open
+  Connecting --> Error: setup failure
+  Connected --> Closing: close
+  Connected --> Error: terminal transport failure
+  Closing --> Closed: close event or timeout
+  Error --> Closed: finalize
+  Closed --> [*]
+```
+
+Recovery creates a new connection:
+
+1. finalize and audit the failed connection;
+2. keep the same logical session ID;
+3. derive safe context from durable transcript and domain state;
+4. create a replacement port with a new connection ID;
+5. record the recovery relationship explicitly;
+6. resume only unacknowledged application fragments according to provider
+   semantics.
+
+Never claim lossless replay when the provider-neutral contract cannot restore
+provider-native conversation state.
+
+---
+
+## Invariant 7: Keep Provider Secrets and Contracts Upstream
+
+The client must not receive permanent provider API keys. The application
+gateway speaks an application-owned protocol; the platform adapter speaks the
+provider protocol.
+
+For realtime intelligence:
+
+- provider-specific model creation and wire mapping go through Vercel AI SDK
+  provider packages;
+- Archipel exposes normalized client and server event unions;
+- a generic server WebSocket carries the provider configuration returned by
+  the AI SDK adapter;
+- provider-native events remain available only as an audited `raw` escape
+  hatch.
+
+This boundary allows the application to switch providers without rewriting
+authentication, persistence, metering, or the client transport.
+
+---
+
+## Invariant 8: Shutdown Is Part of Correctness
+
+The owner of a long-lived connection must implement deterministic teardown:
+
+1. reject or stop accepting new client input;
+2. clear periodic timers;
+3. close the upstream socket with a bounded timeout;
+4. emit the final partial billing interval;
+5. emit the connection-end event;
+6. flush queued metering within the shutdown budget;
+7. release the process-local ownership record.
+
+The Nest application must enable shutdown hooks for `OnModuleDestroy` to run
+on process signals.
+
+---
+
+## Failure Policy
+
+| Failure | Retry in place? | Required action |
+| --- | --- | --- |
+| Transient provider token creation | Yes, bounded | Retry with backoff before socket creation |
+| Socket open timeout | No hidden reconnect | Fail connection attempt and report retryability |
+| Outbound command failure | Caller decides | Keep client data unacknowledged when safe to retry |
+| Malformed provider event | No | Report receive error; close if ordering is unsafe |
+| Queue or byte limit exceeded | No | Apply backpressure or close with explicit reason |
+| Metering adapter failure | Bounded retry | Persist through a durable local adapter; surface failure |
+| Provider disconnect | No hidden reconnect | Finalize connection and start explicit recovery |
+| Process shutdown | No | Drain and close within the configured timeout |
+
+---
+
+## Checklist
+
+- Logical session and physical connection IDs are distinct.
+- Exactly one process owns an active upstream connection.
+- The client keeps unacknowledged fragments durably.
+- The application persists fragments idempotently before acknowledgement.
+- Streaming continues per fragment; there is no whole-session upload gate.
+- Provider commands and events preserve per-connection order.
+- Every queue, collection, timer, and byte buffer is bounded.
+- Metering events have stable idempotency keys.
+- Ledger debit and AI audit persistence share one transaction.
+- Provider token data never reaches the client-facing protocol.
+- Reconnect creates a visible new connection.
+- Recovery claims only the context the provider contract can reconstruct.
+- Shutdown closes sockets and flushes final metering.
+
+See [AI Realtime Voice](../guides/ai-realtime-voice) for the concrete
+`platform-intelligence` integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "description": "MCP server providing Archipel platform knowledge - documentation, query patterns, and coding conventions - to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",