diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 65560b2a6e3..511a61d0d2b 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -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. diff --git a/packages/sdk/src/effect/opencode.ts b/packages/sdk/src/effect/opencode.ts index 6814062ea87..fb43c0c7cda 100644 --- a/packages/sdk/src/effect/opencode.ts +++ b/packages/sdk/src/effect/opencode.ts @@ -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 = EmbeddedHost.CreateOptions export type EmbedOptions = EmbeddedHost.EmbedOptions -export type InstanceOptions = SdkInstances.Options +export type InstanceOptions = SdkInstances.Options export type InstanceConfiguration = SdkInstances.Configuration export type Interface = Omit & { @@ -28,13 +28,12 @@ export type Interface = Omit & { readonly plugin: EmbeddedHost.Interface["plugins"]["register"] & OpenCodeClient["plugin"] } -export const create: ( - options?: CreateOptions, +export const create: ( + options?: CreateOptions, embed?: EmbedOptions, -) => Effect.Effect = Effect.fn("OpenCode.create")(function* ( - options: CreateOptions = {}, - embed: EmbedOptions = {}, -) { +) => Effect.Effect = Effect.fn("OpenCode.create")(function* < + R = never, +>(options: CreateOptions = {}, 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()("@opencode-ai/sdk/OpenCode") {} -export const layer = (options: CreateOptions = {}): Layer.Layer => - Layer.effect(Service, create(options)) +export const layer = ( + options: CreateOptions = {}, +): Layer.Layer> => Layer.effect(Service, create(options)) diff --git a/packages/sdk/src/effect/workerd.ts b/packages/sdk/src/effect/workerd.ts index 68ba69e8a9d..34c9a041be8 100644 --- a/packages/sdk/src/effect/workerd.ts +++ b/packages/sdk/src/effect/workerd.ts @@ -7,13 +7,13 @@ import { OpenCode } from "./opencode" export type Configuration = WorkerdProfile.Configuration -export interface CreateOptions extends WorkerdProfile.Options { +export interface CreateOptions extends WorkerdProfile.Options { readonly log?: OpenCode.CreateOptions["log"] readonly workspaceProviders?: OpenCode.CreateOptions["workspaceProviders"] - readonly instances?: OpenCode.CreateOptions["instances"] + readonly instances?: OpenCode.CreateOptions["instances"] } -export const create = ({ log, workspaceProviders, instances, ...options }: CreateOptions) => { +export const create = ({ log, workspaceProviders, instances, ...options }: CreateOptions) => { 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 => +export const layer = ( + options: CreateOptions, +): Layer.Layer> => Layer.effect(OpenCode.Service, create(options)) export type Interface = OpenCode.Interface diff --git a/packages/sdk/src/internal/host.ts b/packages/sdk/src/internal/host.ts index 46bc6792e75..26ade32e843 100644 --- a/packages/sdk/src/internal/host.ts +++ b/packages/sdk/src/internal/host.ts @@ -13,10 +13,10 @@ import { context, layer, type LogOptions } from "../logging" import { OwnedFetch } from "./fetch" import { SdkInstances } from "./instances" -export interface CreateOptions extends Omit { +export interface CreateOptions extends Omit { readonly log?: LogOptions readonly workspaceProviders?: Readonly> - readonly instances?: SdkInstances.Options + readonly instances?: SdkInstances.Options } /** 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* ( + options: CreateOptions = {}, embed: EmbedOptions = {}, ) { const { log, workspaceProviders, instances, ...server } = options + const selector = instances ? SdkInstances.provide(instances, yield* Effect.context()) : 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))), ) diff --git a/packages/sdk/src/internal/instances.ts b/packages/sdk/src/internal/instances.ts index 1a613cb64c5..d6e9cdf39b6 100644 --- a/packages/sdk/src/internal/instances.ts +++ b/packages/sdk/src/internal/instances.ts @@ -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 { /** 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 + /** + * 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 +} + +/** Closes `configure` over services captured where the SDK entrypoint was built; the host graph has none of its own. */ +export function provide(options: Options, context: Context.Context): 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) => Context.merge(context, ambient))), + } } /** Replaces the host's `Instance.node`; `replacements` resolves lazily so instances inherit the final host graph. */ diff --git a/packages/sdk/test/instances-effect.test.ts b/packages/sdk/test/instances-effect.test.ts index 2a0e1cb93fa..9021d191cb5 100644 --- a/packages/sdk/test/instances-effect.test.ts +++ b/packages/sdk/test/instances-effect.test.ts @@ -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 Effect.Effect }>()( + "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, +)