dsh-realtime 0.0.0-stage → 0.1.0

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.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/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.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/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Types for the realtime voice seam. This module contains **no runtime code** — a
+ * DeepSeek Harness convention that keeps type-only imports erasable.
+ *
+ * @module dsh-realtime/types
+ */
+/** A model route a realtime adapter can serve. */
+export interface RealtimeProviderInfo {
+    /** Route id a caller passes as `RealtimeSessionOptions.provider`. Must equal the registered route. */
+    id: string;
+    /** Human-readable label for diagnostics and surfaces. */
+    name: string;
+    /** Optional one-line description of what this route speaks. */
+    description?: string;
+}
+/** One voice model advertised by an adapter. Catalog membership is advisory: it never gates a session. */
+export interface RealtimeModelInfo {
+    /** Exact model id passed as `RealtimeSessionOptions.model`. */
+    id: string;
+    /** Human-readable label. */
+    name: string;
+    /** What the model can take in, e.g. `audio`, `text`, `image`. */
+    inputModalities?: readonly RealtimeModality[];
+    /** What the model puts out, e.g. `audio`, `text`. */
+    outputModalities?: readonly RealtimeModality[];
+}
+/** A modality a realtime model accepts or emits. */
+export type RealtimeModality = 'audio' | 'text' | 'image';
+/** Raw audio encoding expected on the wire. */
+export interface RealtimeAudioFormat {
+    /** Sample rate in Hz. `24000` for GPT-Live-1. */
+    sampleRate: number;
+    /** Channel count. `1` (mono) for GPT-Live-1. */
+    channels: number;
+    /** Sample encoding. `pcm16` is signed little-endian 16-bit. */
+    encoding: 'pcm16';
+}
+/** What a caller asks an adapter to open. */
+export interface RealtimeSessionOptions {
+    /** Registered route to use. Selects the adapter. */
+    provider: string;
+    /** Exact model id. */
+    model: string;
+    /**
+     * Opening system instructions.
+     *
+     * Advisory at the seam: the protocol may treat these as immutable once a session starts, in which
+     * case an adapter must surface a coded error rather than silently dropping the request. Extending
+     * live instructions is `RealtimeSession.appendInstructions`, not a new session.
+     */
+    instructions?: string;
+    /** Output voice id. Provider-specific; `undefined` leaves the provider default. */
+    voice?: string;
+    /** Cancellation for session establishment. Implementations must settle promptly after it aborts. */
+    signal?: AbortSignal;
+    /** Handler callbacks for the life of the session. */
+    handlers?: RealtimeSessionHandlers;
+}
+/** A delegated unit of work handed to the application by the voice model. */
+export interface RealtimeDelegation {
+    /** Opaque correlation id. Preserve it unchanged on every update about this delegation. */
+    id: string;
+    /** Who is expected to do the work. `client` means this application. */
+    target: 'client' | 'responses';
+    /**
+     * Position on the session timeline, in milliseconds.
+     *
+     * Note there is deliberately **no task text** here: the protocol sends metadata only, so a
+     * consumer reconstructs intent from transcripts plus its own application state.
+     */
+    offsetMs: number;
+}
+/** A transcript fragment from either side of the conversation. */
+export interface RealtimeTranscript {
+    /** Which side spoke. */
+    kind: 'input' | 'output';
+    /** The fragment text. Deltas concatenate in arrival order. */
+    text: string;
+    /** Whether this fragment closes the utterance. */
+    final: boolean;
+}
+/** Cumulative session usage. The protocol reports this in audio-seconds, not tokens. */
+export interface RealtimeUsage {
+    /** Cumulative audio seconds billed for this session. */
+    seconds: number;
+}
+/** Callbacks an adapter invokes for session lifetime events. */
+export interface RealtimeSessionHandlers {
+    /** The session is established and can accept audio. */
+    onReady?(info: RealtimeSessionStarted): void;
+    /** A transcript fragment arrived. */
+    onTranscript?(transcript: RealtimeTranscript): void;
+    /** The model delegated work to this application. */
+    onDelegation?(delegation: RealtimeDelegation): void;
+    /** Cumulative usage was updated. */
+    onUsage?(usage: RealtimeUsage): void;
+    /** Raw output audio, already decoded from the wire encoding. */
+    onAudio?(pcm16: Uint8Array): void;
+    /** The session ended. `reason` is provider-supplied when available. */
+    onClosed?(reason?: string): void;
+    /**
+     * A session-scoped failure the adapter contained rather than throwing.
+     *
+     * Adapters report here for failures that occur *after* the session opened; failures that prevent
+     * the session opening are thrown from `session()`.
+     */
+    onError?(error: Error): void;
+}
+/** Facts about an established session. */
+export interface RealtimeSessionStarted {
+    /** The route that opened it. */
+    provider: string;
+    /** The model the provider accepted — which may differ from the requested id if the provider aliases. */
+    model: string;
+    /** The output voice the provider accepted. */
+    voice?: string;
+    /** Audio encoding the session expects for input. */
+    inputAudio: RealtimeAudioFormat;
+    /** Audio encoding the session emits. */
+    outputAudio: RealtimeAudioFormat;
+}
+/**
+ * A live voice session.
+ *
+ * Implementations own the transport. Callers own the conversation: they push audio in, receive
+ * callbacks, and answer delegations through the append methods.
+ */
+export interface RealtimeSession {
+    /** Provider-assigned session identifier, for correlation in logs. */
+    readonly id: string;
+    /** Facts the provider accepted at startup. */
+    readonly started: RealtimeSessionStarted;
+    /**
+     * Append one frame of microphone audio.
+     *
+     * There is deliberately **no end-of-utterance call**: endpointing belongs to the provider, and a
+     * client-side detector would be a second, competing turn boundary. Frames are the only input.
+     * @param pcm16 - raw samples in the session's `inputAudio` format.
+     */
+    sendAudio(pcm16: Uint8Array): void;
+    /** Stop the provider consuming microphone audio, without ending the session. */
+    muteInput(): void;
+    /** Resume microphone consumption after {@link muteInput}. */
+    unmuteInput(): void;
+    /**
+     * Return a delegated result for the model to **speak aloud**.
+     * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
+     * @param delegationId - the delegation this answers, or `undefined` for session-wide context.
+     */
+    appendCommentary(content: string, delegationId?: string): Promise<void>;
+    /**
+     * Add context the model may use **without speaking it** — progress, facts, intermediate state.
+     * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
+     * @param delegationId - the delegation this relates to, or `undefined` for session-wide context.
+     */
+    appendThinking(content: string, delegationId?: string): Promise<void>;
+    /**
+     * Steer the live conversation's behaviour (tone, brevity, policy) without speaking anything.
+     * @param content - plain text, non-empty and within {@link MAX_APPEND_CHARS}.
+     * @param delegationId - `undefined` for session-wide steering.
+     */
+    appendInstructions(content: string, delegationId?: string): Promise<void>;
+    /**
+     * End the session and release the transport. Idempotent.
+     * @returns a promise settling once the transport is released.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Upper bound, in characters, on one context append.
+ *
+ * The provider's real limit is **500 tokens**, which this seam cannot count without binding to a
+ * tokenizer it does not own. The character ceiling is therefore a deliberate conservative proxy:
+ * it is enforced here so that an over-long append fails locally with a coded error rather than
+ * halfway through a live conversation. Exact token accounting belongs to the adapter.
+ */
+export declare const MAX_APPEND_CHARS = 2000;
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,16 @@
+/**
+ * Types for the realtime voice seam. This module contains **no runtime code** — a
+ * DeepSeek Harness convention that keeps type-only imports erasable.
+ *
+ * @module dsh-realtime/types
+ */
+/**
+ * Upper bound, in characters, on one context append.
+ *
+ * The provider's real limit is **500 tokens**, which this seam cannot count without binding to a
+ * tokenizer it does not own. The character ceiling is therefore a deliberate conservative proxy:
+ * it is enforced here so that an over-long append fails locally with a coded error rather than
+ * halfway through a live conversation. Exact token accounting belongs to the adapter.
+ */
+export const MAX_APPEND_CHARS = 2000;
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "dsh-realtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Realtime voice capability seam for DeepSeek Harness: a provider registry plus the session adapter base.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./error": {
+      "types": "./lib/error.d.ts",
+      "default": "./lib/error.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/index.d.ts",
+    "lib/types.js",
+    "lib/types.d.ts",
+    "lib/error.js",
+    "lib/error.d.ts"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "realtime",
+    "voice",
+    "speech",
+    "seam"
+  ],
+  "homepage": "https://github.com/Travizm/dsh-openai-live",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Travizm/dsh-openai-live.git",
+    "directory": "packages/realtime"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --dry"
+  }
 }