@moxxy/plugin-channel-web 0.27.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+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/dist/channel.d.ts

@@ -0,0 +1,152 @@
+import type { Channel, ChannelHandle, ChannelStartOptsBase, ClientSession, PermissionResolver, TunnelProviderDef } from '@moxxy/sdk';
+/** Injectable seams so the kill path can be unit-tested without real processes. */
+export interface FreePortDeps {
+    pidsListeningOn(port: number): Promise<ReadonlyArray<number>>;
+    pidCommand(pid: number): Promise<string>;
+    kill(pid: number, signal: number | NodeJS.Signals): void;
+    /** Grace delay between SIGTERM and the SIGKILL sweep. */
+    graceMs?: number;
+}
+/**
+ * Free a TCP port ONLY if every process holding it is a moxxy process
+ * (stale `moxxy serve` leftovers — legitimate self-healing). Returns true
+ * when a kill was attempted. Anything else holding the port (the default,
+ * 4040, is also ngrok's local-UI port!) is left alone — the caller falls
+ * back to an ephemeral port instead. SIGTERM → grace → SIGKILL.
+ */
+export declare function freeTcpPortIfMoxxy(port: number, logger: WebChannelOptions['logger'], deps?: FreePortDeps): Promise<boolean>;
+/** The path the tunnel exposes us under (e.g. `/web`), or `''` for the root. */
+export declare function basePathFromUrl(url: string): string;
+/** Inject the base path into index.html so relative assets (`app.js`) resolve
+ *  under it and the client builds the right WS URL — works at root or `/web`. */
+export declare function injectBaseHtml(html: string, basePath: string): string;
+export interface WebChannelOptions {
+    readonly port?: number;
+    readonly host?: string;
+    /** Token gating every request + the WS handshake. Generated if unset. */
+    readonly authToken?: string;
+    /** Tools the model may call without a human prompt (no clicker in this loop). */
+    readonly allowedTools?: ReadonlyArray<string>;
+    /** Resolve the session's active tunnel provider (injected by the CLI builder). */
+    readonly getTunnel?: () => TunnelProviderDef | null;
+    /**
+     * Publish/clear the live surface so `present_view` can return the public URL
+     * the agent relays to the user. Called with the surface on start, null on stop.
+     */
+    readonly publishSurface?: (surface: {
+        url: string;
+        nextViewId: () => string;
+    } | null) => void;
+    /**
+     * Publish/clear live controls so the agent's `web_set_tunnel` tool can switch
+     * the tunnel without a restart. `retunnel` closes the current tunnel (no leak)
+     * and re-opens via the now-active provider, returning the new share URL.
+     */
+    readonly publishControls?: (controls: WebSurfaceControls | null) => void;
+    readonly logger?: {
+        info?(msg: string, meta?: Record<string, unknown>): void;
+        warn?(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+export interface WebSurfaceControls {
+    retunnel(): Promise<string | null>;
+}
+export interface WebStartOpts extends ChannelStartOptsBase {
+    readonly session: ClientSession;
+}
+export declare class WebChannel implements Channel<WebStartOpts> {
+    readonly name = "web";
+    readonly permissionResolver: PermissionResolver;
+    private port;
+    private readonly host;
+    private readonly token;
+    private readonly logger;
+    private readonly getTunnel;
+    private readonly publishSurface;
+    private readonly publishControls;
+    private server;
+    private wss;
+    private readonly clients;
+    /**
+     * Built screens replayed to a newly-connected browser, keyed by logical
+     * `name`. UNNAMED views all share {@link UNNAMED_VIEW_KEY} (latest wins), so
+     * an agent that presents many unnamed views over a long session can't leak
+     * one ViewDoc per render. Named views LRU-evict at {@link MAX_REPLAY_VIEWS}.
+     */
+    private readonly views;
+    private unsubscribe;
+    private session;
+    private busy;
+    private controller;
+    private tunnel;
+    private tunnelBase;
+    /** Public path the surface is served under (e.g. `/web` behind the relay; `''` local). */
+    private basePath;
+    private viewSeq;
+    private droppedFrames;
+    private lastDropWarnAt;
+    constructor(opts?: WebChannelOptions);
+    /** The local URL (token embedded). */
+    get url(): string;
+    /** The URL to hand the user — the tunnel base if open, else local. */
+    get shareUrl(): string;
+    start(startOpts: WebStartOpts): Promise<ChannelHandle>;
+    /**
+     * Bind the HTTP server, with recovery if the port is already in use.
+     * A stale `moxxy serve` from a prior install often leaves 4040 bound
+     * even after its unix socket has been released — if (and only if) the
+     * holder is verifiably a moxxy process we kill it and retry. Anything
+     * else (ngrok's local UI also defaults to 4040) is never signalled;
+     * we bind an ephemeral port instead and log loudly which port the
+     * surface actually got (the share URL embeds the real port either way).
+     */
+    private bindServerWithRetry;
+    /**
+     * (Re-)open the tunnel via the active provider, closing any prior one FIRST so
+     * a switch never leaks a subprocess. Non-fatal: on failure (e.g. the relay
+     * not installed) we fall back to the local URL.
+     */
+    private openTunnel;
+    /** Switch tunnels live (agent's web_set_tunnel) and republish the surface URL. */
+    private retunnel;
+    private stop;
+    private validToken;
+    /** Strip the public base path (if any) so internal routing stays root-relative.
+     *  Tolerant: handles both `/web/app.js` (relay didn't strip) and `/app.js`
+     *  (relay stripped the first request line). */
+    private stripBase;
+    private handleHttp;
+    /**
+     * Defense-in-depth headers for the internet-exposed surface (served over
+     * public tunnels). CSP contains any future renderer regression: scripts may
+     * only load from this origin (`'self'`) — no inline scripts — while the inline
+     * `<style>` block needs `style-src 'unsafe-inline'`; `connect-src` permits the
+     * same-origin WebSocket. `frame-ancestors 'none'` + `X-Frame-Options: DENY`
+     * stop the tokenized page from being framed (clickjacking); `Referrer-Policy:
+     * no-referrer` keeps the `?t` token out of the Referer header on agent-authored
+     * outbound links.
+     */
+    private securityHeaders;
+    private serveFile;
+    /**
+     * Record a view frame for replay with a bounded footprint. Named views key
+     * by their name (re-render replaces in place) under an LRU bounded at
+     * {@link MAX_REPLAY_VIEWS}; unnamed views all collapse into a single
+     * latest-wins slot so an unbounded stream of unnamed renders can't leak.
+     */
+    private rememberView;
+    private onConnection;
+    /**
+     * Handle a browser → server frame. This is a trust boundary (tunnels put
+     * it on the public internet): every frame is schema-validated before any
+     * field access, and invalid ones are dropped — a thrown error in a ws
+     * 'message' listener escalates to a process-level uncaughtException.
+     */
+    private onMessage;
+    /** Count a dropped inbound frame; warn at most once per window (no log spam). */
+    private dropFrame;
+    private drive;
+    private broadcast;
+    private send;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAElB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAuEpB,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACzD,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EACnC,IAAI,GAAE,YAA+B,GACpC,OAAO,CAAC,OAAO,CAAC,CAoDlB;AAKD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;iFACiF;AACjF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,MAAM,CAAA;KAAE,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9F;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,CAAC;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC1D,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAa,SAAQ,oBAAoB;IACxD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED,qBAAa,UAAW,YAAW,OAAO,CAAC,YAAY,CAAC;IACtD,QAAQ,CAAC,IAAI,SAAS;IACtB,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAChD,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsC;IACrE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuC;IACvE,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,UAAU,CAAuB;IACzC,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;gBAEf,IAAI,GAAE,iBAAsB;IAoBxC,sCAAsC;IACtC,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,sEAAsE;IACtE,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAEK,KAAK,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAoD5D;;;;;;;;OAQG;YACW,mBAAmB;IAmDjC;;;;OAIG;YACW,UAAU;IAyBxB,kFAAkF;YACpE,QAAQ;YAMR,IAAI;IA4BlB,OAAO,CAAC,UAAU;IAWlB;;mDAE+C;IAC/C,OAAO,CAAC,SAAS;YASH,UAAU;IAwBxB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;YAYT,SAAS;IAiBvB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,YAAY;IAUpB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAiCjB,iFAAiF;IACjF,OAAO,CAAC,SAAS;YAWH,KAAK;IAkBnB,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,IAAI;CAOb"}