@helyx/bot 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.4.9
+
+### Patch Changes
+
+- Polish the Stage 4-6 resource dashboard and Discord flows, add durable
+  reaction-role controls, repair poll and giveaway lifecycle handling, and
+  strengthen shard-safe scheduling, retention, permissions and resource
+  inspection.
+- Updated dependencies
+  - @helyx/control-protocol@0.1.5
+  - @helyx/module-manifest@0.4.2
+  - @helyx/database@0.4.3
+  - @helyx/sdk@0.3.4
+  - @helyx/platform@0.2.7
+  - @helyx/core@0.1.9
+  - @helyx/framework@0.1.9
+
+## 0.4.8
+
+### Patch Changes
+
+- Updated dependencies
+  - @helyx/platform@0.2.6
+
 ## 0.4.7
 
 ### Patch Changes

package/dist/control-server.js

@@ -10,6 +10,7 @@ import { SHARD_HEALTH_STALE_MS, } from "./shard-contracts.js";
 const snowflake = z.string().regex(/^\d{17,20}$/u);
 const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
 const configurationValue = z.record(z.string(), z.union([
+    z.null(),
     z.string(),
     z.boolean(),
     z.number().finite(),
@@ -1099,7 +1100,7 @@ export async function createBotControlServer(input) {
         const body = mutationContext
             .extend({
             expectedRevision: z.number().int().min(0),
-            value: managedResourceObject,
+            value: managedResourceObject.optional().default({}),
         })
             .strict()
             .parse(request.body);

package/dist/discord-owned-message-service.js

@@ -21,7 +21,7 @@ export class DiscordOwnedMessageDeletionService {
             return { cleared: false };
         const reaction = message.reactions.resolve(emoji.cacheKey);
         if (!reaction)
-            return { cleared: false };
+            return { cleared: true };
         await reaction.remove();
         return { cleared: true };
     }
@@ -108,6 +108,14 @@ function prepareEmojiIdentifier(value) {
     if (value.length < 1 || value.length > 128 || /[\r\n]/u.test(value)) {
         throw new Error("Invalid bounded Discord emoji identifier");
     }
+    const canonicalCustom = /^custom:(\d{17,20})$/u.exec(value);
+    if (canonicalCustom) {
+        const id = canonicalCustom[1];
+        return { identifier: id, cacheKey: id };
+    }
+    const canonicalUnicode = /^unicode:(.+)$/u.exec(value);
+    if (canonicalUnicode)
+        value = canonicalUnicode[1];
     const custom = /^(?:<a?:([A-Za-z0-9_]{2,32}):(\d{17,20})>|([A-Za-z0-9_]{2,32}):(\d{17,20}))$/u.exec(value);
     if (custom) {
         const name = custom[1] ?? custom[3];

package/dist/events.js

@@ -574,9 +574,13 @@ export class DiscordResourceInspection {
         const guild = await this.client.guilds.fetch(input.guildId);
         if (guild.id !== input.guildId)
             throw new Error("Discord guild validation failed");
+        const canonicalCustom = /^custom:(\d{17,20})$/u.exec(input.emojiIdentifier);
+        const canonicalUnicode = /^unicode:(.+)$/u.exec(input.emojiIdentifier);
         const custom = customEmojiIdentifier.exec(input.emojiIdentifier);
-        if (!custom) {
-            const normalized = input.emojiIdentifier.normalize("NFKC").trim();
+        if (!custom && !canonicalCustom) {
+            const normalized = (canonicalUnicode?.[1] ?? input.emojiIdentifier)
+                .normalize("NFKC")
+                .trim();
             const valid = isSingleUnicodeEmoji(normalized);
             return {
                 guildId: guild.id,
@@ -590,7 +594,9 @@ export class DiscordResourceInspection {
                     : {}),
             };
         }
-        const emojiId = custom[2] ?? custom[4];
+        const emojiId = canonicalCustom?.[1] ?? custom?.[2] ?? custom?.[4];
+        if (!emojiId)
+            throw new Error("Invalid bounded Discord emoji identifier");
         const emoji = await guild.emojis.fetch(emojiId).catch(() => null);
         if (!emoji)
             return {
@@ -612,7 +618,7 @@ export class DiscordResourceInspection {
             kind: "custom",
             canonicalEmojiKey: `custom:${emoji.id}`,
             emojiId: emoji.id,
-            name: emoji.name ?? custom[1] ?? custom[3] ?? "emoji",
+            name: emoji.name ?? custom?.[1] ?? custom?.[3] ?? "emoji",
         };
     }
     async inspectChannel(input) {

package/dist/interactions.js

@@ -67,7 +67,24 @@ export function installInteractions(client, modules, registration, logger, servi
     });
     async function handleInteraction(interaction) {
         try {
-            if (interaction.isChatInputCommand()) {
+            if (interaction.isAutocomplete()) {
+                const registered = commands.get(interaction.commandName);
+                const subcommandName = registered?.contribution.subcommands?.length
+                    ? interaction.options.getSubcommand(false)
+                    : null;
+                const subcommand = subcommandName
+                    ? registered?.contribution.subcommands?.find(({ name }) => name === subcommandName)
+                    : undefined;
+                if (!registered ||
+                    !subcommand?.autocomplete ||
+                    !(await authorizeAutocomplete(interaction, registered.moduleId, subcommand.permissionId ??
+                        `${registered.contribution.name}.${subcommand.name}`, services, registration.selfAuthorizingGuildModuleIds?.has(registered.moduleId) ?? false, subcommand.authorization === "resource-scoped"))) {
+                    await interaction.respond([]);
+                    return;
+                }
+                await subcommand.autocomplete(createAutocompleteContext(interaction, services));
+            }
+            else if (interaction.isChatInputCommand()) {
                 const registered = commands.get(interaction.commandName);
                 if (registered) {
                     const { contribution: command, moduleId } = registered;
@@ -217,6 +234,8 @@ export function toCommandDefinition(registered) {
 }
 function addCommandOption(builder, option) {
     if (option.type === "string") {
+        if (option.autocomplete && option.choices?.length)
+            throw new Error(`Command option ${option.name} cannot use choices and autocomplete together`);
         builder.addStringOption((optionBuilder) => {
             optionBuilder
                 .setName(option.name)
@@ -228,6 +247,8 @@ function addCommandOption(builder, option) {
                 optionBuilder.setMaxLength(option.maxLength);
             if (option.choices)
                 optionBuilder.addChoices(...option.choices);
+            if (option.autocomplete)
+                optionBuilder.setAutocomplete(option.autocomplete);
             return optionBuilder;
         });
         return;
@@ -335,6 +356,41 @@ function createCommandContext(interaction, services) {
         },
     };
 }
+function createAutocompleteContext(interaction, services) {
+    const focused = interaction.options.getFocused(true);
+    const actor = permissionActor(interaction);
+    return {
+        interactionId: interaction.id,
+        userId: actor.userId,
+        userRoleIds: actor.roleIds,
+        userPermissions: actor.permissions,
+        isServerOwner: actor.isServerOwner,
+        isAdministrator: actor.isAdministrator,
+        ...(interaction.guildId ? { serverId: interaction.guildId } : {}),
+        focusedOptionName: focused.name,
+        focusedValue: String(focused.value),
+        services,
+        respond: async (choices) => {
+            if (choices.length > 25)
+                throw new Error("Autocomplete supports at most 25 choices");
+            const values = new Set();
+            const normalized = choices.map(({ name, value }) => {
+                const choiceName = name.trim().normalize("NFC");
+                const choiceValue = value.trim().normalize("NFC");
+                if (choiceName.length < 1 ||
+                    choiceName.length > 100 ||
+                    choiceValue.length < 1 ||
+                    choiceValue.length > 100)
+                    throw new Error("Autocomplete names and values must be between 1 and 100 characters");
+                if (values.has(choiceValue))
+                    throw new Error("Autocomplete choice values must be unique");
+                values.add(choiceValue);
+                return { name: choiceName, value: choiceValue };
+            });
+            await interaction.respond(normalized);
+        },
+    };
+}
 function createModalContext(interaction, services) {
     const updateResponse = interaction.isFromMessage()
         ? async (response) => interaction.update(toUpdateOptions(response)).then(() => undefined)
@@ -467,17 +523,7 @@ export async function authorizeCommand(interaction, moduleId, commandId, rateLim
         if (!resourceScopedCommand) {
             const permissions = services.get(HELYX_SERVICE_NAMES.permissions);
             const policy = await permissions.getEffectivePolicy(interaction.guildId, moduleId, commandId);
-            const actor = {
-                userId: interaction.user.id,
-                roleIds: interaction.member instanceof GuildMember
-                    ? [...interaction.member.roles.cache.keys()]
-                    : (interaction.member?.roles ?? []),
-                permissions: interaction.memberPermissions
-                    ?.toArray()
-                    .map(normalizeDiscordPermission) ?? [],
-                isServerOwner: interaction.guild?.ownerId === interaction.user.id,
-                isAdministrator: interaction.memberPermissions?.has(PermissionFlagsBits.Administrator) ?? false,
-            };
+            const actor = permissionActor(interaction);
             if (!canUseCommand(actor, policy)) {
                 await interaction.reply({
                     content: "You do not have permission to use this command.",
@@ -506,6 +552,32 @@ export async function authorizeCommand(interaction, moduleId, commandId, rateLim
     }
     return true;
 }
+async function authorizeAutocomplete(interaction, moduleId, commandId, services, selfAuthorizingGuildCommand, resourceScopedCommand) {
+    if (!interaction.guildId || selfAuthorizingGuildCommand)
+        return true;
+    const installations = services.get(HELYX_SERVICE_NAMES.installations);
+    if (!(await installations.isModuleEnabled(interaction.guildId, moduleId)))
+        return false;
+    if (resourceScopedCommand)
+        return true;
+    const permissions = services.get(HELYX_SERVICE_NAMES.permissions);
+    const policy = await permissions.getEffectivePolicy(interaction.guildId, moduleId, commandId);
+    return canUseCommand(permissionActor(interaction), policy);
+}
+function permissionActor(interaction) {
+    return {
+        userId: interaction.user.id,
+        roleIds: interaction.member instanceof GuildMember
+            ? [...interaction.member.roles.cache.keys()]
+            : (interaction.member?.roles ?? []),
+        permissions: interaction.memberPermissions
+            ?.toArray()
+            .map(normalizeDiscordPermission) ?? [],
+        isServerOwner: interaction.guild?.ownerId === interaction.user.id,
+        isAdministrator: interaction.memberPermissions?.has(PermissionFlagsBits.Administrator) ??
+            false,
+    };
+}
 export function normalizeDiscordPermission(permission) {
     return permission.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 }
@@ -760,6 +832,10 @@ export function toModal(definition) {
     return modal;
 }
 async function sendFailure(interaction) {
+    if (interaction.isAutocomplete()) {
+        await interaction.respond([]).catch(() => undefined);
+        return;
+    }
     if (!interaction.isRepliable())
         return;
     const message = "Something went wrong while handling that interaction.";

package/dist/scheduled-task-runner.js

@@ -306,11 +306,17 @@ export function createLocalScheduledTaskRoute(input) {
                 .execute(retentionTaskId);
             return result.completed
                 ? { outcome: "completed" }
-                : {
-                    outcome: "deferred",
-                    delayMs: 100,
-                    safeCode: "retention_batch_remaining",
-                };
+                : result.deferredUntil
+                    ? {
+                        outcome: "deferred",
+                        delayMs: Math.max(100, Math.min(86_400_000, result.deferredUntil.getTime() - Date.now())),
+                        safeCode: "retention_rescheduled",
+                    }
+                    : {
+                        outcome: "deferred",
+                        delayMs: 100,
+                        safeCode: "retention_batch_remaining",
+                    };
         }
         const module = modules.get(task.moduleId);
         if (!module)

package/dist/shard-contracts.d.ts

@@ -3,7 +3,7 @@ import type { ManagedResourceValue } from "@helyx/sdk";
 import type { BotControlHandler } from "./control-server.js";
 export declare const SHARD_CONTRACT_VERSION: 1;
 export declare const SHARD_CONTROL_MAX_BYTES: number;
-export declare const SHARD_CONTROL_TIMEOUT_MS = 10000;
+export declare const SHARD_CONTROL_TIMEOUT_MS = 30000;
 export declare const SHARD_HEALTH_STALE_MS = 30000;
 export declare const SHARD_LEASE_HEARTBEAT_TIMEOUT_MS = 20000;
 export declare const shardIdentitySchema: z.ZodObject<{
@@ -182,7 +182,7 @@ export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
     kind: z.ZodLiteral<"guild.module.configuration.update">;
     guildId: z.ZodString;
     moduleId: z.ZodString;
-    value: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
+    value: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNull, z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
     expectedVersion: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
     actorUserId: z.ZodString;
@@ -380,7 +380,7 @@ export declare const shardControlRequestSchema: z.ZodObject<{
         kind: z.ZodLiteral<"guild.module.configuration.update">;
         guildId: z.ZodString;
         moduleId: z.ZodString;
-        value: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
+        value: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNull, z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
         expectedVersion: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         actorUserId: z.ZodString;
@@ -838,7 +838,7 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         kind: z.ZodLiteral<"guild.module.configuration.update">;
         guildId: z.ZodString;
         moduleId: z.ZodString;
-        value: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
+        value: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNull, z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
         expectedVersion: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         actorUserId: z.ZodString;

package/dist/shard-contracts.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 export const SHARD_CONTRACT_VERSION = 1;
 export const SHARD_CONTROL_MAX_BYTES = 64 * 1_024;
-export const SHARD_CONTROL_TIMEOUT_MS = 10_000;
+export const SHARD_CONTROL_TIMEOUT_MS = 30_000;
 export const SHARD_HEALTH_STALE_MS = 30_000;
 export const SHARD_LEASE_HEARTBEAT_TIMEOUT_MS = 20_000;
 const snowflake = z.string().regex(/^\d{17,20}$/u);
@@ -43,6 +43,7 @@ const permissionState = z
 })
     .strict();
 const configurationValue = z.record(z.string().min(1).max(100), z.union([
+    z.null(),
     z.string().max(4_000),
     z.boolean(),
     z.number().finite(),

package/dist/shard-supervisor.d.ts

@@ -5,6 +5,9 @@ import { type ShardCloudRequest, type ShardIdentity, type ShardProcessHealth } f
 import { type ShardCoordinator, type ShardGenerationDescriptor, type ShardLeaderLease, type ShardLease } from "./shard-coordinator.js";
 import type { BotHandle } from "./index.js";
 export declare const STEADY_STATE_LEASE_LOSS_BOUND_MS: number;
+export declare function createStartupWorkerHeartbeatMaintenance(heartbeat: () => void, intervalMs?: number): {
+    stop(): void;
+};
 export declare function deferScheduledRoutingFailures(route: () => Promise<ScheduledTaskExecutionResult>): Promise<ScheduledTaskExecutionResult>;
 export declare function startShardSupervisor(environment: BotEnvironment, processEnvironment: NodeJS.ProcessEnv, workerEntry: string): Promise<BotHandle>;
 export declare function buildShardWorkerEnvironment(source: NodeJS.ProcessEnv, identity: ShardIdentity, restartCount: number): NodeJS.ProcessEnv;

package/dist/shard-supervisor.js

@@ -31,6 +31,13 @@ const WORKER_SHUTDOWN_MS = 5_000;
 const MAX_RESTARTS_PER_WINDOW = 5;
 const RESTART_WINDOW_MS = 10 * 60 * 1_000;
 export const STEADY_STATE_LEASE_LOSS_BOUND_MS = LEASE_RENEW_INTERVAL_MS + LEASE_VALIDATION_TIMEOUT_MS + WORKER_SHUTDOWN_MS;
+export function createStartupWorkerHeartbeatMaintenance(heartbeat, intervalMs = STARTUP_LEASE_RENEW_INTERVAL_MS) {
+    const timer = setInterval(heartbeat, intervalMs);
+    timer.unref();
+    return {
+        stop: () => clearInterval(timer),
+    };
+}
 export async function deferScheduledRoutingFailures(route) {
     try {
         return await route();
@@ -73,6 +80,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let retentionTimer;
     let leaseTimer;
     let startupLeaseTimer;
+    let startupWorkerHeartbeats;
     let startupLeaseRefresh;
     let startupLeaseError;
     let shuttingDown = false;
@@ -297,6 +305,11 @@ export async function startShardSupervisor(environment, processEnvironment, work
             execArgv: process.execArgv,
         });
         await reserveInitialSessionStarts(claimedIds.length, gateway);
+        if (coordinator) {
+            startupWorkerHeartbeats = createStartupWorkerHeartbeatMaintenance(() => {
+                void Promise.all([...localLeases].map(([shardId, lease]) => sendLeaseHeartbeat(shardId, lease)));
+            });
+        }
         await spawnInIdentifyBuckets(claimedIds, gateway.session_start_limit.max_concurrency);
         workersRoutable = true;
         if (leaderLease)
@@ -317,8 +330,11 @@ export async function startShardSupervisor(environment, processEnvironment, work
         await stopStartupLeaseMaintenance();
         if (coordinator)
             await withTimeout(renewStartupOwnership(coordinator, generationDescriptor, deploymentOrder, leaderLease), LEASE_VALIDATION_TIMEOUT_MS);
+        await Promise.all([...localLeases].map(([shardId, lease]) => sendLeaseHeartbeat(shardId, lease)));
         leaseTimer = setInterval(() => void maintainLeases(), LEASE_RENEW_INTERVAL_MS);
         leaseTimer.unref();
+        startupWorkerHeartbeats?.stop();
+        startupWorkerHeartbeats = undefined;
         process.once("SIGINT", () => void shutdown("SIGINT"));
         process.once("SIGTERM", () => void shutdown("SIGTERM"));
         logger.info({
@@ -414,17 +430,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
         };
         shard.env = buildShardWorkerEnvironment(processEnvironment, identity, restartCounts.get(shardId) ?? 0);
         healthByShard.set(shardId, startingHealth(shardId, restartCounts.get(shardId) ?? 0));
-        const launchHeartbeatTimer = coordinator
-            ? setInterval(() => void sendLeaseHeartbeat(shardId, lease), STARTUP_LEASE_RENEW_INTERVAL_MS)
-            : undefined;
-        launchHeartbeatTimer?.unref();
-        try {
-            await spawnWithShutdownGuard(() => shuttingDown, () => shard.spawn(30_000), () => shard.kill());
-        }
-        finally {
-            if (launchHeartbeatTimer)
-                clearInterval(launchHeartbeatTimer);
-        }
+        await spawnWithShutdownGuard(() => shuttingDown, () => shard.spawn(30_000), () => shard.kill());
         await sendLeaseHeartbeat(shardId, lease);
     }
     async function sendLeaseHeartbeat(shardId, lease) {
@@ -985,6 +991,8 @@ export async function startShardSupervisor(environment, processEnvironment, work
             clearInterval(leaseTimer);
         if (startupLeaseTimer)
             clearInterval(startupLeaseTimer);
+        startupWorkerHeartbeats?.stop();
+        startupWorkerHeartbeats = undefined;
         if (retentionTimer)
             clearInterval(retentionTimer);
         workersRoutable = false;

package/dist/shard-worker.js

@@ -207,7 +207,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             if (!parsed.success)
                 return;
             if (parsed.data.type === "helyx.control.request") {
-                void handleControl(identity, controlService, parsed.data);
+                void handleControl(identity, controlService, parsed.data, logger);
             }
             else if (parsed.data.type === "helyx.lease.heartbeat") {
                 if (sameShardIdentity(parsed.data.identity, identity))
@@ -390,7 +390,7 @@ export function shardWorkerCommandRegistration(input) {
         ]),
     };
 }
-async function handleControl(identity, service, request) {
+async function handleControl(identity, service, request, logger) {
     let response;
     const guildId = controlOperationGuildId(request.operation);
     if (request.generation !== identity.generation ||
@@ -418,6 +418,13 @@ async function handleControl(identity, service, request) {
             };
         }
         catch (error) {
+            logger.error({
+                event: "shard.control_failed",
+                requestId: request.requestId,
+                operation: request.operation.kind,
+                guildId,
+                error: safeError(error),
+            }, "Shard control operation failed");
             const mapped = mapBotControlError(error);
             response = {
                 version: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -49,13 +49,13 @@
   },
   "dependencies": {
     "@helyx/config": "0.4.2",
-    "@helyx/control-protocol": "0.1.4",
-    "@helyx/core": "0.1.8",
-    "@helyx/database": "0.4.2",
-    "@helyx/framework": "0.1.8",
-    "@helyx/module-manifest": "0.4.1",
-    "@helyx/platform": "0.2.5",
-    "@helyx/sdk": "0.3.3",
+    "@helyx/control-protocol": "0.1.5",
+    "@helyx/core": "0.1.9",
+    "@helyx/database": "0.4.3",
+    "@helyx/framework": "0.1.9",
+    "@helyx/module-manifest": "0.4.2",
+    "@helyx/platform": "0.2.7",
+    "@helyx/sdk": "0.3.4",
     "discord.js": "14.27.0",
     "fastify": "5.10.0",
     "pino": "10.3.1",