mtech-ai-local-runner 0.1.47 → 0.1.49

package/dist/src/asks/routing.js

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import { SESSION_TTL_MS, WAKE_PERIOD_MS, sessionKey } from "./store.js";
+import { LOWER_UUID } from "./types.js";
+/*
+ * Routing, seen and wake rules for AI-first ask delivery (Work Item e1c08b33, spec sections 4 and 5).
+ * Every function here works on the in-memory AskState and does no I/O, so the rules are tested directly.
+ * The AI's own actions never count as seen: only hook events the runner observes move a delivery forward.
+ */
+/** A session is woken, or a delivery pinned to it, only after a human prompt within the last 30 minutes. */
+export const WAKE_WINDOW_MS = 30 * 60 * 1000;
+/** At most 6 wakes per session per hour (Claude asyncRewake exits and Codex Stop continuations). */
+export const WAKE_LIMIT = 6;
+/** At most 5 deliveries are spelled out in one hook output; the rest are summarized. */
+export const MAX_ITEMS_PER_OUTPUT = 5;
+export function hashSessionId(sessionId) {
+    return createHash("sha256").update(sessionId, "utf8").digest("hex");
+}
+/** Live from its first event until SessionEnd, or until 12 hours pass without an event. */
+export function isLive(session, now) {
+    return session.endedAt === null && now - session.lastEventAt <= SESSION_TTL_MS;
+}
+export function humanPromptWithin(session, now) {
+    return session.lastPromptAt !== null && now - session.lastPromptAt <= WAKE_WINDOW_MS;
+}
+export function turnInProgress(session) {
+    return session.lastPromptAt !== null && (session.lastTurnEndAt === null || session.lastPromptAt > session.lastTurnEndAt);
+}
+export function wakesLeft(session, now) {
+    return WAKE_LIMIT - session.wakes.filter(at => now - at < WAKE_PERIOD_MS).length;
+}
+/** Spec section 5: a live session the delivery names, else the live session with the most recent human prompt. */
+export function chooseSession(item, state, now) {
+    const live = Object.entries(state.sessions).filter(([, session]) => isLive(session, now));
+    const targets = new Set(item.targetSessionHashes);
+    const named = live.filter(([, session]) => targets.has(hashSessionId(session.sessionId)));
+    const pool = named.length > 0 ? named : live;
+    pool.sort(([keyA, a], [keyB, b]) => (b.lastPromptAt ?? -1) - (a.lastPromptAt ?? -1) || b.lastEventAt - a.lastEventAt || keyA.localeCompare(keyB));
+    return pool[0]?.[0] ?? null;
+}
+/**
+ * Where a delivery that is not shown yet goes now:
+ * - no live session, or the chosen one had no human prompt in 30 minutes: a notification, then the next
+ *   SessionStart or prompt in any session;
+ * - the chosen session is in a turn: pinned there, shown at its turn end or next prompt;
+ * - an idle Claude session whose Stop watcher waits, under its hourly limit: woken now;
+ * - otherwise (an idle Codex session, no watcher, or the limit reached): a notification.
+ */
+export function routeItem(item, state, now, watching) {
+    const key = chooseSession(item, state, now);
+    const session = key === null ? undefined : state.sessions[key];
+    if (key === null || session === undefined || !humanPromptWithin(session, now))
+        return { action: "notify" };
+    if (turnInProgress(session))
+        return { action: "pin", sessionKey: key };
+    if (session.app === "claude" && watching.has(key) && wakesLeft(session, now) > 0)
+        return { action: "wake", sessionKey: key };
+    return { action: "notify" };
+}
+/** At most 5 spelled out, oldest first; the rest are summarized by one "and N more" line. */
+export function selectForOutput(items) {
+    const sorted = [...items].sort((a, b) => a.createdAt - b.createdAt || a.receivedAt - b.receivedAt || a.deliveryId.localeCompare(b.deliveryId));
+    return { items: sorted.slice(0, MAX_ITEMS_PER_OUTPUT), more: sorted.slice(MAX_ITEMS_PER_OUTPUT) };
+}
+function everyItem(output) {
+    return [...output.items, ...output.more];
+}
+/** Registers or refreshes the session an event came from. Any event but SessionEnd makes it live again. */
+function touch(state, context) {
+    const key = sessionKey(context.app, context.sessionId);
+    let session = state.sessions[key];
+    if (session === undefined) {
+        session = { app: context.app, sessionId: context.sessionId, cwd: context.cwd, startedAt: context.now, lastEventAt: context.now,
+            lastPromptAt: null, lastTurnEndAt: null, endedAt: null, wakes: [] };
+        state.sessions[key] = session;
+    }
+    session.lastEventAt = context.now;
+    session.endedAt = null;
+    if (context.cwd !== "")
+        session.cwd = context.cwd;
+    return { key, session };
+}
+function markShown(item, key, app, via, now) {
+    item.phase = "shown";
+    item.sessionKey = key;
+    item.shownVia = via;
+    item.shownAt = now;
+    if (item.firstShownVia === null) {
+        item.firstShownVia = via;
+        item.outbox.push({ event: "shown", via, app });
+    }
+}
+function markSeen(item, app, now) {
+    item.phase = "seen";
+    item.seenAt = now;
+    item.outbox.push({ event: "seen", via: item.shownVia ?? "prompt", app });
+}
+function itemsWhere(state, predicate) {
+    return Object.values(state.items).filter(predicate);
+}
+/**
+ * What SessionStart and UserPromptSubmit show in the session `key`: every waiting item and what is pinned to that session.
+ * The one rule for both hooks. A pinned item always names a session, which the store enforces on load (normalizeAskState).
+ */
+function dueFor(state, key) {
+    return itemsWhere(state, item => item.phase === "waiting" || (item.phase === "pinned" && item.sessionKey === key));
+}
+/** Stores new deliveries and queues their received report. A repeated offer queues received again, so a lost report is resent. */
+export function addDeliveries(state, deliveries, now) {
+    const added = [];
+    const repeated = [];
+    for (const delivery of deliveries) {
+        const known = state.items[delivery.deliveryId];
+        if (known !== undefined) {
+            if (!known.outbox.some(report => report.event === "received"))
+                known.outbox.unshift({ event: "received" });
+            repeated.push(known);
+            continue;
+        }
+        const item = { ...delivery, targetSessionHashes: [...delivery.targetSessionHashes], receivedAt: now, phase: "waiting",
+            sessionKey: null, shownVia: null, shownAt: null, firstShownVia: null, notifiedAt: null, seenAt: null, outbox: [{ event: "received" }] };
+        state.items[delivery.deliveryId] = item;
+        added.push(item);
+    }
+    return { added, repeated };
+}
+/** Drops deliveries the Gateway closed (answered, decided, expired or fallen back). Returns the ids it dropped. */
+export function closeDeliveries(state, deliveryIds) {
+    const closed = [];
+    for (const id of deliveryIds) {
+        if (typeof id === "string" && LOWER_UUID.test(id) && state.items[id] !== undefined) {
+            delete state.items[id];
+            closed.push(id);
+        }
+    }
+    return closed;
+}
+/** SessionStart: register the session and show what waits for any session (seen at its next prompt). */
+export function sessionStarted(state, context) {
+    const { key } = touch(state, context);
+    const output = selectForOutput(dueFor(state, key));
+    for (const item of everyItem(output))
+        markShown(item, key, context.app, "session_start", context.now);
+    return output;
+}
+/** UserPromptSubmit: earlier items shown in this session become seen; waiting items are shown and seen at once. */
+export function promptSubmitted(state, context) {
+    const { key, session } = touch(state, context);
+    session.lastPromptAt = context.now;
+    for (const item of itemsWhere(state, item => item.phase === "shown" && item.sessionKey === key))
+        markSeen(item, context.app, context.now);
+    const output = selectForOutput(dueFor(state, key));
+    for (const item of everyItem(output)) {
+        markShown(item, key, context.app, "prompt", context.now);
+        markSeen(item, context.app, context.now);
+    }
+    return output;
+}
+/**
+ * Stop: what is pinned to this session is shown at its turn end, unless the turn already continued because of a
+ * Stop hook or the hourly wake limit is reached. Then it waits for any session and gets a notification instead.
+ */
+export function turnEnded(state, context, options) {
+    const { key, session } = touch(state, context);
+    const pinned = itemsWhere(state, item => item.phase === "pinned" && item.sessionKey === key);
+    session.lastTurnEndAt = context.now;
+    if (pinned.length === 0)
+        return { items: [], more: [] };
+    if (options.stopHookActive || wakesLeft(session, context.now) <= 0) {
+        for (const item of pinned) {
+            item.phase = "waiting";
+            item.sessionKey = null;
+        }
+        return { items: [], more: [] };
+    }
+    const output = selectForOutput(pinned);
+    for (const item of everyItem(output))
+        markShown(item, key, context.app, "stop", context.now);
+    session.wakes.push(context.now);
+    return output;
+}
+/** SessionEnd: the session is no longer live; what was pinned to it waits for another session. */
+export function sessionEnded(state, context) {
+    const key = sessionKey(context.app, context.sessionId);
+    const session = state.sessions[key];
+    if (session !== undefined) {
+        session.endedAt = context.now;
+        session.lastEventAt = context.now;
+    }
+    for (const item of itemsWhere(state, item => item.phase === "pinned" && item.sessionKey === key)) {
+        item.phase = "waiting";
+        item.sessionKey = null;
+    }
+}
+/**
+ * Re-decides every delivery not shown yet. Pins are applied at once. Wakes and notifications are returned for
+ * the hub to carry out; it confirms each with confirmWake or confirmNotified. One notification per delivery.
+ * Plan, deliver and confirm must not interleave for the same state: the hub serializes them, and notifiedAt is set only by confirmNotified.
+ */
+export function planRoutes(state, now, watching) {
+    const wakeGroups = new Map();
+    const notify = [];
+    for (const item of itemsWhere(state, item => item.phase === "waiting" || item.phase === "pinned")) {
+        const decision = routeItem(item, state, now, watching);
+        if (decision.action === "notify") {
+            item.phase = "waiting";
+            item.sessionKey = null;
+            if (item.notifiedAt === null)
+                notify.push(item);
+            continue;
+        }
+        item.phase = "pinned";
+        item.sessionKey = decision.sessionKey;
+        if (decision.action === "wake")
+            wakeGroups.set(decision.sessionKey, [...wakeGroups.get(decision.sessionKey) ?? [], item]);
+    }
+    return { wakes: [...wakeGroups].map(([key, items]) => ({ sessionKey: key, output: selectForOutput(items) })), notify };
+}
+/** The hub delivered a wake to the session's watcher: everything in it counts as shown there. */
+export function confirmWake(state, key, output, now) {
+    const session = state.sessions[key];
+    if (session === undefined)
+        return;
+    for (const item of everyItem(output)) {
+        if (state.items[item.deliveryId] === item && item.phase === "pinned" && item.sessionKey === key)
+            markShown(item, key, session.app, "rewake", now);
+    }
+    session.wakes.push(now);
+}
+/** The notification was attempted. Only one that was shown is reported, as shown via notification. */
+export function confirmNotified(state, deliveryId, now, shown) {
+    const item = state.items[deliveryId];
+    if (item === undefined)
+        return;
+    item.notifiedAt = now;
+    if (shown && item.firstShownVia === null) {
+        item.firstShownVia = "notification";
+        item.outbox.push({ event: "shown", via: "notification" });
+    }
+}

package/dist/src/asks/runtime.js

@@ -0,0 +1,206 @@
+import { AskHub, hubSocketPath } from "./hub.js";
+import { AskInbox } from "./inbox.js";
+import { AskStore } from "./store.js";
+import { refreshShim } from "./shim.js";
+import { installedApps } from "./integrations.js";
+import { createNotifier } from "./notifier.js";
+/*
+ * AI-first ask delivery inside the daemon (Work Item e1c08b33). It rides on the existing session-open loop:
+ * no new long-poll. The hub runs for as long as that loop runs, deliveries from each wait are stored and
+ * reported, and heartbeats advertise ask_inbox only while the hub is up and an integration is installed.
+ */
+/** How long a shutdown waits for saves, notifications and a report in flight before it gives up and lets the lock go. */
+const SHUTDOWN_WAIT_MS = 5000;
+/**
+ * How long advertisement() waits for a start in progress. The full daemon's first heartbeat can come before the hub is
+ * up; without the wait it would leave ask_inbox out, the Gateway would stop sending ask keys, and the stored deliveries
+ * would end. Bounded, so a heartbeat, and the job claim behind it, is never held up longer than this.
+ */
+export const ADVERTISEMENT_START_WAIT_MS = 2000;
+function errorCode(error) {
+    const code = error?.code;
+    if (typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code))
+        return code;
+    const message = error instanceof Error ? error.message : "";
+    return /^[A-Z0-9_]{1,64}$/.test(message) ? message : "UNKNOWN";
+}
+export class AskRuntime {
+    deps;
+    controller = new AbortController();
+    inbox;
+    hub;
+    started = false;
+    /** The one start of this run, kept so advertisement() can wait for it; null until start() is called. */
+    starting = null;
+    flushing = null;
+    flushAgain = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.inbox = new AskInbox({ store: new AskStore(deps.stateRoot), now: deps.now, notify: deps.notify ?? createNotifier({ log: event => this.log(event) }),
+            onChange: () => this.flushSoon(), log: event => this.log(event) });
+        this.hub = new AskHub({ socketPath: hubSocketPath(deps.stateRoot), handler: this.inbox, log: event => this.log(event) });
+    }
+    /** True while the hub listens; only then are deliveries taken and ask_inbox advertised. */
+    get ready() {
+        return this.started;
+    }
+    /**
+     * Never throws, and runs once per daemon run. Without a hub (it cannot listen, or the stored state cannot be read:
+     * the next save would overwrite it), deliveries are left to the Gateway, which sends Slack when they are not received.
+     */
+    start() {
+        this.starting ??= this.startOnce();
+        return this.starting;
+    }
+    async startOnce() {
+        try {
+            await this.inbox.load();
+            await this.hub.start();
+            this.started = true;
+        }
+        catch (error) {
+            this.log({ event: "ask_hub_unavailable", code: errorCode(error) });
+            return;
+        }
+        // Installed integrations keep running the hook client of the release that runs now.
+        try {
+            await refreshShim({ stateRoot: this.deps.stateRoot });
+        }
+        catch (error) {
+            this.log({ event: "ask_shim_refresh_failed", code: errorCode(error) });
+        }
+    }
+    /**
+     * Shutdown, inside the daemon lock: waiting watchers are released, the hub stops, then saves, notifications and a
+     * report in flight are waited for, for at most SHUTDOWN_WAIT_MS. Safe to call again.
+     */
+    async stop() {
+        this.started = false;
+        this.controller.abort();
+        this.inbox.releaseAll("shutdown");
+        try {
+            await this.hub.stop();
+        }
+        catch { /* A socket left behind is removed at the next start. */ }
+        const settled = (async () => {
+            await this.flushing?.catch(() => undefined);
+            await this.inbox.idle();
+        })();
+        let timer;
+        const timedOut = await Promise.race([
+            settled.then(() => false, () => false),
+            new Promise(resolve => { timer = setTimeout(() => resolve(true), this.deps.shutdownWaitMs ?? SHUTDOWN_WAIT_MS); }),
+        ]);
+        clearTimeout(timer);
+        if (timedOut)
+            this.log({ event: "ask_shutdown_timed_out" });
+    }
+    /**
+     * Takes the ask keys of one session-open wait result. Reports go out in the background. Never throws.
+     *
+     * The Gateway sends ask_deliveries (and closed_delivery_ids) only while asks are on for this runner: the switch is on,
+     * the runner's person is a pilot actor and it has stored this runner's ask_inbox. A result without ask_deliveries
+     * therefore means asks are off, and every stored delivery ends here with no report: the Gateway's fallback owns them.
+     * A result with the key present but empty changes nothing.
+     *
+     * Resolves false when the result's closures could not be handled (the hub is down, or closing failed), so the push
+     * transport does not acknowledge them and the Gateway lists them again (Work Item 25d8ea74).
+     */
+    async handleWait(result) {
+        if (!this.started)
+            return false;
+        let closuresHandled = true;
+        try {
+            if (result.askDeliveries === undefined) {
+                await this.inbox.endAll();
+                return true;
+            }
+            if (result.closedDeliveryIds !== undefined && result.closedDeliveryIds.length > 0) {
+                closuresHandled = false;
+                await this.inbox.close(result.closedDeliveryIds);
+                closuresHandled = true;
+            }
+            if (result.askDeliveries.length > 0)
+                await this.inbox.receive(result.askDeliveries);
+        }
+        catch (error) {
+            this.log({ event: "ask_delivery_failed", code: errorCode(error) });
+        }
+        this.flushSoon();
+        return closuresHandled;
+    }
+    /**
+     * heartbeat runner.session_open.ask_inbox, or undefined when the hub is down or nothing is installed. While a start is
+     * in progress it waits for it, for at most ADVERTISEMENT_START_WAIT_MS; before start() it answers at once.
+     */
+    async advertisement() {
+        if (!this.started && this.starting !== null)
+            await this.waitForStart(this.starting);
+        if (!this.started)
+            return undefined;
+        let apps = [];
+        try {
+            apps = await (this.deps.installedApps ?? (() => installedApps(this.deps.env, this.deps.stateRoot)))();
+        }
+        catch {
+            apps = [];
+        }
+        return apps.length > 0 ? { version: 1, apps: [...apps] } : undefined;
+    }
+    /** Resolves when the start settles or the bound passes, whichever comes first. Never rejects: start() never throws. */
+    async waitForStart(starting) {
+        let timer;
+        await Promise.race([
+            starting,
+            new Promise(resolve => { timer = setTimeout(resolve, this.deps.advertisementStartWaitMs ?? ADVERTISEMENT_START_WAIT_MS); }),
+        ]);
+        clearTimeout(timer);
+    }
+    /** One flush at a time; a request that arrives during a flush runs it once more afterwards. */
+    flush() {
+        if (this.flushing !== null) {
+            this.flushAgain = true;
+            return this.flushing;
+        }
+        this.flushing = (async () => {
+            try {
+                do {
+                    this.flushAgain = false;
+                    await this.inbox.flush(this.deps.report, this.controller.signal);
+                } while (this.flushAgain && !this.controller.signal.aborted);
+            }
+            finally {
+                this.flushing = null;
+            }
+        })();
+        return this.flushing;
+    }
+    flushSoon() {
+        if (this.started)
+            void this.flush().catch(error => { if (!this.controller.signal.aborted)
+                this.log({ event: "ask_report_failed", code: errorCode(error) }); });
+    }
+    log(event) {
+        try {
+            this.deps.log?.(event);
+        }
+        catch { /* Logging never stops delivery. */ }
+    }
+}
+/** Runs the asks hub for exactly as long as the session-open loop: started before its first wait, stopped after its last. */
+export function withAsks(asks, loop) {
+    return {
+        async run() {
+            await asks.start();
+            try {
+                await loop.run();
+            }
+            finally {
+                await asks.stop();
+            }
+        },
+        stop() {
+            loop.stop();
+        },
+    };
+}

package/dist/src/asks/shim.js

@@ -0,0 +1,78 @@
+import { access, chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/*
+ * The stable hook entry point <stateRoot>/bin/gateway-hook (Work Item e1c08b33, spec section 8.3). Claude Code and
+ * Codex run only this path, so the hook command never changes when the runner is upgraded and Codex does not ask
+ * for trust again. The shim names the Node executable and hook client of the release that wrote it; the daemon
+ * rewrites it at start so it follows the running release.
+ */
+export const SHIM_FILE = join("bin", "gateway-hook");
+// Paths go into single quotes in the shim and double quotes in hook commands; only characters that stay literal in
+// both are allowed (the same set as the PreToolUse hook command), so no quote, $, backquote or backslash.
+const SAFE_PATH = /^[A-Za-z0-9._/:@+~,=% -]+$/;
+export function shimPath(stateRoot) {
+    return join(stateRoot, SHIM_FILE);
+}
+/** The hook client installed next to this module (dist/src/asks/hook-client.js in the package). */
+export function hookClientScript() {
+    return fileURLToPath(new URL("./hook-client.js", import.meta.url));
+}
+function safePath(label, path) {
+    if (!isAbsolute(path) || !SAFE_PATH.test(path)) {
+        // The code is set as well, so the logs that keep only an error's code name it.
+        throw Object.assign(new Error(`ASK_HOOK_PATH_UNSAFE: the ${label} path must be absolute and free of quotes and shell characters`), { code: "ASK_HOOK_PATH_UNSAFE" });
+    }
+    return path;
+}
+/** The command line in every installed hook. It names only the shim, the app and the event. */
+export function hookCommand(stateRoot, app, event) {
+    return `"${safePath("shim", shimPath(stateRoot))}" ${app} ${event}`;
+}
+export function renderShim(input) {
+    const node = safePath("Node executable", input.nodePath);
+    const client = safePath("hook client", input.clientPath);
+    const stateRoot = safePath("state root", input.stateRoot);
+    return [
+        "#!/bin/sh",
+        "# Written by mtech-ai-local-runner for AI Gateway asks. The runner rewrites this file; do not edit it.",
+        `node='${node}'`,
+        `client='${client}'`,
+        "# A runner release that is gone must never disturb a session: print nothing and succeed.",
+        "[ -x \"$node\" ] && [ -f \"$client\" ] || exit 0",
+        `exec "$node" "$client" '--state-root=${stateRoot}' "$@"`,
+        "",
+    ].join("\n");
+}
+/** Writes the shim atomically with mode 0755 for this release. Returns whether its content changed. */
+export async function writeShim(input) {
+    const path = shimPath(input.stateRoot);
+    const content = renderShim({ nodePath: input.nodePath ?? process.execPath, clientPath: input.clientPath ?? hookClientScript(), stateRoot: input.stateRoot });
+    if (await readFile(path, "utf8").catch(() => null) === content)
+        return { path, changed: false };
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode: 0o755 });
+        await chmod(temporary, 0o755);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    return { path, changed: true };
+}
+/** Points an existing shim at the running release. It never creates one: installing an integration does. */
+export async function refreshShim(input) {
+    try {
+        await access(shimPath(input.stateRoot));
+    }
+    catch {
+        return false;
+    }
+    return (await writeShim(input)).changed;
+}
+export async function removeShim(stateRoot) {
+    await rm(shimPath(stateRoot), { force: true });
+}