File size: 2,478 Bytes
0dbc9de | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 | # OpenCode V2 Promise Plugin API
The Promise plugin API is the async/await equivalent of `@opencode-ai/plugin/v2/effect`. It grants plugins the same two in-process capabilities:
- `hook` installs behavior at an OpenCode extension point.
- `reload` reruns every transform hook for a stateful domain.
The only difference from the Effect API is the async boundary: hook callbacks, hook registration, `reload`, and `Registration.dispose` use Promises instead of Effects.
## Defining A Plugin
```ts
import { define } from "@opencode-ai/plugin/v2/promise"
export const Plugin = define({
id: "example",
setup: async (ctx) => {
await ctx.catalog.transform((catalog) => {
catalog.provider.update("example", (provider) => {
provider.name = "Example"
})
})
},
})
```
Plugin setup registers hooks imperatively. It does not return a hook object.
Configuration supplied for the plugin is available as `ctx.options`.
A registration may be removed early through `dispose`:
```ts
const registration = await ctx.catalog.transform(applyCatalog)
await registration.dispose()
```
## Transform Hooks
Transform hooks contribute to stateful domains. The draft editor is synchronous; the callback may be `async` when it needs to await other work:
```ts
await ctx.agent.transform((agent) => {
agent.update("reviewer", (item) => {
item.description = "Reviews code for regressions"
item.mode = "subagent"
})
})
```
Available transform hooks are namespaced by domain:
```ts
ctx.agent.transform
ctx.catalog.transform
ctx.command.transform
ctx.integration.transform
ctx.reference.transform
ctx.skill.transform
```
## Runtime Hooks
Runtime hooks intercept live operations:
```ts
await ctx.aisdk.sdk(async (event) => {
if (event.package !== "@ai-sdk/xai") return
const mod = await import("@ai-sdk/xai")
event.sdk = mod.createXai(event.options)
})
await ctx.aisdk.language((event) => {
if (event.model.providerID !== "xai") return
event.language = event.sdk.responses(event.model.api.id)
})
```
## Reloading A Domain
When data captured by a transform changes, reload the affected domain:
```ts
let data = await loadCatalog()
await ctx.catalog.transform((catalog) => {
applyCatalog(data, catalog)
})
data = await loadCatalog()
await ctx.catalog.reload()
```
Available reload operations are:
```ts
ctx.agent.reload()
ctx.catalog.reload()
ctx.command.reload()
ctx.integration.reload()
ctx.reference.reload()
ctx.skill.reload()
```
|