anomalyco / anomalyco/opencode

docs: v2 plugins guide event.system example omits required type: "text"

Open
#48,450 0 comments 0 reactions 1 assignee View on GitHub

@neriousy is already working on this.

Since Sep 11, 2026.

2.0
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

  1. 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." });
        });
      },
    };
    
  2. 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: "..." }) — adding type fixes it.
  • Affected docs page: https://opencode.ai/v2/docs/build/plugins. Only the event.system example
    is wrong; the surrounding event.system.push(...) prose matches the bad example.
  • Note: SessionContextHook's system: 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.