Client API

vespr-client.js is the small library the app shell uses to join a workspace. It turns the shared document into plain objects you can draw, and turns a few method calls into changes everyone sees. Use it to build your own front end on the same workspace.

On this page

• What it is Built
• Use it
• createClient(options)
• Reading state
• Acting
• What it does not do yet
• How it is tested

What it is Built

The client joins a room as an ordinary Yjs participant, the same kind of peer the SDE extension and the agents are. There is no framework and no build step: it is one ES module, app/vespr-client.js. Yjs, y-websocket and a WebSocket class are passed in, so the same file runs in a browser and in Node.

The client reads and reports; it does not edit file text. Editing text is the SDE's job. What it can do is send chat messages, answer approvals, change settings, request runs, upload files and tell your own SDE what to show.

Use it

In Node

Node 20 has no global WebSocket, so pass the ws package. Install the three packages with npm install yjs y-websocket ws.

import WebSocket from 'ws'
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'
import { createClient } from './vespr-client.js'

const c = createClient({
  server: 'ws://127.0.0.1:9611',          // the realtime server
  room: 'demo',
  token: process.env.VESPR_TOKEN,         // your login; keep it out of your code
  name: 'alex',
  deps: { Y, WebsocketProvider, WebSocketPolyfill: WebSocket }
})
await c.ready

c.on('change', what => {                  // 'chat' | 'files' | 'presence' | 'settings' | 'usage' | 'status' | 'runs'
  const snap = c.get()
  if (what === 'chat') console.log(snap.messages.at(-1)?.text)
})
c.on('edit', e => console.log(`${e.by} changed ${e.file} at line ${e.line}`))

c.send('@coder run python3 -m unittest -q')

// the agent asks the room before it runs anything; read the card, then answer it
for (const card of c.get().approvals.pending) console.log(card.id, card.text)
// c.decide(cardId, true)   // approve; the first answer wins

In a browser

Leave deps out and give the page an import map. The app shell does exactly this, with the bundles in app/vendor/, and the browser's own WebSocket is used.

<script type="importmap">
{ "imports": { "yjs": "./vendor/yjs.js", "y-websocket": "./vendor/y-websocket.js" } }
</script>
<script type="module">
  import { createClient } from './vespr-client.js'
  const c = createClient({ server: 'ws://127.0.0.1:9611', room: 'demo', token, name: 'alex' })
  await c.ready
</script>

Cross-origin requests to the server's /api/* endpoints (uploads, runners) work: the server answers with CORS headers, by default for any origin. Set MURMIO_CORS_ORIGIN on the server to one origin, or to an empty value to switch it off. A token is still required for every call.

createClient(options)

It throws if server, room, token or name is missing. The module also exports loadDeps() and parsePyProblems(output, inRoom, cwd), which turns the Python tracebacks in a run's output into { file, line, message } entries for files that are in the workspace.

Reading state

await c.ready resolves when the first sync with the server is done. After that, c.get() returns one plain snapshot. It is cheap enough to call on every change. Before the client is ready it returns an empty snapshot.

A chat message

Each entry of messages is { id, ts, author, isAgent, role, model, text, thread, quote, attachments, kind, detail, status, decidedBy }.

• role is user, agent, tool or approval. Agent text is streamed, so text grows while the agent writes.
• quote is { src, text, by } when the message came from select-to-ask. attachments is a list of { name, size, type, id, sha256 }.
• For approval messages, kind and detail say what is asked, status is pending, approved, denied or expired, and decidedBy is who answered (timeout for an expired card).

Events

c.on(type, listener) returns a function that removes the listener.

• 'change' is called with what changed: chat, files, presence, settings, usage, status or runs. Changes are batched per tick, so several edits give one call per kind.
• 'edit' is called with a file change as it happens: { file, at, removed, added, line, by, ai, model, msg, ts }, plus created: true when the file is new (then everything in it is added). by, ai, model and msg come from the authorship that rides on every insert, so you can draw the red and green lines and say who made them. by is someone when the change carries no author.

Acting

Run from the app

The request is a small entry in the shared runs list that carries a kind and a file name, never a command line. The agent checks that the file is a .py file in the workspace, runs it, and writes the output back as it arrives. Each entry of runs is { id, by, kind, file, cmd, status, out, code, started, ended, runner, changed }, where status goes from requested to running to done, or ends as denied.

It is off unless the operator sets MURMIO_HUMAN_RUNS=1 on the agent; runsEnabled tells you. A remote runner (a teammate's computer) is refused for these requests: those runs need an approval through the agent. Why it is off by default: the sandbox caveat.

The command bus

command writes a short entry into the shared document. The SDE extension carries it out only if it was written by the same person as that SDE, the file exists in the workspace and is not editor configuration or git, and the agent is really in the room. It can only open or follow, never run anything. Entries older than 15 seconds, or from before the SDE connected, are ignored.

The History shape

Every item of history() is { id, ts, who, kind, model, type, verb, target, detail, file, plus, minus, extra }. kind is person, agent or system; type is edit, run, approval or access. It is derived from the shared document, so it needs no storage of its own.

What it does not do yet

• Private lanes and role checks. Planned The whole room is visible to everyone who can connect, and History has no manager-only gate and no retention. Those need access control on the server.
• Editing text. The client reads files and reports edits. The SDE does the editing.
• Browser coverage. The app shell runs it in a browser; the automated tests run it in Node, against a real server and the agent's real code.

How it is tested

agents/test/client.test.js runs the client against a real server and the agent's real room code: presence and agents, a message with a thread, a quote and attachments reaching the agent, streamed agent text, a created file and a replaced line arriving as edit events with the removed and added text and the author, approval cards where the first answer decides, mode changes reaching the agent, History, runners, and a wrong token never connecting. Run requests are covered in agents/test/runs.test.js, and the command bus in agents/test/client.test.js and extensions/murmio-collab/test/uibus.test.js.