anomalyco/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-07-22 02:05:26 -04:00
Code Issues 5.9k Packages Projects Releases 19 Wiki Activity

[FEATURE]: Plugin package tool types should stay aligned #5519

New Issue
Open
opened 2026-02-16 17:53:40 -05:00 by yindo · 0 comments
yindo commented 2026-02-16 17:53:40 -05:00
Owner
Copy Link
Copy Source

Originally created by @eXamadeus on GitHub (Jan 13, 2026).

Originally assigned to: @thdxr on GitHub.

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

  • #7147 - Plugin package not using latest SDK types (event types)
  • #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

Originally created by @eXamadeus on GitHub (Jan 13, 2026). Originally assigned to: @thdxr on GitHub. ### Feature hasn't been suggested before. - [x] 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 - #7147 - Plugin package not using latest SDK types (event types) - #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
yindo added the discussion label 2026-02-16 17:53:40 -05:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
acp
bad
bug
discussion
docs
documentation
enhancement
extension
good first issue
growth
help-wanted
mcp
model-problem
needs:compliance
nix
opentui
perf
pull-request
Mirrored from GitHub Pull Request
 tui
web
windows
zen
No Label discussion
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: anomalyco/opencode#5519
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?