@driftengine/ai 3.61.0

package/src/provider/types.ts

@@ -0,0 +1,96 @@
+/**
+ * The provider seam. Provider-specific concerns stay behind adapters.
+ *
+ * Capability is **declared rather than assumed**, so a session refuses an
+ * unsupported requirement early and in words instead of discovering it in
+ * production at whatever a failed request costs.
+ */
+
+/**
+ * What a provider says it can do.
+ *
+ * Declared by the adapter rather than probed, except where a probe is cheap and
+ * honest — `createLocalProvider` runs one, because a local model's availability is
+ * a property of the device rather than of the configuration.
+ */
+export interface AiProviderCapabilities {
+  readonly text: boolean;
+  readonly streamingText: boolean;
+  readonly structuredOutput: boolean;
+  readonly toolCalling: boolean;
+  readonly realtimeAudio: boolean;
+  readonly imageInput: boolean;
+  readonly local: boolean;
+}
+
+/**
+ * Context assembled for one request.
+ *
+ * Declared minimally here and widened where it is built. What the seam needs is
+ * the capture tick: a model must be able to know its snapshot may be stale, and a
+ * buffered agent widens that gap on purpose.
+ */
+export interface AssembledContextLike {
+  readonly capturedAtTick: number;
+}
+
+export type AiEvent =
+  | { readonly kind: 'text'; readonly text: string }
+  | {
+      readonly kind: 'toolCall';
+      readonly callId: string;
+      readonly toolId: string;
+      readonly args: unknown;
+    }
+  | { readonly kind: 'usage'; readonly inputTokens: number; readonly outputTokens: number }
+  | {
+      readonly kind: 'done';
+      readonly reason: 'complete' | 'aborted' | 'error';
+      readonly message?: string;
+    };
+
+export interface AiRequest {
+  readonly preamble: string;
+  readonly context: AssembledContextLike;
+  readonly toolIds: readonly string[];
+  readonly signal: AbortSignal;
+}
+
+export interface AiSessionOptions {
+  readonly model: string;
+  readonly systemPrompt?: string;
+  readonly maxOutputTokens?: number;
+  readonly temperature?: number;
+}
+
+export interface AiSession {
+  run(request: AiRequest): AsyncIterable<AiEvent>;
+  abort(reason?: string): void;
+}
+
+export interface AiProvider {
+  readonly id: string;
+  readonly capabilities: AiProviderCapabilities;
+  createSession(options: AiSessionOptions): AiSession;
+}
+
+export interface AiProviderConfig {
+  readonly kind: 'proxy' | 'local' | 'deterministic';
+  readonly session: AiSessionOptions;
+  /**
+   * The provider itself, where the caller already has one.
+   *
+   * Adapters that must be constructed — a local model that has to probe the device —
+   * are built by their own factory and handed here, so this function does one job:
+   * comparing what is declared against what is required.
+   */
+  readonly provider?: AiProvider;
+  /** Adapter-specific, and never a credential — see `adapters/proxy.ts`. */
+  readonly adapter?: Readonly<Record<string, unknown>>;
+}
+
+export interface AiProviderResult {
+  readonly provider: AiProvider | null;
+  /** Always a sentence, on both paths. An empty reason is the silent no-op. */
+  readonly reason: string;
+}

package/src/realtime/session.ts

@@ -0,0 +1,63 @@
+import type { AiEvent, AiProvider, AiRequest, AiSession } from '../provider/types.ts';
+
+/**
+ * A realtime transport, emitting the same events every other session emits.
+ *
+ * **Additive.** Nothing downstream branches on transport: the buffered loop, the floor,
+ * the admission guards and the command log all see the same `AiEvent` union they
+ * already see. A session with realtime configured still has exactly one request in
+ * flight, because the state machine does not know what a transport is.
+ *
+ * **Audio stays bridged, not coupled.** This module imports nothing from
+ * `@driftengine/audio`, and the package declares no dependency on it. A consumer wires
+ * its own microphone and speaker to whatever this yields, because the moment an AI
+ * package owned an audio graph it would be an AI package that knew what a mix was.
+ */
+export interface RealtimeOptions {
+  readonly model: string;
+  /** Frames a consumer pushes in. Text here, because audio is the consumer's to carry. */
+  readonly input?: AsyncIterable<string>;
+}
+
+export type RealtimeResult =
+  | { readonly session: AiSession; readonly reason: string }
+  | { readonly session: null; readonly reason: string };
+
+/**
+ * Open a realtime session, or refuse before connecting.
+ *
+ * Refused **before** any transport is opened, in the shape §32 requires of every other
+ * provider decision: a socket opened against a provider that cannot hold a realtime
+ * conversation is a socket that fails later and more expensively than a string
+ * comparison.
+ */
+export function createRealtimeSession(
+  provider: AiProvider,
+  options: RealtimeOptions,
+): RealtimeResult {
+  if (!provider.capabilities.realtimeAudio) {
+    return {
+      session: null,
+      reason: `provider "${provider.id}" declares no realtime transport — a session cannot be opened against it`,
+    };
+  }
+
+  const inner = provider.createSession({ model: options.model });
+  let disposed = false;
+
+  return {
+    session: {
+      run(request: AiRequest): AsyncIterable<AiEvent> {
+        return inner.run(request);
+      },
+      abort(reason?: string): void {
+        /* A second disposal is a no-op rather than an error. Disposal races a scene
+           replacement and a hot reload, and both may reach the same session. */
+        if (disposed) return;
+        disposed = true;
+        inner.abort(reason ?? 'realtime session disposed');
+      },
+    },
+    reason: `realtime session open against "${provider.id}"`,
+  };
+}