PR #60760: fix(telegram): break circular dependency that crashes gateway on startup

• Repository: openclaw/openclaw
• Author: openperf
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/60760

Description (problem / solution / changelog)

Summary

• Problem: Since commit bc457fd1b8 (present on main as of 2026.4.3+), the gateway fails to start with Error: telegram command config contract surface is unavailable thrown at src/plugin-sdk/telegram-command-config.ts:35. The crash is deterministic and affects every startup when the Telegram extension is bundled.

• Root Cause: src/plugin-sdk/telegram-command-config.ts line 40-41 assigns TELEGRAM_COMMAND_NAME_PATTERN as a module-level constant by calling loadTelegramCommandConfigContract() at module load time. This function calls getBundledChannelContractSurfaceModule({ pluginId: "telegram" }), which uses jiti to load extensions/telegram/contract-api.ts. However, contract-api.ts re-exports collectTelegramSecurityAuditFindings from ./src/security-audit.js, which imports openclaw/plugin-sdk/config-runtime. That module in turn re-exports from ./telegram-command-config.js — the very module that is still initializing. jiti detects the circular reference and returns null for the still-loading module, causing the contract variable to be null and the throw new Error(...) to fire. The three exported functions (normalizeTelegramCommandName, normalizeTelegramCommandDescription, resolveTelegramCustomCommands) do not trigger this issue because they call loadTelegramCommandConfigContract() lazily inside their function bodies, only at runtime when actually invoked.

• Fix: Replace the module-level loadTelegramCommandConfigContract().TELEGRAM_COMMAND_NAME_PATTERN call with an inlined regex literal /^[a-z0-9_]{1,32}$/. This value is identical to the canonical definition in extensions/telegram/src/command-config.ts line 1 and matches the Telegram Bot API specification for command names. By inlining the constant, the module no longer performs any side-effect calls at load time, completely eliminating the circular dependency trigger. A regression test is added to contract-surfaces.test.ts that asserts the inlined pattern stays in sync with the extension source.

• What changed:

  • src/plugin-sdk/telegram-command-config.ts: Replaced loadTelegramCommandConfigContract().TELEGRAM_COMMAND_NAME_PATTERN (module-level call) with an inlined regex literal and a JSDoc comment explaining the rationale.
  • src/channels/plugins/contract-surfaces.test.ts: Added a regression test that dynamically imports the inlined constant and compares its source and flags against the Telegram extension's contract surface to catch future drift.

• What did NOT change (scope boundary):

  • extensions/telegram/src/command-config.ts — the canonical source of truth for the regex is untouched.
  • extensions/telegram/contract-api.ts and extensions/telegram/contract-surfaces.ts — no changes to extension public surfaces.
  • src/channels/plugins/contract-surfaces.ts — the contract surface loader is untouched.
  • src/plugin-sdk/config-runtime.ts — the re-export barrel is untouched; it still re-exports TELEGRAM_COMMAND_NAME_PATTERN from telegram-command-config.js.
  • src/config/zod-schema.providers-core.ts — the Zod schema that uses normalizeTelegramCommandName and resolveTelegramCustomCommands is untouched; those functions remain lazy and are unaffected.
  • No global module loading behavior, jiti configuration, or plugin discovery logic was modified.

Reproduction

1. Check out the main branch at or after commit bc457fd1b8.
2. Run pnpm build (or start the gateway directly if using a pre-built artifact).
3. Observe the gateway crashes immediately on startup with:

   Error: telegram command config contract surface is unavailable
       at loadTelegramCommandConfigContract (dist/zod-schema.providers-core-BhgCFixp.js:88:23)

4. The circular dependency chain is:

   extensions/telegram/contract-api.ts
     → ./src/security-audit.js
       → openclaw/plugin-sdk/config-runtime
         → ./telegram-command-config.js
           → loadTelegramCommandConfigContract() [module load time]
             → getBundledChannelContractSurfaceModule({ pluginId: "telegram" })
               → jiti loads extensions/telegram/contract-api.ts [already loading → null]
                 → throws "telegram command config contract surface is unavailable"

Risk / Mitigation

• Risk: The inlined regex could drift from the canonical definition in extensions/telegram/src/command-config.ts if someone updates the extension pattern without updating the inlined copy.
• Mitigation: The new regression test in contract-surfaces.test.ts dynamically loads both the inlined constant and the extension contract surface, then asserts their source and flags are identical. Any drift will cause a test failure in the contracts test lane (pnpm test:contracts). Additionally, the JSDoc comment on the inlined constant explicitly references the extension source file and line number, making the relationship discoverable during code review.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Gateway
• Telegram
• Plugin SDK
• Config

Linked Issue/PR

Fixes #60685

Changed files

• src/channels/plugins/contract-surfaces.test.ts (modified, +18/-0)
• src/plugin-sdk/telegram-command-config.ts (modified, +17/-2)