mtech-ai-local-runner 0.1.47 → 0.1.49

package/dist/src/transport/reverb-socket.js

@@ -0,0 +1,144 @@
+import WebSocket from "ws";
+import { decodeFrame, pingFrame, pongFrame, subscribeFrame } from "./pusher-protocol.js";
+const CONNECT_TIMEOUT_MS = 10_000;
+const SUBSCRIBE_TIMEOUT_MS = 10_000;
+/** How long close() waits for the server's close frame before dropping the connection. */
+const CLOSE_GRACE_MS = 1_000;
+const PONG_TIMEOUT_MS = 10_000;
+const MAX_PING_INTERVAL_MS = 30_000;
+/*
+ * ws sends no User-Agent of its own, and the ELSA load balancer's WAF (AWS managed common rules) answers a request
+ * without one with 403 before Reverb sees it. Measured against the development Reverb on 2026-10-24.
+ */
+export function pushSocketOptions(packageVersion, connectTimeoutMs) {
+    return { handshakeTimeout: connectTimeoutMs, headers: { "User-Agent": `mtec-ai-local-runner/${packageVersion}` } };
+}
+export function pushSocketUrl(target, packageVersion) {
+    const url = new URL(target.url);
+    if (url.protocol !== "wss:")
+        throw new Error("PUSH_URL_NOT_WSS");
+    url.pathname = `/app/${encodeURIComponent(target.appKey)}`;
+    url.search = new URLSearchParams({ protocol: "7", client: "mtec-ai-local-runner", version: packageVersion, flash: "false" }).toString();
+    return url.toString();
+}
+export class ReverbSocket {
+    target;
+    events;
+    options;
+    socket;
+    ended = false;
+    ownerClosed = false;
+    pingIntervalMs;
+    connectTimer;
+    subscribeTimer;
+    pingTimer;
+    pongTimer;
+    constructor(target, events, options) {
+        this.target = target;
+        this.events = events;
+        this.options = options;
+        this.pingIntervalMs = options.maxPingIntervalMs ?? MAX_PING_INTERVAL_MS;
+        const connectTimeoutMs = options.connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
+        const url = pushSocketUrl(target, options.packageVersion);
+        const create = options.createSocket ?? ((value) => new WebSocket(value, pushSocketOptions(options.packageVersion, connectTimeoutMs)));
+        this.socket = create(url);
+        this.connectTimer = setTimeout(() => this.fail("connect_timeout"), connectTimeoutMs);
+        this.socket.on("message", data => this.onMessage(String(data)));
+        this.socket.on("close", () => this.fail("closed"));
+        this.socket.on("error", () => this.fail("error"));
+    }
+    subscribe(auth) {
+        if (this.ended)
+            return;
+        clearTimeout(this.subscribeTimer);
+        this.subscribeTimer = setTimeout(() => this.fail("subscribe_timeout"), this.options.subscribeTimeoutMs ?? SUBSCRIBE_TIMEOUT_MS);
+        this.send(subscribeFrame(this.target.channel, auth));
+    }
+    close() {
+        if (this.ended)
+            return;
+        this.ownerClosed = true;
+        this.end();
+        try {
+            this.socket.close();
+        }
+        catch { /* Closing a socket that is already gone is fine. */ }
+        // ws waits up to 30 s for the server's close frame, which would hold a stopping daemon open.
+        const drop = setTimeout(() => { try {
+            this.socket.terminate();
+        }
+        catch { /* Already gone. */ } }, CLOSE_GRACE_MS);
+        drop.unref?.();
+    }
+    onMessage(raw) {
+        if (this.ended)
+            return;
+        this.armPing();
+        const frame = decodeFrame(raw, { channel: this.target.channel, event: this.target.event });
+        switch (frame.kind) {
+            case "connected":
+                clearTimeout(this.connectTimer);
+                this.pingIntervalMs = Math.min(frame.activityTimeoutSeconds * 1000, this.options.maxPingIntervalMs ?? MAX_PING_INTERVAL_MS);
+                this.armPing();
+                this.events.onConnected(frame.socketId);
+                break;
+            case "subscribed":
+                clearTimeout(this.subscribeTimer);
+                this.events.onSubscribed();
+                break;
+            case "signal":
+                this.events.onSignal();
+                break;
+            case "ping":
+                this.send(pongFrame());
+                break;
+            case "error":
+                // The Pusher close code decides how soon the transport reconnects (4000-4099: not unchanged).
+                this.fail(frame.code !== undefined && Number.isInteger(frame.code) && frame.code >= 4000 && frame.code <= 4299 ? `protocol_error_${frame.code}` : "protocol_error");
+                break;
+            default:
+                break;
+        }
+    }
+    armPing() {
+        clearTimeout(this.pongTimer);
+        this.pongTimer = undefined;
+        clearTimeout(this.pingTimer);
+        if (this.ended)
+            return;
+        this.pingTimer = setTimeout(() => {
+            this.send(pingFrame());
+            if (this.ended)
+                return;
+            this.pongTimer = setTimeout(() => this.fail("pong_timeout"), this.options.pongTimeoutMs ?? PONG_TIMEOUT_MS);
+        }, this.pingIntervalMs);
+    }
+    send(frame) {
+        if (this.ended)
+            return;
+        try {
+            this.socket.send(frame);
+        }
+        catch {
+            this.fail("send_failed");
+        }
+    }
+    fail(reason) {
+        if (this.ended)
+            return;
+        this.end();
+        try {
+            this.socket.terminate();
+        }
+        catch { /* The socket may already be gone. */ }
+        if (!this.ownerClosed)
+            this.events.onClosed(reason);
+    }
+    end() {
+        this.ended = true;
+        clearTimeout(this.connectTimer);
+        clearTimeout(this.subscribeTimer);
+        clearTimeout(this.pingTimer);
+        clearTimeout(this.pongTimer);
+    }
+}

package/dist/src/transport/runner-transport.js

@@ -0,0 +1,265 @@
+const MAX_BACKOFF_MS = 30_000;
+/** A subscription must last this long before a later loss starts the reconnect backoff from 1 s again. */
+const STABLE_SUBSCRIPTION_MS = 60_000;
+/**
+ * Pusher closes 4000-4099 mean "do not reconnect unchanged" (for example 4001 unknown app, 4009 unauthorized).
+ * The runner keeps its fallback syncs and tries the socket again only this much later, or when the push target changes.
+ */
+const REJECTED_RECONNECT_MS = 600_000;
+const REJECTED_REASON = /^protocol_error_40\d\d$/;
+/** The caught error's own failure code (such as GATEWAY_HTTP_503), never its message. */
+function causeOf(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : undefined;
+}
+export class RunnerTransport {
+    deps;
+    controller = new AbortController();
+    current = "starting";
+    socket;
+    target;
+    syncSeconds = 30;
+    fallbackSeconds = 8;
+    /** Set by run(). A request before it is dropped: run() syncs first, and only after the first heartbeat. */
+    started = false;
+    inFlight = false;
+    dirty = false;
+    lastSyncAt = Number.NEGATIVE_INFINITY;
+    syncFailures = 0;
+    /** After a failed sync, requests before this time wait for the retry already scheduled (same backoff as before). */
+    retryNotBefore = 0;
+    socketFailures = 0;
+    syncTimer;
+    /** When the pending sync timer fires; a lost socket keeps it when it is already due sooner than the fallback. */
+    syncDueAt = Number.POSITIVE_INFINITY;
+    subscribedAt;
+    reconnectTimer;
+    release;
+    stopped = new Promise(resolve => { this.release = resolve; });
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get state() { return this.current; }
+    async run() {
+        // A pending promise alone does not keep Node alive; this referenced timer does until stop().
+        const keepAlive = setInterval(() => undefined, 60_000);
+        try {
+            this.started = true;
+            this.requestSync("start");
+            await this.stopped;
+        }
+        finally {
+            clearInterval(keepAlive);
+        }
+    }
+    stop() {
+        if (this.current === "stopped")
+            return;
+        this.current = "stopped";
+        this.controller.abort();
+        clearTimeout(this.syncTimer);
+        clearTimeout(this.reconnectTimer);
+        this.closeSocket();
+        this.release();
+    }
+    requestSync(reason) {
+        if (!this.started || this.current === "stopped")
+            return;
+        if (this.inFlight) {
+            this.dirty = true;
+            return;
+        }
+        if (Date.now() < this.retryNotBefore)
+            return;
+        this.trigger(reason);
+    }
+    /** Starts a sync now, or once the minimum gap has passed. Timers call it directly: they are the backoff. */
+    trigger(reason) {
+        if (this.current === "stopped")
+            return;
+        if (this.inFlight) {
+            this.dirty = true;
+            return;
+        }
+        clearTimeout(this.syncTimer);
+        this.syncDueAt = Number.POSITIVE_INFINITY;
+        const wait = this.lastSyncAt + (this.deps.minSyncGapMs ?? 1000) - Date.now();
+        if (wait > 0) {
+            this.syncDueAt = Date.now() + wait;
+            this.syncTimer = setTimeout(() => { void this.runSync(reason); }, wait);
+            return;
+        }
+        void this.runSync(reason);
+    }
+    async runSync(reason) {
+        if (this.current === "stopped" || this.inFlight)
+            return;
+        this.inFlight = true;
+        this.lastSyncAt = Date.now();
+        let retryInMs;
+        try {
+            const result = await this.deps.sync(reason, this.controller.signal);
+            // A sync that resolves after stop() must not reopen a socket or re-arm a timer.
+            if (this.isStopped())
+                return;
+            this.syncFailures = 0;
+            this.retryNotBefore = 0;
+            this.syncSeconds = result.syncSeconds;
+            this.fallbackSeconds = result.fallbackSyncSeconds;
+            this.applyPush(result.push);
+            try {
+                await this.deps.dispatch(result);
+            }
+            catch (error) {
+                this.report({ event: "transport_dispatch_failed", cause: causeOf(error) });
+            }
+        }
+        catch (error) {
+            if (!this.isStopped()) {
+                this.syncFailures += 1;
+                retryInMs = this.backoff(this.syncFailures);
+                this.retryNotBefore = Date.now() + retryInMs;
+                this.report({ event: "transport_sync_failed", reason, cause: causeOf(error) });
+            }
+        }
+        finally {
+            this.inFlight = false;
+        }
+        if (this.isStopped())
+            return;
+        if (this.dirty) {
+            this.dirty = false;
+            // After a failed sync the signal waits out the backoff with the retry instead of skipping it.
+            if (retryInMs === undefined) {
+                this.requestSync("signal");
+                return;
+            }
+        }
+        this.schedule(retryInMs);
+    }
+    schedule(overrideMs) {
+        clearTimeout(this.syncTimer);
+        const subscribed = this.current === "subscribed";
+        const ms = overrideMs ?? (subscribed ? this.syncSeconds : this.fallbackSeconds) * 1000;
+        const reason = subscribed ? "periodic" : "fallback";
+        this.syncDueAt = Date.now() + ms;
+        this.syncTimer = setTimeout(() => this.trigger(reason), ms);
+    }
+    applyPush(push) {
+        if (this.isStopped())
+            return;
+        if (push === null) {
+            this.target = undefined;
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+            this.closeSocket();
+            this.current = "fallback";
+            return;
+        }
+        const changed = !this.target || this.target.url !== push.url || this.target.appKey !== push.appKey
+            || this.target.channel !== push.channel || this.target.event !== push.event;
+        this.target = push;
+        if (changed) {
+            this.closeSocket();
+            this.connect();
+            return;
+        }
+        if (!this.socket && !this.reconnectTimer)
+            this.connect();
+    }
+    connect() {
+        const target = this.target;
+        if (!target || this.current === "stopped")
+            return;
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.current = "connecting";
+        this.subscribedAt = undefined;
+        let socket;
+        const events = {
+            onConnected: socketId => { void this.subscribe(socket, socketId); },
+            onSubscribed: () => {
+                if (!socket || this.socket !== socket || this.current === "stopped")
+                    return;
+                this.current = "subscribed";
+                // The backoff restarts only once a subscription has held (see lostSocket), so a server that accepts and
+                // then drops every subscription cannot drive a reconnect and sync storm.
+                this.subscribedAt = Date.now();
+                this.report({ event: "transport_subscribed" });
+                this.requestSync("signal");
+            },
+            onSignal: () => { if (socket && this.socket === socket)
+                this.requestSync("signal"); },
+            onClosed: reason => { if (socket && this.socket === socket)
+                this.lostSocket(reason); },
+        };
+        try {
+            socket = this.deps.openSocket(target, events);
+            this.socket = socket;
+        }
+        catch (error) {
+            this.report({ event: "transport_socket_failed", cause: causeOf(error) });
+            this.lostSocket("open_failed");
+        }
+    }
+    async subscribe(socket, socketId) {
+        if (!socket || this.socket !== socket)
+            return;
+        try {
+            const { channel, auth } = await this.deps.authorize(socketId, this.controller.signal);
+            if (this.socket !== socket)
+                return;
+            if (channel !== this.target?.channel)
+                throw Object.assign(new Error("channel mismatch"), { code: "PUSH_CHANNEL_MISMATCH" });
+            socket.subscribe(auth);
+        }
+        catch (error) {
+            if (this.socket !== socket)
+                return;
+            this.report({ event: "transport_auth_failed", cause: causeOf(error) });
+            this.closeSocket();
+            this.lostSocket("auth_failed");
+        }
+    }
+    /** The socket is gone without us closing it: sync on the fallback interval and reconnect with backoff. */
+    lostSocket(reason) {
+        this.socket = undefined;
+        if (this.current === "stopped")
+            return;
+        this.current = "fallback";
+        this.report({ event: "transport_socket_closed", reason });
+        if (this.subscribedAt !== undefined && Date.now() - this.subscribedAt >= STABLE_SUBSCRIPTION_MS)
+            this.socketFailures = 0;
+        this.subscribedAt = undefined;
+        this.socketFailures += 1;
+        clearTimeout(this.reconnectTimer);
+        const reconnectInMs = REJECTED_REASON.test(reason) ? REJECTED_RECONNECT_MS : this.backoff(this.socketFailures);
+        this.reconnectTimer = setTimeout(() => { this.reconnectTimer = undefined; this.connect(); }, reconnectInMs);
+        // Keep a sync that is already due sooner (the next fallback sync, or a signal waiting out the minimum gap):
+        // restarting the timer on every lost socket would stretch the fallback interval past the latency target.
+        if (!this.inFlight && this.syncDueAt > Date.now() + this.fallbackSeconds * 1000)
+            this.schedule();
+    }
+    closeSocket() {
+        const socket = this.socket;
+        this.socket = undefined;
+        try {
+            socket?.close();
+        }
+        catch { /* Closing must not stop the transport. */ }
+    }
+    backoff(failures) {
+        const base = Math.min(MAX_BACKOFF_MS, (this.deps.backoffBaseMs ?? 1000) * (2 ** Math.min(5, failures - 1)));
+        return base + Math.floor(base * 0.2 * (this.deps.random ?? Math.random)());
+    }
+    /** Read through a method: stop() may run while a sync awaits, which narrowing on the field cannot see. */
+    isStopped() {
+        return this.current === "stopped";
+    }
+    report(event) {
+        try {
+            this.deps.report?.(event);
+        }
+        catch { /* Logging cannot stop the transport. */ }
+    }
+}

package/dist/src/transport/side-loops.js

@@ -0,0 +1,50 @@
+export function sideLoops(deps) {
+    let stopped = false;
+    return {
+        async run() {
+            await deps.heartbeat.tick();
+            if (stopped)
+                return;
+            await Promise.all([deps.transport.run(), deps.heartbeat.run()]);
+        },
+        stop() {
+            stopped = true;
+            try {
+                deps.onStop?.();
+            }
+            catch { /* Stopping must reach both loops. */ }
+            deps.transport.stop();
+            deps.heartbeat.stop();
+        },
+    };
+}
+/** A heartbeat function that decides for itself when to send (the messenger's), called on a fixed tick. */
+export function tickingHeartbeat(beat, tickMs, signal) {
+    let timer;
+    let release;
+    const stopped = new Promise(resolve => { release = resolve; });
+    let ended = false;
+    const tick = async () => { try {
+        await beat(signal);
+    }
+    catch { /* The beat reports its own failures. */ } };
+    return {
+        tick,
+        async run() {
+            const loop = () => {
+                if (ended)
+                    return;
+                timer = setTimeout(() => { void tick().then(loop); }, tickMs);
+            };
+            loop();
+            await stopped;
+        },
+        stop() {
+            if (ended)
+                return;
+            ended = true;
+            clearTimeout(timer);
+            release();
+        },
+    };
+}

package/dist/src/transport/sync-dispatch.js

@@ -0,0 +1,91 @@
+/*
+ * Closures the runner has handled and not yet acknowledged (Work Item 25d8ea74). A closure is listed until the
+ * runner acknowledges it on a later sync, so a lost sync response cannot lose it (at-least-once). take() hands the
+ * ids to the next sync; restore() puts them back when that sync fails.
+ */
+export class PendingClosureAcks {
+    ids = new Set();
+    add(ids) {
+        for (const id of ids)
+            if (typeof id === "string" && id !== "" && this.ids.size < 200)
+                this.ids.add(id);
+    }
+    take() {
+        const taken = [...this.ids].slice(0, 50);
+        for (const id of taken)
+            this.ids.delete(id);
+        return taken;
+    }
+    restore(ids) { this.add(ids); }
+}
+/** Pauses before the second and third report attempts. The Gateway treats a repeated report as idempotent. */
+const REPORT_RETRY_DELAYS_MS = [1000, 2000];
+function causeOf(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : undefined;
+}
+export function createSyncDispatcher(deps) {
+    const fail = (stage, code, error) => {
+        const cause = causeOf(error);
+        try {
+            deps.reportError?.({ stage, code, ...(cause ? { cause } : {}) });
+        }
+        catch { /* Logging cannot stop dispatch. */ }
+    };
+    const handleOpen = async (request) => {
+        let result;
+        try {
+            result = await deps.open(request);
+        }
+        catch (error) {
+            if (!deps.signal.aborted)
+                fail("open", "SESSION_OPEN_OPEN_FAILED", error);
+            return;
+        }
+        const openId = request?.open_id;
+        if (typeof openId !== "string" || openId === "")
+            return;
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await deps.report(openId, result, deps.signal);
+                return;
+            }
+            catch (error) {
+                if (deps.signal.aborted)
+                    return;
+                const retryDelay = REPORT_RETRY_DELAYS_MS[attempt];
+                if (retryDelay === undefined) {
+                    fail("report", "SESSION_OPEN_REPORT_FAILED", error);
+                    return;
+                }
+                await deps.delay(retryDelay, deps.signal).catch(() => undefined);
+                if (deps.signal.aborted)
+                    return;
+            }
+        }
+    };
+    return async (result) => {
+        // Asks first: they are local and quick, while each open can spend seconds on report retries.
+        if (deps.asks) {
+            try {
+                const handled = await deps.asks.handleWait({
+                    ...(result.askDeliveries !== undefined ? { askDeliveries: result.askDeliveries } : {}),
+                    ...(result.closedDeliveryIds !== undefined ? { closedDeliveryIds: result.closedDeliveryIds } : {}),
+                });
+                // Acknowledged only once handled: a failed handleWait leaves them for the Gateway to list again.
+                if (handled !== false)
+                    deps.closureAcks?.add(result.closedDeliveryIds ?? []);
+            }
+            catch (error) {
+                fail("asks", "ASK_DISPATCH_FAILED", error);
+            }
+        }
+        if (result.jobAvailable)
+            deps.jobs?.notify();
+        for (const request of result.opens) {
+            if (deps.signal.aborted)
+                return;
+            await handleOpen(request);
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "private": false,
   "license": "UNLICENSED",
   "bin": {
@@ -34,11 +34,13 @@
   },
   "dependencies": {
     "smol-toml": "1.9.1",
-    "uuid": "11.1.1"
+    "uuid": "11.1.1",
+    "ws": "8.18.3"
   },
   "devDependencies": {
     "@types/node": "22.19.11",
     "@types/uuid": "10.0.0",
+    "@types/ws": "8.18.1",
     "typescript": "5.9.3",
     "vitest": "4.0.18"
   }