anomalyco / anomalyco/opencode
docs: v2 plugins guide event.system example omits required type: "text"
@neriousy is already working on this.
Since Sep 11, 2026.
- Dominant language
- TypeScript
- Stars
- 209k
- Forks
- 27.5k
- PR merge metrics
- PR metrics pending
Description
Summary
The V2 plugins guide's context-hook example pushes { text } onto event.system, but the
LLM.SystemPart schema enforced by SessionModelRequest.prepare requires type: "text".
Following the example verbatim makes every model call fail with Error: Schema validation failed.
Environment
- opencode version: 0.0.0-beta-19271
- OS: Linux 6.17.0-1022-azure (x86_64, Ubuntu)
- Terminal: TERM=xterm-256color (TERM_PROGRAM unset, COLORTERM unset)
- Shell: /usr/bin/zsh
- Install/channel: beta (
@opencode-ai/cli) - Active plugins:
@plannotator/opencode@latest; one local plugin under~/.config/opencode/plugins/
Reproduction
-
Create a V2 plugin with the context hook exactly as documented at
https://opencode.ai/v2/docs/build/plugins ("Sessions" → "Model requests"):export default { id: "example", async setup(ctx) { await ctx.session.hook("context", (event) => { event.system.push({ text: "Keep the review focused on correctness." }); }); }, }; -
Load it (e.g.
~/.config/opencode/plugins/example.js) and run any prompt:
opencode2 run "hi".
Expected Behavior
The documented example works as written.
Actual Behavior
Every request fails before dispatch:
level=ERROR message="Failed to drain Session" cause="Error: Schema validation failed
at SessionModelRequest.prepare (...)"
The Effect Schema issue pointer is ["system"][3]["type"] → MissingKey. LLM.SystemPart is
defined as:
{ type: "text"; text: string; cache?: LLM.CacheHint; metadata?: Record<string, unknown> }
so { text } alone is rejected.
Additional Context
- Correct form:
event.system.push({ type: "text", text: "..." })— addingtypefixes it. - Affected docs page: https://opencode.ai/v2/docs/build/plugins. Only the
event.systemexample
is wrong; the surroundingevent.system.push(...)prose matches the bad example. - Note:
SessionContextHook'ssystem: SystemPart[]type in the same page does not spell out the
type: "text"discriminant either, so the omission is consistent in the docs.
Schema failure excerpt (truncated)
"issues": [
{
"_tag": "Pointer",
"path": ["system"],
"issue": {
"_tag": "Composite",
"issues": [
{
"_tag": "Pointer",
"path": [3],
"issue": {
"_tag": "Composite",
"issues": [
{ "_tag": "Pointer", "path": ["type"], "issue": { "_tag": "MissingKey" } }
]
}
}
]
}
}
]
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.