@poolzin/pool-bot 2026.2.24 → 2026.2.25

package/dist/gateway/server-methods/nodes.js

@@ -1,36 +1,182 @@
-import { approveNodePairing, listNodePairing, rejectNodePairing, renamePairedNode, requestNodePairing, verifyNodeToken, } from "../../infra/node-pairing.js";
-import { listDevicePairing } from "../../infra/device-pairing.js";
-import { ErrorCodes, errorShape, validateNodeDescribeParams, validateNodeEventParams, validateNodeInvokeParams, validateNodeInvokeResultParams, validateNodeListParams, validateNodePairApproveParams, validateNodePairListParams, validateNodePairRejectParams, validateNodePairRequestParams, validateNodePairVerifyParams, validateNodeRenameParams, } from "../protocol/index.js";
-import { respondInvalidParams, respondUnavailableOnThrow, safeParseJson, uniqueSortedStrings, } from "./nodes.helpers.js";
 import { loadConfig } from "../../config/config.js";
+import { listDevicePairing } from "../../infra/device-pairing.js";
+import { approveNodePairing, listNodePairing, rejectNodePairing, renamePairedNode, requestNodePairing, verifyNodeToken, } from "../../infra/node-pairing.js";
+import { loadApnsRegistration, resolveApnsAuthConfigFromEnv, sendApnsAlert, sendApnsBackgroundWake, } from "../../infra/push-apns.js";
 import { isNodeCommandAllowed, resolveNodeCommandAllowlist } from "../node-command-policy.js";
+import { sanitizeNodeInvokeParamsForForwarding } from "../node-invoke-sanitize.js";
+import { ErrorCodes, errorShape, validateNodeDescribeParams, validateNodeEventParams, validateNodeInvokeParams, validateNodeListParams, validateNodePairApproveParams, validateNodePairListParams, validateNodePairRejectParams, validateNodePairRequestParams, validateNodePairVerifyParams, validateNodeRenameParams, } from "../protocol/index.js";
+import { handleNodeInvokeResult } from "./nodes.handlers.invoke-result.js";
+import { respondInvalidParams, respondUnavailableOnNodeInvokeError, respondUnavailableOnThrow, safeParseJson, uniqueSortedStrings, } from "./nodes.helpers.js";
+const NODE_WAKE_RECONNECT_WAIT_MS = 3_000;
+const NODE_WAKE_RECONNECT_RETRY_WAIT_MS = 12_000;
+const NODE_WAKE_RECONNECT_POLL_MS = 150;
+const NODE_WAKE_THROTTLE_MS = 15_000;
+const NODE_WAKE_NUDGE_THROTTLE_MS = 10 * 60_000;
+const nodeWakeById = new Map();
+const nodeWakeNudgeById = new Map();
 function isNodeEntry(entry) {
-    if (entry.clientMode === "node")
+    if (entry.role === "node") {
         return true;
-    if (entry.role === "node")
-        return true;
-    if (Array.isArray(entry.roles) && entry.roles.includes("node"))
+    }
+    if (Array.isArray(entry.roles) && entry.roles.includes("node")) {
         return true;
+    }
     return false;
 }
-function normalizeNodeInvokeResultParams(params) {
-    if (!params || typeof params !== "object")
-        return params;
-    const raw = params;
-    const normalized = { ...raw };
-    if (normalized.payloadJSON === null) {
-        delete normalized.payloadJSON;
+async function delayMs(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function maybeWakeNodeWithApns(nodeId, opts) {
+    const state = nodeWakeById.get(nodeId) ?? { lastWakeAtMs: 0 };
+    nodeWakeById.set(nodeId, state);
+    if (state.inFlight) {
+        return await state.inFlight;
+    }
+    const now = Date.now();
+    const force = opts?.force === true;
+    if (!force && state.lastWakeAtMs > 0 && now - state.lastWakeAtMs < NODE_WAKE_THROTTLE_MS) {
+        return { available: true, throttled: true, path: "throttled", durationMs: 0 };
+    }
+    state.inFlight = (async () => {
+        const startedAtMs = Date.now();
+        const withDuration = (attempt) => ({
+            ...attempt,
+            durationMs: Math.max(0, Date.now() - startedAtMs),
+        });
+        try {
+            const registration = await loadApnsRegistration(nodeId);
+            if (!registration) {
+                return withDuration({ available: false, throttled: false, path: "no-registration" });
+            }
+            const auth = await resolveApnsAuthConfigFromEnv(process.env);
+            if (!auth.ok) {
+                return withDuration({
+                    available: false,
+                    throttled: false,
+                    path: "no-auth",
+                    apnsReason: auth.error,
+                });
+            }
+            state.lastWakeAtMs = Date.now();
+            const wakeResult = await sendApnsBackgroundWake({
+                auth: auth.value,
+                registration,
+                nodeId,
+                wakeReason: "node.invoke",
+            });
+            if (!wakeResult.ok) {
+                return withDuration({
+                    available: true,
+                    throttled: false,
+                    path: "send-error",
+                    apnsStatus: wakeResult.status,
+                    apnsReason: wakeResult.reason,
+                });
+            }
+            return withDuration({
+                available: true,
+                throttled: false,
+                path: "sent",
+                apnsStatus: wakeResult.status,
+                apnsReason: wakeResult.reason,
+            });
+        }
+        catch (err) {
+            // Best-effort wake only.
+            const message = err instanceof Error ? err.message : String(err);
+            if (state.lastWakeAtMs === 0) {
+                return withDuration({
+                    available: false,
+                    throttled: false,
+                    path: "send-error",
+                    apnsReason: message,
+                });
+            }
+            return withDuration({
+                available: true,
+                throttled: false,
+                path: "send-error",
+                apnsReason: message,
+            });
+        }
+    })();
+    try {
+        return await state.inFlight;
+    }
+    finally {
+        state.inFlight = undefined;
+    }
+}
+async function maybeSendNodeWakeNudge(nodeId) {
+    const startedAtMs = Date.now();
+    const withDuration = (attempt) => ({
+        ...attempt,
+        durationMs: Math.max(0, Date.now() - startedAtMs),
+    });
+    const lastNudgeAtMs = nodeWakeNudgeById.get(nodeId) ?? 0;
+    if (lastNudgeAtMs > 0 && Date.now() - lastNudgeAtMs < NODE_WAKE_NUDGE_THROTTLE_MS) {
+        return withDuration({ sent: false, throttled: true, reason: "throttled" });
+    }
+    const registration = await loadApnsRegistration(nodeId);
+    if (!registration) {
+        return withDuration({ sent: false, throttled: false, reason: "no-registration" });
+    }
+    const auth = await resolveApnsAuthConfigFromEnv(process.env);
+    if (!auth.ok) {
+        return withDuration({
+            sent: false,
+            throttled: false,
+            reason: "no-auth",
+            apnsReason: auth.error,
+        });
     }
-    else if (normalized.payloadJSON !== undefined && typeof normalized.payloadJSON !== "string") {
-        if (normalized.payload === undefined) {
-            normalized.payload = normalized.payloadJSON;
+    try {
+        const result = await sendApnsAlert({
+            auth: auth.value,
+            registration,
+            nodeId,
+            title: "Pool Bot needs a quick reopen",
+            body: "Tap to reopen Pool Bot and restore the node connection.",
+        });
+        if (!result.ok) {
+            return withDuration({
+                sent: false,
+                throttled: false,
+                reason: "apns-not-ok",
+                apnsStatus: result.status,
+                apnsReason: result.reason,
+            });
         }
-        delete normalized.payloadJSON;
+        nodeWakeNudgeById.set(nodeId, Date.now());
+        return withDuration({
+            sent: true,
+            throttled: false,
+            reason: "sent",
+            apnsStatus: result.status,
+            apnsReason: result.reason,
+        });
     }
-    if (normalized.error === null) {
-        delete normalized.error;
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return withDuration({
+            sent: false,
+            throttled: false,
+            reason: "send-error",
+            apnsReason: message,
+        });
+    }
+}
+async function waitForNodeReconnect(params) {
+    const timeoutMs = Math.max(250, params.timeoutMs ?? NODE_WAKE_RECONNECT_WAIT_MS);
+    const pollMs = Math.max(50, params.pollMs ?? NODE_WAKE_RECONNECT_POLL_MS);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (params.context.nodeRegistry.get(params.nodeId)) {
+            return true;
+        }
+        await delayMs(pollMs);
     }
-    return normalized;
+    return Boolean(params.context.nodeRegistry.get(params.nodeId));
 }
 export const nodeHandlers = {
     "node.pair.request": async ({ params, respond, context }) => {
@@ -227,14 +373,17 @@ export const nodeHandlers = {
                 };
             });
             nodes.sort((a, b) => {
-                if (a.connected !== b.connected)
+                if (a.connected !== b.connected) {
                     return a.connected ? -1 : 1;
+                }
                 const an = (a.displayName ?? a.nodeId).toLowerCase();
                 const bn = (b.displayName ?? b.nodeId).toLowerCase();
-                if (an < bn)
+                if (an < bn) {
                     return -1;
-                if (an > bn)
+                }
+                if (an > bn) {
                     return 1;
+                }
                 return a.nodeId.localeCompare(b.nodeId);
             });
             respond(true, { ts: Date.now(), nodes }, undefined);
@@ -287,7 +436,7 @@ export const nodeHandlers = {
             }, undefined);
         });
     },
-    "node.invoke": async ({ params, respond, context }) => {
+    "node.invoke": async ({ params, respond, context, client, req }) => {
         if (!validateNodeInvokeParams(params)) {
             respondInvalidParams({
                 respond,
@@ -303,13 +452,69 @@ export const nodeHandlers = {
             respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "nodeId and command required"));
             return;
         }
+        if (command === "system.execApprovals.get" || command === "system.execApprovals.set") {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "node.invoke does not allow system.execApprovals.*; use exec.approvals.node.*", { details: { command } }));
+            return;
+        }
         await respondUnavailableOnThrow(respond, async () => {
-            const nodeSession = context.nodeRegistry.get(nodeId);
+            let nodeSession = context.nodeRegistry.get(nodeId);
             if (!nodeSession) {
-                respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "node not connected", {
-                    details: { code: "NOT_CONNECTED" },
-                }));
-                return;
+                const wakeReqId = req.id;
+                const wakeFlowStartedAtMs = Date.now();
+                context.logGateway.info(`node wake start node=${nodeId} req=${wakeReqId} command=${command}`);
+                const wake = await maybeWakeNodeWithApns(nodeId);
+                context.logGateway.info(`node wake stage=wake1 node=${nodeId} req=${wakeReqId} ` +
+                    `available=${wake.available} throttled=${wake.throttled} ` +
+                    `path=${wake.path} durationMs=${wake.durationMs} ` +
+                    `apnsStatus=${wake.apnsStatus ?? -1} apnsReason=${wake.apnsReason ?? "-"}`);
+                if (wake.available) {
+                    const waitStartedAtMs = Date.now();
+                    const waitTimeoutMs = NODE_WAKE_RECONNECT_WAIT_MS;
+                    const reconnected = await waitForNodeReconnect({
+                        nodeId,
+                        context,
+                        timeoutMs: waitTimeoutMs,
+                    });
+                    const waitDurationMs = Math.max(0, Date.now() - waitStartedAtMs);
+                    context.logGateway.info(`node wake stage=wait1 node=${nodeId} req=${wakeReqId} ` +
+                        `reconnected=${reconnected} timeoutMs=${waitTimeoutMs} durationMs=${waitDurationMs}`);
+                }
+                nodeSession = context.nodeRegistry.get(nodeId);
+                if (!nodeSession && wake.available) {
+                    const retryWake = await maybeWakeNodeWithApns(nodeId, { force: true });
+                    context.logGateway.info(`node wake stage=wake2 node=${nodeId} req=${wakeReqId} force=true ` +
+                        `available=${retryWake.available} throttled=${retryWake.throttled} ` +
+                        `path=${retryWake.path} durationMs=${retryWake.durationMs} ` +
+                        `apnsStatus=${retryWake.apnsStatus ?? -1} apnsReason=${retryWake.apnsReason ?? "-"}`);
+                    if (retryWake.available) {
+                        const waitStartedAtMs = Date.now();
+                        const waitTimeoutMs = NODE_WAKE_RECONNECT_RETRY_WAIT_MS;
+                        const reconnected = await waitForNodeReconnect({
+                            nodeId,
+                            context,
+                            timeoutMs: waitTimeoutMs,
+                        });
+                        const waitDurationMs = Math.max(0, Date.now() - waitStartedAtMs);
+                        context.logGateway.info(`node wake stage=wait2 node=${nodeId} req=${wakeReqId} ` +
+                            `reconnected=${reconnected} timeoutMs=${waitTimeoutMs} durationMs=${waitDurationMs}`);
+                    }
+                    nodeSession = context.nodeRegistry.get(nodeId);
+                }
+                if (!nodeSession) {
+                    const totalDurationMs = Math.max(0, Date.now() - wakeFlowStartedAtMs);
+                    const nudge = await maybeSendNodeWakeNudge(nodeId);
+                    context.logGateway.info(`node wake nudge node=${nodeId} req=${wakeReqId} sent=${nudge.sent} ` +
+                        `throttled=${nudge.throttled} reason=${nudge.reason} durationMs=${nudge.durationMs} ` +
+                        `apnsStatus=${nudge.apnsStatus ?? -1} apnsReason=${nudge.apnsReason ?? "-"}`);
+                    context.logGateway.warn(`node wake done node=${nodeId} req=${wakeReqId} connected=false ` +
+                        `reason=not_connected totalMs=${totalDurationMs}`);
+                    respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "node not connected", {
+                        details: { code: "NOT_CONNECTED" },
+                    }));
+                    return;
+                }
+                const totalDurationMs = Math.max(0, Date.now() - wakeFlowStartedAtMs);
+                context.logGateway.info(`node wake done node=${nodeId} req=${wakeReqId} connected=true totalMs=${totalDurationMs}`);
             }
             const cfg = loadConfig();
             const allowlist = resolveNodeCommandAllowlist(cfg, nodeSession);
@@ -324,17 +529,26 @@ export const nodeHandlers = {
                 }));
                 return;
             }
+            const forwardedParams = sanitizeNodeInvokeParamsForForwarding({
+                command,
+                rawParams: p.params,
+                client,
+                execApprovalManager: context.execApprovalManager,
+            });
+            if (!forwardedParams.ok) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, forwardedParams.message, {
+                    details: forwardedParams.details ?? null,
+                }));
+                return;
+            }
             const res = await context.nodeRegistry.invoke({
                 nodeId,
                 command,
-                params: p.params,
+                params: forwardedParams.params,
                 timeoutMs: p.timeoutMs,
                 idempotencyKey: p.idempotencyKey,
             });
-            if (!res.ok) {
-                respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, res.error?.message ?? "node invoke failed", {
-                    details: { nodeError: res.error ?? null },
-                }));
+            if (!respondUnavailableOnNodeInvokeError(respond, res)) {
                 return;
             }
             const payload = res.payloadJSON ? safeParseJson(res.payloadJSON) : res.payload;
@@ -347,39 +561,7 @@ export const nodeHandlers = {
             }, undefined);
         });
     },
-    "node.invoke.result": async ({ params, respond, context, client }) => {
-        const normalizedParams = normalizeNodeInvokeResultParams(params);
-        if (!validateNodeInvokeResultParams(normalizedParams)) {
-            respondInvalidParams({
-                respond,
-                method: "node.invoke.result",
-                validator: validateNodeInvokeResultParams,
-            });
-            return;
-        }
-        const p = normalizedParams;
-        const callerNodeId = client?.connect?.device?.id ?? client?.connect?.client?.id;
-        if (callerNodeId && callerNodeId !== p.nodeId) {
-            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "nodeId mismatch"));
-            return;
-        }
-        const ok = context.nodeRegistry.handleInvokeResult({
-            id: p.id,
-            nodeId: p.nodeId,
-            ok: p.ok,
-            payload: p.payload,
-            payloadJSON: p.payloadJSON ?? null,
-            error: p.error ?? null,
-        });
-        if (!ok) {
-            // Late-arriving results (after invoke timeout) are expected and harmless.
-            // Return success instead of error to reduce log noise; client can discard.
-            context.logGateway.debug(`late invoke result ignored: id=${p.id} node=${p.nodeId}`);
-            respond(true, { ok: true, ignored: true }, undefined);
-            return;
-        }
-        respond(true, { ok: true }, undefined);
-    },
+    "node.invoke.result": handleNodeInvokeResult,
     "node.event": async ({ params, respond, context, client }) => {
         if (!validateNodeEventParams(params)) {
             respondInvalidParams({

package/dist/gateway/server-methods/push.js

@@ -0,0 +1,53 @@
+import { loadApnsRegistration, normalizeApnsEnvironment, resolveApnsAuthConfigFromEnv, sendApnsAlert, } from "../../infra/push-apns.js";
+import { ErrorCodes, errorShape, validatePushTestParams } from "../protocol/index.js";
+import { respondInvalidParams, respondUnavailableOnThrow } from "./nodes.helpers.js";
+function normalizeOptionalString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export const pushHandlers = {
+    "push.test": async ({ params, respond }) => {
+        if (!validatePushTestParams(params)) {
+            respondInvalidParams({
+                respond,
+                method: "push.test",
+                validator: validatePushTestParams,
+            });
+            return;
+        }
+        const nodeId = String(params.nodeId ?? "").trim();
+        if (!nodeId) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "nodeId required"));
+            return;
+        }
+        const title = normalizeOptionalString(params.title) ?? "Pool Bot";
+        const body = normalizeOptionalString(params.body) ?? `Push test for node ${nodeId}`;
+        await respondUnavailableOnThrow(respond, async () => {
+            const registration = await loadApnsRegistration(nodeId);
+            if (!registration) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `node ${nodeId} has no APNs registration (connect iOS node first)`));
+                return;
+            }
+            const auth = await resolveApnsAuthConfigFromEnv(process.env);
+            if (!auth.ok) {
+                respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, auth.error));
+                return;
+            }
+            const overrideEnvironment = normalizeApnsEnvironment(params.environment);
+            const result = await sendApnsAlert({
+                auth: auth.value,
+                registration: {
+                    ...registration,
+                    environment: overrideEnvironment ?? registration.environment,
+                },
+                nodeId,
+                title,
+                body,
+            });
+            respond(true, result, undefined);
+        });
+    },
+};

package/dist/gateway/server-reload-handlers.js

@@ -1,6 +1,6 @@
 import { startGmailWatcher, stopGmailWatcher } from "../hooks/gmail-watcher.js";
 import { resetDirectoryCache } from "../infra/outbound/target-resolver.js";
-import { authorizeGatewaySigusr1Restart, setGatewaySigusr1RestartPolicy, } from "../infra/restart.js";
+import { emitGatewayRestart, setGatewaySigusr1RestartPolicy } from "../infra/restart.js";
 import { setCommandLaneConcurrency } from "../process/command-queue.js";
 import { resolveAgentMaxConcurrent, resolveSubagentMaxConcurrent } from "../config/agent-limits.js";
 import { isTruthyEnvValue } from "../infra/env.js";
@@ -105,8 +105,7 @@ export function createGatewayReloadHandlers(params) {
             params.logReload.warn("no SIGUSR1 listener found; restart skipped");
             return;
         }
-        authorizeGatewaySigusr1Restart();
-        process.emit("SIGUSR1");
+        emitGatewayRestart();
     };
     return { applyHotReload, requestGatewayRestart };
 }

package/dist/gateway/server-runtime-config.js

@@ -13,6 +13,10 @@ export async function resolveGatewayRuntimeConfig(params) {
     const openResponsesConfig = params.cfg.gateway?.http?.endpoints?.responses;
     const openResponsesEnabled = params.openResponsesEnabled ?? openResponsesConfig?.enabled ?? false;
     const controlUiBasePath = normalizeControlUiBasePath(params.cfg.gateway?.controlUi?.basePath);
+    const controlUiRootRaw = params.cfg.gateway?.controlUi?.root;
+    const controlUiRoot = typeof controlUiRootRaw === "string" && controlUiRootRaw.trim().length > 0
+        ? controlUiRootRaw.trim()
+        : undefined;
     const authBase = params.cfg.gateway?.auth ?? {};
     const authOverrides = params.auth ?? {};
     const authConfig = {
@@ -56,6 +60,7 @@ export async function resolveGatewayRuntimeConfig(params) {
             ? { ...openResponsesConfig, enabled: openResponsesEnabled }
             : undefined,
         controlUiBasePath,
+        controlUiRoot,
         resolvedAuth,
         authMode,
         tailscaleConfig,

package/dist/gateway/server-runtime-state.js

@@ -60,6 +60,7 @@ export async function createGatewayRuntimeState(params) {
             handleHooksRequest,
             handlePluginRequest,
             resolvedAuth: params.resolvedAuth,
+            rateLimiter: params.rateLimiter,
             tlsOptions: params.gatewayTls?.enabled ? params.gatewayTls.tlsOptions : undefined,
         });
         try {
@@ -93,6 +94,7 @@ export async function createGatewayRuntimeState(params) {
             canvasHost,
             clients,
             resolvedAuth: params.resolvedAuth,
+            rateLimiter: params.rateLimiter,
         });
     }
     const agentRunSeq = new Map();

package/dist/gateway/server-ws-runtime.js

@@ -8,6 +8,7 @@ export function attachGatewayWsHandlers(params) {
         canvasHostEnabled: params.canvasHostEnabled,
         canvasHostServerPort: params.canvasHostServerPort,
         resolvedAuth: params.resolvedAuth,
+        rateLimiter: params.rateLimiter,
         gatewayMethods: params.gatewayMethods,
         events: params.events,
         logGateway: params.logGateway,