dsh-realtime 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Travis Driessen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# dsh-realtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A realtime voice capability seam for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).**
+
+DSH ships ~40 `ctx.*` capability seams (`ctx.llm`, `ctx.tools`, `ctx.subagents`, …) and **no voice
+seam of any kind**. This package is the proposal and the implementation of that missing seam: a
+provider registry over the live-session vocabulary, plus the adapter base every voice backend extends.
+
+> **Status: staged.** This is a third-party proposal, not an official `@deepseek-ai` package. It is
+> built to the harness's package conventions so it can be contributed upstream without restructuring.
+
+## The model
+
+A **provider registry**, mirroring `ctx.llm`:
+
+```ts
+export const name = 'realtime-openai-live'
+export const inject = ['realtime']
+
+export function apply(ctx: Context, config: Config) {
+  ctx.realtime.registerAdapter(['openai-live'], new OpenAiLiveAdapter(config))
+}
+```
+
+The seam is deliberately thin. It owns three things:
+
+| Owned here | Owned by the adapter |
+|---|---|
+| Route registration, all-or-nothing, disposed with the fiber | The transport (WebSocket, WebRTC, in-process) |
+| Provider metadata and advisory model catalogues | Wire encoding and decoding |
+| Append bounds (`MAX_APPEND_CHARS`) and coded failures | Token accounting and provider error mapping |
+
+## What the seam deliberately does not have
+
+- **No end-of-utterance call.** Endpointing belongs to the voice provider. A client-side detector
+  would be a second, competing turn boundary — and the protocol family this targets has no commit
+  event at all, so the absence is enforced upstream, not merely preferred here.
+- **No turn management.** Turn-taking is session state, not conversation state. `sendAudio` pushes
+  frames and callbacks deliver what happens; nothing here decides who speaks next.
+- **No auto-answer for delegations.** `onDelegation` hands the consumer a delegation and the
+  consumer decides. There is no default path that answers on the consumer's behalf, because a
+  default that resolves work the application has not authorised is exactly the failure this design
+  refuses to make possible.
+
+## Failure semantics
+
+Failures that prevent a session opening are **thrown** from `session()`. Failures after a session
+opened are delivered to `handlers.onError` — a session that dies mid-conversation must not look like
+a rejected request. Codes are stable and branchable; message text is not part of the API.
+
+## Registration and disposal
+
+`registerAdapter` validates the whole candidate set before mutating anything, so a rejected
+registration leaves the registry exactly as it was. The registration is created through `ctx.effect`,
+so it is withdrawn with the contributing fiber — HMR unmounts routes rather than leaking them.
+
+## Known limitations and deferred work
+
+- **Append bounds are characters, not tokens.** The provider's real limit is 500 tokens. Counting
+  tokens exactly would bind this seam to a tokenizer it does not own, so `MAX_APPEND_CHARS` is a
+  documented conservative proxy. An adapter that can count tokens should tighten it rather than
+  widening the seam's promise.
+- **No session resumption.** The protocol fixes provider, model, voice and delegation mode at
+  startup; a seam-level `resume` would advertise a capability the wire cannot honour.
+- **The model catalogue is advisory.** Absence from `listModels` must never become request rejection.
+- **Build layout deviates from the harness's.** A `@deepseek-ai` package compiles to `lib/types` and
+  ships a separately bundled `lib/index.js`; this repo compiles flat to `lib/`. The `main`/`types`
+  entries and the `.ts`-extension import style match, so the source is portable — but packaging must
+  be reconciled before an upstream PR. Tracked here rather than silently diverging.

package/lib/error.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Typed failures for the realtime seam, carrying stable machine codes.
+ *
+ * Codes are the seam's API: a consumer branches on `code`, never on message text. Adding a code is a
+ * minor release; changing what an existing code means is a breaking one.
+ *
+ * @module dsh-realtime/error
+ */
+/** Stable machine codes raised by this seam. */
+export declare const REALTIME_ERROR_CODES: Readonly<{
+    /** A registration named an empty or malformed provider route. */
+    INVALID_PROVIDER: "INVALID_PROVIDER";
+    /** A route already has an adapter registered by another registration. */
+    DUPLICATE_PROVIDER: "DUPLICATE_PROVIDER";
+    /** Registration was released, so it can no longer replace its routes. */
+    REGISTRATION_DISPOSED: "REGISTRATION_DISPOSED";
+    /** No adapter is registered for the requested route. */
+    NO_ADAPTER: "NO_ADAPTER";
+    /** An append was empty, not a string, or over the seam's bound. */
+    INVALID_APPEND: "INVALID_APPEND";
+    /** The session has already been closed. */
+    SESSION_CLOSED: "SESSION_CLOSED";
+    /** The credential an adapter needs is absent or unusable. Names the setting, never the value. */
+    MISSING_CREDENTIAL: "MISSING_CREDENTIAL";
+    /** The provider reported a failure, or an operation it was expected to acknowledge never was. */
+    PROVIDER_ERROR: "PROVIDER_ERROR";
+    /** A recorded session could not be read as a recording. */
+    INVALID_RECORDING: "INVALID_RECORDING";
+}>;
+/** One of {@link REALTIME_ERROR_CODES}. */
+export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES];
+/**
+ * A typed seam failure.
+ *
+ * The constructor validates its own arguments rather than trusting callers: a failure raised while
+ * reporting a failure is the worst place to discover a malformed argument.
+ */
+export declare class RealtimeError extends Error {
+    /** Stable machine code. Branch on this, never on `message`. */
+    readonly code: RealtimeErrorCode;
+    /**
+     * @param message - non-empty human-readable summary. Must not contain secret material.
+     * @param code - one of {@link REALTIME_ERROR_CODES}.
+     * @param options - optional `cause`.
+     */
+    constructor(message: string, code: RealtimeErrorCode, options?: ErrorOptions);
+}
+//# sourceMappingURL=error.d.ts.map

package/lib/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gDAAgD;AAChD,eAAO,MAAM,oBAAoB;IAC/B,iEAAiE;;IAEjE,yEAAyE;;IAEzE,yEAAyE;;IAEzE,wDAAwD;;IAExD,mEAAmE;;IAEnE,2CAA2C;;IAE3C,iGAAiG;;IAEjG,iGAAiG;;IAEjG,2DAA2D;;EAE3D,CAAA;AAEF,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAA;AAEhG;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAEhC;;;;OAIG;IACH,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,YAAY,EAU3E;CACF"}

package/lib/error.js

@@ -0,0 +1,56 @@
+/**
+ * Typed failures for the realtime seam, carrying stable machine codes.
+ *
+ * Codes are the seam's API: a consumer branches on `code`, never on message text. Adding a code is a
+ * minor release; changing what an existing code means is a breaking one.
+ *
+ * @module dsh-realtime/error
+ */
+/** Stable machine codes raised by this seam. */
+export const REALTIME_ERROR_CODES = Object.freeze({
+    /** A registration named an empty or malformed provider route. */
+    INVALID_PROVIDER: 'INVALID_PROVIDER',
+    /** A route already has an adapter registered by another registration. */
+    DUPLICATE_PROVIDER: 'DUPLICATE_PROVIDER',
+    /** Registration was released, so it can no longer replace its routes. */
+    REGISTRATION_DISPOSED: 'REGISTRATION_DISPOSED',
+    /** No adapter is registered for the requested route. */
+    NO_ADAPTER: 'NO_ADAPTER',
+    /** An append was empty, not a string, or over the seam's bound. */
+    INVALID_APPEND: 'INVALID_APPEND',
+    /** The session has already been closed. */
+    SESSION_CLOSED: 'SESSION_CLOSED',
+    /** The credential an adapter needs is absent or unusable. Names the setting, never the value. */
+    MISSING_CREDENTIAL: 'MISSING_CREDENTIAL',
+    /** The provider reported a failure, or an operation it was expected to acknowledge never was. */
+    PROVIDER_ERROR: 'PROVIDER_ERROR',
+    /** A recorded session could not be read as a recording. */
+    INVALID_RECORDING: 'INVALID_RECORDING',
+});
+/**
+ * A typed seam failure.
+ *
+ * The constructor validates its own arguments rather than trusting callers: a failure raised while
+ * reporting a failure is the worst place to discover a malformed argument.
+ */
+export class RealtimeError extends Error {
+    /** Stable machine code. Branch on this, never on `message`. */
+    code;
+    /**
+     * @param message - non-empty human-readable summary. Must not contain secret material.
+     * @param code - one of {@link REALTIME_ERROR_CODES}.
+     * @param options - optional `cause`.
+     */
+    constructor(message, code, options) {
+        if (typeof message !== 'string' || message.length === 0) {
+            throw new TypeError('RealtimeError message must be a non-empty string');
+        }
+        if (typeof code !== 'string' || code.length === 0) {
+            throw new TypeError('RealtimeError code must be a non-empty string');
+        }
+        super(message, options);
+        this.name = 'RealtimeError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=error.js.map

package/lib/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gDAAgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,iEAAiE;IACjE,gBAAgB,EAAE,kBAAkB;IACpC,yEAAyE;IACzE,kBAAkB,EAAE,oBAAoB;IACxC,yEAAyE;IACzE,qBAAqB,EAAE,uBAAuB;IAC9C,wDAAwD;IACxD,UAAU,EAAE,YAAY;IACxB,mEAAmE;IACnE,cAAc,EAAE,gBAAgB;IAChC,2CAA2C;IAC3C,cAAc,EAAE,gBAAgB;IAChC,iGAAiG;IACjG,kBAAkB,EAAE,oBAAoB;IACxC,iGAAiG;IACjG,cAAc,EAAE,gBAAgB;IAChC,2DAA2D;IAC3D,iBAAiB,EAAE,mBAAmB;CACvC,CAAC,CAAA;AAKF;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,+DAA+D;IACtD,IAAI,CAAmB;IAEhC;;;;OAIG;IACH,YAAY,OAAe,EAAE,IAAuB,EAAE,OAAsB;QAC1E,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAA;QACzE,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAA;QACtE,CAAC;QACD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF"}

package/lib/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Realtime voice seam: a provider registry plus the adapter base every voice backend extends.
+ *
+ * Exports the `RealtimeRuntime` service as the **default** export (a DeepSeek Harness convention for
+ * service packages) and the abstract `RealtimeAdapter` for provider backends. Function plugins
+ * must supply `name` / `inject` / `Config` / `apply` and no default export; this package is a
+ * service package, so it is mounted as a class plugin and default-exports its service.
+ *
+ * @module dsh-realtime
+ */
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { RealtimeDelegation, RealtimeModelInfo, RealtimeProviderInfo, RealtimeSession, RealtimeSessionHandlers, RealtimeSessionOptions } from './types.ts';
+export * from './types.ts';
+export * from './error.ts';
+export { RealtimeError, REALTIME_ERROR_CODES } from './error.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        realtime: RealtimeRuntime;
+    }
+}
+/**
+ * What {@link RealtimeRuntime.registerAdapter} returns: the disposer, plus an atomic route
+ * replacement for the same adapter instance.
+ */
+export interface AdapterRegistrationHandle {
+    /** Release every route this registration currently holds. */
+    (): void;
+    /**
+     * Replace this registration's routes, keeping the same adapter instance. The candidate set is
+     * validated in full first — a conflict with another registration or a malformed route throws and
+     * leaves the current routes untouched — and the swap is one synchronous section, so no observer
+     * can see the registry between release and re-registration.
+     *
+     * An empty array is legal here (a plugin whose configuration emptied holds zero routes while
+     * staying registered), unlike an empty initial registration.
+     *
+     * Throws `REGISTRATION_DISPOSED` once the registration was released: its routes are gone and its
+     * disposer has already run, so anything registered afterwards would have no owner left to release it.
+     * @param providers - the complete next route set for this registration.
+     */
+    replace(providers: string[]): void;
+}
+/**
+ * Provider-wire adapter for the realtime session vocabulary.
+ *
+ * Register implementations with `ctx.realtime.registerAdapter(providers, adapter)`. The single
+ * required method is {@link session}; every other method exists so a provider can describe itself
+ * without the seam having to special-case it.
+ */
+export declare abstract class RealtimeAdapter {
+    /**
+     * Describe one provider route owned by this adapter.
+     * @param provider - a route passed to `registerAdapter()` for this instance.
+     * @returns detached display metadata whose `id` must equal `provider`.
+     */
+    providerInfo(provider: string): RealtimeProviderInfo;
+    /**
+     * List the voice models this adapter can currently advertise for one owned route.
+     *
+     * The result is advisory: an adapter may accept unlisted model ids, and consumers must not turn
+     * absence into request rejection.
+     * @param _provider - one provider route owned by this adapter.
+     * @returns discoverable models in adapter-preferred order.
+     */
+    listModels(_provider: string): Promise<readonly RealtimeModelInfo[]>;
+    /**
+     * Open one voice session. The only required method.
+     *
+     * Implementations must honor `options.signal` during establishment, and must throw (rather than
+     * resolve with a dead session) when the session cannot open.
+     * @param options - the fully-resolved request; `options.provider` selects the registered route.
+     * @returns the live session, with `options.handlers` already wired.
+     */
+    abstract session(options: RealtimeSessionOptions): Promise<RealtimeSession>;
+}
+/**
+ * The `realtime` service: an adapter registry over the session vocabulary.
+ *
+ * Registration is effect-based, so HMR or a disposal unmounts routes with the contributing fiber —
+ * there is no separate teardown path that can be forgotten.
+ */
+export declare class RealtimeRuntime extends Service {
+    private readonly adapters;
+    /**
+     * @param ctx - the Cordis context this service is mounted on.
+     */
+    constructor(ctx: Context);
+    /**
+     * Register an adapter for the given provider routes, all-or-nothing.
+     *
+     * Disposed with the fiber. Throws `INVALID_PROVIDER` for a malformed route, `DUPLICATE_PROVIDER`
+     * if any route is already held by another registration.
+     * @param providers - every provider route this adapter should serve.
+     * @param adapter - the adapter that opens sessions for those routes.
+     * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+     */
+    registerAdapter(providers: string[], adapter: RealtimeAdapter): AdapterRegistrationHandle;
+    /**
+     * Validate one candidate route set for `adapter`, treating routes this registration already holds
+     * as available.
+     *
+     * Nothing is mutated: a rejected candidate leaves the registry exactly as it was, which is what
+     * makes {@link AdapterRegistrationHandle.replace} a swap rather than a delete-then-add that can
+     * strand the registry empty.
+     * @param providers - candidate routes.
+     * @param adapter - the adapter that would own them.
+     * @param owned - routes this same registration already holds.
+     * @returns registrations ready to commit.
+     */
+    private prepare;
+    /**
+     * Swap this registration's routes for the prepared ones in one synchronous section, so no
+     * observer can see the registry between the release and the re-registration.
+     * @param owned - mutable set tracking which routes this registration holds.
+     * @param registrations - validated registrations to install.
+     */
+    private commit;
+    /**
+     * Describe the provider routes that currently have an adapter.
+     * @returns detached provider metadata in registration order.
+     */
+    listProviders(): RealtimeProviderInfo[];
+    /**
+     * Resolve the adapter owning one route.
+     * @param provider - registered route to look up.
+     * @returns that route's registration.
+     * @throws RealtimeError `NO_ADAPTER` when the route is unregistered.
+     */
+    private registration;
+    /**
+     * Discover the voice models one registered route advertises.
+     * @param provider - registered route to inspect.
+     * @returns detached model metadata in adapter-preferred order, duplicates removed.
+     */
+    listModels(provider: string): Promise<RealtimeModelInfo[]>;
+    /**
+     * Open one voice session through the adapter registered for its route.
+     *
+     * A field this seam cannot honor is rejected here rather than forwarded as a no-op — the caller
+     * learns the request is unsupported before a live conversation depends on it.
+     * @param options - the session request; `options.provider` selects the adapter.
+     * @returns the adapter's live session.
+     * @throws RealtimeError `NO_ADAPTER` for an unregistered route.
+     */
+    session(options: RealtimeSessionOptions): Promise<RealtimeSession>;
+    /**
+     * Validate one context append against the seam's bounds.
+     *
+     * Exposed so an adapter can enforce the same bound the seam promises, instead of each backend
+     * re-deriving it. Bound enforcement lives at the operation that makes the decision: a caller that
+     * bypasses this cannot silently send an over-long append.
+     * @param content - candidate append text.
+     * @param maxChars - character ceiling; defaults to the provider's documented bound.
+     * @returns the content unchanged, for convenient inline use.
+     * @throws RealtimeError `INVALID_APPEND` for a non-string, empty, or over-long value.
+     */
+    static assertAppendable(content: string, maxChars: number): string;
+}
+/** Re-exported so adapters can type their handler wiring without a second import. */
+export type { RealtimeDelegation, RealtimeSessionHandlers };
+export default RealtimeRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,QAAQ,EAAE,eAAe,CAAA;KAC1B;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,IAAI,IAAI,CAAA;IACR;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;GAMG;AACH,8BAAsB,eAAe;IACnC;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAEnD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAEnE;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC5E;AAQD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;OAEG;IACH,YAAY,GAAG,EAAE,OAAO,EAEvB;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,yBAAyB,CAiCxF;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAgCf;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IASd;;;OAGG;IACH,aAAa,IAAI,oBAAoB,EAAE,CAEtC;IAED;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe/D;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBvE;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;CACF;AAED,qFAAqF;AACrF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAA;eAE5C,eAAe"}

package/lib/index.js

@@ -0,0 +1,239 @@
+/**
+ * Realtime voice seam: a provider registry plus the adapter base every voice backend extends.
+ *
+ * Exports the `RealtimeRuntime` service as the **default** export (a DeepSeek Harness convention for
+ * service packages) and the abstract `RealtimeAdapter` for provider backends. Function plugins
+ * must supply `name` / `inject` / `Config` / `apply` and no default export; this package is a
+ * service package, so it is mounted as a class plugin and default-exports its service.
+ *
+ * @module dsh-realtime
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { REALTIME_ERROR_CODES, RealtimeError } from './error.js';
+export * from './types.js';
+export * from './error.js';
+export { RealtimeError, REALTIME_ERROR_CODES } from './error.js';
+/**
+ * Provider-wire adapter for the realtime session vocabulary.
+ *
+ * Register implementations with `ctx.realtime.registerAdapter(providers, adapter)`. The single
+ * required method is {@link session}; every other method exists so a provider can describe itself
+ * without the seam having to special-case it.
+ */
+export class RealtimeAdapter {
+    /**
+     * Describe one provider route owned by this adapter.
+     * @param provider - a route passed to `registerAdapter()` for this instance.
+     * @returns detached display metadata whose `id` must equal `provider`.
+     */
+    providerInfo(provider) {
+        return { id: provider, name: provider };
+    }
+    /**
+     * List the voice models this adapter can currently advertise for one owned route.
+     *
+     * The result is advisory: an adapter may accept unlisted model ids, and consumers must not turn
+     * absence into request rejection.
+     * @param _provider - one provider route owned by this adapter.
+     * @returns discoverable models in adapter-preferred order.
+     */
+    listModels(_provider) {
+        return Promise.resolve([]);
+    }
+}
+/**
+ * The `realtime` service: an adapter registry over the session vocabulary.
+ *
+ * Registration is effect-based, so HMR or a disposal unmounts routes with the contributing fiber —
+ * there is no separate teardown path that can be forgotten.
+ */
+export class RealtimeRuntime extends Service {
+    adapters = new Map();
+    /**
+     * @param ctx - the Cordis context this service is mounted on.
+     */
+    constructor(ctx) {
+        super(ctx, 'realtime');
+    }
+    /**
+     * Register an adapter for the given provider routes, all-or-nothing.
+     *
+     * Disposed with the fiber. Throws `INVALID_PROVIDER` for a malformed route, `DUPLICATE_PROVIDER`
+     * if any route is already held by another registration.
+     * @param providers - every provider route this adapter should serve.
+     * @param adapter - the adapter that opens sessions for those routes.
+     * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+     */
+    registerAdapter(providers, adapter) {
+        if (providers.length === 0) {
+            throw new RealtimeError('an adapter must register at least one provider', REALTIME_ERROR_CODES.INVALID_PROVIDER);
+        }
+        // Routes this registration currently holds; `replace` rewrites it, and the disposer releases
+        // whatever it holds at disposal time.
+        const owned = new Set();
+        // `owned` being empty cannot report disposal on its own, because `replace([])` legally leaves a
+        // live registration holding none.
+        let released = false;
+        const dispose = this.ctx.effect(function* () {
+            this.commit(owned, this.prepare(providers, adapter, owned));
+            yield () => {
+                released = true;
+                for (const provider of owned)
+                    this.adapters.delete(provider);
+                owned.clear();
+            };
+        }.bind(this), 'realtime.registerAdapter()');
+        const handle = (() => void dispose());
+        handle.replace = (next) => {
+            // Registering here would leak: the effect's disposer already ran, so nothing remains to
+            // release whatever this call would put in the map.
+            if (released) {
+                throw new RealtimeError('a disposed adapter registration cannot replace its routes', REALTIME_ERROR_CODES.REGISTRATION_DISPOSED);
+            }
+            this.commit(owned, this.prepare(next, adapter, owned));
+        };
+        return handle;
+    }
+    /**
+     * Validate one candidate route set for `adapter`, treating routes this registration already holds
+     * as available.
+     *
+     * Nothing is mutated: a rejected candidate leaves the registry exactly as it was, which is what
+     * makes {@link AdapterRegistrationHandle.replace} a swap rather than a delete-then-add that can
+     * strand the registry empty.
+     * @param providers - candidate routes.
+     * @param adapter - the adapter that would own them.
+     * @param owned - routes this same registration already holds.
+     * @returns registrations ready to commit.
+     */
+    prepare(providers, adapter, owned) {
+        const unique = new Set();
+        const registrations = [];
+        for (const provider of providers) {
+            if (typeof provider !== 'string' || provider.length === 0) {
+                throw new RealtimeError('adapter provider names must be non-empty strings', REALTIME_ERROR_CODES.INVALID_PROVIDER);
+            }
+            if (unique.has(provider) || (this.adapters.has(provider) && !owned.has(provider))) {
+                throw new RealtimeError(`an adapter for provider "${provider}" is already registered`, REALTIME_ERROR_CODES.DUPLICATE_PROVIDER);
+            }
+            const info = adapter.providerInfo(provider);
+            if (typeof info.id !== 'string' || info.id !== provider
+                || typeof info.name !== 'string' || info.name.length === 0) {
+                throw new RealtimeError(`adapter metadata for provider "${provider}" must preserve its id and have a non-empty name`, REALTIME_ERROR_CODES.INVALID_PROVIDER);
+            }
+            unique.add(provider);
+            registrations.push({
+                adapter,
+                provider: info.description === undefined
+                    ? { id: info.id, name: info.name }
+                    : { id: info.id, name: info.name, description: info.description },
+            });
+        }
+        return registrations;
+    }
+    /**
+     * Swap this registration's routes for the prepared ones in one synchronous section, so no
+     * observer can see the registry between the release and the re-registration.
+     * @param owned - mutable set tracking which routes this registration holds.
+     * @param registrations - validated registrations to install.
+     */
+    commit(owned, registrations) {
+        for (const provider of owned)
+            this.adapters.delete(provider);
+        owned.clear();
+        for (const registration of registrations) {
+            this.adapters.set(registration.provider.id, registration);
+            owned.add(registration.provider.id);
+        }
+    }
+    /**
+     * Describe the provider routes that currently have an adapter.
+     * @returns detached provider metadata in registration order.
+     */
+    listProviders() {
+        return [...this.adapters.values()].map(({ provider }) => ({ ...provider }));
+    }
+    /**
+     * Resolve the adapter owning one route.
+     * @param provider - registered route to look up.
+     * @returns that route's registration.
+     * @throws RealtimeError `NO_ADAPTER` when the route is unregistered.
+     */
+    registration(provider) {
+        const registration = this.adapters.get(provider);
+        if (registration === undefined) {
+            throw new RealtimeError(`no realtime adapter registered for provider "${provider}"`, REALTIME_ERROR_CODES.NO_ADAPTER);
+        }
+        return registration;
+    }
+    /**
+     * Discover the voice models one registered route advertises.
+     * @param provider - registered route to inspect.
+     * @returns detached model metadata in adapter-preferred order, duplicates removed.
+     */
+    async listModels(provider) {
+        const models = await this.registration(provider).adapter.listModels(provider);
+        const seen = new Set();
+        const detached = [];
+        for (const model of models) {
+            if (typeof model.id !== 'string' || model.id.length === 0 || seen.has(model.id))
+                continue;
+            seen.add(model.id);
+            detached.push({
+                id: model.id,
+                name: typeof model.name === 'string' && model.name.length > 0 ? model.name : model.id,
+                ...model.inputModalities === undefined ? {} : { inputModalities: [...model.inputModalities] },
+                ...model.outputModalities === undefined ? {} : { outputModalities: [...model.outputModalities] },
+            });
+        }
+        return detached;
+    }
+    /**
+     * Open one voice session through the adapter registered for its route.
+     *
+     * A field this seam cannot honor is rejected here rather than forwarded as a no-op — the caller
+     * learns the request is unsupported before a live conversation depends on it.
+     * @param options - the session request; `options.provider` selects the adapter.
+     * @returns the adapter's live session.
+     * @throws RealtimeError `NO_ADAPTER` for an unregistered route.
+     */
+    async session(options) {
+        if (typeof options.provider !== 'string' || options.provider.length === 0) {
+            throw new RealtimeError('a session needs a non-empty provider route', REALTIME_ERROR_CODES.INVALID_PROVIDER);
+        }
+        if (typeof options.model !== 'string' || options.model.length === 0) {
+            throw new RealtimeError('a session needs a non-empty model id', REALTIME_ERROR_CODES.INVALID_PROVIDER);
+        }
+        if (options.instructions !== undefined && options.instructions.length === 0) {
+            throw new RealtimeError('session instructions must be non-empty when supplied', REALTIME_ERROR_CODES.INVALID_APPEND);
+        }
+        if (options.signal?.aborted) {
+            throw new RealtimeError('session establishment was aborted before it started', REALTIME_ERROR_CODES.SESSION_CLOSED, {
+                cause: options.signal.reason,
+            });
+        }
+        return await this.registration(options.provider).adapter.session(options);
+    }
+    /**
+     * Validate one context append against the seam's bounds.
+     *
+     * Exposed so an adapter can enforce the same bound the seam promises, instead of each backend
+     * re-deriving it. Bound enforcement lives at the operation that makes the decision: a caller that
+     * bypasses this cannot silently send an over-long append.
+     * @param content - candidate append text.
+     * @param maxChars - character ceiling; defaults to the provider's documented bound.
+     * @returns the content unchanged, for convenient inline use.
+     * @throws RealtimeError `INVALID_APPEND` for a non-string, empty, or over-long value.
+     */
+    static assertAppendable(content, maxChars) {
+        if (typeof content !== 'string' || content.length === 0) {
+            throw new RealtimeError('an append needs non-empty content', REALTIME_ERROR_CODES.INVALID_APPEND);
+        }
+        if (content.length > maxChars) {
+            throw new RealtimeError(`an append of ${content.length} characters exceeds the ${maxChars}-character seam bound`, REALTIME_ERROR_CODES.INVALID_APPEND);
+        }
+        return content;
+    }
+}
+export default RealtimeRuntime;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}