mtech-ai-local-runner 0.1.46 → 0.1.48

package/dist/src/asks/integrations.js

@@ -0,0 +1,433 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, copyFile, mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { hookCommand, removeShim, writeShim } from "./shim.js";
+import { APPS } from "./types.js";
+/*
+ * Installing the AI Gateway asks hooks into the employee's own Claude Code and Codex (Work Item e1c08b33, spec
+ * section 8.4). Only on request: setup --integrations or integrations install. Setup never asks.
+ *
+ * Claude Code: a skills-directory plugin, ~/.claude/skills/mtec-ai-gateway-asks/ with .claude-plugin/plugin.json
+ * and hooks/hooks.json. It loads as mtec-ai-gateway-asks@skills-dir with no install step; settings.json is never
+ * touched. Codex: four handlers appended to ~/.codex/hooks.json after a backup of the file. Codex parses that file
+ * strictly (unknown top-level keys make it skip the whole file) and keys hook trust by position, so the handlers
+ * carry no extra fields, are appended after the person's own hooks, and are found again by their command: a
+ * quoted path ending in /mtec-ai-local-runner/bin/gateway-hook, then "codex" and the event. Every handler runs the
+ * stable shim only, so a runner upgrade changes no hook and Codex never asks for trust again.
+ *
+ * The apps' homes can move (CLAUDE_CONFIG_DIR, CODEX_HOME), but the LaunchAgent that runs the daemon gets only PATH.
+ * So every install adds the dir it used to a list per app in <stateRoot>/integrations.json, and every check and removal
+ * looks in the dir the current environment names and in every recorded one. A dir leaves the list only when nothing of
+ * this runner's is left in it, so a second install into another dir never orphans the first.
+ */
+export const CLAUDE_PLUGIN_NAME = "mtec-ai-gateway-asks";
+const CLAUDE_HOOKS_DESCRIPTION = "AI Gateway asks from colleagues, shown by mtech-ai-local-runner. Remove with: npx mtech-ai-local-runner integrations remove claude";
+const CODEX_FILE_DESCRIPTION = "Hooks written by mtech-ai-local-runner for AI Gateway asks.";
+const RUNNER_CODEX_COMMAND = /^"[^"]*\/mtec-ai-local-runner\/bin\/gateway-hook" codex (session-start|prompt|stop|session-end)$/;
+/** <stateRoot>/integrations.json: the app dirs that installs used, for the daemon, doctor, remove and uninstall. */
+export const INTEGRATIONS_FILE = "integrations.json";
+const RECORD_KEYS = { claude: "claude_config_dir", codex: "codex_home" };
+/** The person's home: HOME, else the account's home directory. Never a relative path. */
+function homeDirectory(env) {
+    let account = "";
+    try {
+        account = os.homedir();
+    }
+    catch { /* No home for this account either. */ }
+    for (const candidate of [env.HOME, account]) {
+        if (candidate && isAbsolute(candidate))
+            return candidate;
+    }
+    throw new Error("INTEGRATION_HOME_UNKNOWN: no absolute home directory was found. Set HOME, or CLAUDE_CONFIG_DIR and CODEX_HOME.");
+}
+/** CLAUDE_CONFIG_DIR moves Claude Code's home; the default is ~/.claude. */
+export function claudeConfigDir(env) {
+    return env.CLAUDE_CONFIG_DIR ? resolve(env.CLAUDE_CONFIG_DIR) : join(homeDirectory(env), ".claude");
+}
+/** CODEX_HOME moves Codex's home; the default is ~/.codex. */
+export function codexHome(env) {
+    return env.CODEX_HOME ? resolve(env.CODEX_HOME) : join(homeDirectory(env), ".codex");
+}
+const claudePluginDirIn = (configDir) => join(configDir, "skills", CLAUDE_PLUGIN_NAME);
+const codexHooksFileIn = (home) => join(home, "hooks.json");
+/**
+ * Where the current environment says the integrations live. Throws INTEGRATION_HOME_UNKNOWN when it names no home.
+ * It ignores <stateRoot>/integrations.json: callers that want what is installed must use integrationStatus or installedApps.
+ */
+export function integrationPaths(env) {
+    return { claudePluginDir: claudePluginDirIn(claudeConfigDir(env)), codexHooksFile: codexHooksFileIn(codexHome(env)) };
+}
+export function claudePluginManifest() {
+    return { name: CLAUDE_PLUGIN_NAME, version: "1.0.0", description: "Shows AI Gateway asks and answers from colleagues in this session.",
+        author: { name: "MTEC AI Gateway" } };
+}
+/** hooks/hooks.json of the Claude plugin. The Stop hook is the asyncRewake watcher, with a 3600 s timeout. */
+export function claudeHooksFile(stateRoot) {
+    const handler = (event, extra = {}) => ({ type: "command", command: hookCommand(stateRoot, "claude", event), ...extra });
+    return { description: CLAUDE_HOOKS_DESCRIPTION, hooks: {
+            SessionStart: [{ hooks: [handler("session-start", { timeout: 10 })] }],
+            UserPromptSubmit: [{ hooks: [handler("prompt", { timeout: 10 })] }],
+            Stop: [{ hooks: [handler("stop", { asyncRewake: true, timeout: 3600 })] }],
+            SessionEnd: [{ hooks: [handler("session-end")] }],
+        } };
+}
+/** The four Codex matcher groups. Never change them: Codex trusts a hook by its hash, which covers these fields. */
+export function codexHookGroups(stateRoot) {
+    const group = (event, timeout) => ({ hooks: [{ type: "command", command: hookCommand(stateRoot, "codex", event), timeout }] });
+    return { SessionStart: group("session-start", 10), UserPromptSubmit: group("prompt", 10), Stop: group("stop", 10), SessionEnd: group("session-end", 3) };
+}
+function isRunnerCodexHandler(handler) {
+    const command = handler?.command;
+    return typeof command === "string" && RUNNER_CODEX_COMMAND.test(command);
+}
+/** Codex's hooks.json as a plain object, refusing any shape this code would not edit safely. */
+export function parseCodexHooks(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("CODEX_HOOKS_JSON_INVALID");
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("CODEX_HOOKS_JSON_INVALID");
+    const hooks = value.hooks;
+    if (hooks !== undefined && (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)))
+        throw new Error("CODEX_HOOKS_JSON_INVALID");
+    for (const groups of Object.values(hooks ?? {})) {
+        if (!Array.isArray(groups) || groups.some(group => group === null || typeof group !== "object" || !Array.isArray(group.hooks))) {
+            throw new Error("CODEX_HOOKS_JSON_INVALID");
+        }
+    }
+    return value;
+}
+/** This runner's handlers in a document, as one string per handler (its event and the handler), whichever state root wrote them. */
+function runnerCodexEntries(document) {
+    return Object.entries(document.hooks ?? {}).flatMap(([event, groups]) => groups.flatMap(group => group.hooks.filter(isRunnerCodexHandler).map(handler => JSON.stringify({ event, handler }))));
+}
+/** True when the document holds exactly the four handlers this runner writes for this state root, wherever they sit. */
+function hasCurrentRunnerCodexHooks(document, stateRoot) {
+    const ours = runnerCodexEntries(document);
+    const expected = Object.entries(codexHookGroups(stateRoot)).map(([event, group]) => JSON.stringify({ event, handler: group.hooks[0] }));
+    return ours.length === expected.length && expected.every(entry => ours.includes(entry));
+}
+/** The document without this runner's handlers. A group or event list left empty by that is dropped too. */
+export function withoutRunnerCodexHooks(document) {
+    const hooks = {};
+    let changed = false;
+    for (const [event, groups] of Object.entries(document.hooks ?? {})) {
+        const kept = [];
+        for (const group of groups) {
+            const handlers = group.hooks.filter(handler => !isRunnerCodexHandler(handler));
+            if (handlers.length === group.hooks.length) {
+                kept.push(group);
+                continue;
+            }
+            changed = true;
+            if (handlers.length > 0)
+                kept.push({ ...group, hooks: handlers });
+        }
+        if (kept.length > 0 || groups.length === 0)
+            hooks[event] = kept;
+    }
+    return { document: document.hooks === undefined ? document : { ...document, hooks }, changed };
+}
+/**
+ * The document with this runner's four groups appended after everything else, replacing any older copies.
+ * A document that already holds exactly the current four is left as it is: moving them behind hooks the person
+ * added since would move those hooks' trust keys.
+ */
+export function withRunnerCodexHooks(document, stateRoot) {
+    if (hasCurrentRunnerCodexHooks(document, stateRoot))
+        return { document, changed: false };
+    const stripped = withoutRunnerCodexHooks(document).document;
+    const hooks = { ...stripped.hooks ?? {} };
+    for (const [event, group] of Object.entries(codexHookGroups(stateRoot))) {
+        hooks[event] = [...hooks[event] ?? [], group];
+    }
+    const next = { ...stripped, hooks };
+    return { document: next, changed: JSON.stringify(next) !== JSON.stringify(document) };
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function writeAtomic(path, content, mode) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode, flag: "wx" });
+        await chmod(temporary, mode);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+/** Copies the Codex hooks file aside before it is changed. A backup is never overwritten. */
+async function backup(path, now) {
+    const target = `${path}.mtec-ai-local-runner-${new Date(now).toISOString().replace(/[:.]/g, "-")}.bak`;
+    await copyFile(path, target, constants.COPYFILE_EXCL);
+    return target;
+}
+const pretty = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** 0600 temporary file, fsync, rename, directory fsync: the idiom of the ask store. */
+async function writeDurable(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(content);
+            await file.sync();
+        }
+        catch (error) {
+            await file.close().catch(() => undefined);
+            throw error;
+        }
+        await file.close();
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    const directory = await open(dirname(path), "r");
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+/**
+ * The recorded dirs. A missing, unreadable or malformed record counts as no record, and a value that is not an absolute
+ * path is left out. A record written before the lists held one dir per app as a string: that is a list of one.
+ */
+async function readRecord(stateRoot) {
+    const record = { claude_config_dir: [], codex_home: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(join(stateRoot, INTEGRATIONS_FILE), "utf8"));
+    }
+    catch {
+        return record;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return record;
+    for (const key of [RECORD_KEYS.claude, RECORD_KEYS.codex]) {
+        const value = parsed[key];
+        const dirs = typeof value === "string" ? [value] : Array.isArray(value) ? value : [];
+        for (const dir of dirs) {
+            if (typeof dir === "string" && isAbsolute(dir) && !record[key].includes(dir))
+                record[key].push(dir);
+        }
+    }
+    return record;
+}
+/** Saves the record; an app with no dir left is left out, and the file is deleted when neither has one. */
+async function saveRecord(stateRoot, record) {
+    const path = join(stateRoot, INTEGRATIONS_FILE);
+    if (record.claude_config_dir.length === 0 && record.codex_home.length === 0) {
+        await rm(path, { force: true });
+        return;
+    }
+    await writeDurable(path, pretty({
+        ...(record.claude_config_dir.length === 0 ? {} : { claude_config_dir: record.claude_config_dir }),
+        ...(record.codex_home.length === 0 ? {} : { codex_home: record.codex_home }),
+    }));
+}
+/** Adds a dir to the app's list; one already there is not added again. */
+async function recordDirectory(app, dir, stateRoot) {
+    const record = await readRecord(stateRoot);
+    const key = RECORD_KEYS[app];
+    if (record[key].includes(dir))
+        return;
+    await saveRecord(stateRoot, { ...record, [key]: [...record[key], dir] });
+}
+/** The plugin dir or hooks file of an app in one of its dirs. */
+const placeIn = (app, dir) => (app === "claude" ? claudePluginDirIn(dir) : codexHooksFileIn(dir));
+/** The plugin dir or hooks file in each place to look: the one the environment names first, then every recorded one. */
+async function placesOf(app, env, stateRoot) {
+    const places = [placeIn(app, app === "claude" ? claudeConfigDir(env) : codexHome(env))];
+    for (const dir of (await readRecord(stateRoot))[RECORD_KEYS[app]]) {
+        const place = placeIn(app, dir);
+        if (!places.includes(place))
+            places.push(place);
+    }
+    return places;
+}
+async function claudeState(pluginDir, stateRoot) {
+    let manifest;
+    let hooks;
+    // Only a missing file means nothing is installed; any other read error leaves the state unknown.
+    try {
+        manifest = await readOptional(join(pluginDir, ".claude-plugin", "plugin.json"));
+        hooks = await readOptional(join(pluginDir, "hooks", "hooks.json"));
+    }
+    catch {
+        return "unreadable";
+    }
+    if (manifest === null && hooks === null)
+        return "not_installed";
+    return manifest === pretty(claudePluginManifest()) && hooks === pretty(claudeHooksFile(stateRoot)) ? "installed" : "outdated";
+}
+async function codexState(hooksFile, stateRoot) {
+    let raw;
+    try {
+        raw = await readOptional(hooksFile);
+    }
+    catch {
+        return "unreadable";
+    }
+    if (raw === null)
+        return "not_installed";
+    let document;
+    try {
+        document = parseCodexHooks(raw);
+    }
+    catch {
+        return "unreadable";
+    }
+    if (runnerCodexEntries(document).length === 0)
+        return "not_installed";
+    return hasCurrentRunnerCodexHooks(document, stateRoot) ? "installed" : "outdated";
+}
+const STATE_ORDER = ["installed", "outdated", "unreadable", "not_installed"];
+/**
+ * An app counts as installed when the dir the environment names or any recorded dir has this runner's hooks.
+ * The report names the place behind the strongest state, in the order installed, outdated, unreadable, not installed.
+ */
+export async function integrationStatus(app, env, stateRoot) {
+    const places = await placesOf(app, env, stateRoot);
+    const states = await Promise.all(places.map(place => app === "claude" ? claudeState(place, stateRoot) : codexState(place, stateRoot)));
+    for (const state of STATE_ORDER) {
+        const index = states.indexOf(state);
+        if (index >= 0)
+            return { app, state, path: places[index] };
+    }
+    return { app, state: "not_installed", path: places[0] };
+}
+/**
+ * Installs one app's hooks in the dir the environment names. An app already installed there exactly as this runner
+ * writes it is skipped and reported installed: its files are not rewritten. The shim (a no-op when it already runs this
+ * release) and the record of the dir are still made sure of, so the hooks there keep working.
+ */
+export async function installIntegration(app, env, stateRoot, options = {}) {
+    const shim = () => writeShim({ stateRoot, nodePath: options.nodePath, clientPath: options.clientPath });
+    if (app === "claude") {
+        // A home that cannot be found throws here, before anything is written.
+        const configDir = claudeConfigDir(env);
+        const pluginDir = claudePluginDirIn(configDir);
+        await shim();
+        // The dir is recorded before the hooks are written, so the daemon never misses hooks that exist.
+        await recordDirectory("claude", configDir, stateRoot);
+        if (await claudeState(pluginDir, stateRoot) === "installed")
+            return { app, state: "installed", path: pluginDir };
+        await writeAtomic(join(pluginDir, ".claude-plugin", "plugin.json"), pretty(claudePluginManifest()), 0o644);
+        await writeAtomic(join(pluginDir, "hooks", "hooks.json"), pretty(claudeHooksFile(stateRoot)), 0o644);
+        return { app, state: "installed", path: pluginDir };
+    }
+    const home = codexHome(env);
+    const hooksFile = codexHooksFileIn(home);
+    // The Codex file is read and checked before anything is written, so one that does not parse leaves no shim behind either.
+    const raw = await readOptional(hooksFile);
+    const current = raw === null ? { description: CODEX_FILE_DESCRIPTION } : parseCodexHooks(raw);
+    const { document, changed } = withRunnerCodexHooks(current, stateRoot);
+    await shim();
+    await recordDirectory("codex", home, stateRoot);
+    if (!changed)
+        return { app, state: "installed", path: hooksFile };
+    const saved = raw === null ? undefined : await backup(hooksFile, options.now ?? Date.now());
+    const mode = raw === null ? 0o600 : (await stat(hooksFile)).mode & 0o777;
+    await writeAtomic(hooksFile, pretty(document), mode);
+    return { app, state: "installed", path: hooksFile, ...(saved ? { backup: saved } : {}) };
+}
+async function removeClaudeAt(pluginDir) {
+    const manifest = await readOptional(join(pluginDir, ".claude-plugin", "plugin.json"));
+    // Only a directory this runner wrote is removed.
+    if (manifest === null || JSON.parse(manifest).name !== CLAUDE_PLUGIN_NAME)
+        return { changed: false };
+    await rm(pluginDir, { recursive: true, force: true });
+    return { changed: true };
+}
+async function removeCodexAt(hooksFile, now) {
+    const raw = await readOptional(hooksFile);
+    if (raw === null)
+        return { changed: false };
+    const { document, changed } = withoutRunnerCodexHooks(parseCodexHooks(raw));
+    if (!changed)
+        return { changed: false };
+    const saved = await backup(hooksFile, now);
+    if (Object.keys(document.hooks ?? {}).length === 0 && document.description === CODEX_FILE_DESCRIPTION && Object.keys(document).length === 2) {
+        await rm(hooksFile, { force: true });
+    }
+    else {
+        await writeAtomic(hooksFile, pretty(document), (await stat(hooksFile)).mode & 0o777);
+    }
+    return { changed: true, backup: saved };
+}
+/**
+ * Removes this runner's hooks from the dir the environment names and from every recorded one, then drops from the
+ * record each dir where nothing of ours is left. A place that fails does not stop the others, and its dir stays
+ * recorded; the first failure is thrown at the end.
+ */
+export async function removeIntegration(app, env, stateRoot, options = {}) {
+    const places = await placesOf(app, env, stateRoot);
+    const now = options.now ?? Date.now();
+    const cleaned = [];
+    let failure;
+    for (const place of places) {
+        try {
+            const result = app === "claude" ? await removeClaudeAt(place) : await removeCodexAt(place, now);
+            if (result.changed)
+                cleaned.push({ path: place, ...(result.backup ? { backup: result.backup } : {}) });
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    try {
+        const record = await readRecord(stateRoot);
+        const key = RECORD_KEYS[app];
+        const kept = [];
+        for (const dir of record[key]) {
+            const place = placeIn(app, dir);
+            // A dir leaves the record only when nothing of this runner's is left there.
+            if ((app === "claude" ? await claudeState(place, stateRoot) : await codexState(place, stateRoot)) !== "not_installed")
+                kept.push(dir);
+        }
+        if (kept.length !== record[key].length)
+            await saveRecord(stateRoot, { ...record, [key]: kept });
+    }
+    catch (error) {
+        failure ??= error;
+    }
+    if (failure !== undefined)
+        throw failure;
+    const [first, ...others] = cleaned;
+    return { app, state: (await integrationStatus(app, env, stateRoot)).state, path: first?.path ?? places[0],
+        ...(first?.backup ? { backup: first.backup } : {}), ...(others.length > 0 ? { alsoCleaned: others } : {}) };
+}
+/** ask_inbox.apps: the integrations installed exactly as this runner writes them. */
+export async function installedApps(env, stateRoot) {
+    const reports = await Promise.all(APPS.map(app => integrationStatus(app, env, stateRoot)));
+    return reports.filter(report => report.state === "installed").map(report => report.app);
+}
+/** Removes the shim once no integration uses it any more: no place the environment names or the record lists has our hooks. */
+export async function removeShimIfUnused(env, stateRoot) {
+    const reports = await Promise.all(APPS.map(app => integrationStatus(app, env, stateRoot)));
+    if (reports.some(report => report.state !== "not_installed"))
+        return false;
+    await removeShim(stateRoot);
+    return true;
+}

package/dist/src/asks/messenger.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { McpGatewayClient } from "../gateway-client.js";
+import { Daemon } from "../daemon/daemon.js";
+import { ProcessLock } from "../daemon/process-lock.js";
+import { runnerDisplayName } from "../daemon/runtime.js";
+import { SessionOpener, sessionOpenAdvertisement } from "../daemon/session-opener.js";
+import { SessionOpenPoller, abortableDelay } from "../daemon/session-open-poller.js";
+import { packageVersion } from "../package-version.js";
+import { AskRuntime, withAsks } from "./runtime.js";
+/*
+ * Messenger mode (Work Item e1c08b33, spec section 8.1). Setup chose it because no executor is admitted on
+ * this Mac. The daemon runs the session-open loop only: there is no jobs loop, no adapter probe, no PreToolUse
+ * self-test and no executor host, so nothing built here can start an executor.
+ */
+/** A messenger has no jobs loop, so its session-open loop sends the heartbeat: at daemon start, then every 600 s. */
+export const MESSENGER_HEARTBEAT_MS = 600_000;
+const HEARTBEAT_RETRY_MS = 60_000;
+/**
+ * The waits before resending a heartbeat that had to leave session_open out, one after another: 60, 120, 240 s, then the
+ * regular 600 s for as long as session-open detection keeps failing. A heartbeat that carries session_open resets it.
+ * Retrying every minute would cost about ten times the heartbeat calls of an idle runner.
+ */
+export const PARTIAL_HEARTBEAT_RETRY_MS = [60_000, 120_000, 240_000, MESSENGER_HEARTBEAT_MS];
+/** Stands in for the job poller: it keeps the daemon alive until stop() and never asks for a job. */
+export function idleJobPoller() {
+    let release;
+    const stopped = new Promise(resolve => { release = resolve; });
+    return {
+        async run() {
+            // A pending promise alone does not keep Node alive; this referenced timer does until stop().
+            const timer = setInterval(() => undefined, 60_000);
+            try {
+                await stopped;
+            }
+            finally {
+                clearInterval(timer);
+            }
+        },
+        stop() { release(); },
+    };
+}
+/**
+ * Sends the heartbeat when it is due: at once, then every 600 s, and also as soon as what it advertises changes
+ * (an integration installed or removed). A failed one is retried a minute later. One that went out without session_open
+ * (send resolves false) is retried after PARTIAL_HEARTBEAT_RETRY_MS: the Gateway then keeps the session_open, and the
+ * ask_inbox, it stored last, so what this beat would have advertised does not count as sent.
+ */
+export function messengerHeartbeat(send, options = {}) {
+    const now = options.now ?? Date.now;
+    let dueAt = Number.NEGATIVE_INFINITY;
+    /** What the Gateway was last told; unset until a beat carried session_open. Unset, only the time decides. */
+    let sentKey;
+    /** Heartbeats in a row that had to leave session_open out. */
+    let partials = 0;
+    return async (signal) => {
+        let key = sentKey ?? "";
+        try {
+            key = options.advertised ? await options.advertised() : "";
+        }
+        catch { /* Unchanged as far as we know. */ }
+        if (now() < dueAt && (sentKey === undefined || key === sentKey))
+            return;
+        sentKey = key;
+        try {
+            if (await send(signal) === false) {
+                sentKey = undefined;
+                dueAt = now() + PARTIAL_HEARTBEAT_RETRY_MS[Math.min(partials, PARTIAL_HEARTBEAT_RETRY_MS.length - 1)];
+                partials += 1;
+            }
+            else {
+                partials = 0;
+                dueAt = now() + MESSENGER_HEARTBEAT_MS;
+            }
+        }
+        catch (error) {
+            dueAt = now() + HEARTBEAT_RETRY_MS;
+            const code = error?.code;
+            if (!signal.aborted)
+                options.reportError?.(typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : "UNKNOWN");
+        }
+    };
+}
+export async function buildMessengerDaemon(input) {
+    const log = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); };
+    const home = input.env.HOME ?? "";
+    const gateway = new McpGatewayClient({ mcpUrl: input.gatewayMcpUrl, tokenProvider: input.tokenProvider, runnerId: input.runnerId, fetchFn: input.fetchFn });
+    const asks = new AskRuntime({ stateRoot: input.stateRoot, env: input.env, now: input.now, log, installedApps: input.installedApps,
+        report: (deliveryId, report, signal) => gateway.reportAskDelivery({ deliveryId, ...report }, signal) });
+    const heartbeat = messengerHeartbeat(async (signal) => {
+        let sessionOpen;
+        // A detection error only leaves session_open out; the Gateway keeps what it stored.
+        try {
+            sessionOpen = await sessionOpenAdvertisement({ home });
+        }
+        catch {
+            sessionOpen = undefined;
+        }
+        const askInbox = await asks.advertisement();
+        await gateway.heartbeatLocalRunner({
+            deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
+            displayName: runnerDisplayName(), packageVersion: packageVersion(), capabilities: [], mode: "messenger",
+            // Without an integration, session_open still goes out (clients only): the Gateway keeps the last one it stored, and would keep long-polling for asks.
+            ...(sessionOpen ? { sessionOpen: { ...sessionOpen, ...(askInbox ? { ask_inbox: askInbox } : {}) } } : {}),
+        }, signal);
+        // Without session_open the Gateway keeps its stored ask_inbox, which may be stale: send again, backing off.
+        return sessionOpen !== undefined;
+    }, { now: input.now, reportError: code => log({ event: "messenger_heartbeat_failed", code }),
+        advertised: async () => JSON.stringify(await asks.advertisement() ?? null) });
+    const opener = new SessionOpener({ home });
+    const sessionOpens = new SessionOpenPoller({
+        wait: async (signal) => {
+            await heartbeat(signal);
+            const result = await gateway.waitForSessionOpens(25, signal);
+            await asks.handleWait(result);
+            return result;
+        },
+        open: request => opener.open(request),
+        report: async (openId, result, signal) => {
+            await gateway.reportSessionOpen({ openId, status: result.status, surface: result.surface,
+                failureCode: result.status === "failed" ? result.failureCode : undefined }, signal);
+        },
+        delay: abortableDelay,
+        reportError: diagnostic => log({ event: "session_open_poller_failed", ...diagnostic }),
+    });
+    const daemon = new Daemon({
+        lock: new ProcessLock(join(input.stateRoot, "daemon.lock")),
+        // Job state belongs to a full runner: a messenger never reads, reconciles or suspends on it.
+        state: { load: async () => null },
+        reconcile: async () => undefined,
+        poller: idleJobPoller(),
+        sessionOpens: withAsks(asks, sessionOpens),
+    });
+    return { daemon, close: async () => { daemon.stop(); } };
+}

package/dist/src/asks/notifier.js

@@ -0,0 +1,73 @@
+import { execFile as nodeExecFile } from "node:child_process";
+/*
+ * The macOS notification for a delivery with no live session to go to (Work Item e1c08b33, spec section 8.5).
+ * One per delivery, a fixed text per subject type and direction, no buttons. /usr/bin/osascript runs through
+ * execFile, never a shell, and the text reaches AppleScript as an argument, never as script source.
+ */
+const ASK_TEXT = {
+    decision: "AI Gateway: a colleague asked you for a decision. Open Claude or ChatGPT to see it.",
+    review: "AI Gateway: a colleague asked you for a review. Open Claude or ChatGPT to see it.",
+    request: "AI Gateway: a colleague asked you for an answer. Open Claude or ChatGPT to see it.",
+};
+const ANSWER_TEXT = {
+    decision: "AI Gateway: your decision request has been answered. Open Claude or ChatGPT to continue.",
+    review: "AI Gateway: your review request has been answered. Open Claude or ChatGPT to continue.",
+    request: "AI Gateway: your work request has been answered. Open Claude or ChatGPT to continue.",
+};
+export const OSASCRIPT = "/usr/bin/osascript";
+const SCRIPT = ["on run argv", "display notification (item 1 of argv) with title \"AI Gateway\"", "end run"];
+/**
+ * How long one notification may take. A hung osascript is killed after this, and a notifier that is still not done
+ * by then is given up on, so a delivery's notification can never hold AskInbox.idle(), and so a shutdown, for longer.
+ * Shorter than the asks runtime's shutdown wait (5 s), so the notification gives up before the shutdown has to.
+ */
+export const NOTIFY_TIMEOUT_MS = 3_000;
+export function notificationText(item) {
+    return (item.direction === "ask" ? ASK_TEXT : ANSWER_TEXT)[item.subjectType];
+}
+/** The arguments osascript gets: the fixed script, then the text as its only argument. */
+export function notificationArguments(text) {
+    return [...SCRIPT.flatMap(line => ["-e", line]), text];
+}
+const TIMEOUT_CODE = "NOTIFIER_TIMEOUT";
+function failureCode(error) {
+    const failure = error;
+    // execFile kills a process that outlives its timeout and reports it as killed, with no code of its own.
+    if (failure?.killed === true)
+        return TIMEOUT_CODE;
+    return typeof failure?.code === "string" && /^[A-Z0-9_]{1,64}$/.test(failure.code) ? failure.code : "UNKNOWN";
+}
+/** Resolves when the work does, and rejects with the timeout code when it has not by then. Never leaves the timer running. */
+function within(work, timeoutMs) {
+    let timer;
+    const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(Object.assign(new Error(TIMEOUT_CODE), { code: TIMEOUT_CODE })), timeoutMs);
+    });
+    // A run that throws before it returns a promise is a failure like any other.
+    const started = new Promise(resolve => resolve(work()));
+    return Promise.race([started, limit]).then(() => undefined).finally(() => clearTimeout(timer));
+}
+/** Resolves true when macOS took the notification; false off macOS or when osascript fails or hangs. */
+export function createNotifier(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const timeoutMs = deps.timeoutMs ?? NOTIFY_TIMEOUT_MS;
+    const exec = deps.execFile ?? nodeExecFile;
+    const run = deps.run ?? ((file, args) => new Promise((resolve, reject) => {
+        exec(file, args, { timeout: timeoutMs, killSignal: "SIGKILL" }, error => (error ? reject(error) : resolve(undefined)));
+    }));
+    return async (item) => {
+        if (platform !== "darwin")
+            return false;
+        try {
+            await within(() => run(OSASCRIPT, notificationArguments(notificationText(item))), timeoutMs);
+            return true;
+        }
+        catch (error) {
+            try {
+                deps.log?.({ event: "ask_notifier_failed", code: failureCode(error) });
+            }
+            catch { /* Logging never stops delivery. */ }
+            return false;
+        }
+    };
+}