mandala-computer-mcp 0.1.0

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,GAAG,cAAc,CAAC;CAChC;AAED,MAAM,OAAO,QAAS,SAAQ,YAAY;IAiB7B;IACA;IAjBF,IAAI,GAAG,UAAU,CAAC;IAC3B;;;;;;;;;;;OAWG;IACM,MAAM,CAAU;IACzB,YACE,OAAe,EACN,MAAc,EACd,IAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAU;QAGvB,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC,CAAC;AAC/E,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC;AAEtF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,YAAY;YACf,OAAO,mGAAmG,CAAC;QAC7G,KAAK,UAAU;YACb,OAAO,6FAA6F,CAAC;QACvG,KAAK,aAAa;YAChB,OAAO,+IAA+I,CAAC;QACzJ,KAAK,aAAa;YAChB,OAAO,wFAAwF,CAAC;QAClG;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,IAAa;IAClC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,MAAM,GAAI,IAA6B,CAAC,MAAM,CAAC;IACrD,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED,uDAAuD;AACvD,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,GAAG,qBAAqB,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACjC,IAAI,GAAG,gBAAgB,CAAC;CAClC;AAED,qEAAqE;AACrE,MAAM,OAAO,qBAAsB,SAAQ,QAAQ;IACxC,IAAI,GAAG,uBAAuB,CAAC;CACzC;AAED,kDAAkD;AAClD,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAChC,IAAI,GAAG,eAAe,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAChC,IAAI,GAAG,eAAe,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAOvC;IANF,IAAI,GAAG,mBAAmB,CAAC;IACpC,YACE,OAAe,EACf,MAAc,EACd,IAAa;IACb,2EAA2E;IAClE,YAAqB;QAE9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAFpB,iBAAY,GAAZ,YAAY,CAAS;IAGhC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CAAC,IAAa;IAC9B,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI,CAAC;IAC/C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAkD,CAAC;IAClF,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,wBAAyB,SAAQ,QAAQ;IAOzC;IANF,IAAI,GAAG,0BAA0B,CAAC;IAC3C,YACE,OAAe,EACf,MAAc,EACd,IAAc;IACd,+EAA+E;IACtE,IAAa;QAEtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAFpB,SAAI,GAAJ,IAAI,CAAS;IAGxB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IAO/B;IANF,IAAI,GAAG,gBAAgB,CAAC;IACjC,YACE,OAAe,EACf,MAAc,EACd,IAAc;IACd,gFAAgF;IACvE,YAAqB;QAE9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAFpB,iBAAY,GAAZ,YAAY,CAAS;IAGhC,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACnC,IAAI,GAAG,kBAAkB,CAAC;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAe,SAAQ,YAAY;IACrC,IAAI,GAAG,gBAAgB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACxC,IAAI,GAAG,mBAAmB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,4BAA6B,SAAQ,iBAAiB;IACxD,IAAI,GAAG,8BAA8B,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,GAAG,qBAAqB,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,QAAQ;IACzC,IAAI,GAAG,wBAAwB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,GAAG,qBAAqB,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACjC,IAAI,GAAG,gBAAgB,CAAC;CAClC;AAED,MAAM,SAAS,GAAoC;IACjD,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,qBAAqB;IAC1B,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,aAAa;IAClB,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,qBAAqB;IACrB,GAAG,EAAE,wBAAwB;IAC7B,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,2DAA2D;IAC3D,GAAG,EAAE,cAAc;IACnB,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,4EAA4E;IAC5E,8EAA8E;IAC9E,+EAA+E;IAC/E,4FAA4F;IAC5F,yEAAyE;IACzE,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,gBAAgB;IACrB,GAAG,EAAE,mBAAmB;IACxB,6EAA6E;IAC7E,yEAAyE;IACzE,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,mBAAmB;IACxB,+EAA+E;IAC/E,mEAAmE;IACnE,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,cAAc;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,sBAAsB,GAC1B,iFAAiF;IACjF,wFAAwF;IACxF,iCAAiC,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,uBAAuB,GAC3B,sFAAsF;IACtF,uFAAuF;IACvF,uFAAuF;IACvF,sFAAsF;IACtF,uFAAuF;IACvF,oDAAoD,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,yBAAyB,GAC7B,wFAAwF;IACxF,qFAAqF;IACrF,qFAAqF;IACrF,sFAAsF;IACtF,iBAAiB,CAAC;AAEpB,oFAAoF;AACpF,SAAS,qBAAqB,CAAC,MAAc;IAC3C,OAAO,CACL,sBAAsB,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAChG,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,uBAAuB,GAC3B,qFAAqF;IACrF,wFAAwF;IACxF,yFAAyF;IACzF,0FAA0F;IAC1F,wFAAwF;IACxF,6DAA6D,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,mBAAmB,GACvB,sFAAsF;IACtF,sFAAsF;IACtF,uFAAuF;IACvF,wFAAwF;IACxF,mFAAmF;IACnF,qFAAqF,CAAC;AAExF,8EAA8E;AAC9E,MAAM,0BAA0B,GAC9B,oFAAoF;IACpF,wFAAwF;IACxF,wFAAwF;IACxF,yFAAyF;IACzF,0FAA0F;IAC1F,sFAAsF;IACtF,uFAAuF;IACvF,2BAA2B,CAAC;AAE9B,gEAAgE;AAChE,MAAM,kBAAkB,GACtB,sFAAsF;IACtF,mFAAmF;IACnF,sFAAsF;IACtF,sCAAsC,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,SAAS,aAAa,CAAC,IAAa;IAClC,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,GAAG,GAAI,IAA4B,CAAC,KAAK,CAAC;IAChD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAe,EAAE,IAAc;IAC5E,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC;IAC1C,6EAA6E;IAC7E,8EAA8E;IAC9E,6EAA6E;IAC7E,sCAAsC;IACtC,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,KAAK;YAAE,OAAO,IAAI,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjF,CAAC;IACD,4EAA4E;IAC5E,4EAA4E;IAC5E,0EAA0E;IAC1E,EAAE;IACF,8EAA8E;IAC9E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,4EAA4E;IAC5E,6EAA6E;IAC7E,8DAA8D;IAC9D,IAAI,GAAG,KAAK,mBAAmB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,mBAAmB,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,GAAG,KAAK,mBAAmB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACxD,qEAAqE;QACrE,2DAA2D;QAC3D,MAAM,IAAI,GAAG,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,uBAAuB,CAAC;QAC5E,OAAO,IAAI,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,GAAG,KAAK,cAAc,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,IAAI,cAAc,CAAC,kBAAkB,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,GAAG,KAAK,sBAAsB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3D,OAAO,IAAI,sBAAsB,CAAC,0BAA0B,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,0EAA0E;IAC1E,8EAA8E;IAC9E,8EAA8E;IAC9E,+EAA+E;IAC/E,kCAAkC;IAClC,IAAI,GAAG,YAAY,iBAAiB;QAAE,OAAO,KAAK,CAAC;IACnD,4EAA4E;IAC5E,6EAA6E;IAC7E,wEAAwE;IACxE,IAAI,GAAG,YAAY,4BAA4B;QAAE,OAAO,KAAK,CAAC;IAC9D,4EAA4E;IAC5E,8EAA8E;IAC9E,4EAA4E;IAC5E,6EAA6E;IAC7E,0CAA0C;IAC1C,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACxD,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/C,IAAI,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;IACrD,CAAC;IACD,OAAO,CACL,GAAG,YAAY,aAAa;QAC5B,GAAG,YAAY,cAAc;QAC7B,GAAG,YAAY,gBAAgB;QAC/B,GAAG,YAAY,iBAAiB,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,CAAC,CAAC,GAAG,YAAY,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,YAAY,iBAAiB,CAAC;QAAE,OAAO,KAAK,CAAC;IACpF,IAAI,GAAG,YAAY,iBAAiB;QAAE,OAAO,KAAK,CAAC;IACnD,IAAI,GAAG,YAAY,cAAc;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChF,OAAO,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,406 @@
+/**
+ * What a computer is doing, held open on this side of the model.
+ *
+ * `GET computers/:id/events` (platform OPL-3785) is a websocket that says what
+ * a computer is doing without being asked, so that an agent stops paying for a
+ * screenshot to learn that nothing has changed. Every other client of that
+ * stream hands it to its caller as an iterator, because every other caller sits
+ * in a loop. A model does not: it takes turns, and between two turns there is
+ * nobody here to read a socket.
+ *
+ * So the socket lives HERE, in the session, and the model holds nothing but a
+ * cursor. One connection per computer, opened the first time a tool asks about
+ * it, kept across turns, reaped when nothing has asked for a while. What
+ * arrives while the model is thinking goes into a bounded ring, and the next
+ * `poll_events` or `wait_for_event` is handed it in order. The model never
+ * learns that a socket exists.
+ *
+ * That is the whole of OPL-3926's decision, and the alternative it rejects is
+ * worth naming: an MCP `resources/subscribe` and a `notifications/*` doorbell.
+ * The spec's notification filter is a closed vocabulary — `toolsListChanged`,
+ * `promptsListChanged`, `resourcesListChanged`, `resourceSubscriptions` — with
+ * no channel for a server's own domain events, so a `window.opened` could only
+ * ride in as `resources/updated` on some URI, and that notification carries a
+ * URI and no payload. The model would still have to read. Which makes the
+ * doorbell an addition to this file rather than a replacement for it, and one
+ * whose bell nothing on the other end rings yet.
+ *
+ * Written against the `events_url` entry in the platform's `web/lib/apidoc.ts`,
+ * which is the reference this must not contradict.
+ */
+import type { Api } from './api.js';
+/**
+ * The part of a `WebSocket` this file uses.
+ *
+ * Structural rather than a named class, so undici's, the global one and a
+ * test's stand-in all satisfy it without any of them being imported at the call
+ * site. Nothing here ever sends: the stream is one-way, and the reference says
+ * nothing a client writes to it means anything.
+ */
+export type EventSocket = {
+    addEventListener(type: 'open', fn: () => void): void;
+    addEventListener(type: 'message', fn: (ev: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'error', fn: () => void): void;
+    addEventListener(type: 'close', fn: () => void): void;
+    close(): void;
+};
+export type EventSocketFactory = (url: string) => EventSocket;
+/**
+ * undici's `WebSocket`, not Node's global one.
+ *
+ * The same choice `api.ts` makes about `fetch` and for a plainer reason: this
+ * package already depends on undici, `engines` says Node 20.3 and the global
+ * `WebSocket` did not arrive unflagged until Node 22. A server that worked on
+ * the Node it claims to support for every tool except these two would be a
+ * worse failure than not shipping them, because it only appears at the moment
+ * somebody waits for something.
+ */
+export declare const defaultEventSocket: EventSocketFactory;
+/**
+ * One frame off the stream, as the platform wrote it.
+ *
+ * Deliberately NOT re-shaped into a typed union the way the SDKs do. What
+ * reads this is a model reading JSON, so the platform's own spelling is the
+ * one worth handing over — and the reference promises the vocabulary grows,
+ * so a frame this build has never heard of has to arrive intact rather than be
+ * flattened into whatever fields this file happened to know about.
+ */
+export type ComputerEvent = Record<string, unknown> & {
+    type: string;
+};
+/**
+ * One nominated tree, as the opening frame reports it back.
+ *
+ * `path` is the nomination as the HOST normalised it, and that is the spelling
+ * every `file.changed` carries in `watch` — so a client matching on what it
+ * sent matches nothing the day the two differ. What this server does about that
+ * is {@link Subscription.hostPath}: it goes on nominating in its own spelling,
+ * because that is what every reconnect has to re-send, and matches in the
+ * host's.
+ *
+ * `armed` is the field a client gets wrong. A tree is not being watched because
+ * the socket accepted the nomination: the guest has to be asked, and on a
+ * computer nobody has opened a terminal on the host must install the watcher
+ * into the guest first. `true` here means live NOW and no event is coming to
+ * say so — somebody else nominated it first and the guest answers a nomination
+ * once. `false` means wait for `{watch, armed: true}` on the stream. The same
+ * split as `ready`: state in `hello`, transitions on the stream.
+ */
+export type Watched = {
+    path: string;
+    armed: boolean;
+};
+/** The opening frame, once per connection. */
+export type Hello = {
+    computer: string;
+    cursor: string;
+    /** Whether the desktop has ALREADY been announced ready for the session it is in. */
+    ready: boolean;
+    /** What THIS computer can emit — not everything the platform knows how to. */
+    events: string[];
+    /** The desktop as this host last saw it. Absent when a cursor was honoured. */
+    windows?: unknown[];
+    /**
+     * The trees this stream reports `file.changed` under, normalised by the host.
+     *
+     * ABSENT rather than empty when nothing was nominated, and the difference is
+     * the one that matters here: absent is also what a host that has never heard
+     * of `&watch=` sends back to a nomination, and this server has to be able to
+     * tell "you asked for nothing" from "this host cannot honour what you asked
+     * for" without waiting out a timeout to discover it.
+     */
+    watching?: Watched[];
+};
+/**
+ * How many trees ONE stream may nominate, which is the platform's own cap.
+ *
+ * There is a second, larger one this client cannot enforce: a computer watches
+ * at most 32 distinct trees across every stream open on it, and a nomination
+ * past that is refused on the upgrade — which reaches a websocket client as a
+ * socket that would not open and nothing else. See {@link Subscription.nominate}
+ * for what is done about that.
+ */
+export declare const MAX_WATCHES = 4;
+/** The platform's bound on one nominated path, in BYTES rather than characters. */
+export declare const MAX_WATCH_PATH_BYTES = 256;
+/**
+ * A nominated path, in the spelling the host will accept — or a refusal saying
+ * why it will not.
+ *
+ * A mirror of the platform's `cleanWatchPath`, and mirrored rather than left to
+ * the server for one reason: a path the host refuses is a `400` on the UPGRADE,
+ * and an upgrade that fails reaches a websocket client as an error event with
+ * no status and no body. Undici says "Received network error or non-101 status
+ * code" and that is the whole of it. So a bad path sent optimistically is
+ * indistinguishable here from a host that is down, and the answer a model would
+ * get is a reconnect loop under "could not open the event stream" — for a
+ * mistake that is entirely visible before anything is sent.
+ *
+ * Normalising rather than refusing the shapes people actually type is the
+ * platform's choice and is kept: a trailing slash and a `.` segment name one
+ * directory unambiguously. What must not happen is normalising SILENTLY, since
+ * the cleaned form is what events carry and what a caller has to match on — so
+ * the tools say what a path became when it changed.
+ */
+export declare function cleanWatchPath(input: string): string;
+/** How many events one computer may hold for a model that has not read them. */
+export declare const MAX_BUFFERED = 1024;
+/** How long a subscription nothing has asked about is kept open. */
+export declare const IDLE_REAP_MS: number;
+/** What a read of the buffer hands back. */
+export type Delivery = {
+    events: ComputerEvent[];
+    /** Where the caller is now, to pass back as `since`. */
+    cursor: string;
+    /** Events that were in the buffer and are not in this batch. Nothing is lost. */
+    more: number;
+    /**
+     * What was lost before it could be read, and why — `undefined` when nothing
+     * was. `events: null` is a number this server does not know rather than none:
+     * a platform gap says the history is short, not how short.
+     */
+    loss?: Loss;
+    /** The opening frame of the connection now open, if one has landed. */
+    hello?: Hello;
+    /** True on the first read of a subscription: the caller has no earlier place. */
+    attached: boolean;
+};
+export type Loss = {
+    events: number | null;
+    reason: string;
+};
+/** Whether a subscription can still be expected to produce anything. */
+export type SubscriptionState = {
+    status: 'connecting' | 'open';
+}
+/** Nothing more will arrive, and reopening would answer the same way. */
+ | {
+    status: 'stopped';
+    reason: string;
+};
+/**
+ * One computer's event stream, held across turns.
+ *
+ * Single-consumer, like the session it belongs to. It keeps its own place in
+ * the platform's stream so that a socket which drops mid-turn resumes rather
+ * than restarts, and it keeps the model's place in the buffer so that a model
+ * which asks nothing for four turns is still handed what happened during them.
+ */
+export declare class Subscription {
+    #private;
+    readonly computerId: string;
+    constructor(api: Api, computerId: string, socketFor: EventSocketFactory, since?: string, watches?: string[]);
+    /** The trees this stream nominates, in this client's own spelling. */
+    get nominations(): string[];
+    /**
+     * Where a REPLACEMENT for this subscription should start.
+     *
+     * The position after the last event the MODEL was handed — deliberately not
+     * `#resume`, which is after the last event this SOCKET received. The two are
+     * the same only when the model is caught up, and the case where they differ
+     * is the case this exists for: events arrive, the model is busy on another
+     * computer, the idle sweep reaps the subscription and its ring goes with it.
+     * Handing the replacement `#resume` there would ask the platform to replay
+     * from AFTER the unread events — losing exactly what the memory was meant to
+     * preserve, and losing it silently, since a `since` the platform can honour
+     * produces no gap.
+     *
+     * Before anything has been delivered the answer is where this stream began,
+     * which replays the whole buffer.
+     */
+    get resumeCursor(): string | undefined;
+    get state(): SubscriptionState;
+    get idleMs(): number;
+    /** What this computer can emit, as last stated. `undefined` before `hello`. */
+    get eventTypes(): string[] | undefined;
+    /**
+     * The trees nominated on this stream, and whether each is live yet.
+     *
+     * In the HOST's spelling, because that is the one every event carries and so
+     * the one a reader of this has to be able to match on.
+     */
+    get watching(): Watched[];
+    /** What the host calls a tree this stream nominated. Its own name until it says. */
+    hostPath(nominated: string): string;
+    /** Whether this tree is being watched right now. */
+    isArmed(path: string): boolean;
+    /**
+     * Which arming of this tree is current.
+     *
+     * Compared rather than read: a caller holds the number from when it started
+     * waiting and asks whether it still holds, which is how a re-arm ends a wait
+     * that was looking for file paths.
+     */
+    armGeneration(path: string): number;
+    /** The last thing this tree said it had lost, if it has said one since arming. */
+    lostFor(path: string): string | undefined;
+    /**
+     * Whether this host honoured the nomination at all.
+     *
+     * `undefined` while nothing has been nominated or no opening frame has been
+     * seen since. `false` is a host with no `file.changed` — see
+     * {@link #watchingEchoed}.
+     */
+    get watchesHonoured(): boolean | undefined;
+    /** Whether the connection now open nominated this tree and has greeted. */
+    nominationLive(path: string): boolean;
+    /**
+     * Whether this tree is being watched RIGHT NOW, connection included.
+     *
+     * The question {@link isArmed} does not answer and the one a quiet answer has
+     * to be built on. `#armed` is what the last opening frame said, and it is
+     * deliberately not cleared when a socket dies — clearing it would make every
+     * routine reconnect look like a re-arm, which is a "go and re-read the tree"
+     * for an interruption the platform's own replay covered. But a tree on a
+     * connection that is not up is not being watched at this instant, and a tool
+     * that said "watched for the whole of that and still is" while reconnecting
+     * would be wrong about the half of that sentence it can actually check.
+     */
+    watchLive(path: string): boolean;
+    /** Whether this stream is still nominating this tree at all. */
+    nominates(path: string): boolean;
+    /** Whether the connection carrying this tree was refused. See {@link WATCH_SHED_AFTER}. */
+    watchWasRefused(path: string): boolean;
+    /**
+     * Whether this tree went unwatched between a previous subscription and this
+     * one, and has not been told about it yet. Reading it CLEARS it: it is a
+     * thing to say once.
+     */
+    takeInterruption(path: string): boolean;
+    /** Mark it in use, so the idle sweep leaves it alone. */
+    touch(): void;
+    /**
+     * Ask this stream to report file changes under a tree.
+     *
+     * The one thing on this socket that has to be ASKED for: without a nomination
+     * no `file.changed` can arrive at all, which makes a watch a connection
+     * parameter rather than an event type to add to a list. So nominating
+     * something new reopens the connection — with this subscription's own
+     * `since`, so the reconnect resumes rather than restarts and nothing on the
+     * stream is missed by it.
+     *
+     * Already-nominated is a no-op that moves the tree to the front of the queue,
+     * and that ordering is what {@link MAX_WATCHES} costs: a fifth tree evicts the
+     * one nobody has asked about for longest. Evicting rather than refusing is
+     * deliberate — a model that has moved on to a different directory should not
+     * have to know that four earlier ones are in the way — but it is never
+     * SILENT, because a dropped watch is a tree that stops reporting. The caller
+     * is handed what went and says so.
+     *
+     * It says only what it EVICTED, and not whether it reopened anything. The
+     * caller has a sharper question than "did this change something" —
+     * {@link nominationLive}, which asks whether the open connection is carrying
+     * the tree — and the two differ in the case that matters: a nomination this
+     * call did not change can still be off the wire, because the connection
+     * carrying it dropped a moment ago.
+     */
+    nominate(path: string): {
+        evicted?: string;
+    };
+    /** Open the socket, if it is not already open. Returns at once. */
+    start(): void;
+    /** Close the socket and stop reconnecting. The buffer goes with it. */
+    close(reason?: string): void;
+    /**
+     * Everything the model has not been handed, oldest first.
+     *
+     * `since` is an override rather than the ordinary way in. A model that passes
+     * nothing gets what it has not seen, which is what "what happened while I was
+     * thinking" means and is the call that cannot be got wrong; a model that
+     * keeps a cursor can rewind or resume with one. Both are the same position in
+     * the end — this class holds it either way.
+     */
+    read(opts?: {
+        since?: string;
+        limit: number;
+        through?: number;
+    }): Delivery;
+    /**
+     * Where a read or a wait starts: the model's own place, or the cursor it named.
+     *
+     * A cursor this buffer cannot place is not an error and not silence. It may
+     * be from before the socket opened, from before a reap, or simply not one of
+     * ours; either way the events between there and here are not something this
+     * server holds, and saying so is the whole of the gap discipline — never a
+     * frame the model has to interpret, always a sentence and, from the tool, the
+     * state it would otherwise have gone to reconcile against.
+     */
+    resolveFrom(since?: string): number;
+    /**
+     * Wait for an event this predicate accepts, or for the deadline.
+     *
+     * Resolves with the matching event's index, or `undefined` for a wait that
+     * ended without one — a deadline, a caller who hung up, or a stream that
+     * stopped. None of those three is an error here and the caller says which.
+     */
+    waitFor(matches: (ev: ComputerEvent) => boolean, deadline: AbortSignal, cancel?: AbortSignal, since?: string, abandon?: () => boolean): Promise<number | undefined>;
+    /**
+     * Wait until this subscription has an opening frame, or has stopped.
+     *
+     * Separate from {@link waitFor} rather than expressed as a predicate over it,
+     * and the reason is worth keeping: `waitFor` evaluates its predicate against
+     * BUFFERED EVENTS, so a condition that is not about an event — "has hello
+     * landed" — is never evaluated at all on a computer where nothing is
+     * happening. Written that way it does not answer late, it answers at the
+     * deadline, on the one call where the deadline is twenty seconds.
+     */
+    attached(deadline: AbortSignal, cancel?: AbortSignal): Promise<void>;
+    /**
+     * Wait until the open connection is carrying this tree and has greeted.
+     *
+     * The counterpart to {@link attached} for a nomination, and separate for the
+     * reason the two of them are separate from {@link waitFor}: what is being
+     * waited for is not an event, so a predicate over the ring would never be
+     * evaluated on a computer where nothing is happening. `attached` cannot serve
+     * here either — it is satisfied the moment `#types` is set, which a
+     * nomination does not clear, so it would return at once and leave the caller
+     * reading the PREVIOUS connection's `watching`.
+     */
+    nominated(path: string, deadline: AbortSignal, cancel?: AbortSignal): Promise<void>;
+    /**
+     * Wait until this tree is actually being watched.
+     *
+     * The whole reason a file watch needs its own wait. `hello` accepting a
+     * nomination is not the tree being watched: the guest has to be asked, and on
+     * a computer nobody has opened a terminal on the host installs the watcher
+     * into the guest first — seconds, not milliseconds. inotify reports changes
+     * and not state, so nothing that happens in that window is ever reported.
+     * Returning before this is what makes a tool say "nothing changed" about a
+     * window during which nothing was watching, which is the one sentence a
+     * server whose whole promise is that it was listening must not say.
+     *
+     * Returns on the deadline, on a stopped stream, and on an `unwatchable` —
+     * which is the one `lost` that means the tree is not being watched at all,
+     * and so is not something more waiting will fix. The caller reads
+     * {@link isArmed} to find out which it got.
+     */
+    armedWait(path: string, deadline: AbortSignal, cancel?: AbortSignal): Promise<void>;
+}
+/**
+ * Every computer this session is listening to.
+ *
+ * One per session and not one per process, for the reason `Session` itself is:
+ * over the HTTP transport each caller arrives with their own key, and a
+ * process-wide hub would hold one caller's socket open for another caller's
+ * computer.
+ */
+export declare class EventHub {
+    #private;
+    constructor(api: Api, socketFor?: EventSocketFactory);
+    /** This computer's subscription, opened if this is the first ask. */
+    open(computerId: string): Subscription;
+    /**
+     * Drop one, so the next ask opens a fresh socket and a fresh buffer.
+     *
+     * `remember` is the difference between a stream this session may want to
+     * resume — reaped for idleness, stopped on a computer somebody suspended —
+     * and one there is nothing left to resume: a deleted computer's cursor names
+     * a position in a stream that no longer exists.
+     */
+    drop(computerId: string, reason: string, remember?: boolean): void;
+    /** Close every socket. The session is over, or the process is going away. */
+    closeAll(): void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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