mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-20 01:08:31 +03:00
8de0323975
Co-authored-by: opencode-agent[bot] <219766164+opencode-agent[bot]@users.noreply.github.com>
191 lines
6.0 KiB
Markdown
191 lines
6.0 KiB
Markdown
# OpenCode V2 Effect Plugin API
|
|
|
|
The Effect plugin API grants plugins two in-process capabilities:
|
|
|
|
- `hook` installs behavior at an OpenCode extension point.
|
|
- `reload` reruns every transform hook for a stateful domain.
|
|
|
|
## Defining A Plugin
|
|
|
|
```ts
|
|
import { Plugin } from "@opencode/plugin/effect"
|
|
import { Effect } from "effect"
|
|
|
|
export default Plugin.define({
|
|
id: "example",
|
|
effect: Effect.fn(function* (ctx) {
|
|
yield* ctx.provider.transform((editor) => {
|
|
editor.update("example", (provider) => {
|
|
provider.name = "Example"
|
|
})
|
|
})
|
|
}),
|
|
})
|
|
```
|
|
|
|
Plugin setup registers hooks imperatively through each domain's `hook` method.
|
|
|
|
Configuration supplied for the plugin is available as `ctx.options`.
|
|
|
|
Registrations are owned by the plugin scope. Closing the scope removes them automatically; a registration may also be removed early through `dispose`.
|
|
|
|
## Transform Hooks
|
|
|
|
Transform hooks contribute to stateful domains. Their editor callbacks are
|
|
synchronous, so load effectful data before registering a transform or reloading
|
|
its domain:
|
|
|
|
```ts
|
|
yield *
|
|
ctx.agent.transform((agent) => {
|
|
agent.update("reviewer", (item) => {
|
|
item.description = "Reviews code for regressions"
|
|
item.mode = "subagent"
|
|
})
|
|
})
|
|
```
|
|
|
|
Registry reads rebuild synchronously when registrations changed, applying every transform in registration order to a fresh value; unchanged registries return the previous value. Values read earlier are never mutated. Notifications and resource reconciliation run separately from that materialization.
|
|
|
|
Available transform hooks are namespaced by domain:
|
|
|
|
```ts
|
|
ctx.agent.transform
|
|
ctx.command.transform
|
|
ctx.integration.transform
|
|
ctx.mcp.transform
|
|
ctx.model.transform
|
|
ctx.provider.transform
|
|
ctx.reference.transform
|
|
ctx.skill.transform
|
|
ctx.tool.transform
|
|
ctx.vcs.transform
|
|
ctx.websearch.transform
|
|
```
|
|
|
|
Provider transforms contribute provider settings and immutable model definitions. After provider availability is resolved,
|
|
model transforms edit the complete active-provider candidate collection in order. Use `ctx.model.transform` for runtime
|
|
model restrictions; `editor.provider.get()` reads source templates even when their provider is inactive.
|
|
|
|
```ts
|
|
Effect.gen(function* () {
|
|
yield* ctx.model.transform((editor) => {
|
|
editor
|
|
.list()
|
|
.filter((model) => model.cost.some((tier) => tier.output > 20))
|
|
.forEach((model) => {
|
|
editor.remove(model.providerID, model.id)
|
|
})
|
|
})
|
|
})
|
|
```
|
|
|
|
## Runtime Hooks
|
|
|
|
Runtime hooks intercept live operations rather than rebuilding domain state:
|
|
|
|
```ts
|
|
yield *
|
|
ctx.aisdk.hook(
|
|
"sdk",
|
|
Effect.fn(function* (event) {
|
|
if (event.package !== "@ai-sdk/xai") return
|
|
const mod = yield* Effect.promise(() => import("@ai-sdk/xai"))
|
|
event.sdk = mod.createXai(event.options)
|
|
}),
|
|
)
|
|
|
|
yield *
|
|
ctx.aisdk.hook("language", (event) =>
|
|
Effect.sync(() => {
|
|
if (event.model.providerID !== "xai") return
|
|
event.language = event.sdk.responses(event.model.modelID)
|
|
}),
|
|
)
|
|
```
|
|
|
|
Hooks run sequentially in registration order. Later hooks observe mutations made by earlier hooks.
|
|
|
|
Session context is mutable immediately before provider dispatch:
|
|
|
|
```ts
|
|
yield *
|
|
ctx.session.hook("context", (event) =>
|
|
Effect.sync(() => {
|
|
event.tools.read.description = "Read a file using narrow line ranges."
|
|
delete event.tools.write
|
|
}),
|
|
)
|
|
|
|
yield *
|
|
ctx.session.hook("retry", (event) =>
|
|
Effect.sync(() => {
|
|
if (event.attempt >= 3) event.decision = { retry: false }
|
|
}),
|
|
)
|
|
```
|
|
|
|
When a Session finishes model work with no pending input, the `experimental.idle` hook runs just before it goes idle.
|
|
It is experimental: its name and shape may still change. It does not run after interruption, failure, or control-only
|
|
work such as a manual compaction. Input the hook admits runs in the same execution instead of the Session going idle,
|
|
so a plugin that always admits input must bound its own loop.
|
|
|
|
`event.background` lists background shells and subagents still running for the Session or its descendants. When one of
|
|
the Session's own shells or subagents finishes, its notice wakes the Session and the hook runs again, so a plugin that
|
|
waits for that work can return. Work a descendant owns, such as a shell a subagent left running, wakes that
|
|
descendant instead, so it is listed for information only. Notices admitted with `resume: false`, such as those
|
|
recovered after a restart, wait for the next wake instead:
|
|
|
|
```ts
|
|
yield *
|
|
ctx.session.hook("experimental.idle", (event) =>
|
|
event.background.some((work) => work.kind === "subagent" && work.sessionID === event.sessionID)
|
|
? Effect.void
|
|
: ctx.session
|
|
.synthetic({ sessionID: event.sessionID, text: "Run the tests and fix any failures." })
|
|
.pipe(Effect.ignore),
|
|
)
|
|
```
|
|
|
|
A continuation runs inside the same execution, so a loop that is still going when the server restarts is resumed by
|
|
restart recovery and the hook keeps running. Persist your own state if the loop should come back paused. A hook that
|
|
fails, fails the execution like any other session hook, so handle errors from slow or remote work such as a judge model
|
|
call.
|
|
|
|
## Reloading A Domain
|
|
|
|
When data captured by a transform changes, reload the affected domain:
|
|
|
|
```ts
|
|
Effect.gen(function* () {
|
|
const source = { providers: yield* loadProviders() }
|
|
|
|
yield* ctx.provider.transform((editor) => {
|
|
source.providers.forEach((provider) => editor.add(provider))
|
|
})
|
|
|
|
source.providers = yield* loadProviders()
|
|
yield* ctx.provider.reload()
|
|
})
|
|
```
|
|
|
|
`loadProviders()` returns entries shaped as `{ info: Provider.Info, models: readonly Model.Info[] }`. Provider reloads
|
|
also invalidate the active model result, so every model transform runs again with the refreshed definitions. Model
|
|
callbacks edit raw overrides; provider defaults are merged once when the result is committed.
|
|
|
|
Available reload operations are:
|
|
|
|
```ts
|
|
ctx.agent.reload()
|
|
ctx.command.reload()
|
|
ctx.integration.reload()
|
|
ctx.mcp.reload()
|
|
ctx.model.reload()
|
|
ctx.provider.reload()
|
|
ctx.reference.reload()
|
|
ctx.skill.reload()
|
|
ctx.tool.reload()
|
|
ctx.vcs.reload()
|
|
ctx.websearch.reload()
|
|
```
|