Skip to content

[FEATURE]: Expose read-only persisted session history APIs to v2 plugins #43517

Description

@nulluserid

Feature hasn't been suggested before.

Describe the enhancement you want to request

Please expose the host's read-only persisted session APIs through the native v2 plugin context:

ctx.session.list({ project?, directory?, parentID?, cursor?, limit? })
ctx.session.children({ sessionID, cursor?, limit? })
ctx.session.messages({ sessionID, cursor?, limit? })

A plugin can currently inspect a known session, but after an OpenCode restart it cannot rediscover that session's persisted child tree or read the retained message usage records. Event tracking only works for children observed during the current process lifetime.

One concrete use case is a local usage report that totals a root session and all delegated descendants, grouped by agent and model, and also provides project-level history. Without these APIs, a plugin must either read OpenCode's SQLite database directly or spawn a CLI/API subprocess. Both couple plugins to implementation details outside the supported plugin boundary.

The host already exposes equivalent persisted session data through its session routes, and the dev branch has a useful stats CLI. This request complements those user-facing features: plugins need typed, structured access so they can build scoped tools and reports.

The host should enforce the same project, directory, and authorization boundaries as the existing session APIs, with bounded pagination. A minimal version could expose only list, children, and messages.

Tested against OpenCode 2 beta 17639 on macOS using the native @opencode-ai/plugin promise interface.

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions