[FEATURE]: Plugin package tool types should stay aligned

[eXamadeus]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Summary

• The @opencode-ai/plugin package's tool types consistently lag behind the capabilities available to them.
  • The ToolContext type is often out of date
  • User plugins can only return strings but should easily be able to support proper structured return objects

When new fields are added to the context passed to tools, plugin authors can't access them until someone manually updates the plugin package. A recent "catch up" PR for ToolContext was #8269 where .ask() and .metadata() were added to the types, but the ToolContext is still incomplete.

There is a second problem where the plugin system simply doesn't support returning anything but a string from the .execute function. I can't see any particular reason not to allow users to return properly formatted objects, but one issue might be related to truncation? If so there are ways around that that would still allow users to return metadata, title, and so on.

Current gaps

• ToolContext is missing callID, extra, metadata(), and ask() fields that built-in tools have
• Plugin tools can only return a string, while built-in tools can return structured objects with title, metadata, and attachments

Solutions

I have gone ahead and started a near term fix but also want to propose some longer term ideas.

Near Term

I'll make a PR (#9138) to update the types and allow a structured return object where plugin authors can control the title and metadata. The structured return object is a simple change and something that doesn't affect any of the longer term solutions in any way. It simply gives plugin authors a little more flexibility.

Long Term Proposals

1. Generate plugin types from source: we could derive @opencode-ai/plugin types directly from packages/opencode/src/tool/tool.ts to ensure they stay in sync
2. Shared type package: we could extract tool types into a shared package that both opencode core and plugin package import from
3. CI check: add a check that fails when plugin package types diverge from core tool types

Option 3 is probably the easiest "win", but I think option 1 or 2 are much more valuable over time. Option 1 has the downside of adding core as a dependency for the plugin package (at least I think so...maybe there's a cleaner way).

Any of these would prevent the pattern of plugin types falling behind and requiring periodic catch-up PRs.

Similar, but unrelated SDK v2 issues

• Plugin package not using latest SDK types #7147 - Plugin package not using latest SDK types (event types)
• plugin hook types not aligned with runtime triggers and missing v2 sdk #7641 - Plugin hook types not aligned with runtime triggers (SDK v2 types)

Note

I have a PR up to address the SDK v2 upgrade #8380

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Plugin package not using latest SDK types #7147: Plugin package not using latest SDK types (covers tool context type alignment issues)
• plugin hook types not aligned with runtime triggers and missing v2 sdk #7641: plugin hook types not aligned with runtime triggers and missing v2 sdk (covers the broader type misalignment pattern)
• ToolContext type missing metadata() method that exists at runtime #8219: ToolContext type missing metadata() method that exists at runtime (one specific instance of the missing types issue)

Feel free to ignore if none of these address your specific case.

[eXamadeus]

Yes github bot, the things I linked are related 😆

[eXamadeus]

Still relevant, just waiting on reviews.