feat(httpapi): bridge instance dispose endpoint

kitlangton · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026 · 49129709a627bf1ebbbb72db954e11bad33a3e3b
commit 49129709a627bf1ebbbb72db954e11bad33a3e3b
diff --git a/packages/opencode/specs/effect/http-api.md b/packages/opencode/specs/effect/http-api.md
@@ -163,7 +163,7 @@ Use raw Effect HTTP routes where `HttpApi` does not fit. The goal is deleting Ho
 | `file`                   | `bridged` partial | find text/file/symbol, list/content/status                                               |
 | `mcp`                    | `bridged` partial | status only                                                                              |
 | `workspace`              | `bridged`         | list, get, enter                                                                         |
-| top-level instance reads | `bridged`         | path, vcs, command, agent, skill, lsp, formatter                                         |
+| top-level instance routes | `bridged`         | path, vcs, command, agent, skill, lsp, formatter, dispose                                |
 | experimental JSON routes | `bridged` partial | console reads, tool ids, worktree list, resource list; global session list remains later |
 | `session`                | `later/special`   | large stateful surface plus streaming                                                    |
 | `sync`                   | `later`           | process/control side effects                                                             |

diff --git a/packages/opencode/src/server/routes/instance/httpapi/instance.ts b/packages/opencode/src/server/routes/instance/httpapi/instance.ts
@@ -6,6 +6,7 @@ import { LSP } from "@/lsp"
 import { Vcs } from "@/project"
 import { Skill } from "@/skill"
 import * as InstanceState from "@/effect/instance-state"
+import { Instance } from "@/project/instance"
 import { Effect, Layer, Schema } from "effect"
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
 import { Authorization } from "./auth"
@@ -23,6 +24,7 @@ const VcsDiffQuery = Schema.Struct({
 })
 
 export const InstancePaths = {
+  dispose: "/instance/dispose",
   path: "/path",
   vcs: "/vcs",
   vcsDiff: "/vcs/diff",
@@ -37,6 +39,15 @@ export const InstanceApi = HttpApi.make("instance")
   .add(
     HttpApiGroup.make("instance")
       .add(
+        HttpApiEndpoint.post("dispose", InstancePaths.dispose, {
+          success: Schema.Boolean,
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "instance.dispose",
+            summary: "Dispose instance",
+            description: "Clean up and dispose the current OpenCode instance, releasing all resources.",
+          }),
+        ),
         HttpApiEndpoint.get("path", InstancePaths.path, {
           success: PathInfo,
         }).annotateMerge(
@@ -138,6 +149,17 @@ export const instanceHandlers = Layer.unwrap(
     const skill = yield* Skill.Service
     const vcs = yield* Vcs.Service
 
+    const dispose = Effect.fn("InstanceHttpApi.dispose")(function* () {
+      const ctx = yield* InstanceState.context
+      yield* Effect.sync(() => {
+        // Disposing inline would invalidate the active request scope before HttpApi can send the response.
+        setTimeout(() => {
+          void Instance.restore(ctx, () => Instance.dispose())
+        }, 0)
+      })
+      return true
+    })
+
     const getPath = Effect.fn("InstanceHttpApi.path")(function* () {
       const ctx = yield* InstanceState.context
       return {
@@ -180,6 +202,7 @@ export const instanceHandlers = Layer.unwrap(
 
     return HttpApiBuilder.group(InstanceApi, "instance", (handlers) =>
       handlers
+        .handle("dispose", dispose)
         .handle("path", getPath)
         .handle("vcs", getVcs)
         .handle("vcsDiff", getVcsDiff)

diff --git a/packages/opencode/src/server/routes/instance/index.ts b/packages/opencode/src/server/routes/instance/index.ts
@@ -64,6 +64,7 @@ export const InstanceRoutes = (upgrade: UpgradeWebSocket): Hono => {
     app.get(FilePaths.content, (c) => handler(c.req.raw, context))
     app.get(FilePaths.status, (c) => handler(c.req.raw, context))
     app.get(InstancePaths.path, (c) => handler(c.req.raw, context))
+    app.post(InstancePaths.dispose, (c) => handler(c.req.raw, context))
     app.get(InstancePaths.vcs, (c) => handler(c.req.raw, context))
     app.get(InstancePaths.vcsDiff, (c) => handler(c.req.raw, context))
     app.get(InstancePaths.command, (c) => handler(c.req.raw, context))

diff --git a/packages/opencode/test/server/httpapi-instance.test.ts b/packages/opencode/test/server/httpapi-instance.test.ts
@@ -77,4 +77,16 @@ describe("instance HttpApi", () => {
     expect(formatter.status).toBe(200)
     expect(await formatter.json()).toEqual([])
   })
+
+  test("serves instance dispose through Hono bridge", async () => {
+    await using tmp = await tmpdir()
+
+    const response = await app().request(InstancePaths.dispose, {
+      method: "POST",
+      headers: { "x-opencode-directory": tmp.path },
+    })
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toBe(true)
+  })
 })