Use structured plugin command events

[gabek]

Command tables now receive parsed command invocations from Owncast instead of parsing every chat message independently in JavaScript and Python.

• Report aliases, case sensitivity, moderator gating, and cooldown settings during registration.
• Handle the internal command event in both SDKs while keeping ordinary chat handlers independent.
• Remove the low-level command routers and their unknown, denied, and cooldown callbacks.
• Update the scenario runner to exercise command matching and metadata.
• Remove the obsolete command-router examples and update the remaining examples, author guide, wire protocol, templates, and agent skills.

This is a breaking SDK change and requires the matching Owncast runtime update.

I ran the host-runtime Go tests and the complete JavaScript and Python mod-commands scenario suites.

[Copilot]

Pull request overview

This PR migrates chat command handling from SDK-side message parsing to host/core-driven command matching and dispatch via an internal chat.command event, updating both the JavaScript and Python SDKs plus the scenario runner, examples, and documentation to reflect the new structured command flow.

Changes:

• Switch JS + Python SDKs to declare command registrations for host matching/dispatch and remove the low-level command routers (defineCommands / define_commands) and related callbacks.
• Update the Go scenario runner/expectations to exercise command metadata (aliases, case sensitivity, cooldowns) and to dispatch commands after chat notifications.
• Refresh docs/templates/agent skills and examples; remove obsolete “command-router” examples.

Reviewed changes

Copilot reviewed 40 out of 42 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sdks/python/owncast_plugin/template/AGENTS.md	Update Python template guidance to use plugin.commands({...}).
sdks/python/owncast_plugin/template/.agents/skills/create-owncast-plugin-py/SKILL.md	Update Python skill docs for declarative commands and new behavior (silent unknown/gated).
sdks/python/owncast_plugin/build.py	Stop exporting the removed define_commands symbol from the Python bundle exports.
sdks/python/owncast_plugin/init.py	Implement host-driven command dispatch (chat.command), command registration metadata, and remove SDK-side routing.
sdks/js/index.js	Record command registrations for the host; dispatch matched commands via internal chat.command; remove defineCommands export.
sdks/js/index.d.ts	Update public types/docs for declarative commands and the new command context (invokedAs), remove defineCommands typing.
sdks/js/create-owncast-plugin/template/AGENTS.md	Update JS template guidance to use commands: {...} instead of defineCommands.
sdks/js/create-owncast-plugin/template/.agents/skills/create-owncast-plugin-js/SKILL.md	Update JS skill docs for declarative commands and new behavior (silent unknown/gated).
host-runtime/plugin/testing/scenario.go	Extend command expectation shape to include caseSensitive + cooldownMs.
host-runtime/plugin/testing/runner.go	Ensure chat message steps notify plugins then dispatch matched commands; tighten empty-vs-nil slice comparisons.
examples/python/stream-tracker/src/plugin.py	Refresh example header comment to match new command handling model.
examples/python/stream-ops/src/plugin.py	Refresh example header comment to match new command handling model.
examples/python/README.md	Remove command-router example and adjust mod-commands description to match new semantics.
examples/python/mod-commands/src/plugin.py	Update mod-commands example to cooldown + silent unknown/denied behavior and keep chat handler independent.
examples/python/mod-commands/README.md	Update mod-commands documentation for cooldown + silent behavior.
examples/python/mod-commands/plugin.manifest.json	Update example description to mention cooldowns and declarative commands.
examples/python/mod-commands/INSTRUCTIONS.md	Update instructions to match silent unknown/denied + cooldown.
examples/python/mod-commands/tests/mod-commands.test.json	Update scenario assertions for silent unknown/denied and add cooldown test + metadata expectations.
examples/python/command-router/src/plugin.py	Remove obsolete low-level router example.
examples/python/command-router/README.md	Remove obsolete low-level router example docs.
examples/python/command-router/plugin.manifest.json	Remove obsolete low-level router example manifest.
examples/python/command-router/INSTRUCTIONS.md	Remove obsolete low-level router example instructions.
examples/python/command-router/tests/command-router.test.json	Remove obsolete low-level router example tests.
examples/js/stream-tracker/src/plugin.js	Refresh example header comment to match new command handling model.
examples/js/stream-ops/src/plugin.js	Refresh example header comment to match new command handling model.
examples/js/README.md	Remove command-router example and adjust mod-commands description to match new semantics.
examples/js/mod-commands/src/plugin.js	Update mod-commands example to cooldown + silent unknown/denied behavior and keep chat handler independent.
examples/js/mod-commands/README.md	Update mod-commands documentation for cooldown + silent behavior.
examples/js/mod-commands/plugin.manifest.json	Update example description to mention cooldowns and declarative commands.
examples/js/mod-commands/INSTRUCTIONS.md	Update instructions to match silent unknown/denied + cooldown.
examples/js/mod-commands/tests/mod-commands.test.json	Update scenario assertions for silent unknown/denied and add cooldown test + metadata expectations.
examples/js/ip-bot/src/plugin.js	Update guidance to prefer declarative command tables (no longer defineCommands).
examples/js/command-router/src/plugin.js	Remove obsolete low-level router example.
examples/js/command-router/README.md	Remove obsolete low-level router example docs.
examples/js/command-router/plugin.manifest.json	Remove obsolete low-level router example manifest.
examples/js/command-router/package.json	Remove obsolete low-level router example package manifest.
examples/js/command-router/package-lock.json	Remove obsolete low-level router example lockfile.
examples/js/command-router/INSTRUCTIONS.md	Remove obsolete low-level router example instructions.
examples/js/command-router/tests/command-router.test.json	Remove obsolete low-level router example tests.
docs/WIRE_PROTOCOL.md	Document new register output and internal chat.command event payload/ordering.
docs/PLUGIN_AUTHOR_GUIDE.md	Update author guidance for commands, context shape, and new silent/ordering semantics.
docs/ARCHITECTURE.md	Update architecture notes to reflect command dispatch model and host responsibilities.

Files not reviewed (1)

• examples/js/command-router/package-lock.json: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gabek]

The original toolchain failure cleared after owncast/owncast#5043 merged. The rerun exposed a second integration failure limited to the JavaScript and Python engagement-bot quote and catch-all activity scenarios. #5043 had rebuilt the shared engines from an older SDK branch, overwriting the handlers added by #5039. I rebased this SDK branch onto current main, rebuilt both engines, and verified all engagement-bot and mod-commands scenarios against the combined artifacts. The engine correction is in owncast/owncast#5044. SDK CI will pass once #5044 merges and these workflows rerun against updated develop.