Skip to content

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

Closed

Description

@ArchiTecCTT

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

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" } }
            ]
          }
        }
      ]
    }
  }
]

Activity

  1. Hona commented on Sep 22, 2026

    @Hona
    Member

    Fixed by #48452 (docs: fix v2 plugin system example), merged to v2 as 4e97b78 on 2026-09-11. Closing manually because v2 is not the default branch, so the PR did not auto-close this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions