glovebox-client 0.5.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 dterminal
+
+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,213 @@
+# glovebox-client
+
+Client SDK for talking to a deployed [Glovebox](https://github.com/porkytheblack/glove) server. One WebSocket per session, multiple prompts multiplexed. Streams subscriber events and display slot pushes; resolves with the final assistant message and an outputs map of `FileRef`s the client can read back through the configured storage.
+
+## Install
+
+```sh
+pnpm add glovebox-client
+```
+
+Works in Node (uses `ws`) and the browser (uses the global `WebSocket`). The wire format and auth are identical.
+
+## Usage
+
+### Connecting
+
+```ts
+import { GloveboxClient } from "glovebox-client"
+
+const client = GloveboxClient.make({
+  endpoints: {
+    media: { url: "wss://media.example.com/", key: process.env.GLOVEBOX_MEDIA_KEY! },
+    docs:  { url: "wss://docs.example.com/",  key: process.env.GLOVEBOX_DOCS_KEY!  },
+  },
+})
+
+const media = client.box("media")
+```
+
+`client.box(name)` lazily opens a connection on the first prompt and caches the `Box` afterward. The bearer key from the endpoint config is sent as `Authorization: Bearer ...` on the WS upgrade and on every subsequent HTTP request the SDK makes (`/environment`, `/files/:id`).
+
+### Prompting
+
+```ts
+import { readFile } from "node:fs/promises"
+
+const result = media.prompt("Trim the first 30 seconds off in.mp4 and write trimmed.mp4.", {
+  files: {
+    "in.mp4": { mime: "video/mp4", bytes: await readFile("./in.mp4") },
+  },
+})
+
+for await (const ev of result.events) {
+  if (ev.event_type === "text_delta") process.stdout.write((ev.data as { text: string }).text)
+}
+
+const message = await result.message
+const outputs = await result.outputs
+const trimmed = await result.read("trimmed.mp4")
+await writeFile("./trimmed.mp4", trimmed)
+```
+
+`prompt(text, opts)` returns a `PromptResult` synchronously — the call doesn't await the round-trip. The four async iterables / promises on the result fan out as the server sends frames:
+
+| Member | Type | Settles when |
+|--------|------|--------------|
+| `events` | `AsyncIterable<SubscriberEvent>` | Closed at `complete` / `error`. |
+| `display` | `AsyncIterable<DisplayEvent>` | Closed at `complete` / `error`. Display events are session-scoped on the server, so they fan out to every active prompt. |
+| `message` | `Promise<string>` | Final assistant text from the `complete` frame. |
+| `outputs` | `Promise<Record<string, FileRef>>` | Outputs map from the `complete` frame. |
+| `read(name)` | `Promise<Uint8Array>` | Awaits `outputs`, looks up the named ref, fetches it through the configured `ClientStorage`. |
+| `resolve(slot_id, value)` | `void` | Sends a display resolution back to the server. |
+| `reject(slot_id, error)` | `void` | Sends a display rejection back. |
+| `abort()` | `void` | Sends `{ type: "abort", id }`. |
+
+### Display slots
+
+When a tool inside the agent calls `display.pushAndWait(...)`, the server emits a `display_push`. Route slot pushes by `slot.renderer`, render the input, and call `result.resolve(slot.id, value)` once the user submits.
+
+```ts
+const result = media.prompt("Pick a frame to use as the thumbnail.")
+
+for await (const ev of result.display) {
+  if (ev.type === "push" && ev.slot) {
+    const slot = ev.slot
+    if (slot.renderer === "frame_picker") {
+      const choice = await renderFramePicker(slot.input)
+      result.resolve(slot.id, choice)
+    }
+  } else if (ev.type === "clear") {
+    clearSlot(ev.slot_id!)
+  }
+}
+```
+
+### Reading the environment
+
+```ts
+const env = await media.environment()
+// env.fs.input.path === "/input"
+// env.packages.apt?.includes("ffmpeg")
+```
+
+Cached after the first call. Useful when the same client holds many endpoints and routes prompts based on declared capabilities. Backed by `GET /environment` on the server.
+
+### Send-side errors
+
+Outgoing frames (`prompt`, `abort`, `display_resolve`, `display_reject`) are dispatched through `void this.send(...)`. Failures there are surfaced via:
+
+```ts
+const off = media.onSendError((err) => {
+  console.error("[media] send failed:", err)
+})
+// later
+off()
+```
+
+If no listener is registered, the SDK warns to `console.warn` so the failure doesn't disappear silently.
+
+### Lifecycle
+
+```ts
+await media.close()           // closes one box
+await client.close()          // closes every cached box
+```
+
+Closing rejects every in-flight prompt's `message` and `outputs` and closes the corresponding event/display iterators. The connection is otherwise managed lazily — `prompt()` re-opens after `close()` only if you reach back through `client.box(...)` for a fresh `Box`.
+
+## Custom storage
+
+`DefaultClientStorage` puts files inline (base64) and reads `inline | url | server` refs. That's enough for a lot of agents — tens of MB ride fine — but exceeds what you want over a single WS frame at some point.
+
+Provide a `ClientStorage` to split big inputs out. The contract is two methods:
+
+```ts
+interface ClientStorage {
+  put(name: string, mime: string, bytes: Uint8Array): Promise<FileRef>
+  get(ref: FileRef, opts?: { bearer?: string }): Promise<Uint8Array>
+}
+```
+
+Example: pre-sign an S3 URL on your backend, hand the `s3` ref to the server.
+
+```ts
+import type { ClientStorage } from "glovebox-client"
+import type { FileRef } from "glovebox-client"
+
+class S3UploadingStorage implements ClientStorage {
+  async put(name, mime, bytes): Promise<FileRef> {
+    const { bucket, key, putUrl } = await fetch("/api/sign-upload", {
+      method: "POST",
+      body: JSON.stringify({ name, mime, size: bytes.length }),
+    }).then((r) => r.json())
+    await fetch(putUrl, { method: "PUT", body: bytes, headers: { "Content-Type": mime } })
+    return { kind: "s3", name, mime, bucket, key }
+  }
+
+  async get(ref: FileRef, opts) {
+    if (ref.kind === "s3") {
+      const { getUrl } = await fetch("/api/sign-download", {
+        method: "POST",
+        body: JSON.stringify({ bucket: ref.bucket, key: ref.key }),
+      }).then((r) => r.json())
+      return new Uint8Array(await fetch(getUrl).then((r) => r.arrayBuffer()))
+    }
+    return new DefaultClientStorage().get(ref, opts)
+  }
+}
+
+const client = GloveboxClient.make({
+  endpoints: { media: { url, key } },
+  storage: new S3UploadingStorage(),
+})
+```
+
+The same storage is used for outputs: `result.read(name)` calls `storage.get(ref, { bearer })`, so `s3` refs returned by the server flow through your custom adapter too. The bearer is forwarded only for `server`-kind refs (the kit's authenticated `/files/:id` route).
+
+`PromptOptions.inputs` lets you pass pre-built `FileRef`s alongside (or instead of) raw `files` — handy when the bytes already live somewhere the server can read directly.
+
+## Errors
+
+Server `error` frames reject `result.message` and `result.outputs` with an `Error` carrying the server-supplied `code` (assignable as `(err as Error & { code: string }).code`). The connection itself is preserved — only the failing prompt is dropped. A WS close drops every in-flight prompt with `Error("Connection closed")`. There is no automatic reconnect in v1; a fresh prompt on a closed `Box` throws.
+
+## Public surface
+
+```ts
+import {
+  GloveboxClient,
+  Box,
+  DefaultClientStorage,
+  type GloveboxClientOptions,
+  type BoxEndpoint,
+  type BoxOptions,
+  type PromptOptions,
+  type PromptResult,
+  type SubscriberEvent,
+  type DisplayEvent,
+  type BoxEnvironment,
+  type ClientStorage,
+  type DefaultClientStorageOptions,
+  type FileRef,
+  type SubscriberEventType,
+  type WireSlot,
+} from "glovebox-client"
+```
+
+## Status
+
+v1. The wire protocol is `protocol_version: 1`. Connections are bearer-authed and prompts within a session run sequentially on the server. There is no client-side reconnect / resume — when the socket drops, in-flight prompts reject. JWT auth, multiplexed execution, and a hosted glovebox.dev tier are deferred to v2.
+
+## Companion packages
+
+- **[`glovebox-core`](../glovebox/README.md)** — authoring kit + `glovebox build` CLI.
+- **[`glovebox-kit`](../glovebox-kit/README.md)** — in-container runtime.
+
+## Documentation
+
+- [Glovebox Guide](https://glove.dterminal.net/docs/glovebox)
+- [Full Documentation](https://glove.dterminal.net)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+import { FileRef, SubscriberEventType, WireSlot } from 'glovebox-core/protocol';
+export { FileRef, SubscriberEventType, WireSlot } from 'glovebox-core/protocol';
+
+/**
+ * Client-side storage helpers. Symmetric to the server: the client uploads
+ * inputs, the server uploads outputs. v1 only ships the two adapters that
+ * don't need extra runtime services: inline (for small payloads) and url
+ * (for caller-supplied URLs).
+ */
+interface ClientStorage {
+    /** Wrap raw bytes into a FileRef the server can read. */
+    put(name: string, mime: string, bytes: Uint8Array): Promise<FileRef>;
+    /** Read a FileRef received from the server back into bytes. */
+    get(ref: FileRef, opts?: {
+        bearer?: string;
+    }): Promise<Uint8Array>;
+}
+interface DefaultClientStorageOptions {
+    /** Inline below this many bytes; throws above. Default: no upper bound. */
+    inlineMaxBytes?: number;
+}
+declare class DefaultClientStorage implements ClientStorage {
+    private readonly opts;
+    constructor(opts?: DefaultClientStorageOptions);
+    put(name: string, mime: string, bytes: Uint8Array): Promise<FileRef>;
+    get(ref: FileRef, opts?: {
+        bearer?: string;
+    }): Promise<Uint8Array>;
+}
+
+interface BoxEndpoint {
+    url: string;
+    key: string;
+}
+interface BoxOptions {
+    endpoint: BoxEndpoint;
+    storage?: ClientStorage;
+    /**
+     * Reconnect attempts on connection drop. Default 3, exponential backoff
+     * 500ms / 1s / 2s.
+     */
+    reconnectAttempts?: number;
+}
+interface PromptOptions {
+    /** Caller-supplied input files. Bytes get wrapped via the configured ClientStorage. */
+    files?: Record<string, {
+        mime?: string;
+        bytes: Uint8Array;
+    }>;
+    /** Pre-computed FileRefs (bypasses ClientStorage). Merged with `files`. */
+    inputs?: Record<string, FileRef>;
+}
+interface SubscriberEvent {
+    request_id: string;
+    event_type: SubscriberEventType;
+    data: unknown;
+}
+interface DisplayEvent {
+    type: "push" | "clear";
+    slot?: WireSlot;
+    slot_id?: string;
+}
+interface PromptResult {
+    /** Async iterable of subscriber events (text deltas, tool uses, etc.). */
+    events: AsyncIterable<SubscriberEvent>;
+    /** Async iterable of display slot pushes/clears. */
+    display: AsyncIterable<DisplayEvent>;
+    /** Resolves with the final assistant message. */
+    message: Promise<string>;
+    /** Resolves with the final outputs map. */
+    outputs: Promise<Record<string, FileRef>>;
+    /** Read an output file's bytes through the configured storage. */
+    read(name: string): Promise<Uint8Array>;
+    /** Send a display resolution back to the server. */
+    resolve(slot_id: string, value: unknown): void;
+    /** Send a display rejection back to the server. */
+    reject(slot_id: string, error: unknown): void;
+    /** Abort this prompt. */
+    abort(): void;
+}
+interface BoxEnvironment {
+    name: string;
+    version: string;
+    base: string;
+    fs: Record<string, {
+        path: string;
+        writable: boolean;
+    }>;
+    packages: {
+        apt?: string[];
+        pip?: string[];
+        npm?: string[];
+    };
+    limits?: {
+        cpu?: string;
+        memory?: string;
+        timeout?: string;
+    };
+    protocol_version: 1;
+}
+declare class Box {
+    private readonly opts;
+    private ws;
+    private opening;
+    private closed;
+    private nextId;
+    private readonly inflight;
+    private readonly storage;
+    constructor(opts: BoxOptions);
+    get bearer(): string;
+    close(): Promise<void>;
+    prompt(text: string, opts?: PromptOptions): PromptResult;
+    /**
+     * Fetch the deployed glovebox's environment spec — useful for routing
+     * decisions when an app holds many endpoints. Cached after first fetch.
+     */
+    environment(): Promise<BoxEnvironment>;
+    /** Subscribe to send-side errors that escape `void this.send(...)` callsites. */
+    onSendError(listener: (err: unknown) => void): () => void;
+    private envCache?;
+    private sendErrorListeners;
+    private emitSendError;
+    private dispatchPrompt;
+    private send;
+    private ensureOpen;
+    private openSocket;
+    private handleMessage;
+}
+
+interface GloveboxClientOptions {
+    endpoints: Record<string, BoxEndpoint>;
+    storage?: ClientStorage;
+}
+/**
+ * Holds a registry of named glovebox endpoints and lazily constructs `Box`
+ * connections on demand.
+ *
+ *     const client = GloveboxClient.make({
+ *       endpoints: {
+ *         media: { url: "wss://media.example.com/run", key: process.env.GLOVEBOX_MEDIA_KEY! },
+ *       },
+ *     })
+ *
+ *     const result = client.box("media").prompt("trim this", { files: { "in.mp4": ... } })
+ */
+declare class GloveboxClient {
+    private readonly opts;
+    private boxes;
+    private constructor();
+    static make(opts: GloveboxClientOptions): GloveboxClient;
+    box(name: string): Box;
+    close(): Promise<void>;
+}
+
+export { Box, type BoxEndpoint, type BoxEnvironment, type BoxOptions, type ClientStorage, DefaultClientStorage, type DefaultClientStorageOptions, type DisplayEvent, GloveboxClient, type GloveboxClientOptions, type PromptOptions, type PromptResult, type SubscriberEvent };

package/dist/index.js

@@ -0,0 +1,353 @@
+// src/storage.ts
+var DefaultClientStorage = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  async put(name, mime, bytes) {
+    if (this.opts.inlineMaxBytes !== void 0 && bytes.length > this.opts.inlineMaxBytes) {
+      throw new Error(
+        `File ${name} (${bytes.length} bytes) exceeds inlineMaxBytes (${this.opts.inlineMaxBytes}); provide a custom ClientStorage that uploads to S3 or another backend`
+      );
+    }
+    return {
+      kind: "inline",
+      name,
+      mime,
+      data: bytesToBase64(bytes)
+    };
+  }
+  async get(ref, opts) {
+    if (ref.kind === "inline") return base64ToBytes(ref.data);
+    if (ref.kind === "url" || ref.kind === "server") {
+      const headers = ref.kind === "url" && ref.headers ? { ...ref.headers } : {};
+      if (ref.kind === "server" && opts?.bearer) {
+        headers["Authorization"] = `Bearer ${opts.bearer}`;
+      }
+      const res = await fetch(ref.url, { headers });
+      if (!res.ok) throw new Error(`Failed to fetch ${ref.url}: ${res.status} ${res.statusText}`);
+      return new Uint8Array(await res.arrayBuffer());
+    }
+    throw new Error(`DefaultClientStorage cannot get ref of kind ${ref.kind}; pass a custom ClientStorage`);
+  }
+};
+function bytesToBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return btoa(s);
+}
+function base64ToBytes(b64) {
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(b64, "base64"));
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+// src/wire.ts
+async function pickWebSocket() {
+  if (typeof globalThis !== "undefined" && typeof globalThis.WebSocket === "function") {
+    return globalThis.WebSocket;
+  }
+  const mod = await import("ws");
+  return mod.WebSocket;
+}
+function httpFromWs(wsUrl, pathname) {
+  const u = new URL(wsUrl);
+  if (u.protocol === "wss:") u.protocol = "https:";
+  else if (u.protocol === "ws:") u.protocol = "http:";
+  u.pathname = pathname;
+  u.search = "";
+  return u.toString();
+}
+
+// src/box.ts
+function asyncQueue() {
+  const buf = [];
+  let waker = null;
+  let closed = false;
+  const next = () => {
+    if (buf.length > 0) return Promise.resolve({ value: buf.shift(), done: false });
+    if (closed) return Promise.resolve({ value: void 0, done: true });
+    return new Promise((resolve) => {
+      waker = resolve;
+    });
+  };
+  return {
+    push(value) {
+      if (closed) return;
+      if (waker) {
+        const w = waker;
+        waker = null;
+        w({ value, done: false });
+      } else {
+        buf.push(value);
+      }
+    },
+    close() {
+      closed = true;
+      if (waker) {
+        const w = waker;
+        waker = null;
+        w({ value: void 0, done: true });
+      }
+    },
+    iter() {
+      return { [Symbol.asyncIterator]: () => ({ next }) };
+    }
+  };
+}
+var Box = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.storage = opts.storage ?? new DefaultClientStorage();
+  }
+  ws = null;
+  opening = null;
+  closed = false;
+  nextId = 1;
+  inflight = /* @__PURE__ */ new Map();
+  storage;
+  get bearer() {
+    return this.opts.endpoint.key;
+  }
+  async close() {
+    this.closed = true;
+    if (this.ws) this.ws.close(1e3, "client closed");
+    for (const inflight of this.inflight.values()) {
+      inflight.events.close();
+      inflight.display.close();
+      inflight.rejectMessage(new Error("Connection closed"));
+      inflight.rejectOutputs(new Error("Connection closed"));
+    }
+    this.inflight.clear();
+  }
+  prompt(text, opts) {
+    if (this.closed) throw new Error("Box is closed");
+    const id = `req_${this.nextId++}`;
+    const events = asyncQueue();
+    const display = asyncQueue();
+    let resolveMessage = () => void 0;
+    let rejectMessage = () => void 0;
+    const messagePromise = new Promise((res, rej) => {
+      resolveMessage = res;
+      rejectMessage = rej;
+    });
+    let resolveOutputs = () => void 0;
+    let rejectOutputs = () => void 0;
+    const outputsPromise = new Promise((res, rej) => {
+      resolveOutputs = res;
+      rejectOutputs = rej;
+    });
+    this.inflight.set(id, {
+      events,
+      display,
+      resolveMessage,
+      rejectMessage,
+      resolveOutputs,
+      rejectOutputs
+    });
+    void this.dispatchPrompt(id, text, opts).catch((err) => {
+      const inflight = this.inflight.get(id);
+      if (inflight) {
+        inflight.events.close();
+        inflight.display.close();
+        inflight.rejectMessage(err);
+        inflight.rejectOutputs(err);
+        this.inflight.delete(id);
+      }
+    });
+    const sendOrEmit = (msg) => {
+      this.send(msg).catch((err) => {
+        this.emitSendError(err);
+      });
+    };
+    const result = {
+      events: events.iter(),
+      display: display.iter(),
+      message: messagePromise,
+      outputs: outputsPromise,
+      read: async (name) => {
+        const outputs = await outputsPromise;
+        const ref = outputs[name];
+        if (!ref) throw new Error(`No output named ${name}`);
+        return this.storage.get(ref, { bearer: this.bearer });
+      },
+      resolve: (slot_id, value) => sendOrEmit({ type: "display_resolve", slot_id, value }),
+      reject: (slot_id, error) => sendOrEmit({ type: "display_reject", slot_id, error }),
+      abort: () => sendOrEmit({ type: "abort", id })
+    };
+    return result;
+  }
+  /**
+   * Fetch the deployed glovebox's environment spec — useful for routing
+   * decisions when an app holds many endpoints. Cached after first fetch.
+   */
+  async environment() {
+    if (this.envCache) return this.envCache;
+    const url = httpFromWs(this.opts.endpoint.url, "/environment");
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.bearer}` }
+    });
+    if (!res.ok) {
+      throw new Error(`environment fetch failed: ${res.status} ${res.statusText}`);
+    }
+    const env = await res.json();
+    this.envCache = env;
+    return env;
+  }
+  /** Subscribe to send-side errors that escape `void this.send(...)` callsites. */
+  onSendError(listener) {
+    this.sendErrorListeners.add(listener);
+    return () => this.sendErrorListeners.delete(listener);
+  }
+  envCache;
+  sendErrorListeners = /* @__PURE__ */ new Set();
+  emitSendError(err) {
+    if (this.sendErrorListeners.size === 0) {
+      console.warn("[glovebox-client] send failed:", err);
+      return;
+    }
+    for (const fn of this.sendErrorListeners) {
+      try {
+        fn(err);
+      } catch {
+      }
+    }
+  }
+  // ─── internals ────────────────────────────────────────────────────────
+  async dispatchPrompt(id, text, opts) {
+    const inputs = { ...opts?.inputs ?? {} };
+    if (opts?.files) {
+      for (const [name, f] of Object.entries(opts.files)) {
+        inputs[name] = await this.storage.put(name, f.mime ?? "application/octet-stream", f.bytes);
+      }
+    }
+    await this.send({ type: "prompt", id, text, inputs });
+  }
+  async send(msg) {
+    const ws = await this.ensureOpen();
+    ws.send(JSON.stringify(msg));
+  }
+  async ensureOpen() {
+    if (this.ws) return this.ws;
+    if (this.opening) return this.opening;
+    this.opening = this.openSocket();
+    try {
+      this.ws = await this.opening;
+      return this.ws;
+    } finally {
+      this.opening = null;
+    }
+  }
+  async openSocket() {
+    const Ctor = await pickWebSocket();
+    const headers = { Authorization: `Bearer ${this.opts.endpoint.key}` };
+    const ws = new Ctor(this.opts.endpoint.url, void 0, { headers });
+    await new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => resolve());
+      ws.addEventListener("error", (event) => reject(new Error(event.message ?? "websocket error")));
+    });
+    ws.addEventListener("message", (event) => {
+      let msg;
+      try {
+        msg = JSON.parse(typeof event.data === "string" ? event.data : String(event.data));
+      } catch {
+        return;
+      }
+      this.handleMessage(msg);
+    });
+    ws.addEventListener("close", () => {
+      this.ws = null;
+      for (const [, inflight] of this.inflight) {
+        inflight.events.close();
+        inflight.display.close();
+        inflight.rejectMessage(new Error("Connection closed"));
+        inflight.rejectOutputs(new Error("Connection closed"));
+      }
+      this.inflight.clear();
+    });
+    return ws;
+  }
+  handleMessage(msg) {
+    switch (msg.type) {
+      case "event": {
+        const inflight = this.inflight.get(msg.id);
+        if (inflight) {
+          inflight.events.push({
+            request_id: msg.id,
+            event_type: msg.event_type,
+            data: msg.data
+          });
+        }
+        return;
+      }
+      case "display_push": {
+        for (const inflight of this.inflight.values()) {
+          inflight.display.push({ type: "push", slot: msg.slot });
+        }
+        return;
+      }
+      case "display_clear": {
+        for (const inflight of this.inflight.values()) {
+          inflight.display.push({ type: "clear", slot_id: msg.slot_id });
+        }
+        return;
+      }
+      case "complete": {
+        const inflight = this.inflight.get(msg.id);
+        if (inflight) {
+          inflight.resolveOutputs(msg.outputs);
+          inflight.resolveMessage(msg.message);
+          inflight.events.close();
+          inflight.display.close();
+          this.inflight.delete(msg.id);
+        }
+        return;
+      }
+      case "error": {
+        const inflight = this.inflight.get(msg.id);
+        if (inflight) {
+          const err = Object.assign(new Error(msg.error.message), { code: msg.error.code });
+          inflight.rejectMessage(err);
+          inflight.rejectOutputs(err);
+          inflight.events.close();
+          inflight.display.close();
+          this.inflight.delete(msg.id);
+        }
+        return;
+      }
+      case "pong":
+        return;
+    }
+  }
+};
+
+// src/client.ts
+var GloveboxClient = class _GloveboxClient {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  boxes = /* @__PURE__ */ new Map();
+  static make(opts) {
+    return new _GloveboxClient(opts);
+  }
+  box(name) {
+    const cached = this.boxes.get(name);
+    if (cached) return cached;
+    const endpoint = this.opts.endpoints[name];
+    if (!endpoint) throw new Error(`Unknown glovebox endpoint: ${name}`);
+    const box = new Box({ endpoint, storage: this.opts.storage });
+    this.boxes.set(name, box);
+    return box;
+  }
+  async close() {
+    await Promise.all([...this.boxes.values()].map((b) => b.close()));
+    this.boxes.clear();
+  }
+};
+export {
+  Box,
+  DefaultClientStorage,
+  GloveboxClient
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "glovebox-client",
+  "version": "0.5.0",
+  "description": "Client SDK for talking to a deployed Glovebox server",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/porkytheblack/glove.git",
+    "directory": "packages/glovebox-client"
+  },
+  "homepage": "https://github.com/porkytheblack/glove",
+  "bugs": "https://github.com/porkytheblack/glove/issues",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "glovebox-core": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}