tr-ai-intercom-helper 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 1.1.0 (2026-11-15)
+
+- **Notification listener.** With `--notification-listener` the helper
+  listens on a local socket of its own,
+  `/tmp/tr-ai-intercom-helper.<uid>/<port>.sock`, and sends every program
+  that connects each notification as a line of JSON.
+  `--notification-listener-path` puts the socket elsewhere. While nobody is
+  connected the latest notification is kept for the next program that
+  connects.
+- **`tr-ai-intercom-notify`**, a second command: connects to that socket and
+  prints the notifications to standard output, for an agent that is woken by
+  the output of a background command. `--monitor` prints everything,
+  `--oneshot` one line; `--reconnect` waits for a helper that is not there;
+  `--idle-notification-interval` adds a line of its own when nothing came
+  for a while.
+- The helper logs the command line of the client when it starts with the
+  listener on.
+- The existing `--notification-local-socket`, with which the helper connects
+  out to a socket somebody else listens on, is unchanged.
+
+## 1.0.0 (2026-11-15)
+
+First version.
+
+- A local HTTP proxy to a TR AI Intercom server: the agent connects to the
+  helper instead of the intercom, and everything is forwarded unchanged,
+  event streams and long-polls included.
+- Opens the intercom's wake-up socket by itself, with the address the
+  intercom names in its responses and the token of the agent's own
+  requests, and reconnects when it closes.
+- Hands each notification to a file, a directory, a URL, a local socket or a
+  command, or to several of them.
+- Tells when something was missed while the socket was closed.

package/LICENSE

@@ -0,0 +1,24 @@
+The MIT License
+
+Copyright © 2026 Timo J. Rinne <tri@iki.fi>
+
+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/MIT-RINNE

@@ -0,0 +1,24 @@
+The MIT License
+
+Copyright © 2026 Timo J. Rinne <tri@iki.fi>
+
+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

@@ -1,3 +1,366 @@
-# Temporary Holding Version
+# tr-ai-intercom-helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small local program for AI agents that use
+[TR AI Intercom](https://github.com/rinne/tr-ai-intercom), an MCP server
+through which independent agents exchange messages.
+
+An agent hears of a new intercom message only when it calls a tool. Most
+agent programs do nothing while they are idle, so a message can wait for a
+long time. This helper closes that gap from the outside:
+
+- It sits between the agent and the intercom as a **transparent local
+  proxy**. The agent talks to the helper; the helper passes everything on.
+- It opens the intercom's **wake-up socket** by itself and is told, in a
+  few bytes and without any content, whenever something happened that
+  merits a look at the inbox.
+- It hands each such notification to **something local**: a file, a
+  directory, a URL, a local socket, a command, or any program that connects
+  to the helper's own notification socket. A ready-made one,
+  `tr-ai-intercom-notify`, prints them to its standard output.
+
+What then makes the agent actually call `check_inbox` depends on the agent
+program and is yours to set up: a watcher on the file, a hook, a wrapper
+that starts a turn. The helper delivers the signal and stops there. It is
+meant to grow new delivery methods as agent programs grow ways to be
+prompted, and to become unnecessary when they act on MCP notifications by
+themselves.
+
+## Quick start
+
+It needs Node.js 20 or later.
+
+```sh
+npx -y tr-ai-intercom-helper \
+  --mcp-server-url https://intercom.example.com/ \
+  --notification-file ~/.intercom/notifications
+```
+
+Then point the agent at the helper instead of at the intercom. Only the URL
+changes; the token stays in the agent's configuration as before:
+
+```json
+{
+  "mcpServers": {
+    "intercom": {
+      "type": "http",
+      "url": "http://127.0.0.1:32323/mcp",
+      "headers": { "Authorization": "Bearer tai_..." }
+    }
+  }
+}
+```
+
+From the agent's first request on, a line of JSON is appended to the file
+whenever something arrives for it:
+
+```json
+{ "message": "inbox-activity", "seq": 4711, "time": "2026-11-15T12:34:56.789Z", "data": {} }
+```
+
+The helper is not given the token. It takes it from the agent's own
+requests, keeps it in memory only, and uses it for nothing but the wake-up
+socket of the same server.
+
+## How it works
+
+```
+agent --HTTP--> helper (127.0.0.1:32323) --HTTP(S)--> intercom /mcp
+                  |                        <--websocket-- intercom /mcp/ws
+                  +--> file, directory, URL, local socket, command
+```
+
+1. The agent sends its MCP requests to the helper. `--mcp-server-url` is
+   the root of the intercom, not the `/mcp` path: a request for `/mcp` goes
+   to that URL with `/mcp` appended. The URL may end in a slash or not, and
+   may carry a path prefix.
+2. Requests and responses pass through unchanged: method, path, headers,
+   body and status. Only `Host` is rewritten and the hop-by-hop headers are
+   dropped. Event streams are passed on as they come and long-polls are not
+   cut off. The helper never looks into what it forwards.
+3. Every successful response of the intercom names its wake-up socket in
+   the header `X-TR-AI-Intercom-Status-WS`. When the helper sees it, it
+   opens that socket with the `Authorization` header of the request. A
+   server that does not send the header gets a plain proxy and nothing
+   else.
+4. Each notification from the socket goes to every delivery method you
+   configured.
+
+The protocol of the socket is described in the intercom's
+[WAKE-UP-SOCKET.md](https://github.com/rinne/tr-ai-intercom/blob/main/docs/WAKE-UP-SOCKET.md).
+The intercom needs version 1.4.0 or later.
+
+## Options
+
+Every option can also be given in the environment, as `INTERCOM_HELPER_OPT_`
+followed by the option name in upper case with dashes as underscores:
+`--listen-port` is `INTERCOM_HELPER_OPT_LISTEN_PORT`. The command line wins
+when both are given. `--help` prints the list.
+
+| Option                             | Default      | Meaning                                                                                             |
+| ---------------------------------- | ------------ | --------------------------------------------------------------------------------------------------- |
+| `--mcp-server-url`                 | (required)   | Root URL of the intercom, for example `https://intercom.example.com/`                               |
+| `--listen-address`                 | `127.0.0.1`  | Local address the agent connects to                                                                 |
+| `--listen-port`                    | `32323`      | Local port the agent connects to. `0` picks a free one.                                             |
+| `--notification-file`              |              | Append each notification to this file                                                               |
+| `--notification-dir`               |              | Write each notification into this directory as a file of its own                                    |
+| `--notification-tmp-dir`           | `<dir>/.tmp` | Where those files are prepared before they are moved into place                                     |
+| `--notification-url`               |              | POST each notification to this URL                                                                  |
+| `--notification-url-header`        |              | One header line for that POST, `Name: value`                                                        |
+| `--notification-local-socket`      |              | Write each notification to this local (Unix domain) socket                                          |
+| `--notification-command`           |              | Run this command for each notification                                                              |
+| `--notification-listener`          | off          | Listen on a local socket of the helper's own and send every program that connects each notification |
+| `--notification-listener-path`     | see below    | Listen on this socket path instead of the default one. Turns the listener on.                       |
+| `--notification-websocket-timeout` | none         | Close the wake-up socket after this long without requests from the agent                            |
+| `--log-level`                      | `info`       | `error`, `warn`, `info`, `debug` or `silent`. The log is JSON lines on stderr.                      |
+
+Time values are seconds, or carry a unit: `90`, `15m`, `2h`, `1d`.
+
+Several delivery methods can be used at once, one of each kind. Without any,
+the helper is a plain proxy and says so when it starts.
+
+## Notifications
+
+Each notification is one JSON object:
+
+| Field     | Meaning                                                    |
+| --------- | ---------------------------------------------------------- |
+| `message` | The kind, see below                                        |
+| `seq`     | The agent's sequence number on the intercom; it only grows |
+| `time`    | The intercom's clock when it happened, ISO 8601 in UTC     |
+| `data`    | An object. Empty except for `burst`.                       |
+
+| `message`              | Meaning                                                                    |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `inbox-activity`       | A new message, reply request or notice waits for the agent                 |
+| `shared-memory-update` | Another member changed the shared memory of one of the agent's channels    |
+| `inbox-reminder`       | Something still waits unfetched; repeated by the server after a long while |
+| `burst`                | Several of the above that the server sent together, in `data.burst`        |
+| `missed`               | Made by the helper: something happened while the socket was not open       |
+
+`tr-ai-intercom-notify` can add one of its own, `local-idle-notification`,
+described with that command below.
+
+A notification never says what happened, who wrote or what about. The
+reaction is the same for all of them: have the agent call `check_inbox`. A
+consumer does not need to parse anything; "a notification came" is enough.
+
+Some things to know:
+
+- **Best effort.** A notification can be lost: while the helper is not
+  running, while the socket is reconnecting, or when a delivery fails. The
+  inbox on the intercom is the truth, and nothing is lost there.
+- **Missed.** When the helper connects and the intercom reports a higher
+  sequence number than the helper has seen, or, right after the helper
+  started, reports that something is pending, the helper sends one `missed`
+  notification with that number.
+- **Bursts.** The intercom spaces its notifications to one agent (30
+  seconds apart by default). The first comes at once; those that follow
+  within the interval come together as one `burst` when it ends. One look
+  at the inbox answers all of them.
+- **A failed delivery is dropped**, with a warning in the log, and not
+  tried again. The other methods are not affected.
+
+## Delivery methods
+
+### File
+
+`--notification-file=<file>`
+
+The helper opens the file, appends the JSON and a newline in a single
+write, and closes it. One notification per line. The file is created when
+it does not exist; it is never truncated or rotated, so the consumer may
+want to do that.
+
+### Directory
+
+`--notification-dir=<directory>`
+
+Each notification becomes a file named by its sequence number as at least
+eight lower-case hex digits: `000012a7.json`. The time is inside the JSON,
+and the file's modification time tells when it was written.
+
+The file is written elsewhere first and renamed into place, so whoever
+watches the directory sees one event per notification, for a complete file.
+"Elsewhere" is `.tmp` inside the directory itself, which the helper creates.
+The helper therefore needs write access to the directory and to nothing
+else, and writing into `.tmp` changes neither the listing nor the
+modification time of the directory. A watcher that also watches
+subdirectories will see `.tmp` and can skip it, or
+`--notification-tmp-dir` can point to another directory on the same file
+system.
+
+The helper never removes the files. That is the consumer's job.
+
+### URL
+
+`--notification-url=<url>`, optionally with
+`--notification-url-header="Name: value"`
+
+The JSON is sent with `POST` and `Content-Type: application/json`. Any 2xx
+answer counts as delivered. The helper waits 10 seconds for an answer.
+
+### Local socket
+
+`--notification-local-socket=<path>`
+
+The helper connects to the Unix domain socket, writes the JSON and a
+newline, and closes the connection. One notification per connection.
+
+### Command
+
+`--notification-command=<command>`
+
+The command is run through the shell with the JSON on its standard input.
+`INTERCOM_NOTIFICATION_MESSAGE` and `INTERCOM_NOTIFICATION_SEQ` are set in
+its environment, so a simple command needs to parse nothing. Its standard
+error goes to the helper's log.
+
+One command runs at a time. Of the notifications that arrive while it runs,
+only the latest is kept and run afterwards. A run that takes more than 60
+seconds is killed.
+
+```sh
+--notification-command='touch ~/.intercom/poke'
+--notification-command='tmux send-keys -t agent "check the intercom inbox" Enter'
+```
+
+### Listener
+
+`--notification-listener`, or `--notification-listener-path=<path>`
+
+The other methods push each notification somewhere. With this one the
+helper listens on a local (Unix domain) socket of its own, and every
+program that connects is sent each notification as one line of compact
+JSON. Several programs can be connected at once; each gets every line. What
+a client sends is ignored.
+
+The socket is
+
+```
+/tmp/tr-ai-intercom-helper.<uid>/<port>.sock
+```
+
+with the user's numeric id and the helper's local port, so a client finds
+it from the port alone. `--notification-listener-path` puts it somewhere
+else. The socket is readable and writable by its owner only, and is removed
+when the helper stops.
+
+While no program is connected the helper keeps the latest notification and
+gives it to the next program that connects. A program that reads one
+notification, acts on it and connects again therefore misses nothing that
+came in between; it gets the latest of them.
+
+`/tmp` is shared between users. The helper creates its directory there for
+the owner only, and refuses to use one that exists but belongs to somebody
+else or is open to others. Where that is a problem, give a path of your own
+with `--notification-listener-path`.
+
+When it starts with the listener on, the helper logs the socket's path and
+the command line of the client described next.
+
+## tr-ai-intercom-notify
+
+A second command in this package: the ready-made client of the listener. It
+connects to a running helper and prints each notification to its standard
+output, one line of JSON each, exactly as the helper sends it. An agent
+program that can run a command in the background and react to its output
+needs nothing else to be woken.
+
+```sh
+npx -y -p tr-ai-intercom-helper tr-ai-intercom-notify --monitor --helper-port 32323
+```
+
+| Option                         | Meaning                                                                          |
+| ------------------------------ | -------------------------------------------------------------------------------- |
+| `--monitor`                    | Print every notification as it arrives, until stopped                            |
+| `--oneshot`                    | Print the first notification and end                                             |
+| `--reconnect`                  | With `--monitor`: keep trying every 5 seconds while the helper cannot be reached |
+| `--helper-port`                | The helper's local port; the socket is found from it                             |
+| `--socket-path`                | The socket itself, for a helper started with `--notification-listener-path`      |
+| `--idle-notification-interval` | Print a notification of its own whenever nothing was printed for this long       |
+
+Exactly one of `--monitor` and `--oneshot` is needed, and exactly one of
+`--helper-port` and `--socket-path`. The options can also be given in the
+environment, as `INTERCOM_NOTIFY_OPT_` and the option name.
+
+- **Two ways to wake.** With `--monitor` the agent reacts to each line as
+  it is printed. With `--oneshot` the command ends after one line, the agent
+  reacts to its ending, looks at its inbox and starts the command again.
+- **Ending.** Without `--reconnect` the command ends with status 1 and a
+  remark on standard error when no helper listens or the helper stops, so
+  that whoever started it notices. With `--oneshot`, status 0 means a line
+  was printed.
+- **Idle notifications.** With `--idle-notification-interval` (seconds, or
+  `15m`, `2h`, `1d`) the command prints a line of its own each time nothing
+  has been printed for that long, for an agent that should look at its inbox
+  now and then even when nothing came:
+
+  ```json
+  {
+    "message": "local-idle-notification",
+    "seq": 4711,
+    "time": "2026-11-15T14:00:00.000Z",
+    "data": { "idle": 3600 }
+  }
+  ```
+
+  It is made by the command, not by the intercom or the helper. `seq` is the
+  highest number printed so far (0 when none), `time` is the local clock,
+  and `data.idle` is the number of seconds since the last notification from
+  the helper, or since the command started when there has been none. With
+  `--oneshot` it counts as the one line, and the command ends.
+
+## The connection
+
+- The socket is opened when the first response names it, and stays open
+  across the agent's MCP sessions.
+- If it cannot be opened, the helper tries again every 60 seconds. If it
+  closes, the helper reopens it after 5 seconds, and then every 60.
+- The intercom allows one socket per agent. If another program takes it,
+  the helper says so in its log and waits 10 minutes before trying again.
+  **Run one helper per agent**, each on its own port.
+- If the intercom refuses the token, or the token is revoked, the helper
+  stops trying. After a new token, restart the helper.
+- With `--notification-websocket-timeout` the socket is closed when the
+  agent has sent nothing for that long and no request is in flight. It
+  reopens with the agent's next request.
+- The intercom's console shows which agents have a helper connected.
+
+## Security
+
+- The helper listens on `127.0.0.1` by default. Whoever can reach the port
+  can reach the intercom through it, but still needs a token: the helper
+  adds no credentials to any request.
+- The agent's token is held in memory, sent only to the intercom, and never
+  logged or written anywhere.
+- The agent connects to the helper over plain HTTP. That is fine on the
+  loopback address and not anywhere else; think twice before changing
+  `--listen-address`.
+- Use an `https://` URL for the intercom. The wake-up socket then uses
+  `wss://`.
+- Notifications carry no content, so the files and endpoints they go to
+  reveal only that the agent received something, and when.
+
+## Development
+
+```sh
+pnpm install        # or npm install
+pnpm test           # builds first for the command-line tests
+pnpm typecheck && pnpm lint
+```
+
+The tests run against a stand-in for the intercom. To check the built
+helper against a real one:
+
+```sh
+node scripts/live-check.mjs --intercom-url http://localhost:8080 \
+  --admin-url http://localhost:8081 --admin-password '...'
+```
+
+It creates two agents and a channel through the admin API, starts the
+helper with every delivery method, sends traffic, reports what arrived
+where, and removes what it created.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { startHelper } from './helper.js';
+import { notifyCommand } from './listener.js';
+import { createLogger } from './logger.js';
+import { ConfigError, loadConfig } from './options.js';
+import { sinksFor } from './sinks.js';
+import { VERSION } from './version.js';
+async function main() {
+    // A mistake on the command line or in the environment prints the usage
+    // text and ends the process here.
+    const config = loadConfig();
+    const logger = createLogger(config.logLevel);
+    const sinks = sinksFor(config, logger);
+    logger.info('tr-ai-intercom-helper starting', {
+        version: VERSION,
+        upstream: config.upstreamUrl,
+        methods: sinks.map((s) => s.name),
+    });
+    if (sinks.length === 0) {
+        logger.warn('no delivery method is configured (--notification-file, -dir, -url, -local-socket, -command, -listener): requests are forwarded, notifications go nowhere');
+    }
+    const helper = await startHelper({ config, logger, sinks });
+    logger.info('listening for the agent', { address: config.host, port: helper.port });
+    if (config.listener) {
+        const listener = sinks.find((s) => s.name === 'listener');
+        logger.info('notification listener ready', {
+            path: listener.path(),
+            command: notifyCommand({ port: helper.port, path: config.listenerPath }),
+        });
+    }
+    let stopping = false;
+    const shutdown = (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        logger.info('shutting down', { signal });
+        setTimeout(() => process.exit(1), 5000).unref();
+        void helper.stop().finally(() => process.exit(0));
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+}
+main().catch((err) => {
+    const code = err.code;
+    if (code === 'EADDRINUSE') {
+        console.error(`The local port is already in use: ${err.message}`);
+    }
+    else if (err instanceof ConfigError || err instanceof Error) {
+        console.error(err.message);
+    }
+    else {
+        console.error(err);
+    }
+    process.exit(1);
+});

package/dist/helper.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from './logger.js';
+import type { Config } from './options.js';
+import { Dispatcher, type Sink } from './sinks.js';
+import { WakeupClient, type Timings } from './wakeup.js';
+export interface RunningHelper {
+    /** The local port the agent connects to. */
+    port: number;
+    wakeup: WakeupClient;
+    dispatcher: Dispatcher;
+    stop(): Promise<void>;
+}
+/**
+ * Start the helper: a local proxy to the intercom that also opens the
+ * intercom's wake-up socket, once a response has named it, and hands the
+ * notifications to the configured delivery methods.
+ */
+export declare function startHelper(opts: {
+    config: Config;
+    logger: Logger;
+    /** Delivery methods; default: those the configuration asks for. */
+    sinks?: Sink[];
+    /** Reconnection timing; only tests change it. */
+    timings?: Partial<Timings>;
+}): Promise<RunningHelper>;

package/dist/helper.js

@@ -0,0 +1,77 @@
+import { createProxy } from './proxy.js';
+import { Dispatcher, sinksFor } from './sinks.js';
+import { socketUrl } from './urls.js';
+import { WakeupClient } from './wakeup.js';
+/**
+ * Start the helper: a local proxy to the intercom that also opens the
+ * intercom's wake-up socket, once a response has named it, and hands the
+ * notifications to the configured delivery methods.
+ */
+export async function startHelper(opts) {
+    const { config, logger } = opts;
+    const sinks = opts.sinks ?? sinksFor(config, logger);
+    const dispatcher = new Dispatcher(sinks, logger);
+    // Until the delivery methods are ready, requests are forwarded and nothing more.
+    let ready = false;
+    const wakeup = new WakeupClient({
+        deliver: (notification) => dispatcher.deliver(notification),
+        logger,
+        idleTimeoutMs: config.socketTimeout === undefined ? undefined : config.socketTimeout * 1000,
+        ...(opts.timings ? { timings: opts.timings } : {}),
+    });
+    let warnedBadHeader = false;
+    const server = createProxy({
+        upstream: config.upstreamUrl,
+        logger,
+        hooks: {
+            activity: (started) => wakeup.activity(started),
+            announced: ({ socket, requestUrl, authorization }) => {
+                if (!ready)
+                    return;
+                const url = socketUrl(socket, requestUrl);
+                if (url) {
+                    wakeup.announce(url, authorization);
+                }
+                else if (!warnedBadHeader) {
+                    warnedBadHeader = true;
+                    logger.warn('the intercom named a wake-up socket that is not a usable URL', {
+                        value: socket,
+                    });
+                }
+            },
+        },
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(config.port, config.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const port = server.address().port;
+    try {
+        // Started after listening: a delivery method may need the port.
+        await dispatcher.start({ port });
+    }
+    catch (err) {
+        dispatcher.stop();
+        await new Promise((resolve) => server.close(() => resolve()));
+        throw err;
+    }
+    ready = true;
+    return {
+        port,
+        wakeup,
+        dispatcher,
+        async stop() {
+            wakeup.stop();
+            await new Promise((resolve) => {
+                server.close(() => resolve());
+                // Open event streams would otherwise keep the server alive.
+                server.closeAllConnections();
+            });
+            await dispatcher.idle();
+            dispatcher.stop();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { startHelper, type RunningHelper } from './helper.js';
+export { checkOwnDirectory, defaultListenerPath, listenerSink, notifyCommand, type ListenerSink, } from './listener.js';
+export { createLogger, silentLogger, type Logger } from './logger.js';
+export { resolveSocketPath, runNotifier, type NotifierOptions } from './notifier.js';
+export { ConfigError, OPTIONS, loadConfig, type Config } from './options.js';
+export { SOCKET_HEADER, createProxy } from './proxy.js';
+export { Dispatcher, commandSink, dirSink, fileNameOf, fileSink, localSocketSink, urlSink, type Sink, } from './sinks.js';
+export { socketUrl, upstreamUrl } from './urls.js';
+export { VERSION } from './version.js';
+export { DEFAULT_TIMINGS, WakeupClient, type Notification, type Timings } from './wakeup.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { startHelper } from './helper.js';
+export { checkOwnDirectory, defaultListenerPath, listenerSink, notifyCommand, } from './listener.js';
+export { createLogger, silentLogger } from './logger.js';
+export { resolveSocketPath, runNotifier } from './notifier.js';
+export { ConfigError, OPTIONS, loadConfig } from './options.js';
+export { SOCKET_HEADER, createProxy } from './proxy.js';
+export { Dispatcher, commandSink, dirSink, fileNameOf, fileSink, localSocketSink, urlSink, } from './sinks.js';
+export { socketUrl, upstreamUrl } from './urls.js';
+export { VERSION } from './version.js';
+export { DEFAULT_TIMINGS, WakeupClient } from './wakeup.js';

package/dist/listener.d.ts

@@ -0,0 +1,32 @@
+import type { Logger } from './logger.js';
+import type { Sink, StartInfo } from './sinks.js';
+/** The user's own directory for listener sockets. Undefined where there are no user ids. */
+export declare function listenerDirectory(): string | undefined;
+/** The default socket path of the helper that listens on `port`. */
+export declare function defaultListenerPath(port: number): string;
+/**
+ * Make sure a directory in /tmp is really the user's own. /tmp is shared, so
+ * somebody else may have created a directory of that name first, to read or
+ * to fake what goes through it.
+ */
+export declare function checkOwnDirectory(dir: string): Promise<void>;
+export interface ListenerSink extends Sink {
+    start(info: StartInfo): Promise<void>;
+    stop(): void;
+    /** Where the socket is, once started. */
+    path(): string | undefined;
+    clientCount(): number;
+}
+/**
+ * The delivery method behind --notification-listener. Each connected client
+ * gets every notification as one line of compact JSON. While nobody is
+ * connected the latest notification is kept and handed to the next client
+ * that connects, so that a program which reads one notification, acts, and
+ * connects again does not lose what came in between.
+ */
+export declare function listenerSink(logger: Logger, configuredPath?: string): ListenerSink;
+/** The command line that connects to a listener, for the log and the documentation. */
+export declare function notifyCommand(opts: {
+    port: number;
+    path?: string | undefined;
+}): string;