feat(sdk): resolve instance configuration from provided services (#46875)

This commit is contained in:
Kit Langton
2026-09-02 14:24:12 -04:00
committed by GitHub
Unverified
parent 4b6e879ba8
commit 318a82f784
6 changed files with 125 additions and 38 deletions
+16 -14
View File
@@ -73,7 +73,7 @@ The selector is installed before automatic recovery starts. Its callbacks must b
Use a persistent `database.path` to recover Sessions after restart; the default database is in memory. Workerd uses its injected Durable Object storage. After restart, the next capability-dependent operation or recovery drain rebuilds the selected instance from saved Session metadata and application data.
Promise plugin resources should be acquired in `setup` and released by its cleanup function. Effect configuration can acquire resources in its supplied instance Scope; capture application services before creating the SDK host.
Promise plugin resources should be acquired in `setup` and released by its cleanup function. Effect configuration can acquire resources in its supplied instance Scope and require services provided to the SDK entrypoint (see the Effect section).
## Workerd
@@ -118,24 +118,26 @@ const session = yield * opencode.sessions.get({ sessionID })
The Effect Workerd entrypoint is `@opencode-ai/sdk/workerd/effect`.
Effect configuration uses the same keys and lifetime rules, with canonical `Session.Info` values and an Effect-returning factory:
Effect configuration uses the same keys and lifetime rules, with canonical `Session.Info` values and an Effect-returning factory. `configure` may require services; `OpenCode.create` and `OpenCode.layer` carry those requirements, so the application satisfies them where it builds the SDK, as with any other Effect callback:
```ts
import { OpenCode } from "@opencode-ai/sdk/effect"
import { Effect, Schema } from "effect"
import { threads } from "./threads-effect"
import { Effect, Layer, Schema } from "effect"
import { Threads } from "./threads-effect"
import { slackPlugin } from "./slack-plugin-effect"
const threadMetadata = Schema.decodeUnknownSync(Schema.Struct({ threadID: Schema.String }))
const opencode =
yield *
OpenCode.create({
database: { path: "./sessions.db" },
instances: {
key: (session) => threadMetadata(session.metadata).threadID,
configure: (threadID) => threads.get(threadID).pipe(Effect.map((thread) => ({ plugins: [slackPlugin(thread)] }))),
},
})
const opencode = OpenCode.layer({
database: { path: "./sessions.db" },
instances: {
key: (session) => threadMetadata(session.metadata).threadID,
configure: (threadID) =>
Effect.gen(function* () {
const threads = yield* Threads
return { plugins: [slackPlugin(yield* threads.get(threadID))] }
}),
},
}).pipe(Layer.provide(Threads.layer))
```
Both Workerd entrypoints also accept `instances`. The public `OpenCode.InstanceOptions` and `OpenCode.InstanceConfiguration` types describe the corresponding Promise or Effect callbacks.
Resources acquired in `configure` still belong to the instance, not to the Scope the SDK was built in. Both Workerd entrypoints also accept `instances`. The public `OpenCode.InstanceOptions` and `OpenCode.InstanceConfiguration` types describe the corresponding Promise or Effect callbacks.
+10 -10
View File
@@ -10,9 +10,9 @@ import type { SdkInstances } from "../internal/instances"
export type { LogEntry, LogLevel, LogOptions, LogWriter } from "../logging"
export type CreateOptions = EmbeddedHost.CreateOptions
export type CreateOptions<R = never> = EmbeddedHost.CreateOptions<R>
export type EmbedOptions = EmbeddedHost.EmbedOptions
export type InstanceOptions = SdkInstances.Options
export type InstanceOptions<R = never> = SdkInstances.Options<R>
export type InstanceConfiguration = SdkInstances.Configuration
export type Interface = Omit<OpenCodeClient, "plugin" | "workspace"> & {
@@ -28,13 +28,12 @@ export type Interface = Omit<OpenCodeClient, "plugin" | "workspace"> & {
readonly plugin: EmbeddedHost.Interface["plugins"]["register"] & OpenCodeClient["plugin"]
}
export const create: (
options?: CreateOptions,
export const create: <R = never>(
options?: CreateOptions<R>,
embed?: EmbedOptions,
) => Effect.Effect<Interface, Config.ConfigError | Error, Scope.Scope> = Effect.fn("OpenCode.create")(function* (
options: CreateOptions = {},
embed: EmbedOptions = {},
) {
) => Effect.Effect<Interface, Config.ConfigError | Error, Scope.Scope | R> = Effect.fn("OpenCode.create")(function* <
R = never,
>(options: CreateOptions<R> = {}, embed: EmbedOptions = {}) {
const host = yield* Effect.acquireRelease(EmbeddedHost.create(options, embed), (host) => Effect.promise(host.close))
const client = yield* OpenCode.make({ baseUrl: "http://opencode.local" }).pipe(
Effect.provide(
@@ -57,5 +56,6 @@ export const create: (
export class Service extends Context.Service<Service, Interface>()("@opencode-ai/sdk/OpenCode") {}
export const layer = (options: CreateOptions = {}): Layer.Layer<Service, Config.ConfigError | Error> =>
Layer.effect(Service, create(options))
export const layer = <R = never>(
options: CreateOptions<R> = {},
): Layer.Layer<Service, Config.ConfigError | Error, Exclude<R, Scope.Scope>> => Layer.effect(Service, create(options))
+6 -4
View File
@@ -7,13 +7,13 @@ import { OpenCode } from "./opencode"
export type Configuration = WorkerdProfile.Configuration
export interface CreateOptions extends WorkerdProfile.Options {
export interface CreateOptions<R = never> extends WorkerdProfile.Options {
readonly log?: OpenCode.CreateOptions["log"]
readonly workspaceProviders?: OpenCode.CreateOptions["workspaceProviders"]
readonly instances?: OpenCode.CreateOptions["instances"]
readonly instances?: OpenCode.CreateOptions<R>["instances"]
}
export const create = ({ log, workspaceProviders, instances, ...options }: CreateOptions) => {
export const create = <R = never>({ log, workspaceProviders, instances, ...options }: CreateOptions<R>) => {
const profile = WorkerdProfile.make(options)
return OpenCode.create(
{ ...profile.options, log, workspaceProviders, instances },
@@ -21,7 +21,9 @@ export const create = ({ log, workspaceProviders, instances, ...options }: Creat
)
}
export const layer = (options: CreateOptions): Layer.Layer<OpenCode.Service, Config.ConfigError | Error> =>
export const layer = <R = never>(
options: CreateOptions<R>,
): Layer.Layer<OpenCode.Service, Config.ConfigError | Error, Exclude<R, Scope.Scope>> =>
Layer.effect(OpenCode.Service, create(options))
export type Interface = OpenCode.Interface
+6 -5
View File
@@ -13,10 +13,10 @@ import { context, layer, type LogOptions } from "../logging"
import { OwnedFetch } from "./fetch"
import { SdkInstances } from "./instances"
export interface CreateOptions extends Omit<ServerOptions, "hostname" | "port" | "password"> {
export interface CreateOptions<R = never> extends Omit<ServerOptions, "hostname" | "port" | "password"> {
readonly log?: LogOptions
readonly workspaceProviders?: Readonly<Record<string, WorkspaceDriver.Interface>>
readonly instances?: SdkInstances.Options
readonly instances?: SdkInstances.Options<R>
}
/** Host hooks for embedding opencode on a non-default runtime profile. */
@@ -24,11 +24,12 @@ export interface EmbedOptions {
readonly overrides?: LayerNode.Replacements
}
export const create = Effect.fn("EmbeddedHost.create")(function* (
options: CreateOptions = {},
export const create = Effect.fn("EmbeddedHost.create")(function* <R = never>(
options: CreateOptions<R> = {},
embed: EmbedOptions = {},
) {
const { log, workspaceProviders, instances, ...server } = options
const selector = instances ? SdkInstances.provide(instances, yield* Effect.context<R>()) : undefined
const runtime = ManagedRuntime.make(
createEmbeddedRoutes(
{
@@ -39,7 +40,7 @@ export const create = Effect.fn("EmbeddedHost.create")(function* (
workspaceProviders
? [...(embed.overrides ?? []), WorkspaceDriver.node.replace(WorkspaceDriver.registryNode(workspaceProviders))]
: embed.overrides,
instances ? (replacements) => SdkInstances.node(instances, replacements) : undefined,
selector ? (replacements) => SdkInstances.node(selector, replacements) : undefined,
).pipe(Layer.provide(HttpServer.layerServices), Layer.provideMerge(layer(log))),
)
+20 -4
View File
@@ -8,17 +8,33 @@ import { Location } from "@opencode-ai/schema/location"
import type { Session } from "@opencode-ai/schema/session"
import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
import type { LayerNode } from "@opencode-ai/util/effect/layer-node"
import { Duration, Effect, Layer, LayerMap, Scope } from "effect"
import { Context, Duration, Effect, Layer, LayerMap, Scope } from "effect"
export interface Configuration {
readonly plugins: InstancePlugins.List
}
export interface Options {
export interface Options<R = never> {
/** Select a sharing key within the Session's current Location. Must not initialize plugins. */
readonly key: (session: Session.Info) => string
/** Reconstruct configuration on a cache miss. Resources belong to the instance Scope. */
readonly configure: (key: string) => Effect.Effect<Configuration, unknown, Scope.Scope>
/**
* Reconstruct configuration on a cache miss. Resources belong to the instance Scope; other requirements
* are the services the SDK entrypoint was built with.
*/
readonly configure: (key: string) => Effect.Effect<Configuration, unknown, R | Scope.Scope>
}
/** Closes `configure` over services captured where the SDK entrypoint was built; the host graph has none of its own. */
export function provide<R>(options: Options<R>, context: Context.Context<R>): Options {
return {
key: options.key,
// The ambient side wins the merge, so the instance Scope owns configured resources rather than the
// build Scope that was captured alongside the services.
configure: (key) =>
options
.configure(key)
.pipe(Effect.updateContext((ambient: Context.Context<Scope.Scope>) => Context.merge(context, ambient))),
}
}
/** Replaces the host's `Instance.node`; `replacements` resolves lazily so instances inherit the final host graph. */
+67 -1
View File
@@ -8,7 +8,7 @@ import { makeMemoryDriver } from "@opencode-ai/core/environment/index"
import { SessionRunnerModel } from "@opencode-ai/core/session/runner/model"
import { WorkspaceDriver } from "@opencode-ai/core/workspace/driver"
import { Plugin } from "@opencode-ai/plugin/effect"
import { Deferred, Effect, Exit, Layer, Schema, Scope } from "effect"
import { Context, Deferred, Effect, Exit, Layer, Schema, Scope } from "effect"
import { tmpdirScoped } from "../../core/test/fixture/tmpdir"
import { testEffect } from "../../core/test/lib/effect"
import { AbsolutePath, Agent, Location, OpenCode } from "../src/effect"
@@ -234,3 +234,69 @@ it.live(
}),
15_000,
)
class Personas extends Context.Service<Personas, { readonly of: (threadID: string) => Effect.Effect<string> }>()(
"Personas",
) {}
it.live(
"configures instances from services provided to the SDK layer",
() =>
Effect.gen(function* () {
const directory = yield* tmpdirScoped()
const hostScope = yield* Scope.fork(yield* Effect.scope)
const attempts: string[] = []
const released: string[] = []
const layer = OpenCode.layer({
config: { directory: directory.path, project: false, content: "{}" },
models: { fetch: false },
fs: { filewatcher: false },
instances: {
key: (session) => metadata(session.metadata).threadID,
configure: (key) =>
Effect.gen(function* () {
const personas = yield* Personas
const persona = yield* personas.of(key)
const attempt = attempts.push(key)
yield* Effect.addFinalizer(() => Effect.sync(() => released.push(`${key}:${attempt}`)))
if (attempt === 1) return yield* Effect.fail(new Error("Persona store cold"))
return {
plugins: [
Plugin.define({
id: "persona",
effect: (ctx) =>
ctx.session.hook("prompt", (event) =>
Effect.sync(() => {
event.prompt.text += `:${persona}`
}),
),
}),
],
}
}),
},
}).pipe(Layer.provide(Layer.succeed(Personas, { of: (threadID) => Effect.succeed(`persona-for-${threadID}`) })))
const opencode = Context.get(yield* Layer.build(layer).pipe(Scope.provide(hostScope)), OpenCode.Service)
const session = yield* opencode.sessions.create({
title: "Service-configured fixture",
location: Location.Ref.make({ directory: AbsolutePath.make(directory.path) }),
metadata: { threadID: "thread-7" },
})
// A failed construction is discarded with what `configure` acquired, while the host lives on. Resources
// bound to the Scope captured alongside the services would instead linger until the host closes.
const failed = yield* opencode.sessions
.prompt({ sessionID: session.id, text: "Hello", resume: false })
.pipe(Effect.exit)
expect(Exit.isFailure(failed)).toBe(true)
expect(released).toEqual(["thread-7:1"])
const admitted = yield* opencode.sessions.prompt({ sessionID: session.id, text: "Hello", resume: false })
expect(admitted.payload.text).toBe("Hello:persona-for-thread-7")
expect(attempts).toEqual(["thread-7", "thread-7"])
expect(released).toEqual(["thread-7:1"])
yield* Scope.close(hostScope, Exit.void)
expect(released).toEqual(["thread-7:1", "thread-7:2"])
}),
15_000,
)