mtech-ai-local-runner 0.1.47 → 0.1.48

package/dist/src/asks/hub.js

@@ -0,0 +1,202 @@
+import { createServer } from "node:net";
+import { chmod, lstat, mkdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { HUB_SOCKET, HUB_TIMEOUT_MS, MAX_LINE_BYTES, MAX_SOCKET_PATH_BYTES, encodeLine, parseHubRequest, } from "./hub-protocol.js";
+/*
+ * The daemon's local hub (Work Item e1c08b33, spec section 8.2). A Unix socket, mode 0600 in the 0700 state
+ * root, so only this user can reach it. It answers one request per connection and keeps a Claude Stop watcher's
+ * connection open until the handler wakes or releases it. It holds no ask state itself: the handler does.
+ */
+/**
+ * The hook client gives up after HUB_TIMEOUT_MS and prints nothing. A request that has waited this long, a little less
+ * to leave room for the write, can no longer be answered in time: the hub changes nothing for it.
+ */
+export const HUB_ANSWER_WINDOW_MS = HUB_TIMEOUT_MS - 100;
+export function hubSocketPath(stateRoot) {
+    return join(stateRoot, HUB_SOCKET);
+}
+/**
+ * True when nothing more can be sent to, or read from, the client. The client never half-closes its side, so an
+ * ended read side means it left. The socket's own state is read because its 'close' event can come several turns of
+ * the event loop later.
+ */
+function hasLeft(socket) {
+    return socket.destroyed || !socket.writable || socket.readableEnded;
+}
+function waitedTooLong(arrivedAt) {
+    return performance.now() - arrivedAt > HUB_ANSWER_WINDOW_MS;
+}
+/** The client of an event request whose line arrived at `arrivedAt` (performance.now()). */
+export function clientFor(socket, arrivedAt) {
+    return { get gone() { return hasLeft(socket) || waitedTooLong(arrivedAt); } };
+}
+/** The watcher for one watch connection. `answered` is true once anything was sent on it. */
+export function watcherFor(socket, arrivedAt = performance.now()) {
+    let closeEvent = false;
+    let answered = false;
+    const listeners = [];
+    socket.once("close", () => {
+        closeEvent = true;
+        for (const listener of listeners.splice(0))
+            listener();
+    });
+    const closed = () => closeEvent || hasLeft(socket);
+    const send = (message, last) => {
+        if (closed())
+            return false;
+        socket.write(encodeLine(message));
+        answered = true;
+        if (last)
+            socket.end();
+        return true;
+    };
+    return {
+        get closed() { return closed(); },
+        // Once something was sent the client has its answer; only a watch that is still unanswered can be too late.
+        get gone() { return closed() || (!answered && waitedTooLong(arrivedAt)); },
+        get answered() { return answered; },
+        hold: () => send({ v: 1, type: "watching" }, false),
+        wake: text => send({ v: 1, type: "wake", text }, true),
+        release: reason => { send({ v: 1, type: "release", reason }, true); },
+        onClose: listener => { if (closeEvent)
+            listener();
+        else
+            listeners.push(listener); },
+    };
+}
+/** A socket left behind by a daemon that died is removed; anything else at that path is never touched. */
+async function removeStaleSocket(path) {
+    try {
+        if (!(await lstat(path)).isSocket())
+            throw new Error("ASK_HUB_PATH_NOT_A_SOCKET");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    await rm(path, { force: true });
+}
+export class AskHub {
+    options;
+    server = null;
+    sockets = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    get listening() {
+        return this.server !== null;
+    }
+    async start() {
+        // A second listener would remove the live socket as if it were stale.
+        if (this.server !== null)
+            throw new Error("ASK_HUB_ALREADY_LISTENING");
+        const path = this.options.socketPath;
+        if (Buffer.byteLength(path) > MAX_SOCKET_PATH_BYTES)
+            throw new Error("ASK_HUB_SOCKET_PATH_TOO_LONG");
+        const directory = dirname(path);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await chmod(directory, 0o700);
+        await removeStaleSocket(path);
+        const server = createServer(socket => this.connection(socket));
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(path, () => { server.off("error", reject); resolve(); });
+        });
+        // A listening server can still emit an error (accepting with no file descriptors left, say); without a listener Node
+        // would throw it and take the daemon down. Only its code is logged.
+        server.on("error", error => this.logServerError(error));
+        try {
+            // listen() creates the socket with the umask's mode (0755); only this user may connect.
+            await chmod(path, 0o600);
+        }
+        catch (error) {
+            // Never leave a socket listening that is not private, nor a connection that was accepted on it.
+            for (const socket of this.sockets)
+                socket.destroy();
+            await new Promise(resolve => server.close(() => resolve()));
+            await rm(path, { force: true });
+            throw error;
+        }
+        this.server = server;
+    }
+    async stop() {
+        const server = this.server;
+        this.server = null;
+        if (server === null)
+            return;
+        for (const socket of this.sockets)
+            socket.destroy();
+        await new Promise(resolve => server.close(() => resolve()));
+        await rm(this.options.socketPath, { force: true });
+    }
+    connection(socket) {
+        this.sockets.add(socket);
+        socket.once("close", () => this.sockets.delete(socket));
+        socket.on("error", () => undefined);
+        socket.setEncoding("utf8");
+        // A client that never sends a full line is dropped; a watch request clears the timer and stays open.
+        socket.setTimeout(this.options.requestTimeoutMs ?? 2000, () => socket.destroy());
+        let buffer = "";
+        const onData = (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf("\n");
+            // A line over the limit is dropped without an answer, whether or not its end has arrived yet.
+            if (Buffer.byteLength(newline < 0 ? buffer : buffer.slice(0, newline)) > MAX_LINE_BYTES) {
+                socket.destroy();
+                return;
+            }
+            if (newline < 0)
+                return;
+            const arrivedAt = performance.now();
+            socket.off("data", onData);
+            // Keep reading, so the client leaving is seen while its request waits.
+            socket.resume();
+            socket.setTimeout(0);
+            void this.dispatch(buffer.slice(0, newline), socket, arrivedAt);
+        };
+        socket.on("data", onData);
+    }
+    async dispatch(line, socket, arrivedAt) {
+        const reply = (response) => { if (!hasLeft(socket))
+            socket.end(encodeLine(response)); };
+        const request = parseHubRequest(line);
+        if (request === null) {
+            reply({ v: 1, ok: false, code: "invalid_request" });
+            return;
+        }
+        try {
+            if (request.op === "status") {
+                reply({ v: 1, ok: true, status: this.options.handler.status() });
+            }
+            else if (request.op === "event") {
+                reply({ v: 1, ok: true, text: await this.options.handler.event(request, clientFor(socket, arrivedAt)) });
+            }
+            else {
+                const watcher = watcherFor(socket, arrivedAt);
+                await this.options.handler.watch(request, watcher);
+                // The handler sent nothing: it refused a client that had gone. Do not leave a connection open that nobody answers.
+                if (!watcher.answered)
+                    socket.destroy();
+            }
+        }
+        catch (error) {
+            this.logFailure(request.op, error);
+            reply({ v: 1, ok: false, code: "unavailable" });
+        }
+    }
+    logServerError(error) {
+        const code = error?.code;
+        try {
+            this.options.log?.({ event: "ask_hub_server_error", code: typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : "UNKNOWN" });
+        }
+        catch { /* Logging never stops the hub. */ }
+    }
+    logFailure(op, error) {
+        const code = error?.code;
+        try {
+            this.options.log?.({ event: "ask_hub_handler_failed", op, error: typeof code === "string" ? code : error instanceof Error ? error.name : "UNKNOWN" });
+        }
+        catch { /* Logging never stops the hub. */ }
+    }
+}

package/dist/src/asks/inbox.js

@@ -0,0 +1,347 @@
+import { emptyAskState, pruneAskState, sessionKey } from "./store.js";
+import { addDeliveries, closeDeliveries, confirmNotified, confirmWake, isLive, planRoutes, promptSubmitted, sessionEnded, sessionStarted, turnEnded, } from "./routing.js";
+import { droppableDeliveryId, parseAskDelivery } from "./types.js";
+import { renderOutput } from "./templates.js";
+/** The most reports one flush sends, so a misbehaving Gateway can never keep it busy. */
+const MAX_REPORTS_PER_FLUSH = 200;
+/** How many ended delivery ids are remembered, so one offered again is never stored or shown again. */
+const MAX_ENDED = 1000;
+const sameReport = (a, b) => a !== undefined && a.event === b.event && a.via === b.via && a.app === b.app;
+/** The Gateway refused the report itself (not this runner's delivery, or the switch is off): retrying cannot help. */
+const refused = (error) => error?.code === "GATEWAY_TOOL_REJECTED";
+export class AskInbox {
+    deps;
+    state = emptyAskState();
+    watchers = new Map();
+    queue = Promise.resolve();
+    /** Notifications still running, so idle() can wait for them. */
+    notifications = new Set();
+    /** Deliveries this runner could not use, to be reported dropped. Not stored: the Gateway offers them again. */
+    drops = new Set();
+    /** Deliveries that ended here: closed, fallen back, or refused. Offered again, they are ignored. */
+    ended = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() {
+        return (this.deps.now ?? Date.now)();
+    }
+    log(event) {
+        try {
+            this.deps.log?.(event);
+        }
+        catch { /* Logging never stops delivery. */ }
+    }
+    /** Runs one change at a time, in call order. */
+    exclusive(change) {
+        const result = this.queue.then(change);
+        this.queue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /**
+     * Reads the stored state. A missing file or content that is not JSON is an empty state (the store decides). Any other
+     * error propagates: the caller must run without asks, because the next save would overwrite a file it could not read.
+     */
+    async load() {
+        await this.exclusive(async () => {
+            this.state = await this.deps.store.load();
+        });
+    }
+    /** Resolves when every queued change is saved and every notification has finished. For shutdown, before the lock is released. */
+    async idle() {
+        for (;;) {
+            const queue = this.queue;
+            await Promise.all([queue, ...this.notifications]);
+            if (queue === this.queue && this.notifications.size === 0)
+                return;
+        }
+    }
+    status() {
+        const now = this.now();
+        return {
+            deliveries: Object.keys(this.state.items).length,
+            live_sessions: Object.values(this.state.sessions).filter(session => isLive(session, now)).length,
+            watchers: this.watchers.size,
+        };
+    }
+    /**
+     * The answer resolves as soon as the change is made, before the save; the queue is held until the save is done. A
+     * client that is gone gets nothing and changes nothing: marking an ask shown for a hook that cannot print it would
+     * count it as seen later although nobody saw it.
+     */
+    event(request, client) {
+        return new Promise((answer, fail) => {
+            this.exclusive(async () => {
+                if (client.gone) {
+                    answer(null);
+                    return;
+                }
+                const context = { app: request.app, sessionId: request.session_id, cwd: request.cwd, now: this.now() };
+                let text = null;
+                if (request.event === "session-start")
+                    text = renderOutput(sessionStarted(this.state, context), { sessionId: request.session_id });
+                else if (request.event === "prompt")
+                    text = renderOutput(promptSubmitted(this.state, context));
+                else if (request.event === "stop")
+                    text = renderOutput(turnEnded(this.state, context, { stopHookActive: request.stop_hook_active === true }));
+                else {
+                    sessionEnded(this.state, context);
+                    this.release(sessionKey(request.app, request.session_id), "session_ended");
+                }
+                const notify = this.route();
+                answer(text);
+                await this.commit(notify);
+            }).catch(fail);
+        });
+    }
+    /**
+     * A Claude Stop watcher. A Claude turn end is always a watch, so registering one is the session's turn end: it runs
+     * turnEnded(), which shows what is already pinned to the session (via stop) and marks the session idle. Without that
+     * the session would still count as in a turn, and the wake branch of the routing rules could never be reached.
+     * What is not pinned makes the watcher wait, replacing any older watcher of the same session.
+     */
+    watch(request, watcher) {
+        return this.exclusive(async () => {
+            // The client went away, or gave up, while this waited in the queue. Showing it anything would lose the text, and it must not replace an older watcher.
+            if (watcher.gone)
+                return;
+            const key = sessionKey("claude", request.session_id);
+            this.release(key, "replaced");
+            // Claude's own loop guard is the hourly wake limit; stop_hook_active belongs to Stop decisions, not to a rewake.
+            const text = renderOutput(turnEnded(this.state, { app: "claude", sessionId: request.session_id, cwd: request.cwd, now: this.now() }, { stopHookActive: false }));
+            if (text !== null) {
+                watcher.wake(text);
+            }
+            else if (watcher.hold()) {
+                this.watchers.set(key, watcher);
+                watcher.onClose(() => { if (this.watchers.get(key) === watcher)
+                    this.watchers.delete(key); });
+            }
+            await this.settle();
+        });
+    }
+    /**
+     * Deliveries from the session-open wait. A valid one is stored, then reported received (by flush). One that fails
+     * validation, or cannot be stored, is reported dropped, so the Gateway sends today's Slack message at once.
+     */
+    receive(entries) {
+        return this.exclusive(async () => {
+            const deliveries = [];
+            for (const entry of entries) {
+                const delivery = parseAskDelivery(entry);
+                if (delivery !== null && this.ended.has(delivery.deliveryId))
+                    continue;
+                if (delivery !== null) {
+                    deliveries.push(delivery);
+                    continue;
+                }
+                const deliveryId = droppableDeliveryId(entry);
+                if (deliveryId !== null && this.state.items[deliveryId] === undefined)
+                    this.drops.add(deliveryId);
+            }
+            const { added } = addDeliveries(this.state, deliveries, this.now());
+            if (added.length > 0) {
+                if (await this.persist()) {
+                    // Stored now: a dropped report still queued from an earlier failed save is stale.
+                    for (const item of added)
+                        this.drops.delete(item.deliveryId);
+                }
+                else {
+                    for (const item of added) {
+                        delete this.state.items[item.deliveryId];
+                        this.drops.add(item.deliveryId);
+                    }
+                }
+            }
+            await this.settle();
+        });
+    }
+    /** Deliveries the Gateway closed after this runner received them: answered, decided, expired or fallen back. */
+    close(deliveryIds) {
+        return this.exclusive(async () => {
+            const closed = closeDeliveries(this.state, deliveryIds);
+            for (const deliveryId of closed)
+                this.end(deliveryId);
+            if (closed.length > 0)
+                await this.persist();
+        });
+    }
+    /**
+     * Asks are off for this runner (the wait result has no ask keys): every stored delivery ends, with no report, and the
+     * dropped reports not sent yet are dropped too, since the Gateway would refuse them. Waiting watchers stay.
+     */
+    endAll() {
+        return this.exclusive(async () => {
+            const ended = Object.keys(this.state.items);
+            for (const deliveryId of ended)
+                this.end(deliveryId);
+            this.drops.clear();
+            if (ended.length === 0)
+                return;
+            this.log({ event: "ask_deliveries_ended", reason: "asks_off", count: ended.length });
+            await this.persist();
+        });
+    }
+    /** Forgets a delivery for good: it is dropped from the store and never stored or shown again. */
+    end(deliveryId) {
+        delete this.state.items[deliveryId];
+        this.ended.add(deliveryId);
+        if (this.ended.size > MAX_ENDED)
+            this.ended.delete(this.ended.values().next().value);
+    }
+    /**
+     * Sends queued reports in order: drops first, then each delivery's outbox. A transport or server failure stops
+     * the flush and leaves the report queued for the next one. A report the Gateway refuses, or a result that says
+     * the delivery fell back or closed, ends the delivery here.
+     */
+    async flush(send, signal) {
+        // What to send is picked inside the queue, after any change in progress has been saved: receive() holds the queue
+        // until its save is done, so a received report never reaches the Gateway before its delivery is on disk.
+        for (const deliveryId of await this.exclusive(async () => [...this.drops])) {
+            if (signal.aborted)
+                return;
+            if (!this.drops.has(deliveryId))
+                continue;
+            try {
+                await send(deliveryId, { event: "dropped" }, signal);
+            }
+            catch (error) {
+                if (!refused(error)) {
+                    this.reportFailed(error, signal);
+                    return;
+                }
+            }
+            this.drops.delete(deliveryId);
+        }
+        for (let sent = 0; sent < MAX_REPORTS_PER_FLUSH && !signal.aborted; sent += 1) {
+            const next = await this.exclusive(async () => {
+                const item = Object.values(this.state.items).find(candidate => candidate.outbox.length > 0);
+                return item === undefined ? undefined : { deliveryId: item.deliveryId, report: item.outbox[0] };
+            });
+            if (next === undefined)
+                return;
+            const report = next.report;
+            let result;
+            try {
+                result = await send(next.deliveryId, report, signal);
+            }
+            catch (error) {
+                if (!refused(error)) {
+                    this.reportFailed(error, signal);
+                    return;
+                }
+                await this.exclusive(async () => { this.end(next.deliveryId); await this.persist(); });
+                continue;
+            }
+            const status = result?.delivery?.status;
+            await this.exclusive(async () => {
+                const current = this.state.items[next.deliveryId];
+                if (current === undefined)
+                    return;
+                if (sameReport(current.outbox[0], report))
+                    current.outbox.shift();
+                // The Gateway already sent Slack, or the ask is answered: drop it and never show it again.
+                if (status === "fallen_back" || status === "closed")
+                    this.end(next.deliveryId);
+                await this.persist();
+            });
+        }
+    }
+    /** A report that did not get through stays queued. A report the shutdown aborted is no failure, so it is not logged. */
+    reportFailed(error, signal) {
+        if (!signal.aborted)
+            this.log({ event: "ask_report_failed", code: errorCode(error) });
+    }
+    /** Tells every waiting watcher to exit 0, for daemon shutdown. */
+    releaseAll(reason) {
+        for (const key of [...this.watchers.keys()])
+            this.release(key, reason);
+    }
+    release(key, reason) {
+        const watcher = this.watchers.get(key);
+        if (watcher === undefined)
+            return;
+        this.watchers.delete(key);
+        watcher.release(reason);
+    }
+    /**
+     * Prunes, re-routes, wakes watchers and claims notifications; returns the deliveries to notify. Synchronous, so the
+     * plan, the wake and its confirmation can never interleave with another change. Must run inside exclusive().
+     */
+    route() {
+        const now = this.now();
+        pruneAskState(this.state, now);
+        const watching = new Set([...this.watchers].filter(([, watcher]) => !watcher.closed).map(([key]) => key));
+        const plan = planRoutes(this.state, now, watching);
+        for (const { sessionKey: key, output } of plan.wakes) {
+            const watcher = this.watchers.get(key);
+            const text = renderOutput(output);
+            if (watcher === undefined || text === null || !watcher.wake(text))
+                continue;
+            this.watchers.delete(key);
+            confirmWake(this.state, key, output, now);
+        }
+        // Claimed before the notification runs, so a delivery is never notified twice.
+        for (const item of plan.notify)
+            confirmNotified(this.state, item.deliveryId, now, false);
+        return plan.notify.map(item => item.deliveryId);
+    }
+    /** Saves, then starts the notifications and the change callback. Whoever waits for an answer has it by now. Inside exclusive(). */
+    async commit(notify) {
+        await this.persist();
+        if (notify.length > 0)
+            this.startNotifying(notify);
+        try {
+            this.deps.onChange?.();
+        }
+        catch { /* A failed flush trigger is retried after the next wait. */ }
+    }
+    /** route() and commit() together, for a change that has no answer to hand over first. */
+    async settle() {
+        await this.commit(this.route());
+    }
+    async persist() {
+        try {
+            await this.deps.store.save(this.state);
+            return true;
+        }
+        catch (error) {
+            this.log({ event: "ask_store_write_failed", code: error.code ?? "UNKNOWN" });
+            return false;
+        }
+    }
+    startNotifying(deliveryIds) {
+        const running = this.notifyEach(deliveryIds)
+            .catch(error => this.log({ event: "ask_notification_failed", error: error instanceof Error ? error.name : "UNKNOWN" }))
+            .then(() => { this.notifications.delete(running); });
+        this.notifications.add(running);
+    }
+    async notifyEach(deliveryIds) {
+        for (const deliveryId of deliveryIds) {
+            const item = this.state.items[deliveryId];
+            if (item === undefined || this.deps.notify === undefined)
+                continue;
+            let shown = false;
+            try {
+                shown = await this.deps.notify(item);
+            }
+            catch {
+                shown = false;
+            }
+            if (!shown)
+                continue;
+            await this.exclusive(async () => {
+                confirmNotified(this.state, deliveryId, this.now(), true);
+                await this.persist();
+                try {
+                    this.deps.onChange?.();
+                }
+                catch { /* Retried after the next wait. */ }
+            });
+        }
+    }
+}
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : "UNKNOWN";
+}