@openclaw/qqbot 2026.5.1-beta.1

package/src/bridge/commands/framework-registration.ts

@@ -0,0 +1,47 @@
+/**
+ * Register all `requireAuth: true` slash commands with the framework via
+ * `api.registerCommand`.
+ *
+ * Routing through the framework lets `resolveCommandAuthorization()` apply
+ * `commands.allowFrom.qqbot` precedence and the `qqbot:` prefix normalization
+ * before any QQBot command handler runs.
+ *
+ * This module is intentionally thin: it wires the engine-side command
+ * registry (`getFrameworkCommands`) to the framework registration surface via
+ * the three single-responsibility helpers in this directory.
+ */
+
+import type { OpenClawPluginApi, PluginCommandContext } from "openclaw/plugin-sdk/plugin-entry";
+import { getFrameworkCommands } from "../../engine/commands/slash-commands-impl.js";
+import { resolveQQBotAccount } from "../config.js";
+import { buildFrameworkSlashContext } from "./framework-context-adapter.js";
+import { parseQQBotFrom } from "./from-parser.js";
+import { dispatchFrameworkSlashResult } from "./result-dispatcher.js";
+
+export function registerQQBotFrameworkCommands(api: OpenClawPluginApi): void {
+  for (const cmd of getFrameworkCommands()) {
+    api.registerCommand({
+      name: cmd.name,
+      description: cmd.description,
+      requireAuth: true,
+      acceptsArgs: true,
+      handler: async (ctx: PluginCommandContext) => {
+        const from = parseQQBotFrom(ctx.from);
+        const account = resolveQQBotAccount(ctx.config, ctx.accountId ?? undefined);
+        const slashCtx = buildFrameworkSlashContext({
+          ctx,
+          account,
+          from,
+          commandName: cmd.name,
+        });
+        const result = await cmd.handler(slashCtx);
+        return await dispatchFrameworkSlashResult({
+          result,
+          account,
+          from,
+          logger: api.logger,
+        });
+      },
+    });
+  }
+}

package/src/bridge/commands/from-parser.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { parseQQBotFrom } from "./from-parser.js";
+
+describe("parseQQBotFrom", () => {
+  it("parses a group from string", () => {
+    expect(parseQQBotFrom("qqbot:group:ABCDEF")).toEqual({
+      msgType: "group",
+      targetType: "group",
+      targetId: "ABCDEF",
+    });
+  });
+
+  it("parses a channel prefix into the guild msgType", () => {
+    expect(parseQQBotFrom("qqbot:channel:123")).toEqual({
+      msgType: "guild",
+      targetType: "channel",
+      targetId: "123",
+    });
+  });
+
+  it("parses a dm prefix", () => {
+    expect(parseQQBotFrom("qqbot:dm:456")).toEqual({
+      msgType: "dm",
+      targetType: "dm",
+      targetId: "456",
+    });
+  });
+
+  it("parses a c2c prefix", () => {
+    expect(parseQQBotFrom("qqbot:c2c:user-1")).toEqual({
+      msgType: "c2c",
+      targetType: "c2c",
+      targetId: "user-1",
+    });
+  });
+
+  it("is case-insensitive on the qqbot: prefix", () => {
+    expect(parseQQBotFrom("QQBOT:group:gid")).toEqual({
+      msgType: "group",
+      targetType: "group",
+      targetId: "gid",
+    });
+  });
+
+  it("handles target ids that contain a colon", () => {
+    expect(parseQQBotFrom("qqbot:group:GROUP:ID")).toEqual({
+      msgType: "group",
+      targetType: "group",
+      targetId: "GROUP:ID",
+    });
+  });
+
+  it("falls back to c2c for unknown prefixes", () => {
+    expect(parseQQBotFrom("qqbot:unknown:abc")).toEqual({
+      msgType: "c2c",
+      targetType: "c2c",
+      targetId: "abc",
+    });
+  });
+
+  it("falls back to c2c for missing from", () => {
+    expect(parseQQBotFrom(undefined)).toEqual({
+      msgType: "c2c",
+      targetType: "c2c",
+      targetId: "",
+    });
+    expect(parseQQBotFrom(null)).toEqual({
+      msgType: "c2c",
+      targetType: "c2c",
+      targetId: "",
+    });
+    expect(parseQQBotFrom("")).toEqual({
+      msgType: "c2c",
+      targetType: "c2c",
+      targetId: "",
+    });
+  });
+
+  it("treats a bare prefix (no colon) as c2c with that id", () => {
+    expect(parseQQBotFrom("qqbot:c2c")).toEqual({
+      msgType: "c2c",
+      targetType: "c2c",
+      targetId: "c2c",
+    });
+  });
+});

package/src/bridge/commands/from-parser.ts

@@ -0,0 +1,60 @@
+/**
+ * Parse the framework `PluginCommandContext.from` string into the QQBot
+ * message type and send target.
+ *
+ * The framework passes `from` in the form `qqbot:<kind>:<id>` (case-insensitive
+ * prefix). We split that string once and map `<kind>` into the engine-side
+ * `SlashCommandContext.type` enum and the outbound `MediaTargetContext.targetType`
+ * enum. Both enums diverge only for guild/channel, so we keep two lookup
+ * tables to avoid the nested ternary chain the previous implementation used.
+ */
+
+export interface QQBotFromParseResult {
+  /** Message type consumed by SlashCommandContext.type. */
+  msgType: "c2c" | "guild" | "dm" | "group";
+  /** Target type consumed by MediaTargetContext.targetType. */
+  targetType: "c2c" | "group" | "channel" | "dm";
+  /** Raw target id (everything after the first `:`). */
+  targetId: string;
+}
+
+type FromKind = "c2c" | "group" | "channel" | "dm";
+
+const MSG_TYPE_MAP: Record<FromKind, QQBotFromParseResult["msgType"]> = {
+  c2c: "c2c",
+  dm: "dm",
+  group: "group",
+  channel: "guild",
+};
+
+const TARGET_TYPE_MAP: Record<FromKind, QQBotFromParseResult["targetType"]> = {
+  c2c: "c2c",
+  dm: "dm",
+  group: "group",
+  channel: "channel",
+};
+
+function isFromKind(value: string): value is FromKind {
+  return value === "c2c" || value === "dm" || value === "group" || value === "channel";
+}
+
+/**
+ * Parse `ctx.from` into the structured fields the QQBot bridge expects.
+ *
+ * Unknown or missing prefixes fall back to c2c. The remainder after the first
+ * `:` is returned verbatim as the target id, matching what the previous inline
+ * implementation did.
+ */
+export function parseQQBotFrom(from: string | undefined | null): QQBotFromParseResult {
+  const stripped = (from ?? "").replace(/^qqbot:/iu, "");
+  const colonIdx = stripped.indexOf(":");
+  const rawPrefix = colonIdx === -1 ? stripped : stripped.slice(0, colonIdx);
+  const targetId = colonIdx === -1 ? stripped : stripped.slice(colonIdx + 1);
+  const kind: FromKind = isFromKind(rawPrefix) ? rawPrefix : "c2c";
+
+  return {
+    msgType: MSG_TYPE_MAP[kind],
+    targetType: TARGET_TYPE_MAP[kind],
+    targetId,
+  };
+}

package/src/bridge/commands/result-dispatcher.ts

@@ -0,0 +1,76 @@
+/**
+ * Dispatch a slash command result produced on the framework command surface.
+ *
+ * Slash command handlers return one of:
+ *   1. a plain string (text reply),
+ *   2. a `SlashCommandFileResult` (text plus a local file to upload), or
+ *   3. null / unexpected value (we surface a generic warning).
+ *
+ * This module isolates the text/file branching so the framework registration
+ * layer stays declarative and so the file-send side effect has a single
+ * location where logging and error handling live.
+ */
+
+import type { PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+import type { SlashCommandResult } from "../../engine/commands/slash-commands.js";
+import { sendDocument, type MediaTargetContext } from "../../engine/messaging/outbound.js";
+import type { ResolvedQQBotAccount } from "../../types.js";
+import type { QQBotFromParseResult } from "./from-parser.js";
+
+const UNEXPECTED_RESULT_TEXT = "⚠️ 命令返回了意外结果。";
+
+interface FrameworkSlashReply {
+  text: string;
+}
+
+interface DispatchFrameworkSlashResultInput {
+  result: SlashCommandResult;
+  account: ResolvedQQBotAccount;
+  from: QQBotFromParseResult;
+  logger?: PluginLogger;
+}
+
+function hasFilePath(value: unknown): value is { text: string; filePath: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "filePath" in value &&
+    typeof (value as { filePath: unknown }).filePath === "string"
+  );
+}
+
+function buildMediaTarget(
+  account: ResolvedQQBotAccount,
+  from: QQBotFromParseResult,
+): MediaTargetContext {
+  return {
+    targetType: from.targetType,
+    targetId: from.targetId,
+    account: account as unknown as MediaTargetContext["account"],
+  };
+}
+
+export async function dispatchFrameworkSlashResult({
+  result,
+  account,
+  from,
+  logger,
+}: DispatchFrameworkSlashResultInput): Promise<FrameworkSlashReply> {
+  if (typeof result === "string") {
+    return { text: result };
+  }
+
+  if (hasFilePath(result)) {
+    const mediaCtx = buildMediaTarget(account, from);
+    try {
+      await sendDocument(mediaCtx, result.filePath, {
+        allowQQBotDataDownloads: true,
+      });
+    } catch (err) {
+      logger?.warn(`framework slash file send failed: ${String(err)}`);
+    }
+    return { text: result.text };
+  }
+
+  return { text: UNEXPECTED_RESULT_TEXT };
+}

package/src/bridge/config-shared.ts

@@ -0,0 +1,132 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import {
+  applyAccountNameToChannelSection,
+  deleteAccountFromConfigSection,
+  setAccountEnabledInConfigSection,
+} from "openclaw/plugin-sdk/core";
+import type { ChannelSetupInput } from "openclaw/plugin-sdk/setup";
+import {
+  describeAccount as engineDescribeAccount,
+  formatAllowFrom as engineFormatAllowFrom,
+  isAccountConfigured as engineIsAccountConfigured,
+} from "../engine/config/resolve.js";
+import {
+  applySetupAccountConfig as engineApplySetupAccountConfig,
+  validateSetupInput as engineValidateSetupInput,
+} from "../engine/config/setup-logic.js";
+import { normalizeLowercaseStringOrEmpty } from "../engine/utils/string-normalize.js";
+import type { ResolvedQQBotAccount } from "../types.js";
+import {
+  listQQBotAccountIds,
+  resolveDefaultQQBotAccountId,
+  resolveQQBotAccount,
+} from "./config.js";
+
+export const qqbotMeta = {
+  id: "qqbot",
+  label: "QQ Bot",
+  selectionLabel: "QQ Bot (Bot API)",
+  docsPath: "/channels/qqbot",
+  blurb: "Connect to QQ via official QQ Bot API",
+  order: 50,
+} as const;
+
+function validateQQBotSetupInput(params: {
+  accountId: string;
+  input: ChannelSetupInput;
+}): string | null {
+  return engineValidateSetupInput(params.accountId, params.input);
+}
+
+function applyQQBotSetupAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  input: ChannelSetupInput;
+}): OpenClawConfig {
+  return engineApplySetupAccountConfig(
+    params.cfg as unknown as Record<string, unknown>,
+    params.accountId,
+    params.input,
+  ) as OpenClawConfig;
+}
+
+function isQQBotConfigured(account: ResolvedQQBotAccount | undefined): boolean {
+  return engineIsAccountConfigured(account as never);
+}
+
+function describeQQBotAccount(account: ResolvedQQBotAccount | undefined) {
+  return engineDescribeAccount(account as never);
+}
+
+function formatQQBotAllowFrom(params: {
+  allowFrom: Array<string | number> | undefined | null;
+}): string[] {
+  return engineFormatAllowFrom(params.allowFrom);
+}
+
+export const qqbotConfigAdapter = {
+  listAccountIds: (cfg: OpenClawConfig) => listQQBotAccountIds(cfg),
+  resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) =>
+    resolveQQBotAccount(cfg, accountId, { allowUnresolvedSecretRef: true }),
+  defaultAccountId: (cfg: OpenClawConfig) => resolveDefaultQQBotAccountId(cfg),
+  setAccountEnabled: ({
+    cfg,
+    accountId,
+    enabled,
+  }: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    enabled: boolean;
+  }) =>
+    setAccountEnabledInConfigSection({
+      cfg,
+      sectionKey: "qqbot",
+      accountId,
+      enabled,
+      allowTopLevel: true,
+    }),
+  deleteAccount: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) =>
+    deleteAccountFromConfigSection({
+      cfg,
+      sectionKey: "qqbot",
+      accountId,
+      clearBaseFields: ["appId", "clientSecret", "clientSecretFile", "name"],
+    }),
+  isConfigured: isQQBotConfigured,
+  describeAccount: describeQQBotAccount,
+  resolveAllowFrom: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId?: string | null }) =>
+    resolveQQBotAccount(cfg, accountId, { allowUnresolvedSecretRef: true }).config?.allowFrom,
+  formatAllowFrom: ({ allowFrom }: { allowFrom: Array<string | number> | undefined | null }) =>
+    formatQQBotAllowFrom({ allowFrom }),
+};
+
+export const qqbotSetupAdapterShared = {
+  resolveAccountId: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId?: string | null }) =>
+    normalizeLowercaseStringOrEmpty(accountId) || resolveDefaultQQBotAccountId(cfg),
+  applyAccountName: ({
+    cfg,
+    accountId,
+    name,
+  }: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    name?: string;
+  }) =>
+    applyAccountNameToChannelSection({
+      cfg,
+      channelKey: "qqbot",
+      accountId,
+      name,
+    }),
+  validateInput: ({ accountId, input }: { accountId: string; input: ChannelSetupInput }) =>
+    validateQQBotSetupInput({ accountId, input }),
+  applyAccountConfig: ({
+    cfg,
+    accountId,
+    input,
+  }: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    input: ChannelSetupInput;
+  }) => applyQQBotSetupAccountConfig({ cfg, accountId, input }),
+};

package/src/bridge/config.ts

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { getPlatformAdapter } from "../engine/adapter/index.js";
+import {
+  DEFAULT_ACCOUNT_ID as ENGINE_DEFAULT_ACCOUNT_ID,
+  applyAccountConfig,
+  listAccountIds,
+  resolveAccountBase,
+  resolveDefaultAccountId,
+} from "../engine/config/resolve.js";
+import type { ResolvedQQBotAccount, QQBotAccountConfig } from "../types.js";
+
+export const DEFAULT_ACCOUNT_ID = ENGINE_DEFAULT_ACCOUNT_ID;
+
+interface QQBotChannelConfig extends QQBotAccountConfig {
+  accounts?: Record<string, QQBotAccountConfig>;
+  defaultAccount?: string;
+}
+
+/** List all configured QQBot account IDs. */
+export function listQQBotAccountIds(cfg: OpenClawConfig): string[] {
+  return listAccountIds(cfg as unknown as Record<string, unknown>);
+}
+
+/** Resolve the default QQBot account ID. */
+export function resolveDefaultQQBotAccountId(cfg: OpenClawConfig): string {
+  return resolveDefaultAccountId(cfg as unknown as Record<string, unknown>);
+}
+
+/** Resolve QQBot account config for runtime or setup flows. */
+export function resolveQQBotAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+  opts?: { allowUnresolvedSecretRef?: boolean },
+): ResolvedQQBotAccount {
+  const raw = cfg as unknown as Record<string, unknown>;
+  const base = resolveAccountBase(raw, accountId);
+
+  const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
+  /**
+   * Legacy top-level account uses `channels.qqbot` as the base, but per-account
+   * fields (allowFrom, streaming, …) often live under `accounts.default`.
+   * Merge that slice so runtime sees `config.streaming` etc.
+   */
+  const accountConfig: QQBotAccountConfig =
+    base.accountId === DEFAULT_ACCOUNT_ID
+      ? {
+          ...qqbot,
+          ...qqbot?.accounts?.[DEFAULT_ACCOUNT_ID],
+        }
+      : (qqbot?.accounts?.[base.accountId] ?? {});
+
+  let clientSecret = "";
+  let secretSource: "config" | "file" | "env" | "none" = "none";
+
+  const clientSecretPath =
+    base.accountId === DEFAULT_ACCOUNT_ID
+      ? "channels.qqbot.clientSecret"
+      : `channels.qqbot.accounts.${base.accountId}.clientSecret`;
+
+  const adapter = getPlatformAdapter();
+  if (adapter.hasConfiguredSecret(accountConfig.clientSecret)) {
+    clientSecret = opts?.allowUnresolvedSecretRef
+      ? (adapter.normalizeSecretInputString(accountConfig.clientSecret) ?? "")
+      : (adapter.resolveSecretInputString({
+          value: accountConfig.clientSecret,
+          path: clientSecretPath,
+        }) ?? "");
+    secretSource = "config";
+  } else if (accountConfig.clientSecretFile) {
+    try {
+      clientSecret = fs.readFileSync(accountConfig.clientSecretFile, "utf8").trim();
+      secretSource = "file";
+    } catch {
+      secretSource = "none";
+    }
+  } else if (process.env.QQBOT_CLIENT_SECRET && base.accountId === DEFAULT_ACCOUNT_ID) {
+    clientSecret = process.env.QQBOT_CLIENT_SECRET;
+    secretSource = "env";
+  }
+
+  return {
+    accountId: base.accountId,
+    name: accountConfig.name,
+    enabled: base.enabled,
+    appId: base.appId,
+    clientSecret,
+    secretSource,
+    systemPrompt: base.systemPrompt,
+    markdownSupport: base.markdownSupport,
+    config: accountConfig,
+  };
+}
+
+/** Apply account config updates back into the OpenClaw config object. */
+export function applyQQBotAccountConfig(
+  cfg: OpenClawConfig,
+  accountId: string,
+  input: {
+    appId?: string;
+    clientSecret?: string;
+    clientSecretFile?: string;
+    name?: string;
+  },
+): OpenClawConfig {
+  return applyAccountConfig(
+    cfg as unknown as Record<string, unknown>,
+    accountId,
+    input,
+  ) as OpenClawConfig;
+}

package/src/bridge/gateway.ts

@@ -0,0 +1,174 @@
+/**
+ * Gateway entry point — thin bridge shell that constructs
+ * {@link EngineAdapters} and passes them to the engine's
+ * `startGateway`.
+ *
+ * All adapter dependencies are assembled here in one place.
+ */
+
+import { resolveRuntimeServiceVersion } from "openclaw/plugin-sdk/cli-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { EngineAdapters } from "../engine/adapter/index.js";
+import {
+  startGateway as coreStartGateway,
+  type CoreGatewayContext,
+} from "../engine/gateway/gateway.js";
+import type { GatewayPluginRuntime } from "../engine/gateway/types.js";
+import { initSender, registerAccount } from "../engine/messaging/sender.js";
+import type { EngineLogger } from "../engine/types.js";
+import * as _audioModule from "../engine/utils/audio.js";
+import { formatDuration } from "../engine/utils/format.js";
+import { debugLog, debugError } from "../engine/utils/log.js";
+import type { ResolvedQQBotAccount } from "../types.js";
+import { ensurePlatformAdapter } from "./bootstrap.js";
+import { setBridgeLogger } from "./logger.js";
+import { toGatewayAccount } from "./narrowing.js";
+import { resolveQQBotPluginVersion } from "./plugin-version.js";
+import { getQQBotRuntime, getQQBotRuntimeForEngine } from "./runtime.js";
+import { createSdkHistoryAdapter, createSdkMentionGateAdapter } from "./sdk-adapter.js";
+
+// ---- One-time startup initialization (module-level) ----
+
+const _pluginVersion = resolveQQBotPluginVersion(import.meta.url);
+initSender({
+  pluginVersion: _pluginVersion,
+  openclawVersion: resolveRuntimeServiceVersion(),
+});
+
+// ============ Public types ============
+
+export interface GatewayContext {
+  account: ResolvedQQBotAccount;
+  abortSignal: AbortSignal;
+  cfg: OpenClawConfig;
+  onReady?: (data: unknown) => void;
+  onResumed?: (data: unknown) => void;
+  onError?: (error: Error) => void;
+  log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+  };
+  channelRuntime?: {
+    runtimeContexts: {
+      register: (params: {
+        channelId: string;
+        accountId: string;
+        capability: string;
+        context: unknown;
+        abortSignal?: AbortSignal;
+      }) => { dispose: () => void };
+    };
+  };
+}
+
+// ============ Adapter factory ============
+
+/**
+ * Create the full set of engine adapters from the bridge layer.
+ *
+ * This is the **single assembly point** — all SDK → engine binding
+ * happens here. The engine receives a fully-populated
+ * {@link EngineAdapters} object with zero global singletons.
+ */
+function createEngineAdapters(_runtime: GatewayPluginRuntime): EngineAdapters {
+  return {
+    history: createSdkHistoryAdapter(),
+    mentionGate: createSdkMentionGateAdapter(),
+    audioConvert: {
+      convertSilkToWav: _audioModule.convertSilkToWav,
+      isVoiceAttachment: _audioModule.isVoiceAttachment,
+      formatDuration,
+    },
+    outboundAudio: {
+      audioFileToSilkBase64: async (p: string, f?: string[]) =>
+        (await _audioModule.audioFileToSilkBase64(p, f)) ?? undefined,
+      isAudioFile: (p: string, m?: string) => _audioModule.isAudioFile(p, m),
+      shouldTranscodeVoice: (p: string) => _audioModule.shouldTranscodeVoice(p),
+      waitForFile: (p: string, ms?: number) => _audioModule.waitForFile(p, ms),
+    },
+    commands: {
+      resolveVersion: resolveRuntimeServiceVersion,
+      pluginVersion: _pluginVersion,
+      approveRuntimeGetter: () => {
+        const rt = getQQBotRuntime();
+        return { config: rt.config };
+      },
+    },
+  };
+}
+
+// ============ startGateway ============
+
+/**
+ * Start the Gateway WebSocket connection.
+ *
+ * Assembles all adapters and passes them to the engine's core gateway.
+ */
+export async function startGateway(ctx: GatewayContext): Promise<void> {
+  ensurePlatformAdapter();
+
+  const runtime = getQQBotRuntimeForEngine();
+  const accountLogger = createAccountLogger(ctx.log, ctx.account.accountId);
+
+  // Per-account registration (still global — sender is a leaf utility).
+  registerAccount(ctx.account.appId, {
+    logger: accountLogger,
+    markdownSupport: ctx.account.markdownSupport,
+  });
+  setBridgeLogger(accountLogger);
+
+  if (ctx.channelRuntime) {
+    accountLogger.info("Registering approval.native runtime context");
+    const lease = ctx.channelRuntime.runtimeContexts.register({
+      channelId: "qqbot",
+      accountId: ctx.account.accountId,
+      capability: "approval.native",
+      context: { account: ctx.account },
+      abortSignal: ctx.abortSignal,
+    });
+    accountLogger.info(`approval.native context registered (lease=${!!lease})`);
+  } else {
+    accountLogger.info("No channelRuntime — skipping approval.native registration");
+  }
+
+  const coreCtx: CoreGatewayContext = {
+    account: toGatewayAccount(ctx.account),
+    abortSignal: ctx.abortSignal,
+    cfg: ctx.cfg,
+    onReady: ctx.onReady,
+    onResumed: ctx.onResumed,
+    onError: ctx.onError,
+    log: accountLogger,
+    runtime,
+    adapters: createEngineAdapters(runtime),
+  };
+
+  return coreStartGateway(coreCtx);
+}
+
+// ============ Per-account logger factory ============
+
+function createAccountLogger(
+  raw: GatewayContext["log"] | undefined,
+  accountId: string,
+): EngineLogger {
+  const prefix = `[${accountId}]`;
+  const withMeta = (msg: string, meta?: Record<string, unknown>) =>
+    meta && Object.keys(meta).length > 0 ? `${msg} ${JSON.stringify(meta)}` : msg;
+
+  if (!raw) {
+    return {
+      info: (msg, meta) => debugLog(`${prefix} ${withMeta(msg, meta)}`),
+      error: (msg, meta) => debugError(`${prefix} ${withMeta(msg, meta)}`),
+      warn: (msg, meta) => debugError(`${prefix} ${withMeta(msg, meta)}`),
+      debug: (msg, meta) => debugLog(`${prefix} ${withMeta(msg, meta)}`),
+    };
+  }
+  return {
+    info: (msg, meta) => raw.info(`${prefix} ${withMeta(msg, meta)}`),
+    error: (msg, meta) => raw.error(`${prefix} ${withMeta(msg, meta)}`),
+    warn: (msg, meta) => raw.error(`${prefix} ${withMeta(msg, meta)}`),
+    debug: (msg, meta) => raw.debug?.(`${prefix} ${withMeta(msg, meta)}`),
+  };
+}