mtech-ai-local-runner 0.1.46 → 0.1.48

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";
+}