packages/plugin/src/v2/effect/PLAN.md
This document describes the agreed target design for the V2 plugin system. It is an implementation plan, not documentation for the current API.
@opencode-ai/plugin/v2/effect, not @opencode-ai/core.@opencode-ai/sdk types.A plugin setup effect receives PluginHost and imperatively registers transforms and hooks.
export const Plugin = define({
id: "example",
effect: (ctx) =>
Effect.gen(function* () {
yield* ctx.agent.transform(
Effect.fn(function* (agent) {
agent.update("reviewer", (item) => {
item.description = "Reviews code for regressions"
item.mode = "subagent"
})
}),
)
yield* ctx.tool.hook(
"execute.before",
Effect.fn(function* (event) {
event.args.update(sanitizeArgs)
}),
)
}),
})
Plugin setup does not return hooks.
Settled names:
transformrebuildhookdisposeeventagent, command, integration, reference, session, skill, and tool; catalog remains catalog"execute.before" and "execute.after"Each transformable domain exposes:
interface TransformDomain<Editor> {
transform(callback: (editor: Editor) => Effect.Effect<void>): Effect.Effect<Registration, never, Scope.Scope>
rebuild(): Effect.Effect<void>
}
The actual callback may be represented with the project's normal Effect.fn style.
const registration =
yield *
ctx.catalog.transform(
Effect.fn(function* (catalog) {
const integration = yield* ctx.integration.get("anthropic")
if (!integration) return
catalog.provider.update("anthropic", (provider) => {
provider.name = "Anthropic"
})
}),
)
Transforms may perform arbitrary Effects, including reads from other PluginHost services, filesystem I/O, and network I/O. Reads from another domain observe that domain's latest committed state.
Transforms have no typed error channel. Unexpected failures are defects.
transform() creates an independent registration.Registration.dispose removes it early and is idempotent.rebuild() waits until replay and finalization complete.rebuild() always replays every active transform for the domain.rebuild() for the currently rebuilding domain from one of its transforms is rejected.Transforms and runtime hooks return the same Effect registration type.
interface Registration {
readonly dispose: Effect.Effect<void>
}
Registration behavior:
Scope.ScopeDomains expose runtime interception through hook().
const registration =
yield *
ctx.tool.hook(
"execute.before",
Effect.fn(function* (event) {
event.args.update(sanitizeArgs)
}),
)
Runtime hook behavior:
Each hook receives one purpose-built context object rather than separate input/output parameters.
ctx.tool.hook("execute.before", (event) => {
event.args.update((args) => ({
...args,
timeout: 30,
}))
})
Hook context objects may contain:
They must not expose core drafts or unrestricted internal objects.
Both use the same low-level scoped registration registry, but consumers invoke them differently.
ctx.tool.transform(...) // replayed to build effective tool registry state
ctx.tool.hook(...) // invoked at a live tool operation boundary
The shared low-level machinery owns registration order, scope cleanup, disposal, and snapshots. Each domain owns when its transforms or runtime hooks execute.
The Effect API exposes the existing event system as typed streams using generated SDK event discriminants.
ctx.event.subscribe("catalog.updated")
// Stream.Stream<EventCatalogUpdated>
Example:
yield *
ctx.event.subscribe("catalog.updated").pipe(
Stream.runForEach(() => ctx.agent.rebuild()),
Effect.forkScoped,
)
The plugin package derives event payload types from the generated SDK Event union:
type EventMap = {
[Item in Event as Item["type"]]: Item
}
Core resolves the public event type string to its internal event definition and delegates to EventV2.Service.subscribe.
Each transformable core service continues to own:
The initial implementation should evolve the existing generic State helper rather than create a central cross-domain state manager.
base state
→ replay active transforms in order
→ core domain finalization
→ commit effective state
→ publish updated event
No cross-domain transform or transaction API is included.
Each domain has one plugin transform phase followed by core finalization.
Core finalization is for invariants and materialization, not plugin extension behavior.
Examples:
Finalizers should distinguish pre-commit work from post-commit notification. Update events should publish after the new state is visible.
The default distribution uses an opinionated internal order:
1. Built-in agents, commands, and skills
2. Base data sources such as models.dev
3. Configuration projections
4. Provider-specific normalization and authentication
5. External user plugins
6. Core domain finalization
For catalog transforms:
models.dev
→ config provider overrides
→ built-in provider normalization
→ user catalog transforms
→ catalog finalization
This replaces the current distinction between setup-installed State transforms and catalog hooks invoked from the catalog finalizer.
Replacing a plugin with the same ID retains its existing order position. The old plugin is disabled before the replacement setup starts.
Plugin boot runs in an internal registration batch.
begin batch
→ initialize plugins sequentially
→ register transforms and hooks
→ collect affected domains
→ rebuild each affected domain once
→ end batch
Registration itself is not staged per plugin. If setup fails, closing the plugin's child scope removes every registration made before the failure.
Outside a batch, transform registration and disposal rebuild immediately.
Models.dev performs effectful reads directly from its transforms and rebuilds affected domains after refresh.
export const ModelsDevPlugin = define({
id: "models-dev",
effect: (ctx) =>
Effect.gen(function* () {
const modelsDev = yield* ModelsDev.Service
const event = yield* EventV2.Service
yield* ctx.integration.transform(
Effect.fn(function* (integration) {
const data = yield* modelsDev.get()
applyIntegrations(data, integration)
}),
)
yield* ctx.catalog.transform(
Effect.fn(function* (catalog) {
const data = yield* modelsDev.get()
applyCatalog(data, catalog)
}),
)
yield* event.subscribe(ModelsDev.Event.Refreshed).pipe(
Stream.runForEach(
Effect.fn(function* () {
yield* ctx.integration.rebuild()
yield* ctx.catalog.rebuild()
}),
),
Effect.forkScoped({ startImmediately: true }),
)
}),
})
The two domains rebuild sequentially. This plan does not add a cross-domain atomic transaction.
export const ConfigPlugin = define({
id: "config",
effect: (ctx) =>
Effect.gen(function* () {
const config = yield* ConfigSource.Service
yield* ctx.agent.transform(
Effect.fn(function* (agent) {
applyAgentConfig(yield* config.get(), agent)
}),
)
yield* ctx.command.transform(
Effect.fn(function* (command) {
applyCommandConfig(yield* config.get(), command)
}),
)
yield* config.changes.pipe(
Stream.runForEach(
Effect.fn(function* () {
yield* ctx.agent.rebuild()
yield* ctx.command.rebuild()
}),
),
Effect.forkScoped,
)
}),
})
A transform may read another committed service. It must still arrange for its own domain to rebuild when that dependency changes.
export const AnthropicAgentPlugin = define({
id: "anthropic-agent",
effect: (ctx) =>
Effect.gen(function* () {
yield* ctx.agent.transform(
Effect.fn(function* (agent) {
const providers = yield* ctx.catalog.provider.list()
if (!providers.some((provider) => provider.id === "anthropic")) return
agent.update("anthropic-reviewer", (item) => {
item.description = "Reviews code using Anthropic"
item.mode = "subagent"
item.model = {
providerID: "anthropic",
id: "claude-sonnet",
}
})
}),
)
yield* ctx.event.subscribe("catalog.updated").pipe(
Stream.runForEach(() => ctx.agent.rebuild()),
Effect.forkScoped,
)
}),
})
The runtime does not infer cross-domain dependencies.
The imperative registration model maps naturally to a future application embedding API:
const registration = oc.agent.transform((agent) => {
agent.update("reviewer", configureReviewer)
})
registration.dispose()
An application registration is stored as an application-level plugin registration. It attaches to every current Location and is installed during future Location boot. Disposal removes all current attachments and prevents future attachment.
The Effect implementation remains the canonical runtime. Promise and embedding wrappers are deferred until after the Effect API is stable.
PluginHost domain capabilities in @opencode-ai/plugin/v2/effect.Registration.event.subscribe(type).transform(callback) registration.rebuild().HookFunctions as the plugin setup return value.plugin.added catalog mutation handling.