@usebridger/core 0.2.1 → 0.3.0

package/dist/index.mjs

@@ -3,6 +3,7 @@ import { a as sessionStorage, i as pluginStorage, n as assertTenantId, o as shar
 import { b as isCapability, c as normalizeQuery, g as assertCapability, h as assertCanSend, l as normalizeWhere, m as UnsupportedError, o as normalizeDocument, r as transportIssues, s as normalizeIndexes, t as ReconnectionPolicy, u as createMessage, v as groupActionCapability, x as missingCapabilities, y as hasCapability } from "./reconnection--5ulo2FJ.mjs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { pino, stdSerializers } from "pino";
+import { styleText } from "node:util";
 import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
@@ -10,7 +11,7 @@ import { pathToFileURL } from "node:url";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/text/format.ts
 /** Monta o `FormattedText`; os nós já vêm validados e congelados. */
-function formatted(nodes) {
+function formatted$1(nodes) {
 	return Object.freeze({
 		type: "formatted",
 		nodes: Object.freeze([...nodes])
@@ -30,8 +31,8 @@ function isFormatted(value) {
 }
 function style(type, parts) {
 	const children = nodesOf(parts, type);
-	if (children.length === 0) return formatted([]);
-	return formatted([Object.freeze({
+	if (children.length === 0) return formatted$1([]);
+	return formatted$1([Object.freeze({
 		type,
 		children: Object.freeze(children)
 	})]);
@@ -45,8 +46,8 @@ function italic(...parts) {
 /** Código em linha. O conteúdo é sempre literal: não aceita outra formatação dentro. */
 function code(text) {
 	if (typeof text !== "string") throw new TypeError("code: esperava string");
-	if (text === "") return formatted([]);
-	return formatted([Object.freeze({
+	if (text === "") return formatted$1([]);
+	return formatted$1([Object.freeze({
 		type: "code",
 		text
 	})]);
@@ -64,7 +65,7 @@ function link(url, label) {
 	}
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new TypeError(`link: só http e https são aceitos: ${url}`);
 	const children = nodesOf([label ?? url], "link");
-	return formatted([Object.freeze({
+	return formatted$1([Object.freeze({
 		type: "link",
 		url,
 		children: Object.freeze(children.length ? children : [url])
@@ -82,7 +83,7 @@ function mention(contact) {
 		phone: contact.phone ?? null,
 		...contact.username !== void 0 && { username: contact.username }
 	});
-	return formatted([Object.freeze({
+	return formatted$1([Object.freeze({
 		type: "mention",
 		contact: target
 	})]);
@@ -100,7 +101,7 @@ function fmt(strings, ...values) {
 			parts.push(typeof value === "number" ? String(value) : value);
 		}
 	});
-	return formatted(nodesOf(parts, "fmt"));
+	return formatted$1(nodesOf(parts, "fmt"));
 }
 /**
 * Texto visível, sem marcação: o que a pessoa lê. Uma menção vira `@` mais o usuário, o nome, o
@@ -311,6 +312,41 @@ function createPrefixStore(config, port) {
 }
 //#endregion
 //#region src/commands/command.ts
+/** Decompõe a entrada sem validar; a validação fica em `assertCommandDefinition`. */
+function parseAccept(spec) {
+	const quoted = spec.startsWith("quoted:");
+	const rest = quoted ? spec.slice(7) : spec;
+	const colon = rest.indexOf(":");
+	if (colon === -1) return {
+		quoted,
+		type: rest,
+		mimetype: null
+	};
+	return {
+		quoted,
+		type: rest.slice(0, colon),
+		mimetype: rest.slice(colon + 1).toLowerCase()
+	};
+}
+/**
+* O mimetype da mídia casa com o da entrada. Compara só a essência: `audio/ogg; codecs=opus`
+* casa com `audio/ogg`, porque os parâmetros variam por plataforma.
+*/
+function mimetypeMatches(mimetype, pattern) {
+	const essence = mimetype.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+	if (pattern.endsWith("/*")) return essence.startsWith(pattern.slice(0, -1));
+	return essence === pattern;
+}
+const MEDIA_TYPES = /* @__PURE__ */ new Set([
+	"image",
+	"video",
+	"audio",
+	"voice",
+	"sticker",
+	"document"
+]);
+/** `tipo/subtipo` ou `tipo/*`, nos caracteres que o RFC 6838 permite. */
+const MIMETYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/(\*|[a-z0-9][a-z0-9!#$&^_.+-]*)$/;
 const TOKEN = /^\S+$/;
 function assertToken(token, what) {
 	if (!TOKEN.test(token)) throw new TypeError(`${what} de comando inválido: ${JSON.stringify(token)} (vazio ou com espaço)`);
@@ -318,16 +354,26 @@ function assertToken(token, what) {
 /**
 * Lança `TypeError` se o nome ou algum alias for vazio ou tiver espaço (nunca casaria) e
 * `RangeError` se `timeoutMs` não for finito e > 0 (o `setTimeout` trataria `Infinity`/`NaN`
-* como 1 ms e o comando estouraria na hora).
+* como 1 ms e o comando estouraria na hora) ou se `concurrency` não for inteiro >= 1 (0 nunca
+* rodaria). Entrada de `accepts` com mimetype mal formado, ou num tipo sem mídia, e capability
+* desconhecida em `requires` também lançam `TypeError`.
 */
 function assertCommandDefinition(definition) {
 	assertToken(definition.name, "Nome");
 	for (const alias of definition.aliases ?? []) assertToken(alias, "Alias");
 	const { timeoutMs } = definition;
 	if (timeoutMs !== void 0 && !(Number.isFinite(timeoutMs) && timeoutMs > 0)) throw new RangeError(`Prazo do comando "${definition.name}" inválido: ${timeoutMs}`);
+	const { concurrency } = definition;
+	if (concurrency !== void 0 && !(Number.isInteger(concurrency) && concurrency >= 1)) throw new RangeError(`Limite de concorrência do comando "${definition.name}" inválido: ${concurrency}`);
+	for (const spec of definition.accepts ?? []) {
+		const { type, mimetype } = parseAccept(spec);
+		if (mimetype === null) continue;
+		if (!MEDIA_TYPES.has(type) || !MIMETYPE.test(mimetype)) throw new TypeError(`accepts do comando "${definition.name}" inválido: ${JSON.stringify(spec)} (mimetype só em tipo com mídia, como "tipo/subtipo" ou "tipo/*")`);
+	}
+	for (const capability of definition.requires ?? []) if (!isCapability(capability)) throw new TypeError(`requires do comando "${definition.name}": capability desconhecida ${JSON.stringify(capability)}`);
 }
 /**
-* Define um comando. Valida nome, aliases e prazo na definição, para o erro apontar o plugin que
+* Define um comando. Valida nome, aliases, prazo e limite na definição, para o erro apontar o plugin que
 * declarou e não aparecer só quando alguém digitar o comando.
 */
 function command(definition) {
@@ -713,19 +759,41 @@ const FIRST_WHITESPACE = /\s/;
 function mediaOf(message) {
 	return message !== null && "media" in message ? message.media : null;
 }
-/** Primeira entrada de `accepts` que casa, na ordem declarada. */
+/** Primeira entrada de `accepts` que casa (tipo e, se houver, mimetype), na ordem declarada. */
 function resolveAccepts(message, accepts) {
 	for (const spec of accepts) {
-		const quoted = spec.startsWith("quoted:");
+		const { quoted, type, mimetype } = parseAccept(spec);
 		const target = quoted ? message.quoted : message;
-		const type = quoted ? spec.slice(7) : spec;
-		if (target !== null && target.type === type) return {
+		if (target === null || target.type !== type) continue;
+		if (mimetype !== null) {
+			const media = mediaOf(target);
+			if (media === null || !mimetypeMatches(media.mimetype, mimetype)) continue;
+		}
+		return {
 			spec,
 			message: target
 		};
 	}
 	return null;
 }
+/** Roda o `run`; o erro, síncrono ou não, vira `failed`. Nunca rejeita. */
+async function runCommand(definition, ctx, command) {
+	try {
+		await definition.run(ctx);
+		return {
+			consumed: true,
+			status: "ran",
+			command
+		};
+	} catch (error) {
+		return {
+			consumed: true,
+			status: "failed",
+			command,
+			error
+		};
+	}
+}
 function createCommandRouter(options = {}) {
 	const option = options.prefix ?? "!";
 	let prefixOf;
@@ -852,16 +920,17 @@ function createCommandRouter(options = {}) {
 					}
 					media = mediaOf(accepted.message);
 				} else media = mediaOf(message) ?? mediaOf(message.quoted);
-				const commandCtx = Object.assign(base, {
+				const done = runCommand(definition, Object.assign(base, {
 					accepted,
 					media
-				});
-				await definition.run(commandCtx);
-				return {
+				}), command);
+				if (definition.background) return {
 					consumed: true,
-					status: "ran",
-					command
+					status: "background",
+					command,
+					done
 				};
+				return await done;
 			} catch (error) {
 				return {
 					consumed: true,
@@ -914,6 +983,71 @@ function normalizeOwners(owners) {
 	return [...unique.values()];
 }
 //#endregion
+//#region src/logger/pretty.ts
+const LEVELS = {
+	10: ["TRACE", "gray"],
+	20: ["DEBUG", "blue"],
+	30: ["INFO ", "green"],
+	40: ["WARN ", "yellow"],
+	50: ["ERROR", "red"],
+	60: ["FATAL", ["bgRed", "white"]]
+};
+/** Campos que o cabeçalho já mostra ou que não ajudam a ler no terminal. */
+const HIDDEN = /* @__PURE__ */ new Set([
+	"level",
+	"time",
+	"pid",
+	"hostname",
+	"msg",
+	"plugin",
+	"err"
+]);
+/**
+* Embrulha `target` para receber texto legível em vez de JSON. `color` liga as cores ANSI; o
+* `styleText` ainda as desliga com `NO_COLOR` ou quando o stdout não é um terminal.
+*/
+function prettyDestination(target, color) {
+	const paint = (style, text) => color ? styleText(style, text, { stream: process.stdout }) : text;
+	return { write(line) {
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			target.write(line);
+			return;
+		}
+		target.write(`${formatRecord(record, paint)}\n`);
+	} };
+}
+function formatRecord(record, paint) {
+	const [label, style] = LEVELS[record["level"]] ?? ["?    ", "white"];
+	const parts = [paint("gray", clock(record["time"])), paint(style, label)];
+	if (typeof record["plugin"] === "string") parts.push(paint("cyan", `[${record["plugin"]}]`));
+	parts.push(String(record["msg"] ?? ""));
+	const fields = Object.entries(record).filter(([key]) => !HIDDEN.has(key)).map(([key, value]) => paint("gray", `${key}=${formatValue(value)}`));
+	let text = [...parts, ...fields].join(" ");
+	if (record["err"] !== void 0) text += `\n${indent(formatError(record["err"]))}`;
+	return text;
+}
+/** Hora local `HH:MM:SS`; o dia fica de fora, o terminal é para acompanhar ao vivo. */
+function clock(time) {
+	return (typeof time === "number" ? new Date(time) : /* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+}
+function formatValue(value) {
+	if (typeof value === "string") return /^[^\s"=]+$/.test(value) ? value : JSON.stringify(value);
+	return JSON.stringify(value) ?? String(value);
+}
+/** Stack do erro e as das causas, em sequência; sem stack, `tipo: mensagem` ou o JSON. */
+function formatError(err) {
+	if (typeof err !== "object" || err === null) return String(err);
+	const { type, message, stack, cause } = err;
+	const own = stack ?? (message === void 0 ? JSON.stringify(err) : `${type}: ${message}`);
+	return cause === void 0 ? own : `${own}\ncausa: ${formatError(cause)}`;
+}
+function indent(text) {
+	return text.replaceAll(/^/gm, "    ");
+}
+//#endregion
 //#region src/logger/logger.ts
 const CENSOR = "[REDACTED]";
 /**
@@ -921,7 +1055,7 @@ const CENSOR = "[REDACTED]";
 * campo `err` é serializado com `message`, `stack` e `cause`.
 */
 function createLogger(options = {}) {
-	const destination = withSecretsCensored(options.destination, options.secrets);
+	const destination = withSecretsCensored(formatted(options), options.secrets);
 	const root = pino({
 		level: options.level ?? "info",
 		serializers: { err: stdSerializers.errWithCause },
@@ -932,6 +1066,10 @@ function createLogger(options = {}) {
 	}, destination);
 	return wrap(options.bindings ? root.child(options.bindings) : root);
 }
+function formatted(options) {
+	if (options.format !== "pretty") return options.destination;
+	return prettyDestination(options.destination ?? pino.destination(1), !options.destination);
+}
 function withSecretsCensored(destination, secrets) {
 	if (secrets === void 0) return destination;
 	let source;
@@ -984,6 +1122,31 @@ function createNoopLogger() {
 	return NOOP_LOGGER;
 }
 //#endregion
+//#region src/plugin/messages.ts
+/** Placeholder que o kernel preenche: o prefixo de comando do chat (ADR 0063). */
+const PREFIX_PLACEHOLDER = "prefix";
+const PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Nomes dos placeholders do texto, na ordem em que aparecem, sem repetição. */
+function placeholders(text) {
+	return [...new Set(Array.from(text.matchAll(PLACEHOLDER), (match) => match[1]))];
+}
+/** Preenche os placeholders de `text`; `key` só entra na mensagem de erro. */
+function fillMessage(text, values, key) {
+	return text.replaceAll(PLACEHOLDER, (_match, name) => {
+		const value = Object.hasOwn(values, name) ? values[name] : void 0;
+		if (value === void 0) throw new TypeError(`mensagem "${key}": falta o valor do placeholder {${name}}`);
+		return String(value);
+	});
+}
+/** O `ctx.t`: a mensagem `key` das `messages` do plugin, com o `{prefix}` do chat. */
+function formatMessage(messages, key, values, prefix) {
+	if (!Object.hasOwn(messages, key)) throw new TypeError(`mensagem "${key}" não declarada em messages`);
+	return fillMessage(messages[key], {
+		...values,
+		[PREFIX_PLACEHOLDER]: prefix
+	}, key);
+}
+//#endregion
 //#region src/config/schema.ts
 /** Texto que substitui um valor secreto em qualquer exibição (dashboard, `describe`). */
 const SECRET_MASK = "********";
@@ -1203,6 +1366,17 @@ var PluginConfigError = class extends Error {
 //#endregion
 //#region src/config/plugin-configs.ts
 const MESSAGES_KEY = "messages";
+/**
+* Problema da sobrescrita que usa placeholder que o texto padrão não tem (o `{prefix}` vale
+* sempre); `null` se está tudo certo.
+*/
+function placeholderIssue(text, base) {
+	const allowed = [...placeholders(base), PREFIX_PLACEHOLDER];
+	const unknown = placeholders(text).filter((name) => !allowed.includes(name));
+	if (unknown.length === 0) return null;
+	const show = (names) => names.map((name) => `{${name}}`).join(", ");
+	return `placeholder desconhecido ${show(unknown)}; a mensagem aceita ${show(allowed)}`;
+}
 const SECRETS_OWNER = (plugin) => `plugin:${plugin}`;
 const isPlainObject = (value) => {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
@@ -1456,8 +1630,15 @@ function createPluginConfigs(options) {
 				message: "deve ser texto"
 			});
 			else {
-				messages[key] = text;
-				messageSources[at.path] = at.source;
+				const problem = placeholderIssue(text, base[key]);
+				if (problem !== null) issues.push({
+					...at,
+					message: problem
+				});
+				else {
+					messages[key] = text;
+					messageSources[at.path] = at.source;
+				}
 			}
 		}
 		if (issues.length > 0) return {
@@ -2639,7 +2820,7 @@ const SEPARATORS = [
 function splitText(text, limits, measure) {
 	if (measure(text) <= limits.first) return [text];
 	const raw = typeof text === "string";
-	const build = (segments) => raw ? segments.map((s) => s.text).join("") : formatted(rebuild(segments, 0));
+	const build = (segments) => raw ? segments.map((s) => s.text).join("") : formatted$1(rebuild(segments, 0));
 	const chunks = [];
 	const fits = (segments) => measure(build(trim(segments))) <= (chunks.length === 0 ? limits.first : limits.rest);
 	const pack = (segments, level) => {
@@ -3943,17 +4124,18 @@ function definePlugin(definition) {
 * Não edite à mão: `pnpm version-packages` roda o `changeset version` e reescreve esta linha
 * (`scripts/sync-version.ts`); o `version.test.ts` falha se ela divergir do `package.json`.
 */
-const CORE_VERSION = "0.2.1";
+const CORE_VERSION = "0.3.0";
 //#endregion
 //#region src/plugin/declared.ts
 /** Registra os `commands` e o `on` do manifesto. Chamado pelo host antes do `setup`. */
 function installDeclared(definition, ctx) {
 	for (const [name, declared] of Object.entries(definition.commands ?? {})) {
-		const { run, ...rest } = declared;
+		const { run, onReject, ...rest } = declared;
 		ctx.commands.add({
 			...rest,
 			name,
-			run: (c) => run.call(declared, c, ctx)
+			run: (c) => run.call(declared, c, ctx),
+			...onReject && { onReject: (c, rejection) => onReject.call(declared, c, rejection, ctx) }
 		});
 	}
 	for (const [event, listener] of Object.entries(definition.on ?? {})) {
@@ -4141,7 +4323,7 @@ const reportBase = ({ definition, origin }) => ({
 /** Cria o host de plugins. Não roda nada até `start()`. */
 function createPluginHost(options) {
 	const { transport, createContext, log } = options;
-	const coreVersion = options.coreVersion ?? "0.2.1";
+	const coreVersion = options.coreVersion ?? "0.3.0";
 	if (!parseVersion(coreVersion)) throw new RangeError(`coreVersion inválida: "${coreVersion}"`);
 	const setupTimeoutMs = options.setupTimeoutMs ?? 1e4;
 	const teardownTimeoutMs = options.teardownTimeoutMs ?? 5e3;
@@ -5409,7 +5591,12 @@ var MessageContextImpl = class {
 		return state.log;
 	}
 	react(emoji) {
-		return this[STATE].deps.sender.react(this.message.key, emoji, { priority: "high" });
+		const { deps } = this[STATE];
+		if (!deps.reactions) {
+			this.log.debug("react ignorado: o transport não tem a capability \"reactions\"", { emoji });
+			return Promise.resolve();
+		}
+		return deps.sender.react(this.message.key, emoji, { priority: "high" });
 	}
 };
 function replyFor(deps, message, owner) {
@@ -5554,12 +5741,28 @@ const signalDescriptor = { get() {
 	return deadlineOf(this).signal;
 } };
 /**
-* Descritores comuns às execuções que respondem a uma mensagem (comando e passo): `log` do
+* Descritor do `t`: a função presa à mensagem da visão, criada no primeiro acesso e fixada, para
+* `({ t }) => ...` funcionar desestruturado.
+*/
+function textDescriptor(text) {
+	return {
+		configurable: true,
+		get() {
+			const { message } = this;
+			const t = (key, values) => text(message, key, values);
+			Object.defineProperty(this, "t", { value: t });
+			return t;
+		}
+	};
+}
+/**
+* Descritores comuns às execuções que respondem a uma mensagem (comando e passo): `log` e `t` do
 * plugin, `signal`, e `reply`, `react` e `expectReply` presos ao prazo.
 */
-function executionDescriptors(plugin, pluginLog, expect, scope) {
+function executionDescriptors(plugin, pluginLog, expect, text, scope) {
 	return {
 		log: pluginLogDescriptor(pluginLog),
+		t: textDescriptor(text),
 		signal: signalDescriptor,
 		reply: expiringReplyDescriptor(plugin, (view) => pluginReply(view, plugin) ?? Object.getPrototypeOf(view).reply, scope),
 		react: expiringReactDescriptor(plugin, (view) => {
@@ -5570,12 +5773,12 @@ function executionDescriptors(plugin, pluginLog, expect, scope) {
 	};
 }
 /** Deriva os contextos de comando de um plugin. */
-function commandViewFactory(plugin, pluginLog, expect) {
+function commandViewFactory(plugin, pluginLog, expect, text) {
 	const scope = (view) => ({
 		label: `comando "${view.command}"`,
 		fields: { command: view.command }
 	});
-	const runDescriptors = executionDescriptors(plugin, pluginLog, expect, scope);
+	const runDescriptors = executionDescriptors(plugin, pluginLog, expect, text, scope);
 	return { run(ctx, deadline) {
 		const view = Object.create(ctx, runDescriptors);
 		view[DEADLINE] = deadline;
@@ -5586,12 +5789,12 @@ function commandViewFactory(plugin, pluginLog, expect) {
 * Deriva, para os passos de conversa de um plugin, o contexto com `step`, `data` e os campos de
 * execução do comando (`log`, `signal`, `reply`, `react`, `expectReply`).
 */
-function stepViewFactory(plugin, pluginLog, expect) {
+function stepViewFactory(plugin, pluginLog, expect, text) {
 	const scope = (view) => ({
 		label: `passo "${view.step}"`,
 		fields: { step: view.step }
 	});
-	const descriptors = executionDescriptors(plugin, pluginLog, expect, scope);
+	const descriptors = executionDescriptors(plugin, pluginLog, expect, text, scope);
 	return (ctx, deadline, step, data) => {
 		const view = Object.create(ctx, descriptors);
 		Object.assign(view, {
@@ -5623,7 +5826,7 @@ function roleViewFactory(pluginLog) {
 * compartilhados entre os listeners da emissão; o barramento pendura na visão o `Deadline` do
 * listener, que dá o `signal` e prende o `reply`.
 */
-function listenerViewFactory(plugin, pluginLog, expect) {
+function listenerViewFactory(plugin, pluginLog, expect, text) {
 	const kernel = (view) => view[KERNEL_CONTEXT];
 	const scope = (view) => ({
 		label: `listener de "${view.event}"`,
@@ -5643,11 +5846,65 @@ function listenerViewFactory(plugin, pluginLog, expect) {
 		}, scope),
 		react: expiringReactDescriptor(plugin, kernel, scope),
 		expectReply: expectReplyDescriptor(plugin, expect, scope),
-		log: pluginLogDescriptor(pluginLog)
+		log: pluginLogDescriptor(pluginLog),
+		t: textDescriptor(text)
 	};
 	return (ctx) => Object.create(ctx, descriptors);
 }
 //#endregion
+//#region src/commands/concurrency.ts
+function createConcurrencyLimit(max) {
+	let active = 0;
+	const waiting = /* @__PURE__ */ new Set();
+	const release = () => {
+		const next = waiting.values().next();
+		if (next.done) {
+			active--;
+			return;
+		}
+		waiting.delete(next.value);
+		next.value();
+	};
+	const start = (task) => {
+		let result;
+		try {
+			result = task();
+		} catch (error) {
+			release();
+			throw error;
+		}
+		if (isThenable$2(result)) result.then(release, release);
+		else release();
+		return result;
+	};
+	return { run(task, signal) {
+		if (active < max) {
+			active++;
+			return start(task);
+		}
+		return new Promise((resolve, reject) => {
+			if (signal.aborted) {
+				reject(signal.reason);
+				return;
+			}
+			const onAbort = () => {
+				waiting.delete(go);
+				reject(signal.reason);
+			};
+			const go = () => {
+				signal.removeEventListener("abort", onAbort);
+				try {
+					resolve(start(task));
+				} catch (error) {
+					reject(error);
+				}
+			};
+			waiting.add(go);
+			signal.addEventListener("abort", onAbort, { once: true });
+		});
+	} };
+}
+//#endregion
 //#region src/storage/tenant.ts
 /**
 * Storage do plugin que segue o `scope`. Os storages por tenant ficam em cache (as coleções do
@@ -5741,9 +5998,10 @@ function createPluginContextFactory(deps) {
 		};
 		const live = (operation, fn) => (...args) => lifetime.expired ? refuse(operation) : fn(...args);
 		const expect = (message, step, options) => deps.conversations.expect(name, message.chat.id, message.sender.id, step, options);
-		const commandViews = commandViewFactory(name, log, expect);
-		const listenerView = listenerViewFactory(name, log, expect);
-		const stepView = stepViewFactory(name, log, expect);
+		const text = (message, key, values) => formatMessage(messages, key, values, deps.prefixes.get(message.chat));
+		const commandViews = commandViewFactory(name, log, expect, text);
+		const listenerView = listenerViewFactory(name, log, expect, text);
+		const stepView = stepViewFactory(name, log, expect, text);
 		const roleView = roleViewFactory(log);
 		const events = deps.bus.forPlugin(name, {
 			view: (event) => isMessageEvent(event) ? listenerView : void 0,
@@ -5766,6 +6024,15 @@ function createPluginContextFactory(deps) {
 				commands: {
 					add(definition) {
 						guard("commands.add");
+						assertCommandDefinition(definition);
+						const missing = missingCapabilities(deps.transport, definition.requires ?? []);
+						if (missing.length > 0) {
+							log.info(`comando "${definition.name}" não registrado: capability ausente no transport`, {
+								command: definition.name,
+								missing
+							});
+							return;
+						}
 						deps.router.registry.add(name, wrapCommand(name, definition, commandViews, lifetime, deps));
 					},
 					list: () => deps.router.registry.list().map(commandInfo)
@@ -5918,19 +6185,26 @@ function liveTenantStorage(storage, live) {
 function wrapCommand(plugin, definition, views, lifetime, deps) {
 	const { run, onReject, name } = definition;
 	const timeoutMs = definition.timeoutMs ?? deps.commandTimeoutMs;
+	const limit = definition.concurrency === void 0 ? void 0 : createConcurrencyLimit(definition.concurrency);
 	const timed = (stage, execute) => {
 		const deadline = new Deadline(lifetime);
 		return settleWithin(execute(deadline), timeoutMs, () => {
 			const error = new CommandTimeoutError(plugin, name, timeoutMs, stage);
 			deadline.expire(error);
 			return error;
-		}, (error) => deps.onLateCommandError(plugin, name, error), deps.armed, deadline);
+		}, (error) => {
+			if (error === deadline.reason) return;
+			deps.onLateCommandError(plugin, name, error);
+		}, deps.armed, deadline);
 	};
 	return {
 		...definition,
 		run: (ctx) => timed("run", (deadline) => {
-			const view = views.run(ctx, deadline);
-			return replyWithResult(view, run(view));
+			const start = () => {
+				const view = views.run(ctx, deadline);
+				return replyWithResult(view, run(view));
+			};
+			return limit === void 0 ? start() : limit.run(start, deadline.signal);
 		}),
 		...onReject && { onReject: (ctx, rejection) => timed("onReject", (deadline) => onReject(views.run(ctx, deadline), rejection)) }
 	};
@@ -6391,6 +6665,19 @@ function createBot(config) {
 	const timeouts = config.timeouts ?? {};
 	const commandTimeoutMs = timeouts.commandMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
 	const armed = new ArmedTimers();
+	const background = /* @__PURE__ */ new Set();
+	const backgroundWaiters = [];
+	const releaseBackgroundWaiters = () => {
+		for (const resolve of backgroundWaiters.splice(0)) resolve();
+	};
+	const trackBackground = (task) => {
+		background.add(task);
+		task.finally(() => {
+			background.delete(task);
+			if (background.size === 0) releaseBackgroundWaiters();
+		});
+	};
+	const backgroundIdle = () => background.size === 0 ? Promise.resolve() : new Promise((resolve) => backgroundWaiters.push(resolve));
 	const bus = createEventBus({
 		listenerTimeoutMs: timeouts.listenerMs,
 		armed,
@@ -6454,6 +6741,7 @@ function createBot(config) {
 	const contextDeps = {
 		sender: send,
 		quote: hasCapability(transport, "quoted"),
+		reactions: hasCapability(transport, "reactions"),
 		log: getLog,
 		actions: prepareActions
 	};
@@ -6537,6 +6825,14 @@ function createBot(config) {
 	/** Recusa, falha e evento `command` do comando que consumiu a mensagem ou o clique. */
 	async function afterCommand(ctx, result) {
 		const { message } = ctx;
+		if (result.status === "background") {
+			trackBackground(result.done.then((outcome) => afterCommand(ctx, outcome)).catch((error) => ctx.log.error("falha ao concluir o comando em segundo plano", {
+				plugin: result.command.plugin,
+				command: result.command.name,
+				err: error
+			})));
+			return;
+		}
 		if (result.status === "rejected" && result.reply !== null) ctx.reply(result.reply).catch((error) => ctx.log.warn("falha ao enviar a recusa do comando", {
 			plugin: result.command.plugin,
 			command: result.command.name,
@@ -6848,6 +7144,8 @@ function createBot(config) {
 		await scheduler.stop(aborted);
 		await host?.stop(aborted);
 		armed.disarmAll();
+		background.clear();
+		releaseBackgroundWaiters();
 		conversations.close();
 		actions.clear();
 		outbound.close({ drain: false });
@@ -6944,6 +7242,7 @@ function createBot(config) {
 		try {
 			log = config.logger ?? createLogger({
 				level: config.logLevel ?? "info",
+				...config.logFormat && { format: config.logFormat },
 				secrets
 			});
 			transportLog = log.child({ transport: transport.name });
@@ -7047,8 +7346,9 @@ function createBot(config) {
 	*/
 	async function settled() {
 		if (state === "starting") await readyPromise;
-		while (!(inbound.stats().activeChats === 0 && bus.idle && outbound.stats().activeChats === 0)) {
+		while (!(inbound.stats().activeChats === 0 && background.size === 0 && bus.idle && outbound.stats().activeChats === 0)) {
 			await inbound.onIdle();
+			await backgroundIdle();
 			await bus.onIdle();
 			await outbound.onIdle();
 		}