@mulmoclaude/core 1.8.0 → 1.10.0

package/dist/remote-host/server/index.js

@@ -1,6 +1,6 @@
 import { t as errorMessage } from "../../dist-Cwk0e12G.js";
-import { buildHostPresence, byCreatedAt, commandsCollection, hostDoc, isExpired } from "../index.js";
-import { deleteDoc, getFirestore, onSnapshot, query, runTransaction, serverTimestamp, setDoc, updateDoc, where } from "firebase/firestore";
+import { a as hostDoc, i as commandsCollection, n as buildHostPresence, o as isExpired, r as byCreatedAt } from "../../remote-host-D_BRFHcI.js";
+import { deleteDoc, getDocFromServer, getFirestore, onSnapshot, query, runTransaction, serverTimestamp, setDoc, updateDoc, where } from "firebase/firestore";
 import { GoogleAuthProvider, getAuth, initializeAuth, signInWithCredential, signOut } from "firebase/auth";
 import { deleteApp, initializeApp } from "firebase/app";
 import { getStorage } from "firebase/storage";
@@ -9,25 +9,36 @@ var isPlainObject = (value) => {
 	return proto === Object.prototype || proto === null;
 };
 var isWalkable = (value) => typeof value === "object" && value !== null && (Array.isArray(value) || isPlainObject(value));
-/** Every path holding `undefined`, in `a.b.0.c` form. Empty when the value is safe to write. */
-var undefinedPaths = (value, prefix = "") => {
+var childPath = (prefix, key) => prefix ? `${prefix}.${key}` : String(key);
+var withCycleGuard = (value, ancestors, path, walk) => {
+	if (ancestors.has(value)) throw new Error(`circular reference at ${path || "(root)"} — Firestore cannot serialise it`);
+	ancestors.add(value);
+	try {
+		return walk();
+	} finally {
+		ancestors.delete(value);
+	}
+};
+var pathsIn = (value, prefix, ancestors) => {
 	if (value === void 0) return [prefix || "(root)"];
 	if (!isWalkable(value)) return [];
-	const child = (key) => prefix ? `${prefix}.${key}` : String(key);
-	if (Array.isArray(value)) return Array.from(value).flatMap((item, index) => undefinedPaths(item, child(index)));
-	return Object.entries(value).flatMap(([key, item]) => undefinedPaths(item, child(key)));
+	return withCycleGuard(value, ancestors, prefix, () => Array.isArray(value) ? Array.from(value).flatMap((item, index) => pathsIn(item, childPath(prefix, index), ancestors)) : Object.entries(value).flatMap(([key, item]) => pathsIn(item, childPath(prefix, key), ancestors)));
+};
+/** Every path holding `undefined`, in `a.b.0.c` form. Empty when the value is safe to write.
+*  Throws on a circular reply, naming the path it closed the loop at. */
+var undefinedPaths = (value, prefix = "") => pathsIn(value, prefix, /* @__PURE__ */ new WeakSet());
+var strippedIn = (value, prefix, ancestors) => {
+	if (value === void 0) return null;
+	if (!isWalkable(value)) return value;
+	return withCycleGuard(value, ancestors, prefix, () => Array.isArray(value) ? Array.from(value, (item, index) => strippedIn(item, childPath(prefix, index), ancestors)) : Object.fromEntries(Object.entries(value).flatMap(([key, item]) => item === void 0 ? [] : [[key, strippedIn(item, childPath(prefix, key), ancestors)]])));
 };
 /**
 * The same value with every `undefined` removed — object keys dropped, array holes
 * turned into `null` so the surrounding indexes still line up with what the sender
 * meant. Returns `unknown` because a stripped object is no longer the input type.
+* Throws on a circular reply, same as `undefinedPaths`.
 */
-var stripUndefined = (value) => {
-	if (value === void 0) return null;
-	if (!isWalkable(value)) return value;
-	if (Array.isArray(value)) return Array.from(value, (item) => stripUndefined(item));
-	return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => item === void 0 ? [] : [[key, stripUndefined(item)]]));
-};
+var stripUndefined = (value) => strippedIn(value, "", /* @__PURE__ */ new WeakSet());
 /** Does `path` match `pattern`, where `*` stands for exactly one segment?
 *  Segment-wise rather than by regex: no escaping of user-supplied dots, and no
 *  pattern can turn into a catastrophic backtrack. */
@@ -49,6 +60,42 @@ var matchesPathPattern = (path, pattern) => {
 */
 var unexpectedPaths = (paths, expected = []) => paths.filter((path) => !expected.some((pattern) => matchesPathPattern(path, pattern)));
 //#endregion
+//#region src/remote-host/server/presenceBeat.ts
+var PRESENCE_STALE_BEATS = 3;
+var errorText$1 = (error) => error instanceof Error ? error.message : String(error);
+var notify = (report, onThrow) => {
+	try {
+		report();
+	} catch (error) {
+		onThrow?.(error);
+	}
+};
+var createPresenceBeat = (deps) => {
+	const now = deps.now ?? Date.now;
+	const state = { lastAckMs: now() };
+	const announce = (online) => {
+		const fail = (error) => notify(() => deps.onError(errorText$1(error)));
+		const ack = () => notify(() => {
+			state.lastAckMs = now();
+		});
+		notify(() => {
+			deps.write(online).then(ack, fail);
+		}, fail);
+	};
+	const beat = () => {
+		const silentMs = now() - state.lastAckMs;
+		if (silentMs >= deps.staleAfterMs) {
+			notify(() => deps.onStale(silentMs));
+			return;
+		}
+		announce(true);
+	};
+	return {
+		announce,
+		beat
+	};
+};
+//#endregion
 //#region src/remote-host/server/hostRunner.ts
 var DEFAULT_HEARTBEAT_MS = 6e4;
 var TRANSIENT_LISTEN_ERROR_CODES = /* @__PURE__ */ new Set([
@@ -57,6 +104,7 @@ var TRANSIENT_LISTEN_ERROR_CODES = /* @__PURE__ */ new Set([
 	"deadline-exceeded",
 	"internal",
 	"resource-exhausted",
+	"unauthenticated",
 	"unavailable"
 ]);
 var isRecord$1 = (value) => typeof value === "object" && value !== null;
@@ -64,6 +112,8 @@ var listenErrorCode = (error) => isRecord$1(error) && typeof error.code === "str
 var classifyListenerError = (error) => TRANSIENT_LISTEN_ERROR_CODES.has(listenErrorCode(error)) ? "transient" : "fatal";
 var BASE_LISTEN_RETRY_MS = 1e3;
 var MAX_LISTEN_RETRY_MS = 3e4;
+var LISTEN_RETRY_WINDOW_MS = 5 * 6e4;
+var shouldGiveUpListening = (downSinceMs, now, windowMs = LISTEN_RETRY_WINDOW_MS) => now - downSinceMs >= windowMs;
 var backoffDelayMs = (attempt) => Math.min(MAX_LISTEN_RETRY_MS, BASE_LISTEN_RETRY_MS * 2 ** attempt);
 var noop$2 = () => void 0;
 var writeError = (ref, code, message) => updateDoc(ref, {
@@ -187,7 +237,9 @@ function handleListenError(run, error) {
 		message: error.message
 	});
 	if (run.stopped) return;
-	if (classifyListenerError(error) === "fatal" || run.attempt >= 5) {
+	const now = Date.now();
+	run.downSinceMs ??= now;
+	if (classifyListenerError(error) === "fatal" || shouldGiveUpListening(run.downSinceMs, now)) {
 		run.goOffline();
 		return;
 	}
@@ -198,6 +250,7 @@ function subscribeCommands(run) {
 	if (run.stopped) return;
 	run.unsubscribe = onSnapshot(run.queuedCommands, (snapshot) => {
 		run.attempt = 0;
+		run.downSinceMs = null;
 		dispatchAddedCommands(run.ctx, snapshot);
 	}, (error) => handleListenError(run, error));
 }
@@ -209,7 +262,8 @@ var listenForCommands = (queuedCommands, ctx, goOffline) => {
 		stopped: false,
 		unsubscribe: noop$2,
 		retryTimer: null,
-		attempt: 0
+		attempt: 0,
+		downSinceMs: null
 	};
 	subscribeCommands(run);
 	return () => {
@@ -218,36 +272,265 @@ var listenForCommands = (queuedCommands, ctx, goOffline) => {
 		run.unsubscribe();
 	};
 };
-var startHostRunner = (firestore, channel, handlers, options = {}) => {
+var heartbeatMs = (options) => options.heartbeatMs ?? 6e4;
+var presenceStaleAfterMs = (options = {}) => heartbeatMs(options) * 3;
+var buildPresenceBeat = (firestore, channel, handlers, options, onStale) => {
 	const presence = hostDoc(firestore, channel);
-	const writePresence = (online) => {
-		setDoc(presence, {
+	const report = (message) => options.onEvent?.({
+		phase: "error",
+		method: "presence",
+		message
+	});
+	return createPresenceBeat({
+		write: (online) => setDoc(presence, {
 			...buildHostPresence(channel, handlers, online),
 			updatedAt: serverTimestamp()
-		}).catch(noop$2);
-	};
-	const announce = () => {
-		writePresence(true);
+		}),
+		onError: (message) => report(`presence write failed: ${message}`),
+		onStale: (silentMs) => {
+			report(`no presence write acknowledged for ${Math.round(silentMs / 1e3)}s — the remote cannot see this host`);
+			onStale();
+		},
+		staleAfterMs: presenceStaleAfterMs(options)
+	});
+};
+var shutDown = (run, presence) => {
+	if (run.closed) return;
+	run.closed = true;
+	if (run.beat) clearInterval(run.beat);
+	run.beat = null;
+	presence.announce(false);
+	run.stopListening();
+};
+var startHostRunner = (firestore, channel, handlers, options = {}) => {
+	const run = {
+		beat: null,
+		stopListening: noop$2,
+		closed: false
 	};
-	announce();
-	const beat = setInterval(announce, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
-	const queuedCommands = query(commandsCollection(firestore, channel), where("status", "==", "queued"));
-	const ctx = {
+	const presence = buildPresenceBeat(firestore, channel, handlers, options, goOffline);
+	function goOffline() {
+		if (run.closed) return;
+		shutDown(run, presence);
+		options.onClosed?.();
+	}
+	presence.announce(true);
+	run.beat = setInterval(presence.beat, heartbeatMs(options));
+	run.stopListening = listenForCommands(query(commandsCollection(firestore, channel), where("status", "==", "queued")), {
 		firestore,
 		handlers,
 		options,
 		uid: channel.uid
+	}, goOffline);
+	return () => shutDown(run, presence);
+};
+//#endregion
+//#region src/remote-host/server/resilientRunner.ts
+var ONE_SECOND_MS$1 = 1e3;
+var ONE_MINUTE_MS = 60 * ONE_SECOND_MS$1;
+var RECONNECT_BASE_MS = ONE_SECOND_MS$1;
+var RECONNECT_MAX_MS = ONE_MINUTE_MS;
+var SETTLE_MS = ONE_MINUTE_MS;
+var GIVE_UP_MS = 5 * ONE_MINUTE_MS;
+var PROBE_INTERVAL_MS = 90 * ONE_SECOND_MS$1;
+var reconnectDelayMs = (attempt) => Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
+var errorText = (error) => error instanceof Error ? error.message : String(error);
+var scheduleWithTimeout = (task, delayMs) => {
+	const timer = setTimeout(task, delayMs);
+	return () => clearTimeout(timer);
+};
+var setState = (ctx, next) => {
+	ctx.state = next;
+	try {
+		ctx.deps.onHealth?.({
+			state: next,
+			lastError: ctx.lastError,
+			changedAt: ctx.now()
+		});
+	} catch (error) {
+		ctx.deps.log.warn(`host runner health observer threw: ${errorText(error)}`);
+	}
+};
+var clearTimer = (ctx) => {
+	ctx.cancelTimer?.();
+	ctx.cancelTimer = null;
+};
+var clearProbe = (ctx) => {
+	ctx.cancelProbe?.();
+	ctx.cancelProbe = null;
+};
+function scheduleProbe(ctx) {
+	if (ctx.stopped || !ctx.deps.checkAlive) return;
+	clearProbe(ctx);
+	ctx.cancelProbe = ctx.schedule(() => void runProbe(ctx), PROBE_INTERVAL_MS);
+}
+var STALE_REASON = "presence went stale — the phone can no longer see this host";
+async function askAlive(ctx) {
+	try {
+		return {
+			alive: await ctx.deps.checkAlive?.() ?? null,
+			reason: STALE_REASON
+		};
+	} catch (error) {
+		return {
+			alive: false,
+			reason: `presence probe failed: ${errorText(error)}`
+		};
+	}
+}
+async function runProbe(ctx) {
+	ctx.cancelProbe = null;
+	if (ctx.stopped || ctx.state !== "online") return;
+	const answer = await askAlive(ctx);
+	if (ctx.stopped || ctx.state !== "online") return;
+	if (answer.alive === false) {
+		ctx.lastError = answer.reason;
+		ctx.deps.log.warn(`host runner ${answer.reason}`);
+		onUnderlyingClosed(ctx);
+		return;
+	}
+	scheduleProbe(ctx);
+}
+var releaseUnderlying = (ctx) => {
+	const stop = ctx.stopUnderlying;
+	ctx.stopUnderlying = null;
+	try {
+		stop?.();
+	} catch (error) {
+		ctx.deps.log.warn(`host runner teardown failed: ${errorText(error)}`);
+	}
+};
+var markRecovered = (ctx) => {
+	ctx.downSinceMs = null;
+	ctx.attempt = 0;
+	ctx.lastError = null;
+	if (ctx.state === "online") return;
+	ctx.deps.log.info("host runner re-subscribed");
+	setState(ctx, "online");
+	scheduleProbe(ctx);
+};
+async function settle(ctx) {
+	ctx.cancelTimer = null;
+	if (ctx.stopped) return;
+	const answer = await askAlive(ctx);
+	if (ctx.stopped) return;
+	if (answer.alive === false) {
+		ctx.lastError = answer.reason;
+		ctx.deps.log.warn(`host runner is up but still unreachable — ${answer.reason}`);
+		onUnderlyingClosed(ctx);
+		return;
+	}
+	markRecovered(ctx);
+}
+var giveUp = (ctx) => {
+	ctx.stopped = true;
+	clearProbe(ctx);
+	ctx.deps.log.warn(`host runner stayed down for ${Math.round(GIVE_UP_MS / ONE_SECOND_MS$1)}s, giving up (${ctx.lastError ?? "no error reported"})`);
+	setState(ctx, "offline");
+	ctx.deps.options.onClosed?.();
+};
+function scheduleRelaunch(ctx) {
+	const delayMs = reconnectDelayMs(ctx.attempt);
+	ctx.attempt += 1;
+	ctx.deps.log.warn(`host runner closed (${ctx.lastError ?? "no error reported"}); re-subscribing in ${Math.round(delayMs / ONE_SECOND_MS$1)}s`);
+	if (ctx.state !== "reconnecting") setState(ctx, "reconnecting");
+	ctx.cancelTimer = ctx.schedule(() => launch(ctx), delayMs);
+}
+function onUnderlyingClosed(ctx) {
+	if (ctx.stopped) return;
+	releaseUnderlying(ctx);
+	clearTimer(ctx);
+	clearProbe(ctx);
+	ctx.downSinceMs ??= ctx.now();
+	if (ctx.now() - ctx.downSinceMs >= GIVE_UP_MS) giveUp(ctx);
+	else scheduleRelaunch(ctx);
+}
+var CHANNEL_METHODS = /* @__PURE__ */ new Set(["listen", "presence"]);
+var runnerOptions = (ctx) => ({
+	...ctx.deps.options,
+	onEvent: (event) => {
+		if (event.phase === "error") {
+			const text = `${event.method}: ${event.message ?? "no detail"}`;
+			if (CHANNEL_METHODS.has(event.method)) ctx.lastError = text;
+			ctx.deps.log.warn(`host runner event error — ${text}`);
+		}
+		ctx.deps.options.onEvent?.(event);
+	},
+	onClosed: () => onUnderlyingClosed(ctx)
+});
+function launch(ctx) {
+	ctx.cancelTimer = null;
+	if (ctx.stopped) return;
+	try {
+		ctx.stopUnderlying = ctx.deps.start(runnerOptions(ctx));
+	} catch (error) {
+		ctx.lastError = errorText(error);
+		onUnderlyingClosed(ctx);
+		return;
+	}
+	ctx.cancelTimer = ctx.schedule(() => void settle(ctx), SETTLE_MS);
+}
+function startResilientHostRunner(deps) {
+	const ctx = {
+		deps,
+		schedule: deps.schedule ?? scheduleWithTimeout,
+		now: deps.now ?? Date.now,
+		stopUnderlying: null,
+		cancelTimer: null,
+		attempt: 0,
+		downSinceMs: null,
+		lastError: null,
+		state: "online",
+		stopped: false,
+		cancelProbe: null
 	};
-	const goOffline = () => {
-		clearInterval(beat);
-		writePresence(false);
-		options.onClosed?.();
-	};
-	const stopListening = listenForCommands(queuedCommands, ctx, goOffline);
+	setState(ctx, "online");
+	launch(ctx);
+	scheduleProbe(ctx);
 	return () => {
-		clearInterval(beat);
-		writePresence(false);
-		stopListening();
+		ctx.stopped = true;
+		clearTimer(ctx);
+		clearProbe(ctx);
+		releaseUnderlying(ctx);
+	};
+}
+//#endregion
+//#region src/remote-host/server/presenceProbe.ts
+var ONE_SECOND_MS = 1e3;
+var PRESENCE_STALE_MS = presenceStaleAfterMs();
+var PROBE_TIMEOUT_MS = 30 * ONE_SECOND_MS;
+var hasToMillis = (value) => "toMillis" in value && typeof Reflect.get(value, "toMillis") === "function";
+var asMillis = (value) => {
+	if (typeof value === "number") return value;
+	if (typeof value === "object" && value !== null && hasToMillis(value)) return value.toMillis();
+	return null;
+};
+/** Judge a presence document that was read successfully. Exported for its own test:
+*  the freshness rule is the part worth pinning, and it needs no Firestore. */
+var presenceIsFresh = (data, now, staleAfterMs = PRESENCE_STALE_MS) => {
+	if (!data) return null;
+	const updatedAt = asMillis(data.updatedAt);
+	if (updatedAt === null) return null;
+	if (data.online === false) return null;
+	return now - updatedAt < staleAfterMs;
+};
+/** Reject once `timeoutMs` has passed, so a stalled read answers instead of hanging. */
+var withTimeout = async (work, timeoutMs) => {
+	const timer = { handle: null };
+	const deadline = new Promise((_, reject) => {
+		timer.handle = setTimeout(() => reject(/* @__PURE__ */ new Error(`presence read did not answer within ${Math.round(timeoutMs / ONE_SECOND_MS)}s`)), timeoutMs);
+	});
+	try {
+		return await Promise.race([work, deadline]);
+	} finally {
+		if (timer.handle) clearTimeout(timer.handle);
+	}
+};
+/** Reads the host's own presence document from the server and reports whether it is fresh. */
+var createPresenceProbe = (deps) => {
+	const now = deps.now ?? Date.now;
+	return async () => {
+		return presenceIsFresh((await withTimeout(getDocFromServer(hostDoc(deps.firestore(), deps.channel)), deps.timeoutMs ?? PROBE_TIMEOUT_MS)).data(), now(), deps.staleAfterMs ?? PRESENCE_STALE_MS);
 	};
 };
 //#endregion
@@ -258,6 +541,7 @@ var silentLogger = {
 	warn: noop$1,
 	debug: noop$1
 };
+var eventText = (event) => event.message ? `${event.phase} ${event.method} — ${event.message}` : `${event.phase} ${event.method}`;
 var createRemoteHost = (deps) => {
 	const log = deps.log ?? silentLogger;
 	let stopRunner = null;
@@ -283,7 +567,7 @@ var createRemoteHost = (deps) => {
 			uid,
 			hostId: deps.hostId
 		}, deps.handlers, {
-			onEvent: (event) => log.debug(`host event: ${event.phase} ${event.method}`),
+			onEvent: (event) => log.debug(`host event: ${eventText(event)}`),
 			onExpire: deps.onExpire,
 			onClosed: () => {
 				if (stopRunner === runner) {
@@ -480,6 +764,6 @@ var createRemoteHostSession = (config) => {
 	};
 };
 //#endregion
-export { createHostSessionPersistence, createRemoteHost, createRemoteHostAuth, createRemoteHostFirebase, createRemoteHostSession, isSeedableBlob, startHostRunner, stripUndefined, undefinedPaths, unexpectedPaths };
+export { DEFAULT_HEARTBEAT_MS, LISTEN_RETRY_WINDOW_MS, PRESENCE_STALE_BEATS, PRESENCE_STALE_MS, createHostSessionPersistence, createPresenceProbe, createRemoteHost, createRemoteHostAuth, createRemoteHostFirebase, createRemoteHostSession, isSeedableBlob, presenceIsFresh, presenceStaleAfterMs, reconnectDelayMs, startHostRunner, startResilientHostRunner, stripUndefined, undefinedPaths, unexpectedPaths, withTimeout };
 
 //# sourceMappingURL=index.js.map