Companion modules: extending the author experience

Canon: kb/155 — companion_module block parallels cp_extension.

What a module declares

Surface	Purpose
modes	Conversation mode picker; optional agent_id sends POST /v1/agents/call with agent_id in the body.
panels	Sidebar (or other positions): server-driven summaries (e.g. config, stats).
tools	Thread actions; HumanOS wiring for agent/connector routing lands incrementally.
quick_actions	Composer shortcuts using brief_template placeholders.

Install & lifecycle

Same marketplace installation pattern as CP extensions: marketplace_companion_modules rows, cascade delete with the installation. The Companion Platform modules strip loads /v1/orgs/:org_did/companion-modules.

Authoring tips

• Keep brief_template short and use {topic}-style holes the user can edit after insert.
• Modes with agent_id should reference agents your org actually installed.
• Trust tier on the source asset is shown in the shell; align with your governance story.

See also

• human extension create … --template companion-toolkit for a starter manifest.
• CP parallel: docs/guides/building-first-cp-extension.md