OpenCode Plugin: set the Langfuse user per session

[geoff-ux]

The problem

LANGFUSE_USER_ID (or userId in opencode-langfuse.json) is applied to every span the OpenCode process exports. That fits one person running OpenCode in a terminal.

Under opencode serve, one process hosts sessions for several people. Every trace is then filed under one user, or under none, so the Users view and per-user cost can't be used for a served deployment.

Our case: opencode serve behind a Slack bot, where each Slack thread is one OpenCode session owned by one person. Plugin 0.5.1, OpenCode 1.18.32.

Proposal

OpenCode's session API accepts free-form metadata when a session is created. When a session's metadata.userId is a non-empty string, use it as langfuse.user.id on every span of that session.

• LANGFUSE_USER_ID stays the fallback for sessions without it, so nothing changes for existing setups and there is no new configuration.
• Child agent sessions inherit their parent's user, since their spans join the parent's trace.
• A session the plugin has not seen an event for, such as one continued after OpenCode restarts, is read from OpenCode once before its first span starts.

POST /session
{ "metadata": { "userId": "user_01ABC" } }

Patch

I have this working and will open a pull request on langfuse/opencode-observability-plugin and link it here. It passes the repo's format, build, lint, knip and integration checks, and I checked the OpenCode 1 path against a real opencode serve 1.18.32. The OpenCode 2 path is covered by the integration tests only.

Related: the configurable trace tags idea in langfuse/opencode-observability-plugin#34 is a different attribute but the same question of process-wide versus per-session values.

[geoff-ux]

Pull request: langfuse/opencode-observability-plugin#48

[geoff-ux]

Update: I've closed the pull request for now. Our own review found it should not read the session inside hooks that OpenCode waits on, so it needs a rework before it is worth a maintainer's time. The request above still stands; a simpler version would take the user only from the session events the plugin already receives.