@hotrepl/sdk 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johann Glock
+
+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

@@ -0,0 +1,70 @@
+# @hotrepl/sdk
+
+[![npm](https://img.shields.io/npm/v/@hotrepl/sdk.svg)](https://www.npmjs.com/package/@hotrepl/sdk)
+[![license](https://img.shields.io/npm/l/@hotrepl/sdk.svg)](https://github.com/glockyco/HotRepl/blob/main/LICENSE)
+
+The official TypeScript SDK for [HotRepl](https://github.com/glockyco/HotRepl) — a runtime C# REPL
+and typed command bridge for Unity games. Use it to inspect, automate, or export data from any Unity
+game running the HotRepl plugin (BepInEx/Mono) or mod (MelonLoader/IL2CPP).
+
+## Requirements
+
+- A Unity game running the HotRepl plugin (`HotRepl.BepInEx.dll`) or mod
+  (`HotRepl.Host.MelonLoader.dll`). The plugin opens `ws://127.0.0.1:18590` by default.
+- A modern JavaScript runtime (Bun or Node) with WebSocket support.
+
+## Install
+
+```bash
+bun add @hotrepl/sdk           # or: npm install @hotrepl/sdk
+```
+
+## Quickstart
+
+```ts
+import { connect } from "@hotrepl/sdk";
+
+const session = await connect(); // ws://127.0.0.1:18590 by default
+
+// Raw eval — any C# expression, on the game's main thread:
+const product = await session.eval<string>("UnityEngine.Application.productName");
+// → { hasValue: true, value: "Ardenfall", valueType: "System.String", durationMs: 7 }
+
+// Typed, schema-validated game command:
+const preflight = await session.run<{ writable: boolean; freeMb: number }>(
+  "archive.preflight",
+  {},
+);
+// → { output: { writable: true, freeMb: 41213 }, artifacts: {} }
+
+session.close();
+```
+
+Point at a non-default backend with `connect({ url: "ws://host:port" })` or by setting `HOTREPL_URL`
+in the environment.
+
+## What you get
+
+- `connect(options?)` — open a WebSocket session against the game.
+- `Session.eval(code, timeoutMs?)` — evaluate C# on the main thread.
+- `Session.run(name, args, options?)` — invoke a typed, schema-validated command registered by the
+  host or a game mod.
+- `Session.complete`, `Session.reset`, `Session.journal`, `Session.watch` — completion, evaluator
+  reset, evaluation/command history, and frame-by-frame value streaming.
+- `Session.close()` — release the underlying WebSocket. Long-running consumers (servers, daemons)
+  should call this on shutdown.
+- Typed errors: `HotReplError`, `HotReplSessionEvicted`, `HotReplArtifactCorrupted`.
+
+## Reference
+
+- Repository, full docs, and examples:
+  [github.com/glockyco/HotRepl](https://github.com/glockyco/HotRepl)
+- Protocol reference:
+  [`docs/control-plane-protocol.md`](https://github.com/glockyco/HotRepl/blob/main/docs/control-plane-protocol.md)
+- Sibling packages: [`@hotrepl/cli`](https://www.npmjs.com/package/@hotrepl/cli) for shell usage,
+  [`@hotrepl/mcp`](https://www.npmjs.com/package/@hotrepl/mcp) for agent tooling.
+- Issues: [github.com/glockyco/HotRepl/issues](https://github.com/glockyco/HotRepl/issues)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import { ArtifactRef, CommandDescriptor, HandshakeMessage, ServerMessage, SubscribeResultMessage, SubscribeErrorMessage, SessionEvictedMessage, JournalEntry, JobCancelResultMessage, ErrorKind, HotReplErrorEnvelope } from '@hotrepl/protocol';
+
+interface ArtifactReader {
+    readArtifact(ref: ArtifactRef): Promise<Uint8Array>;
+}
+declare class Artifact {
+    readonly ref: ArtifactRef;
+    private readonly reader;
+    constructor(ref: ArtifactRef, reader: ArtifactReader);
+    bytes(): Promise<Uint8Array>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+    open(): Promise<{
+        path?: string;
+        uri: string;
+    }>;
+}
+declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+
+interface Result<T = unknown> {
+    output: T;
+    artifacts: Record<string, Artifact>;
+}
+declare function toResult<T>(output: unknown, artifacts: Record<string, ArtifactRef> | undefined, reader: ArtifactReader): Result<T>;
+type DescriptorCache = Map<string, CommandDescriptor>;
+
+type RuntimeRequest = {
+    type: "eval";
+    id: string;
+    code: string;
+    timeoutMs?: number;
+} | {
+    type: "complete";
+    id: string;
+    code: string;
+    cursor?: number;
+} | {
+    type: "reset";
+    id: string;
+} | {
+    type: "subscribe";
+    id: string;
+    code: string;
+    intervalFrames?: number;
+    limit?: number;
+} | {
+    type: "commands_list";
+    id: string;
+    since?: string;
+} | {
+    type: "command_describe";
+    id: string;
+    name: string;
+} | {
+    type: "command_call";
+    id: string;
+    name: string;
+    args: unknown;
+    timeoutMs?: number;
+} | {
+    type: "job_status";
+    id: string;
+    jobId: string;
+} | {
+    type: "job_cancel";
+    id: string;
+    jobId: string;
+} | {
+    type: "journal_query";
+    id: string;
+    kind?: "eval" | "command";
+    limit?: number;
+};
+interface RuntimeTransport {
+    handshake(): Promise<HandshakeMessage>;
+    request(request: RuntimeRequest): Promise<ServerMessage>;
+    watch(request: Extract<RuntimeRequest, {
+        type: "subscribe";
+    }>): AsyncIterable<WatchWireMessage>;
+    readArtifact(ref: ArtifactRef): Promise<Uint8Array>;
+    onSessionEvicted(listener: (event: SessionEvictedMessage) => void): () => void;
+    close(): void;
+}
+type WatchWireMessage = SubscribeResultMessage | SubscribeErrorMessage;
+interface RunOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    wait?: boolean;
+}
+interface EvalResponse<T = unknown> {
+    hasValue: boolean;
+    value?: T;
+    valueType?: string;
+    stdout?: string;
+    durationMs: number;
+}
+interface JobStatus {
+    jobId: string;
+    state: "running" | "done" | "failed" | "cancelled";
+    progress?: unknown;
+}
+interface WatchTick<T = unknown> {
+    seq: number;
+    hasValue: boolean;
+    value?: T;
+    valueType?: string;
+    final: boolean;
+    durationMs: number;
+}
+declare class JobHandle<T = unknown> {
+    readonly jobId: string;
+    private readonly session;
+    private readonly pollIntervalMs;
+    constructor(session: Session, jobId: string, pollIntervalMs: number);
+    status(): Promise<JobStatus>;
+    result<TOutput = T>(): Promise<Result<TOutput>>;
+    cancel(): Promise<JobCancelResultMessage>;
+}
+declare class Session {
+    readonly handshake: HandshakeMessage;
+    private readonly transport;
+    private readonly descriptors;
+    private readonly evictionListeners;
+    private sequence;
+    private evicted;
+    private closed;
+    constructor(transport: RuntimeTransport, handshake: HandshakeMessage);
+    onSessionEvicted(listener: (event: SessionEvictedMessage) => void): () => void;
+    run<T = unknown>(name: string, args: unknown, options: RunOptions & {
+        wait: false;
+    }): Promise<JobHandle<T>>;
+    run<T = unknown>(name: string, args: unknown, options?: RunOptions): Promise<Result<T>>;
+    eval<T = unknown>(code: string, timeoutMs?: number): Promise<EvalResponse<T>>;
+    reset(): Promise<void>;
+    complete(code: string, cursor?: number): Promise<string[]>;
+    watch<T = unknown>(code: string): AsyncIterable<WatchTick<T>>;
+    journal(query?: {
+        kind?: "eval" | "command";
+        limit?: number;
+    }): Promise<JournalEntry[]>;
+    artifact(ref: ArtifactRef): Artifact;
+    describeCommand(name: string): Promise<CommandDescriptor>;
+    pollJob<T>(jobId: string, pollIntervalMs: number): Promise<Result<T>>;
+    nextId(prefix: string): string;
+    request<T extends ServerMessage>(request: RuntimeRequest): Promise<T>;
+    private commandResult;
+    private jobResult;
+    /**
+     * Close the underlying transport. Safe to call multiple times;
+     * subsequent calls after the first are no-ops.
+     */
+    close(): void;
+    private ensureActive;
+}
+
+interface ConnectOptions {
+    runtime?: RuntimeTransport;
+    url?: string;
+    env?: Record<string, string | undefined>;
+}
+declare function resolveHotReplUrl(options?: ConnectOptions): string;
+declare function connect(options?: ConnectOptions): Promise<Session>;
+
+interface HotReplErrorInput {
+    kind: ErrorKind;
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+}
+declare class HotReplError extends Error {
+    readonly kind: ErrorKind;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly details: unknown;
+    constructor(input: HotReplErrorInput);
+    static fromEnvelope(error: HotReplErrorEnvelope): HotReplError;
+}
+declare class HotReplArtifactCorrupted extends HotReplError {
+    constructor(message: string);
+}
+declare class HotReplSessionEvicted extends HotReplError {
+    readonly event: SessionEvictedMessage;
+    constructor(event: SessionEvictedMessage);
+}
+
+declare class WebSocketTransport implements RuntimeTransport {
+    private readonly socket;
+    private readonly pending;
+    private readonly subscriptions;
+    private readonly evictionListeners;
+    private handshakeMessage;
+    private evicted;
+    private constructor();
+    static connect(url: string): Promise<WebSocketTransport>;
+    handshake(): Promise<HandshakeMessage>;
+    request(request: RuntimeRequest): Promise<ServerMessage>;
+    watch(request: Extract<RuntimeRequest, {
+        type: "subscribe";
+    }>): AsyncIterable<WatchWireMessage>;
+    readArtifact(ref: ArtifactRef): Promise<Uint8Array>;
+    onSessionEvicted(listener: (event: SessionEvictedMessage) => void): () => void;
+    close(): void;
+    private open;
+    private handleSocketMessage;
+    private dispatch;
+    private ensureAvailable;
+    private failAll;
+}
+
+export { Artifact, type ArtifactReader, type ConnectOptions, type DescriptorCache, type EvalResponse, HotReplArtifactCorrupted, HotReplError, type HotReplErrorInput, HotReplSessionEvicted, JobHandle, type JobStatus, type Result, type RunOptions, type RuntimeRequest, type RuntimeTransport, Session, type WatchTick, type WatchWireMessage, WebSocketTransport, connect, resolveHotReplUrl, sha256Hex, toResult };

package/dist/index.js

@@ -0,0 +1,563 @@
+// src/errors.ts
+var HotReplError = class _HotReplError extends Error {
+  kind;
+  code;
+  retryable;
+  details;
+  constructor(input) {
+    super(input.message);
+    this.name = "HotReplError";
+    this.kind = input.kind;
+    this.code = input.code;
+    this.retryable = input.retryable;
+    this.details = input.details;
+  }
+  static fromEnvelope(error) {
+    return new _HotReplError(error);
+  }
+};
+var HotReplArtifactCorrupted = class extends HotReplError {
+  constructor(message) {
+    super({
+      kind: "artifact_missing",
+      code: "artifactHashMismatch",
+      message,
+      retryable: false
+    });
+    this.name = "HotReplArtifactCorrupted";
+  }
+};
+var HotReplSessionEvicted = class extends HotReplError {
+  event;
+  constructor(event) {
+    super({
+      kind: "conflict",
+      code: "sessionEvicted",
+      message: `Session was evicted: ${event.reason}.`,
+      retryable: false
+    });
+    this.name = "HotReplSessionEvicted";
+    this.event = event;
+  }
+};
+
+// src/artifact.ts
+var Artifact = class {
+  ref;
+  reader;
+  constructor(ref, reader) {
+    this.ref = ref;
+    this.reader = reader;
+  }
+  async bytes() {
+    const bytes = await this.reader.readArtifact(this.ref);
+    const actual = await sha256Hex(bytes);
+    if (actual !== this.ref.sha256) {
+      throw new HotReplArtifactCorrupted(
+        `Artifact ${this.ref.uri} hash mismatch: expected ${this.ref.sha256}, got ${actual}.`
+      );
+    }
+    return bytes;
+  }
+  async text() {
+    return new TextDecoder().decode(await this.bytes());
+  }
+  async json() {
+    return JSON.parse(await this.text());
+  }
+  async open() {
+    await this.bytes();
+    return this.ref.path === void 0 ? { uri: this.ref.uri } : { path: this.ref.path, uri: this.ref.uri };
+  }
+};
+async function sha256Hex(bytes) {
+  const digest = await crypto.subtle.digest("SHA-256", webCryptoSource(bytes));
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function webCryptoSource(bytes) {
+  if (bytes.buffer instanceof ArrayBuffer) {
+    return bytes;
+  }
+  return new Uint8Array(bytes);
+}
+
+// src/commands.ts
+function toResult(output, artifacts, reader) {
+  const wrapped = {};
+  for (const [name, ref] of Object.entries(artifacts ?? {})) {
+    wrapped[name] = new Artifact(ref, reader);
+  }
+  return { output, artifacts: wrapped };
+}
+
+// src/connect.ts
+import { PROTOCOL_VERSION as PROTOCOL_VERSION2 } from "@hotrepl/protocol";
+
+// src/session.ts
+import { MESSAGE_TYPES } from "@hotrepl/protocol";
+var JobHandle = class {
+  jobId;
+  session;
+  pollIntervalMs;
+  constructor(session, jobId, pollIntervalMs) {
+    this.session = session;
+    this.jobId = jobId;
+    this.pollIntervalMs = pollIntervalMs;
+  }
+  async status() {
+    const response = await this.session.request({
+      type: "job_status",
+      id: this.session.nextId("status"),
+      jobId: this.jobId
+    });
+    if (response.type === MESSAGE_TYPES.jobResult) {
+      return { jobId: response.jobId, state: response.state };
+    }
+    return { jobId: response.jobId, state: response.state, progress: response.progress };
+  }
+  async result() {
+    return this.session.pollJob(this.jobId, this.pollIntervalMs);
+  }
+  async cancel() {
+    return this.session.request({
+      type: "job_cancel",
+      id: this.session.nextId("cancel"),
+      jobId: this.jobId
+    });
+  }
+};
+var Session = class {
+  handshake;
+  transport;
+  descriptors = /* @__PURE__ */ new Map();
+  evictionListeners = /* @__PURE__ */ new Set();
+  sequence = 0;
+  evicted;
+  closed = false;
+  constructor(transport, handshake) {
+    this.transport = transport;
+    this.handshake = handshake;
+    this.transport.onSessionEvicted((event) => {
+      this.evicted = event;
+      for (const listener of this.evictionListeners) listener(event);
+    });
+  }
+  onSessionEvicted(listener) {
+    this.evictionListeners.add(listener);
+    return () => this.evictionListeners.delete(listener);
+  }
+  async run(name, args, options = {}) {
+    this.ensureActive();
+    const descriptor = await this.describeCommand(name);
+    const request = {
+      type: "command_call",
+      id: this.nextId("cmd"),
+      name,
+      args
+    };
+    if (options.timeoutMs !== void 0) request.timeoutMs = options.timeoutMs;
+    const response = await this.request(request);
+    if (descriptor.kind === "sync") {
+      if (response.type !== MESSAGE_TYPES.commandResult) {
+        throw protocolError("unexpectedResponse", "Expected command_result.");
+      }
+      return this.commandResult(response);
+    }
+    if (response.type === MESSAGE_TYPES.commandResult) {
+      if (response.status === "failed") this.commandResult(response);
+      throw protocolError("unexpectedResponse", "Expected job_accepted.");
+    }
+    if (response.type !== MESSAGE_TYPES.jobAccepted) {
+      throw protocolError("unexpectedResponse", "Expected job_accepted.");
+    }
+    const handle = new JobHandle(this, response.jobId, options.pollIntervalMs ?? 250);
+    return options.wait === false ? handle : handle.result();
+  }
+  async eval(code, timeoutMs) {
+    this.ensureActive();
+    const request = { type: "eval", id: this.nextId("eval"), code };
+    if (timeoutMs !== void 0) request.timeoutMs = timeoutMs;
+    const response = await this.request(request);
+    if (response.type === MESSAGE_TYPES.evalError) throw HotReplError.fromEnvelope(response.error);
+    const result = {
+      hasValue: response.hasValue,
+      value: response.value,
+      durationMs: response.durationMs
+    };
+    if (response.valueType !== void 0) result.valueType = response.valueType;
+    if (response.stdout !== void 0) result.stdout = response.stdout;
+    return result;
+  }
+  async reset() {
+    this.ensureActive();
+    const response = await this.request({
+      type: "reset",
+      id: this.nextId("reset")
+    });
+    if (!response.success) throw protocolError("resetFailed", "Runtime reset failed.");
+  }
+  async complete(code, cursor) {
+    this.ensureActive();
+    if (!this.handshake.evaluator.supportsCompletion) {
+      throw new HotReplError({
+        kind: "unsupported_operation",
+        code: "completionUnsupported",
+        message: "The active evaluator does not support completion.",
+        retryable: false
+      });
+    }
+    const request = { type: "complete", id: this.nextId("complete"), code };
+    if (cursor !== void 0) request.cursor = cursor;
+    const response = await this.request(request);
+    return response.completions;
+  }
+  async *watch(code) {
+    this.ensureActive();
+    const request = {
+      type: "subscribe",
+      id: this.nextId("watch"),
+      code
+    };
+    for await (const event of this.transport.watch(request)) {
+      if (event.type === MESSAGE_TYPES.subscribeError) {
+        throw HotReplError.fromEnvelope(event.error);
+      }
+      const tick = {
+        seq: event.seq,
+        hasValue: event.hasValue,
+        final: event.final,
+        durationMs: event.durationMs
+      };
+      if (event.hasValue && event.value !== void 0) tick.value = event.value;
+      if (event.valueType !== void 0) tick.valueType = event.valueType;
+      yield tick;
+      if (event.final) return;
+    }
+  }
+  async journal(query = {}) {
+    this.ensureActive();
+    const request = { type: "journal_query", id: this.nextId("journal") };
+    if (query.kind !== void 0) request.kind = query.kind;
+    if (query.limit !== void 0) request.limit = query.limit;
+    const response = await this.request(request);
+    return response.entries;
+  }
+  artifact(ref) {
+    return new Artifact(ref, this.transport);
+  }
+  async describeCommand(name) {
+    const cached = this.descriptors.get(name);
+    if (cached !== void 0) return cached;
+    const response = await this.request({
+      type: "command_describe",
+      id: this.nextId("describe"),
+      name
+    });
+    this.descriptors.set(name, response.descriptor);
+    return response.descriptor;
+  }
+  async pollJob(jobId, pollIntervalMs) {
+    while (true) {
+      const response = await this.request({
+        type: "job_status",
+        id: this.nextId("status"),
+        jobId
+      });
+      if (response.type === MESSAGE_TYPES.jobResult) return this.jobResult(response);
+      if (pollIntervalMs > 0) await sleep(pollIntervalMs);
+    }
+  }
+  nextId(prefix) {
+    this.sequence += 1;
+    return `${prefix}-${this.sequence}`;
+  }
+  async request(request) {
+    this.ensureActive();
+    try {
+      const response = await this.transport.request(request);
+      if (response.type === MESSAGE_TYPES.error) throw HotReplError.fromEnvelope(response.error);
+      return response;
+    } catch (error) {
+      if (error instanceof HotReplError) throw error;
+      throw error;
+    }
+  }
+  commandResult(response) {
+    if (response.status === "failed") {
+      throw HotReplError.fromEnvelope(response.error ?? internalError("commandFailed"));
+    }
+    return toResult(response.output, response.artifacts, this.transport);
+  }
+  jobResult(response) {
+    if (response.status === "failed") {
+      throw HotReplError.fromEnvelope(response.error ?? internalError("jobFailed"));
+    }
+    return toResult(response.output, response.artifacts, this.transport);
+  }
+  /**
+   * Close the underlying transport. Safe to call multiple times;
+   * subsequent calls after the first are no-ops.
+   */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.transport.close();
+  }
+  ensureActive() {
+    if (this.evicted === void 0) return;
+    throw new HotReplSessionEvicted(this.evicted);
+  }
+};
+function protocolError(code, message) {
+  return new HotReplError({ kind: "invalid_request", code, message, retryable: false });
+}
+function internalError(code) {
+  return {
+    kind: "internal",
+    code,
+    message: "Runtime returned an error without details.",
+    retryable: false
+  };
+}
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/websocket-transport.ts
+import { MESSAGE_TYPES as MESSAGE_TYPES2 } from "@hotrepl/protocol";
+var AsyncMessageQueue = class {
+  values = [];
+  waiters = [];
+  failure;
+  isClosed = false;
+  push(value) {
+    const waiter = this.waiters.shift();
+    if (waiter !== void 0) {
+      waiter.resolve({ done: false, value });
+      return;
+    }
+    this.values.push(value);
+  }
+  close() {
+    this.isClosed = true;
+    while (this.waiters.length > 0) {
+      this.waiters.shift()?.resolve({ done: true, value: void 0 });
+    }
+  }
+  fail(error) {
+    this.failure = error;
+    this.isClosed = true;
+    while (this.waiters.length > 0) {
+      this.waiters.shift()?.reject(error);
+    }
+  }
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      if (this.values.length > 0) {
+        yield this.values.shift();
+        continue;
+      }
+      if (this.failure !== void 0) throw this.failure;
+      if (this.isClosed) return;
+      const result = await new Promise((resolve, reject) => {
+        this.waiters.push({ reject, resolve });
+      });
+      if (result.done === true) return;
+      yield result.value;
+    }
+  }
+};
+var WebSocketTransport = class _WebSocketTransport {
+  constructor(socket) {
+    this.socket = socket;
+  }
+  pending = /* @__PURE__ */ new Map();
+  subscriptions = /* @__PURE__ */ new Map();
+  evictionListeners = /* @__PURE__ */ new Set();
+  handshakeMessage;
+  evicted;
+  static connect(url) {
+    const transport = new _WebSocketTransport(new WebSocket(url));
+    return transport.open();
+  }
+  handshake() {
+    if (this.handshakeMessage === void 0) {
+      throw new HotReplError({
+        kind: "precondition_failed",
+        code: "handshakeMissing",
+        message: "Runtime handshake has not been received.",
+        retryable: false
+      });
+    }
+    return Promise.resolve(this.handshakeMessage);
+  }
+  request(request) {
+    this.ensureAvailable();
+    return new Promise((resolve, reject) => {
+      this.pending.set(request.id, { reject, resolve });
+      try {
+        this.socket.send(JSON.stringify(request));
+      } catch (error) {
+        this.pending.delete(request.id);
+        reject(error);
+      }
+    });
+  }
+  async *watch(request) {
+    this.ensureAvailable();
+    const queue = new AsyncMessageQueue();
+    this.subscriptions.set(request.id, queue);
+    try {
+      this.socket.send(JSON.stringify(request));
+      for await (const message of queue) {
+        yield message;
+        if (message.final) return;
+      }
+    } finally {
+      this.subscriptions.delete(request.id);
+    }
+  }
+  async readArtifact(ref) {
+    if (ref.path !== void 0) {
+      return new Uint8Array(await Bun.file(ref.path).arrayBuffer());
+    }
+    const response = await fetch(ref.uri);
+    if (!response.ok) {
+      throw new HotReplError({
+        kind: "artifact_missing",
+        code: "artifactReadFailed",
+        message: `Artifact ${ref.uri} could not be read.`,
+        retryable: false
+      });
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+  onSessionEvicted(listener) {
+    this.evictionListeners.add(listener);
+    return () => this.evictionListeners.delete(listener);
+  }
+  close() {
+    this.socket.close();
+  }
+  open() {
+    return new Promise((resolve, reject) => {
+      const failOpen = (error) => {
+        reject(error);
+        this.failAll(error);
+      };
+      this.socket.addEventListener("message", (event) => {
+        void this.handleSocketMessage(event.data).then(resolve, failOpen);
+      });
+      this.socket.addEventListener("error", () => {
+        failOpen(new Error("HotRepl WebSocket connection failed."));
+      });
+      this.socket.on?.("error", () => {
+      });
+      this.socket.addEventListener("close", () => {
+        this.failAll(new Error("HotRepl WebSocket connection closed."));
+      });
+    });
+  }
+  async handleSocketMessage(data) {
+    const message = JSON.parse(await messageText(data));
+    if (message.type === MESSAGE_TYPES2.handshake) {
+      this.handshakeMessage = message;
+      return this;
+    }
+    this.dispatch(message);
+    return this;
+  }
+  dispatch(message) {
+    if (message.type === MESSAGE_TYPES2.sessionEvicted) {
+      this.evicted = message;
+      const error = new HotReplSessionEvicted(message);
+      for (const listener of this.evictionListeners) listener(message);
+      this.failAll(error);
+      return;
+    }
+    if (message.type === MESSAGE_TYPES2.error && message.id !== void 0) {
+      const queue = this.subscriptions.get(message.id);
+      if (queue !== void 0) {
+        this.subscriptions.delete(message.id);
+        queue.fail(HotReplError.fromEnvelope(message.error));
+        return;
+      }
+      const pending2 = this.pending.get(message.id);
+      if (pending2 !== void 0) {
+        this.pending.delete(message.id);
+        pending2.reject(HotReplError.fromEnvelope(message.error));
+        return;
+      }
+    }
+    if (message.type === MESSAGE_TYPES2.subscribeResult || message.type === MESSAGE_TYPES2.subscribeError) {
+      const queue = this.subscriptions.get(message.id);
+      if (queue === void 0) return;
+      queue.push(message);
+      if (message.final) {
+        queue.close();
+        this.subscriptions.delete(message.id);
+      }
+      return;
+    }
+    if (!("id" in message)) return;
+    const pending = this.pending.get(message.id);
+    if (pending === void 0) return;
+    this.pending.delete(message.id);
+    pending.resolve(message);
+  }
+  ensureAvailable() {
+    if (this.evicted !== void 0) throw new HotReplSessionEvicted(this.evicted);
+    if (this.socket.readyState !== WebSocket.OPEN) {
+      throw new HotReplError({
+        kind: "precondition_failed",
+        code: "webSocketNotOpen",
+        message: "HotRepl WebSocket is not open.",
+        retryable: true
+      });
+    }
+  }
+  failAll(error) {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    for (const queue of this.subscriptions.values()) queue.fail(error);
+    this.subscriptions.clear();
+  }
+};
+async function messageText(data) {
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data);
+  if (data instanceof Blob) return data.text();
+  return String(data);
+}
+
+// src/connect.ts
+function resolveHotReplUrl(options = {}) {
+  return options.url ?? options.env?.HOTREPL_URL ?? "ws://127.0.0.1:18590";
+}
+async function connect(options = {}) {
+  const runtime = options.runtime ?? await WebSocketTransport.connect(resolveHotReplUrl(options));
+  const handshake = await runtime.handshake();
+  if (handshake.protocolVersion !== PROTOCOL_VERSION2) {
+    throw new HotReplError({
+      kind: "unsupported_operation",
+      code: "protocolVersionMismatch",
+      message: `Expected protocol ${PROTOCOL_VERSION2}, got ${handshake.protocolVersion}.`,
+      retryable: false
+    });
+  }
+  return new Session(runtime, handshake);
+}
+export {
+  Artifact,
+  HotReplArtifactCorrupted,
+  HotReplError,
+  HotReplSessionEvicted,
+  JobHandle,
+  Session,
+  WebSocketTransport,
+  connect,
+  resolveHotReplUrl,
+  sha256Hex,
+  toResult
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hotrepl/sdk",
+  "version": "2.0.0",
+  "description": "Canonical TypeScript SDK for HotRepl v2 runtimes.",
+  "keywords": [
+    "hotrepl",
+    "unity",
+    "csharp",
+    "repl",
+    "websocket",
+    "sdk",
+    "client"
+  ],
+  "homepage": "https://hotrepl.glockyco.com",
+  "bugs": "https://github.com/glockyco/HotRepl/issues",
+  "license": "MIT",
+  "author": "Johann Glock",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glockyco/HotRepl.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@hotrepl/protocol": "2.0.0"
+  },
+  "devDependencies": {
+    "@hotrepl/testing": "2.0.0"
+  }
+}