spec: OVOS-TOOLS-1, the agent tools bus contract

[openvoiceos-bot]

🤖 Auto-generated by Claude Fable 5.1 (claude-fable-5-1) via Claude Code — NOT human-reviewed. Verify before acting.

What this adds

OVOS-TOOLS-1, a small specification for the agent tools bus surface, in the shape of OVOS-INSTALL-1. It defines the tool definition object, the two toolbox topics (ovos.persona.tools.discover, ovos.persona.tools.call with data.toolbox_id addressing), the four tool service topics (ovos.tools.list, .get, .invoke, .reload), the reply payloads and the error form. Version 1: every shipped component keeps working, and the one topic that changes is kept as a predecessor for a stable cycle.

The decision this PR needs

The wire shape of the toolbox call. The shipped ToolBox.bind in ovos-plugin-manager subscribes to ovos.persona.tools.<toolbox_id>.call, which embeds an identifier that no specification fixes. OVOS-MSG-1 §2.1.1 puts addressing in the payload. This draft picks a static ovos.persona.tools.call with data.toolbox_id, the same shape the PHAL tools plugin already uses for ovos.tools.invoke. The alternative is a <toolbox_id>:call dispatch shape, which needs a defining role and a reserved name.

Evidence the surface is described as shipped

Verified by the model against source, not by a human.

• ovos-plugin-manager dev 1c63579, ovos_plugin_manager/templates/agent_tools.py: bind subscribes to ovos.persona.tools.discover and ovos.persona.tools.{toolbox_id}.call; handle_discover answers {tools, toolbox_id}; handle_call reads name and kwargs and answers {result, toolbox_id} or {error, toolbox_id}; tool_json_list emits name, description, argument_schema, output_schema.
• ovos-PHAL-plugin-tools dev, ovos_phal_plugin_tools/__init__.py: subscribes to ovos.tools.list, .get, .invoke, .reload; payloads as in §5.
• Plan and the clause quoted: knowledge/wiki/plans/persona-contracts.md in the workspace.

Related: architecture#262 catalogues the per-toolbox topic in the divergences appendix; this PR adds the TOOLS-1 rows under §5.7 and the #262 row can drop when both merge.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}