@gakr-gakr/qqbot 0.1.0

package/src/bridge/approval/capability.ts

@@ -0,0 +1,225 @@
+/**
+ * QQ Bot Approval Capability — entry point.
+ *
+ * QQBot uses a simpler approval model than Telegram/Slack: when no
+ * approver list is configured, the bot sends the approval message to the
+ * originating conversation and any participant can approve from there.
+ *
+ * When `execApprovals` IS configured, it gates which requests are
+ * handled natively and who is authorized.  When it is NOT configured,
+ * QQBot falls back to "always handle, anyone can approve".
+ */
+
+import { createChannelApprovalCapability } from "autobot/plugin-sdk/approval-delivery-runtime";
+import { createLazyChannelApprovalNativeRuntimeAdapter } from "autobot/plugin-sdk/approval-handler-adapter-runtime";
+import type { ChannelApprovalNativeRuntimeAdapter } from "autobot/plugin-sdk/approval-handler-runtime";
+import { resolveApprovalRequestSessionConversation } from "autobot/plugin-sdk/approval-native-runtime";
+import type { ChannelApprovalCapability } from "autobot/plugin-sdk/channel-contract";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import { resolveApprovalTarget } from "../../engine/approval/index.js";
+import {
+  isQQBotExecApprovalClientEnabled,
+  matchesQQBotApprovalAccount,
+  shouldHandleQQBotExecApprovalRequest,
+  resolveQQBotExecApprovalConfig,
+  authorizeQQBotApprovalAction,
+} from "../../exec-approvals.js";
+import { ensurePlatformAdapter } from "../bootstrap.js";
+import { resolveQQBotAccount } from "../config.js";
+import { getBridgeLogger } from "../logger.js";
+
+/**
+ * When `execApprovals` is configured, delegate to the profile-based
+ * check.  Otherwise fall back to target-resolvability plus the shared
+ * per-account ownership rule in `matchesQQBotApprovalAccount` so that
+ * each QQBot account handler only delivers approvals that originated
+ * from its own account (openids are account-scoped — cross-account
+ * delivery fails with 500 on the QQ Bot API).
+ */
+function shouldHandleRequest(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  request: {
+    request: {
+      sessionKey?: string | null;
+      turnSourceTo?: string | null;
+      turnSourceChannel?: string | null;
+      turnSourceAccountId?: string | null;
+    };
+  };
+}): boolean {
+  if (hasExecApprovalConfig(params)) {
+    return shouldHandleQQBotExecApprovalRequest(params as never);
+  }
+  if (!canResolveTarget(params.request)) {
+    return false;
+  }
+  return matchesQQBotApprovalAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+    request: params.request as never,
+  });
+}
+
+function hasExecApprovalConfig(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): boolean {
+  return resolveQQBotExecApprovalConfig(params) !== undefined;
+}
+
+function isNativeDeliveryEnabled(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): boolean {
+  if (hasExecApprovalConfig(params)) {
+    return isQQBotExecApprovalClientEnabled(params);
+  }
+  const account = resolveQQBotAccount(params.cfg, params.accountId);
+  return account.enabled && account.secretSource !== "none";
+}
+
+function canResolveTarget(request: {
+  request: { sessionKey?: string | null; turnSourceTo?: string | null };
+}): boolean {
+  const sessionKey = request.request.sessionKey ?? null;
+  const turnSourceTo = request.request.turnSourceTo ?? null;
+
+  const target = resolveApprovalTarget(sessionKey, turnSourceTo);
+  if (target) {
+    return true;
+  }
+
+  const sessionConversation = resolveApprovalRequestSessionConversation({
+    request: request as never,
+    channel: "qqbot",
+    bundledFallback: true,
+  });
+  return sessionConversation?.id != null;
+}
+
+function createQQBotApprovalCapability(): ChannelApprovalCapability {
+  return createChannelApprovalCapability({
+    authorizeActorAction: ({ cfg, accountId, senderId, approvalKind }) =>
+      authorizeQQBotApprovalAction({ cfg, accountId, senderId, approvalKind }),
+
+    getActionAvailabilityState: ({
+      cfg,
+      accountId,
+    }: {
+      cfg: AutoBotConfig;
+      accountId?: string | null;
+      action: "approve";
+    }) => {
+      const enabled = isNativeDeliveryEnabled({ cfg, accountId });
+      return enabled ? { kind: "enabled" } : { kind: "disabled" };
+    },
+
+    getExecInitiatingSurfaceState: ({
+      cfg,
+      accountId,
+    }: {
+      cfg: AutoBotConfig;
+      accountId?: string | null;
+      action: "approve";
+    }) => {
+      const enabled = isNativeDeliveryEnabled({ cfg, accountId });
+      return enabled ? { kind: "enabled" } : { kind: "disabled" };
+    },
+
+    describeExecApprovalSetup: ({ accountId }: { accountId?: string | null }) => {
+      const prefix =
+        accountId && accountId !== "default"
+          ? `channels.qqbot.accounts.${accountId}`
+          : "channels.qqbot";
+      return `QQBot native exec approvals are enabled by default. To restrict who can approve, configure \`${prefix}.execApprovals.approvers\` with QQ user OpenIDs.`;
+    },
+
+    delivery: {
+      hasConfiguredDmRoute: () => true,
+      shouldSuppressForwardingFallback: (input) => {
+        const channel = normalizeOptionalString(input.target?.channel);
+        if (channel !== "qqbot") {
+          return false;
+        }
+        const accountId =
+          normalizeOptionalString(input.target?.accountId) ??
+          normalizeOptionalString(input.request?.request?.turnSourceAccountId);
+        const result = isNativeDeliveryEnabled({ cfg: input.cfg, accountId });
+        getBridgeLogger().debug?.(
+          `[qqbot:approval] shouldSuppressForwardingFallback channel=${channel} accountId=${accountId} → ${result}`,
+        );
+        return result;
+      },
+    },
+
+    native: {
+      describeDeliveryCapabilities: ({ cfg, accountId }) => ({
+        enabled: isNativeDeliveryEnabled({ cfg, accountId }),
+        preferredSurface: "origin" as const,
+        supportsOriginSurface: true,
+        supportsApproverDmSurface: false,
+        notifyOriginWhenDmOnly: false,
+      }),
+      resolveOriginTarget: ({ request }) => {
+        const sessionKey = request.request.sessionKey ?? null;
+        const turnSourceTo = request.request.turnSourceTo ?? null;
+        const target = resolveApprovalTarget(sessionKey, turnSourceTo);
+        if (target) {
+          return { to: `${target.type}:${target.id}` };
+        }
+        const sessionConversation = resolveApprovalRequestSessionConversation({
+          request: request as never,
+          channel: "qqbot",
+          bundledFallback: true,
+        });
+        if (sessionConversation?.id) {
+          const kind = sessionConversation.kind === "group" ? "group" : "c2c";
+          return { to: `${kind}:${sessionConversation.id}` };
+        }
+        return null;
+      },
+    },
+
+    nativeRuntime: createLazyChannelApprovalNativeRuntimeAdapter({
+      eventKinds: ["exec", "plugin"],
+      isConfigured: ({ cfg, accountId }) => {
+        const result = isNativeDeliveryEnabled({ cfg, accountId });
+        getBridgeLogger().debug?.(
+          `[qqbot:approval] nativeRuntime.isConfigured accountId=${accountId} → ${result}`,
+        );
+        return result;
+      },
+      shouldHandle: ({ cfg, accountId, request }) => {
+        const result = shouldHandleRequest({
+          cfg,
+          accountId,
+          request: request as never,
+        });
+        getBridgeLogger().debug?.(
+          `[qqbot:approval] nativeRuntime.shouldHandle accountId=${accountId} → ${result}`,
+        );
+        return result;
+      },
+      load: async () => {
+        // Ensure PlatformAdapter is registered before handler-runtime uses
+        // getPlatformAdapter(). When the framework spawns the approval handler
+        // outside the qqbot gateway startAccount context, channel.ts's
+        // side-effect `import "./bridge/bootstrap.js"` may not have run yet.
+        ensurePlatformAdapter();
+        return (await import("./handler-runtime.js"))
+          .qqbotApprovalNativeRuntime as unknown as ChannelApprovalNativeRuntimeAdapter;
+      },
+    }),
+  });
+}
+
+const qqbotApprovalCapability = createQQBotApprovalCapability();
+
+let cachedCapability: ChannelApprovalCapability | undefined;
+
+export function getQQBotApprovalCapability(): ChannelApprovalCapability {
+  cachedCapability ??= qqbotApprovalCapability;
+  return cachedCapability;
+}

package/src/bridge/approval/handler-runtime.ts

@@ -0,0 +1,204 @@
+/**
+ * QQ Bot Native Approval Runtime Adapter.
+ *
+ * Implements the framework's ChannelApprovalNativeRuntimeSpec to deliver
+ * approval requests as QQ messages with inline keyboard buttons and handle
+ * resolved/expired lifecycle events.
+ *
+ * This file is lazily imported by capability.ts to avoid loading
+ * heavy dependencies on the critical startup path.
+ */
+
+import type { ChannelApprovalNativeRuntimeSpec } from "autobot/plugin-sdk/approval-handler-runtime";
+import { createChannelApprovalNativeRuntimeAdapter } from "autobot/plugin-sdk/approval-handler-runtime";
+import type { ChannelApprovalNativeRuntimeAdapter } from "autobot/plugin-sdk/approval-handler-runtime";
+import { resolveApprovalRequestSessionConversation } from "autobot/plugin-sdk/approval-native-runtime";
+import {
+  buildExecApprovalText,
+  buildPluginApprovalText,
+  buildApprovalKeyboard,
+  resolveApprovalTarget,
+  type ExecApprovalRequest,
+  type PluginApprovalRequest,
+} from "../../engine/approval/index.js";
+import { getMessageApi, accountToCreds } from "../../engine/messaging/sender.js";
+import type { ChatScope, InlineKeyboard, MessageResponse } from "../../engine/types.js";
+import {
+  matchesQQBotApprovalAccount,
+  resolveQQBotExecApprovalConfig,
+  isQQBotExecApprovalClientEnabled,
+  shouldHandleQQBotExecApprovalRequest,
+} from "../../exec-approvals.js";
+import { ensurePlatformAdapter } from "../bootstrap.js";
+import { resolveQQBotAccount } from "../config.js";
+import { getBridgeLogger } from "../logger.js";
+
+type ApprovalRequest = ExecApprovalRequest | PluginApprovalRequest;
+
+type QQBotPendingEntry = {
+  messageId?: string;
+  targetType: ChatScope;
+  targetId: string;
+};
+
+type QQBotPendingPayload = {
+  text: string;
+  keyboard: InlineKeyboard;
+};
+
+function isExecRequest(request: ApprovalRequest): request is ExecApprovalRequest {
+  return "expiresAtMs" in request;
+}
+
+function resolveQQTarget(request: ApprovalRequest): { type: ChatScope; id: string } | null {
+  const sessionConversation = resolveApprovalRequestSessionConversation({
+    request: request as never,
+    channel: "qqbot",
+    bundledFallback: true,
+  });
+
+  const sessionKey = request.request.sessionKey ?? null;
+  const turnSourceTo = request.request.turnSourceTo ?? null;
+
+  const target = resolveApprovalTarget(sessionKey, turnSourceTo);
+  if (target) {
+    return target;
+  }
+
+  if (sessionConversation?.id) {
+    const kind = sessionConversation.kind;
+    const chatScope: ChatScope = kind === "group" ? "group" : "c2c";
+    return { type: chatScope, id: sessionConversation.id };
+  }
+
+  return null;
+}
+
+type QQBotPreparedTarget = { type: ChatScope; id: string };
+
+const qqbotApprovalRuntimeSpec: ChannelApprovalNativeRuntimeSpec<
+  QQBotPendingPayload,
+  QQBotPreparedTarget,
+  QQBotPendingEntry
+> = {
+  eventKinds: ["exec", "plugin"],
+
+  availability: {
+    isConfigured: ({ cfg, accountId }) => {
+      if (resolveQQBotExecApprovalConfig({ cfg, accountId }) !== undefined) {
+        const result = isQQBotExecApprovalClientEnabled({ cfg, accountId });
+        getBridgeLogger().debug?.(
+          `[qqbot:approval-runtime] isConfigured(profile) accountId=${accountId} → ${result}`,
+        );
+        return result;
+      }
+      const account = resolveQQBotAccount(cfg, accountId ?? undefined);
+      const result = account.enabled && account.secretSource !== "none";
+      getBridgeLogger().debug?.(
+        `[qqbot:approval-runtime] isConfigured(fallback) accountId=${accountId} enabled=${account.enabled} secretSource=${account.secretSource} → ${result}`,
+      );
+      return result;
+    },
+    shouldHandle: ({ cfg, accountId, request }) => {
+      if (resolveQQBotExecApprovalConfig({ cfg, accountId }) !== undefined) {
+        const result = shouldHandleQQBotExecApprovalRequest({ cfg, accountId, request });
+        getBridgeLogger().debug?.(
+          `[qqbot:approval-runtime] shouldHandle(profile) accountId=${accountId} → ${result}`,
+        );
+        return result;
+      }
+      const target = resolveQQTarget(request as ApprovalRequest);
+      if (target === null) {
+        getBridgeLogger().debug?.(
+          `[qqbot:approval-runtime] shouldHandle(fallback) accountId=${accountId} target=null → false`,
+        );
+        return false;
+      }
+      const accountMatches = matchesQQBotApprovalAccount({
+        cfg,
+        accountId,
+        request: request as ApprovalRequest,
+      });
+      getBridgeLogger().debug?.(
+        `[qqbot:approval-runtime] shouldHandle(fallback) accountId=${accountId} target=${JSON.stringify(
+          target,
+        )} accountMatches=${accountMatches} → ${accountMatches}`,
+      );
+      return accountMatches;
+    },
+  },
+
+  presentation: {
+    buildPendingPayload: ({ request, view }) => {
+      const req = request as ApprovalRequest;
+      const text = isExecRequest(req) ? buildExecApprovalText(req) : buildPluginApprovalText(req);
+      const keyboard = buildApprovalKeyboard(
+        req.id,
+        view.actions.map((action) => action.decision),
+      );
+      getBridgeLogger().debug?.(
+        `[qqbot:approval-runtime] buildPendingPayload requestId=${req.id} kind=${
+          isExecRequest(req) ? "exec" : "plugin"
+        }`,
+      );
+      return { text, keyboard };
+    },
+    buildResolvedResult: () => ({ kind: "leave" }),
+    buildExpiredResult: () => ({ kind: "leave" }),
+  },
+
+  transport: {
+    prepareTarget: ({ request }) => {
+      const target = resolveQQTarget(request as ApprovalRequest);
+      getBridgeLogger().debug?.(
+        `[qqbot:approval-runtime] prepareTarget requestId=${request.id} target=${JSON.stringify(target)}`,
+      );
+      if (!target) {
+        return null;
+      }
+      return { target, dedupeKey: `${target.type}:${target.id}` };
+    },
+
+    deliverPending: async ({ cfg, accountId, preparedTarget, pendingPayload }) => {
+      // Ensure the PlatformAdapter is registered — resolveQQBotAccount below
+      // calls getPlatformAdapter() to resolve secret inputs.
+      ensurePlatformAdapter();
+      const account = resolveQQBotAccount(cfg, accountId ?? undefined);
+      const creds = accountToCreds(account);
+      const messageApi = getMessageApi(account.appId);
+
+      let result: MessageResponse;
+      try {
+        getBridgeLogger().debug?.(
+          `[qqbot:approval-runtime] deliverPending accountId=${accountId} target=${preparedTarget.type}:${preparedTarget.id}`,
+        );
+        result = await messageApi.sendMessage(
+          preparedTarget.type,
+          preparedTarget.id,
+          pendingPayload.text,
+          creds,
+          { inlineKeyboard: pendingPayload.keyboard },
+        );
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `Failed to send approval message to ${preparedTarget.type}:${preparedTarget.id}: ${msg}`,
+          { cause: err },
+        );
+      }
+
+      getBridgeLogger().debug?.(
+        `[qqbot:approval-runtime] deliverPending success accountId=${accountId} messageId=${result.id ?? ""}`,
+      );
+      return {
+        messageId: result.id,
+        targetType: preparedTarget.type,
+        targetId: preparedTarget.id,
+      };
+    },
+  },
+};
+
+export const qqbotApprovalNativeRuntime = createChannelApprovalNativeRuntimeAdapter(
+  qqbotApprovalRuntimeSpec,
+) as unknown as ChannelApprovalNativeRuntimeAdapter;

package/src/bridge/bootstrap.ts

@@ -0,0 +1,135 @@
+/**
+ * Bootstrap the PlatformAdapter for the built-in version.
+ *
+ * ## Design
+ *
+ * The adapter is registered via two complementary mechanisms:
+ *
+ * 1. **Factory registration** (`registerPlatformAdapterFactory`) — a lightweight
+ *    callback stored in `adapter/index.ts` that is invoked lazily by
+ *    `getPlatformAdapter()` on first access. This guarantees the adapter is
+ *    available regardless of module evaluation order or bundler chunk splitting.
+ *
+ * 2. **Eager side-effect** (`ensurePlatformAdapter()`) — called at module
+ *    evaluation time when `channel.ts` imports this file. Provides the adapter
+ *    immediately for code that runs synchronously during startup.
+ *
+ * Heavy async-only dependencies (`media-runtime`, `config-runtime`,
+ * `approval-gateway-runtime`) are lazy-imported inside each async method body
+ * so that this module evaluates with minimal overhead.
+ *
+ * Synchronous dependencies (`secret-input`, `temp-path`) are imported
+ * statically at the top level so they work reliably in both production and
+ * vitest (which resolves bare specifiers via `resolve.alias`, not Node CJS).
+ */
+
+import {
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "autobot/plugin-sdk/secret-input";
+import { resolvePreferredAutoBotTmpDir } from "autobot/plugin-sdk/temp-path";
+import {
+  registerPlatformAdapter,
+  registerPlatformAdapterFactory,
+  hasPlatformAdapter,
+  type PlatformAdapter,
+} from "../engine/adapter/index.js";
+import type { FetchMediaOptions, FetchMediaResult } from "../engine/adapter/types.js";
+import { getBridgeLogger } from "./logger.js";
+
+function createBuiltinAdapter(): PlatformAdapter {
+  return {
+    async validateRemoteUrl(_url: string, _options?: { allowPrivate?: boolean }): Promise<void> {
+      // Built-in version delegates SSRF validation to readRemoteMediaBuffer's ssrfPolicy.
+    },
+
+    async resolveSecret(value): Promise<string | undefined> {
+      if (typeof value === "string") {
+        return value || undefined;
+      }
+      return undefined;
+    },
+
+    async downloadFile(url: string, destDir: string, filename?: string): Promise<string> {
+      const { readRemoteMediaBuffer } = await import("autobot/plugin-sdk/media-runtime");
+      const result = await readRemoteMediaBuffer({ url, filePathHint: filename });
+      const fs = await import("node:fs");
+      const path = await import("node:path");
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+      const destPath = path.join(destDir, filename ?? "download");
+      fs.writeFileSync(destPath, result.buffer);
+      return destPath;
+    },
+
+    async fetchMedia(options: FetchMediaOptions): Promise<FetchMediaResult> {
+      const { readRemoteMediaBuffer } = await import("autobot/plugin-sdk/media-runtime");
+      const result = await readRemoteMediaBuffer({
+        url: options.url,
+        filePathHint: options.filePathHint,
+        maxBytes: options.maxBytes,
+        maxRedirects: options.maxRedirects,
+        ssrfPolicy: options.ssrfPolicy,
+        requestInit: options.requestInit,
+      });
+      return { buffer: result.buffer, fileName: result.fileName };
+    },
+
+    getTempDir(): string {
+      return resolvePreferredAutoBotTmpDir();
+    },
+
+    hasConfiguredSecret(value: unknown): boolean {
+      return hasConfiguredSecretInput(value);
+    },
+
+    normalizeSecretInputString(value: unknown): string | undefined {
+      return normalizeSecretInputString(value) ?? undefined;
+    },
+
+    resolveSecretInputString(params: { value: unknown; path: string }): string | undefined {
+      return normalizeResolvedSecretInputString(params) ?? undefined;
+    },
+
+    async resolveApproval(approvalId: string, decision: string): Promise<boolean> {
+      try {
+        const { getRuntimeConfig } = await import("autobot/plugin-sdk/runtime-config-snapshot");
+        const { resolveApprovalOverGateway } =
+          await import("autobot/plugin-sdk/approval-gateway-runtime");
+        const cfg = getRuntimeConfig();
+        await resolveApprovalOverGateway({
+          cfg,
+          approvalId,
+          decision: decision as "allow-once" | "allow-always" | "deny",
+          clientDisplayName: "QQBot Approval Handler",
+        });
+        return true;
+      } catch (err) {
+        getBridgeLogger().error(`[qqbot] resolveApproval failed: ${String(err)}`);
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Ensure the built-in PlatformAdapter is registered.
+ *
+ * Safe to call multiple times — only registers on the first invocation.
+ * Exported for backward compatibility with code that calls it explicitly.
+ */
+export function ensurePlatformAdapter(): void {
+  if (!hasPlatformAdapter()) {
+    registerPlatformAdapter(createBuiltinAdapter());
+  }
+}
+
+// Register the adapter factory so getPlatformAdapter() can lazy-init even when
+// this module's side-effect import hasn't executed yet (bundler reordering,
+// framework-spawned approval handlers, etc.).
+registerPlatformAdapterFactory(createBuiltinAdapter);
+
+// Also eagerly register for the normal startup path (imported by channel.ts).
+ensurePlatformAdapter();

package/src/bridge/channel-entry.ts

@@ -0,0 +1,18 @@
+/**
+ * Orchestrator for the QQBot `registerFull` hook.
+ *
+ * Keeping this function in `src/bridge/` (rather than inline in the
+ * `extensions/qqbot/index.ts` channel-entry contract) lets the composition
+ * be unit-tested and aligns with the layering described in the double-repo
+ * migration spec, where bridge-layer composition code is expected to live
+ * under `src/bridge/` (or `src/bootstrap/` in the standalone variant).
+ */
+
+import type { AutoBotPluginApi } from "autobot/plugin-sdk/plugin-entry";
+import { registerQQBotFrameworkCommands } from "./commands/framework-registration.js";
+import { registerQQBotTools } from "./tools/index.js";
+
+export function registerQQBotFull(api: AutoBotPluginApi): void {
+  registerQQBotTools(api);
+  registerQQBotFrameworkCommands(api);
+}

package/src/bridge/commands/framework-context-adapter.ts

@@ -0,0 +1,60 @@
+/**
+ * Adapter that builds a `SlashCommandContext` from a framework
+ * `PluginCommandContext`.
+ *
+ * Framework-registered commands enter the plugin through
+ * `api.registerCommand`, which surfaces a `PluginCommandContext` shape. Our
+ * engine-side command registry, however, is driven by `SlashCommandContext`.
+ * This adapter bridges the two so handlers authored against the engine
+ * registry can be reused unchanged on the framework command surface.
+ */
+
+import type { PluginCommandContext } from "autobot/plugin-sdk/plugin-entry";
+import type { SlashCommandContext } from "../../engine/commands/slash-commands.js";
+import type { ResolvedQQBotAccount } from "../../types.js";
+import type { QQBotFromParseResult } from "./from-parser.js";
+
+/**
+ * Default queue snapshot used for framework-registered commands.
+ *
+ * Framework-side command dispatch runs outside the per-sender queue, so
+ * handlers observe an empty snapshot by design.
+ */
+const DEFAULT_QUEUE_SNAPSHOT = {
+  totalPending: 0,
+  activeUsers: 0,
+  maxConcurrentUsers: 10,
+  senderPending: 0,
+} as const;
+
+interface BuildFrameworkSlashContextInput {
+  ctx: PluginCommandContext;
+  account: ResolvedQQBotAccount;
+  from: QQBotFromParseResult;
+  commandName: string;
+}
+
+export function buildFrameworkSlashContext({
+  ctx,
+  account,
+  from,
+  commandName,
+}: BuildFrameworkSlashContextInput): SlashCommandContext {
+  const args = ctx.args ?? "";
+  const rawContent = args ? `/${commandName} ${args}` : `/${commandName}`;
+
+  return {
+    type: from.msgType,
+    senderId: ctx.senderId ?? "",
+    messageId: "",
+    eventTimestamp: new Date().toISOString(),
+    receivedAt: Date.now(),
+    rawContent,
+    args,
+    accountId: account.accountId,
+    appId: account.appId,
+    accountConfig: account.config as unknown as Record<string, unknown>,
+    commandAuthorized: ctx.isAuthorizedSender,
+    queueSnapshot: { ...DEFAULT_QUEUE_SNAPSHOT },
+  };
+}