refactor(tui): simplify plugin update controls

bun.lock

@@ -986,6 +986,7 @@
         "mime-types": "3.0.2",
         "minimatch": "10.2.5",
         "npm-package-arg": "13.0.2",
+        "pacote": "21.5.1",
         "resolve.exports": "catalog:",
       },
       "devDependencies": {
@@ -995,6 +996,7 @@
         "@types/node": "catalog:",
         "@types/npm-package-arg": "6.1.4",
         "@types/npmcli__arborist": "6.3.3",
+        "@types/pacote": "11.1.8",
         "@typescript/native-preview": "catalog:",
       },
     },

packages/client/src/effect/api/api.ts

@@ -88,8 +88,35 @@ export type PluginListInput = {
 export type PluginListOutput = { readonly location: Location.Info; readonly data: ReadonlyArray<Plugin.Info> }
 export type PluginListOperation<E = never> = (input?: PluginListInput) => Effect.Effect<PluginListOutput, E>
 
+export type PluginCheckInput = {
+  readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+}
+export type PluginCheckOutput = { readonly location: Location.Info; readonly data: ReadonlyArray<Plugin.UpdateInfo> }
+export type PluginCheckOperation<E = never> = (input?: PluginCheckInput) => Effect.Effect<PluginCheckOutput, E>
+
+export type PluginUpdateInput = {
+  readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  readonly name: string
+}
+export type PluginUpdateOutput = { readonly location: Location.Info; readonly data: Plugin.UpdateResult }
+export type PluginUpdateOperation<E = never> = (input: PluginUpdateInput) => Effect.Effect<PluginUpdateOutput, E>
+
+export type PluginUpdateAllInput = {
+  readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+}
+export type PluginUpdateAllOutput = {
+  readonly location: Location.Info
+  readonly data: ReadonlyArray<Plugin.UpdateResult>
+}
+export type PluginUpdateAllOperation<E = never> = (
+  input?: PluginUpdateAllInput,
+) => Effect.Effect<PluginUpdateAllOutput, E>
+
 export interface PluginApi<E = never> {
   readonly list: PluginListOperation<E>
+  readonly check: PluginCheckOperation<E>
+  readonly update: PluginUpdateOperation<E>
+  readonly updateAll: PluginUpdateAllOperation<E>
 }
 
 export type SessionListInput = {

packages/client/src/effect/generated/client.ts

@@ -15,6 +15,12 @@ import type {
   AgentGetOutput,
   PluginListInput,
   PluginListOutput,
+  PluginCheckInput,
+  PluginCheckOutput,
+  PluginUpdateInput,
+  PluginUpdateOutput,
+  PluginUpdateAllInput,
+  PluginUpdateAllOutput,
   SessionListInput,
   SessionListOutput,
   SessionStatsInput,
@@ -313,7 +319,29 @@ const EndpointPluginList = (raw: RawClient["server.plugin"]) => (input?: PluginL
     raw["plugin.list"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
   )
 
-const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({ list: EndpointPluginList(raw) })
+const EndpointPluginCheck = (raw: RawClient["server.plugin"]) => (input?: PluginCheckInput) =>
+  preserveEffect<PluginCheckOutput>()(
+    raw["plugin.check"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
+  )
+
+const EndpointPluginUpdate = (raw: RawClient["server.plugin"]) => (input: PluginUpdateInput) =>
+  preserveEffect<PluginUpdateOutput>()(
+    raw["plugin.update"]({ query: { location: input["location"] }, payload: { name: input["name"] } }).pipe(
+      Effect.mapError(mapClientError),
+    ),
+  )
+
+const EndpointPluginUpdateAll = (raw: RawClient["server.plugin"]) => (input?: PluginUpdateAllInput) =>
+  preserveEffect<PluginUpdateAllOutput>()(
+    raw["plugin.updateAll"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
+  )
+
+const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({
+  list: EndpointPluginList(raw),
+  check: EndpointPluginCheck(raw),
+  update: EndpointPluginUpdate(raw),
+  updateAll: EndpointPluginUpdateAll(raw),
+})
 
 const EndpointSessionList = (raw: RawClient["server.session"]) => (input?: SessionListInput) =>
   preserveEffect<SessionListOutput>()(

packages/client/src/promise/generated/client.ts

@@ -9,6 +9,12 @@ import type {
   AgentGetOutput,
   PluginListInput,
   PluginListOutput,
+  PluginCheckInput,
+  PluginCheckOutput,
+  PluginUpdateInput,
+  PluginUpdateOutput,
+  PluginUpdateAllInput,
+  PluginUpdateAllOutput,
   SessionListInput,
   SessionListOutput,
   SessionStatsInput,
@@ -457,6 +463,43 @@ export function make(options: ClientOptions) {
           },
           requestOptions,
         ),
+      check: (input?: PluginCheckInput, requestOptions?: RequestOptions) =>
+        request<PluginCheckOutput>(
+          {
+            method: "GET",
+            path: `/api/plugin/update`,
+            query: { location: input?.["location"] },
+            successStatus: 200,
+            declaredStatuses: [401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ),
+      update: (input: PluginUpdateInput, requestOptions?: RequestOptions) =>
+        request<PluginUpdateOutput>(
+          {
+            method: "POST",
+            path: `/api/plugin/update`,
+            query: { location: input["location"] },
+            body: { name: input["name"] },
+            successStatus: 200,
+            declaredStatuses: [401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ),
+      updateAll: (input?: PluginUpdateAllInput, requestOptions?: RequestOptions) =>
+        request<PluginUpdateAllOutput>(
+          {
+            method: "POST",
+            path: `/api/plugin/update-all`,
+            query: { location: input?.["location"] },
+            successStatus: 200,
+            declaredStatuses: [401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ),
     },
     session: {
       list: (input?: SessionListInput, requestOptions?: RequestOptions) =>

packages/client/src/promise/generated/types.ts

@@ -426,6 +426,24 @@ export type PluginInfo =
   | { id: string; source: PluginSource; status: "active"; tui: boolean }
   | { id?: string; source: PluginSource; status: "failed"; error: string; tui: boolean }
 
+export type PluginUpdateInfo = {
+  name: string
+  source: PluginSource
+  status: "not-updateable" | "pinned" | "up-to-date" | "available" | "failed"
+  currentVersion?: string
+  latestVersion?: string
+  error?: string
+}
+
+export type PluginUpdateResult = {
+  name: string
+  source: PluginSource
+  status: "not-updateable" | "pinned" | "up-to-date" | "updated" | "failed"
+  previousVersion?: string
+  version?: string
+  error?: string
+}
+
 export type SessionMessageLocationSwitched = {
   id: string
   metadata?: { [x: string]: JsonValue }
@@ -2460,6 +2478,40 @@ export type PluginListOutput = {
   data: Array<PluginInfo>
 }
 
+export type PluginCheckInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+}
+
+export type PluginCheckOutput = {
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
+  data: Array<PluginUpdateInfo>
+}
+
+export type PluginUpdateInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+  readonly name: { readonly name: string }["name"]
+}
+
+export type PluginUpdateOutput = {
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
+  data: PluginUpdateResult
+}
+
+export type PluginUpdateAllInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+}
+
+export type PluginUpdateAllOutput = {
+  location: { directory: string; workspaceID?: string; project: { id: string; directory: string; canonical: string } }
+  data: Array<PluginUpdateResult>
+}
+
 export type SessionListInput = {
   readonly workspace?: {
     readonly workspace?: string | undefined

packages/core/src/plugin.ts

@@ -1,5 +1,5 @@
 export * as Plugin from "./plugin.js"
-export { Event, ID, Info, Source } from "@opencode-ai/schema/plugin"
+export { Event, ID, Info, Source, UpdateInfo, UpdateResult } from "@opencode-ai/schema/plugin"
 
 import { Plugin } from "@opencode-ai/schema/plugin"
 import type { Plugin as PluginDefinition } from "@opencode-ai/plugin/effect/plugin"

packages/core/src/plugin/supervisor-service.ts

@@ -1,6 +1,7 @@
 export * as PluginSupervisor from "./supervisor-service.js"
 
 import { Context, Effect } from "effect"
+import { Plugin } from "@opencode-ai/schema/plugin"
 
 /**
  * Dependency-only supervisor seam. Keep this module free of implementation
@@ -9,6 +10,15 @@ import { Context, Effect } from "effect"
 export interface Interface {
   /** Wait for the initial plugin generation and startup updates to settle. */
   readonly flush: Effect.Effect<void>
+  readonly check: () => Effect.Effect<Plugin.UpdateInfo[]>
+  readonly update: (name: string) => Effect.Effect<Plugin.UpdateResult>
+  readonly updateAll: () => Effect.Effect<Plugin.UpdateResult[]>
 }
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/PluginSupervisor") {}
+
+export const noUpdates = {
+  check: () => Effect.succeed([]),
+  update: () => Effect.die("Plugin updates unavailable"),
+  updateAll: () => Effect.succeed([]),
+} satisfies Omit<Interface, "flush">

packages/core/src/plugin/supervisor.ts

@@ -1,9 +1,9 @@
 export * as PluginSupervisor from "./supervisor.js"
-export { Service, type Interface } from "./supervisor-service.js"
+export { Service, type Interface, noUpdates } from "./supervisor-service.js"
 
 import type { Plugin as PluginDefinition } from "@opencode-ai/plugin/effect/plugin"
 import { Event } from "@opencode-ai/schema/config"
-import { Cause, Effect, Latch, Layer, Schema, Stream } from "effect"
+import { Cause, Effect, Latch, Layer, Schema, Semaphore, Stream } from "effect"
 import path from "path"
 import { pathToFileURL } from "url"
 import { ConfigPluginSource } from "../config/plugin/source.js"
@@ -106,25 +106,30 @@ const load = Effect.fn("PluginSupervisor.load")(function* (
   operation: Extract<ConfigPluginSource.Operation, { type: "add" }>,
 ) {
   const npm = yield* Npm.Service
-  const entrypoint = path.isAbsolute(operation.target)
-    ? pathToFileURL(operation.target).href
-    : (yield* npm.add(operation.target, { subpaths: ["server", ""] })).entrypoint
+  const local = path.isAbsolute(operation.target)
+  const installed = local
+    ? { entrypoint: pathToFileURL(operation.target).href, revision: operation.mtime?.toString() }
+    : yield* npm.add(operation.target, { subpaths: ["server", ""] })
+  const entrypoint = installed.entrypoint
   if (!entrypoint) return yield* Effect.fail(new Error(`Plugin entrypoint not found: ${operation.target}`))
   // Bun currently ignores query parameters when caching file:// imports.
-  const source =
-    operation.mtime === undefined
+  const source = local
+    ? operation.mtime === undefined
       ? entrypoint
       : typeof Bun !== "undefined"
         ? `${operation.target.replaceAll("\\", "/")}?mtime=${operation.mtime}`
         : `${entrypoint}?mtime=${operation.mtime}`
-  yield* Effect.log({ msg: "loading plugin", id: operation.target, entrypoint: source })
+    : installed.revision
+      ? `${entrypoint}?revision=${encodeURIComponent(installed.revision)}`
+      : entrypoint
+  yield* Effect.log({ msg: "loading plugin", local })
   const mod = yield* Effect.promise(() => importModule(source))
   const value = (yield* Schema.decodeUnknownEffect(PluginModule)(mod)).default
   const plugin = "effect" in value ? value : PluginPromise.fromPromise(value)
   return {
     id: plugin.id,
     tui: plugin.tui,
-    version: JSON.stringify(operation),
+    version: `${JSON.stringify(operation)}:${installed.revision ?? ""}`,
     source: pluginSource(operation.target),
     effect: (host) => plugin.effect({ ...host, options: operation.options }),
   } satisfies Plugin.Versioned
@@ -134,15 +139,16 @@ export const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
     const registry = yield* Plugin.Service
+    const npm = yield* Npm.Service
     const sdk = yield* SdkPlugins.Service
     const sources = yield* ConfigPluginSource.Service
     const bus = yield* Bus.Service
     const ready = yield* Latch.make()
+    const activationLock = Semaphore.makeUnsafe(1)
+    const internal = yield* PluginInternal.list()
     let observed = 0
 
     const activate = Effect.fn("PluginSupervisor.activate")(function* () {
-      // Resolve OpenCode's internal plugins with their privileged Location services.
-      const internal = yield* PluginInternal.list()
       // Combine internal plugins with host-contributed SDK plugins in boot order.
       const pre = [
         ...internal.pre.map((plugin) => ({ ...plugin, version: "internal", source: { type: "builtin" as const } })),
@@ -159,6 +165,73 @@ export const layer = Layer.effect(
       // Replace the active generation in one scoped, batched activation.
       yield* registry.activate(resolved.plugins, resolved.failures)
     })
+    const checkOne = Effect.fn("PluginSupervisor.checkOne")(function* (info: Plugin.Info) {
+      const name = pluginName(info)
+      if (info.source.type !== "package") {
+        return { name, source: info.source, status: "not-updateable" } satisfies Plugin.UpdateInfo
+      }
+      const source = info.source
+      return yield* npm.check(source.package).pipe(
+        Effect.map(
+          (update): Plugin.UpdateInfo => ({
+            name,
+            source: info.source,
+            status: update.pinned
+              ? "pinned"
+              : !update.updateable
+                ? "not-updateable"
+                : update.updateAvailable
+                  ? "available"
+                  : "up-to-date",
+            currentVersion: update.currentVersion,
+            latestVersion: update.latestVersion,
+          }),
+        ),
+        Effect.catchCause(() =>
+          Effect.succeed({
+            name,
+            source: info.source,
+            status: "failed",
+            error: "Failed to check plugin update",
+          } satisfies Plugin.UpdateInfo),
+        ),
+      )
+    })
+    const check = Effect.fn("PluginSupervisor.check")(function* () {
+      return yield* Effect.forEach(yield* registry.list(), checkOne, { concurrency: "unbounded" })
+    })
+    const updateOne = Effect.fn("PluginSupervisor.updateOne")(function* (info: Plugin.Info) {
+      const name = pluginName(info)
+      if (info.source.type !== "package") {
+        return { name, source: info.source, status: "not-updateable" } satisfies Plugin.UpdateResult
+      }
+      const source = info.source
+      return yield* npm.update(source.package).pipe(
+        Effect.map(
+          (update): Plugin.UpdateResult => ({
+            name,
+            source: info.source,
+            status: update.pinned
+              ? "pinned"
+              : !update.updateable
+                ? "not-updateable"
+                : update.updated
+                  ? "updated"
+                  : "up-to-date",
+            previousVersion: update.previousVersion,
+            version: update.latestVersion ?? update.currentVersion,
+          }),
+        ),
+        Effect.catchCause(() =>
+          Effect.succeed({
+            name,
+            source: info.source,
+            status: "failed",
+            error: "Failed to update plugin",
+          } satisfies Plugin.UpdateResult),
+        ),
+      )
+    })
     const updates = Stream.merge(sources.changes(), bus.subscribe([Event.Updated, SdkPlugins.Updated])).pipe(
       // Make accepted work visible to flush before coalescing the burst.
       Stream.mapEffect(() =>
@@ -169,19 +242,73 @@ export const layer = Layer.effect(
         }),
       ),
     )
+    const reload = (packages: readonly string[]) =>
+      activationLock.withPermit(
+        Effect.gen(function* () {
+          yield* activate().pipe(Effect.scoped, Effect.provideService(Npm.Service, npm))
+          const failed = (yield* registry.list()).flatMap((info) =>
+            info.status === "failed" && info.source.type === "package" && packages.includes(info.source.package)
+              ? [info.source.package]
+              : [],
+          )
+          if (failed.length === 0) return failed
+          yield* Effect.forEach(failed, (pkg) =>
+            npm
+              .rollback(pkg)
+              .pipe(
+                Effect.catchCause((cause) => Effect.logError("failed to restore plugin package revision", { cause })),
+              ),
+          )
+          yield* activate().pipe(Effect.scoped, Effect.provideService(Npm.Service, npm))
+          return failed
+        }),
+      )
     yield* Stream.concat(Stream.succeed(0), updates).pipe(
       // Keep observing updates while activation runs, retaining only the latest generation request.
       Stream.buffer({ capacity: 1, strategy: "sliding" }),
       Stream.debounce("100 millis"),
       Stream.runForEach((target) =>
         Effect.gen(function* () {
-          yield* activate()
+          yield* activationLock.withPermit(activate())
           if (observed === target) yield* ready.open
         }).pipe(Effect.catchCause((cause) => Effect.logError("failed to reload plugins", { cause }))),
       ),
       Effect.forkScoped({ startImmediately: true }),
     )
-    return Service.of({ flush: ready.await })
+    return Service.of({
+      flush: ready.await,
+      check,
+      update: Effect.fn("PluginSupervisor.update")(function* (name) {
+        const info = (yield* registry.list()).find((info) => pluginName(info) === name || info.id === name)
+        if (!info) {
+          return {
+            name,
+            source: { type: "package", package: name },
+            status: "failed",
+            error: "Plugin not found",
+          }
+        }
+        const result = yield* updateOne(info)
+        if (result.status === "updated" && result.source.type === "package") {
+          const failed = yield* reload([result.source.package])
+          if (failed.length > 0)
+            return { ...result, status: "failed" as const, error: "Updated plugin failed to activate" }
+        }
+        return result
+      }),
+      updateAll: Effect.fn("PluginSupervisor.updateAll")(function* () {
+        const results = yield* Effect.forEach(yield* registry.list(), updateOne)
+        const packages = results.flatMap((result) =>
+          result.status === "updated" && result.source.type === "package" ? [result.source.package] : [],
+        )
+        if (packages.length === 0) return results
+        const failed = yield* reload(packages)
+        return results.map((result) => {
+          if (result.source.type !== "package" || !failed.includes(result.source.package)) return result
+          return { ...result, status: "failed" as const, error: "Updated plugin failed to activate" }
+        })
+      }),
+    })
   }),
 )
 
@@ -199,4 +326,10 @@ function pluginSource(target: string): Plugin.Source {
   return { type: "package", package: target }
 }
 
+function pluginName(info: Plugin.Info) {
+  if (info.source.type === "package") return info.source.package
+  if (info.source.type === "local") return info.source.path
+  return info.id ?? info.source.type
+}
+
 export const node = makeLocationNode({ service: Service, layer, deps: nodeDeps })

packages/core/test/config/plugin.test.ts

@@ -37,6 +37,30 @@ const staticIt = testEffect(
 )
 
 describe("PluginSupervisor config", () => {
+  it.live("reports local and builtin plugins as not updateable", () => {
+    const plugin = path.join(import.meta.dir, "../plugin/fixtures/config-promise-plugin.ts")
+    return withLocation(
+      { plugins: [plugin] },
+      Effect.gen(function* () {
+        yield* ready()
+        const supervisor = yield* PluginSupervisor.Service
+        const updates = yield* supervisor.check()
+
+        expect(updates.find((update) => update.name === plugin)).toEqual({
+          name: plugin,
+          source: { type: "local", path: plugin },
+          status: "not-updateable",
+        })
+        expect(updates.find((update) => update.source.type === "builtin")?.status).toBe("not-updateable")
+        expect(yield* supervisor.update(plugin)).toEqual({
+          name: plugin,
+          source: { type: "local", path: plugin },
+          status: "not-updateable",
+        })
+      }),
+    )
+  })
+
   it.live("applies selectors in order", () =>
     withLocation(
       { plugins: ["-opencode.provider.*", "opencode.provider.openai"] },

packages/core/test/filesystem/watcher.test.ts

@@ -25,13 +25,18 @@ import { host } from "../plugin/host"
 
 type WatcherEvent = { file: string; event: "add" | "change" | "unlink" }
 const describeNative = process.env.CI ? describe.skip : describe
+const pluginUpdates = {
+  check: () => Effect.succeed([]),
+  update: () => Effect.die("unused"),
+  updateAll: () => Effect.succeed([]),
+}
 
 const it = testEffect(AppNodeBuilder.build(LayerNode.group([FSUtil.node, Bus.node])))
 
 const configLayer = Config.testLayer()
 const pluginNode = makeLocationNode({
   service: PluginSupervisor.Service,
-  layer: Layer.succeed(PluginSupervisor.Service, PluginSupervisor.Service.of({ flush: Effect.void })),
+  layer: Layer.succeed(PluginSupervisor.Service, PluginSupervisor.Service.of({ ...pluginUpdates, flush: Effect.void })),
   deps: [],
 })
 
@@ -314,7 +319,7 @@ describe("LocationWatcher subscriptions", () => {
         Effect.gen(function* () {
           const policy = yield* LocationWatcherPolicy.Service
           yield* policy.transform((draft) => draft.add([".git"]))
-          return PluginSupervisor.Service.of({ flush: Effect.void })
+          return PluginSupervisor.Service.of({ ...pluginUpdates, flush: Effect.void })
         }),
       ),
       deps: [LocationWatcherPolicy.node],

packages/core/test/npm-update.test.ts

@@ -0,0 +1,178 @@
+import fs from "fs/promises"
+import path from "path"
+import { fileURLToPath, pathToFileURL } from "url"
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Global } from "@opencode-ai/util/global"
+import { Npm } from "@opencode-ai/util/npm"
+import { tmpdir } from "./fixture/tmpdir"
+
+const npmLayer = (cache: string) =>
+  AppNodeBuilder.build(Npm.node, [[Global.node, Global.layerWith({ cache, state: path.join(cache, "state") })]])
+
+describe("Npm plugin updates", () => {
+  test("checks a moving Git ref without installing and explicitly updates its cached revision", async () => {
+    await using tmp = await tmpdir()
+    const repository = path.join(tmp.path, "plugin")
+    const cache = path.join(tmp.path, "cache")
+    await fs.mkdir(repository)
+    await Bun.write(
+      path.join(repository, "package.json"),
+      JSON.stringify({ name: "fixture-plugin", version: "1.0.0", exports: "./index.js" }),
+    )
+    await Bun.write(path.join(repository, "index.js"), "export default 'first'\n")
+    await Bun.$`git init -q -b main ${repository}`
+    await commit(repository, "first")
+    const first = await revision(repository)
+    const spec = `git+${pathToFileURL(repository).href}#main`
+    const layer = npmLayer(cache)
+
+    const installed = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.add(spec)
+    }).pipe(Effect.scoped, Effect.provide(layer), Effect.runPromise)
+    expect(installed.revision).toBe(first)
+
+    await Bun.write(path.join(repository, "index.js"), "export default 'second'\n")
+    await commit(repository, "second")
+    const second = await revision(repository)
+
+    const checked = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.check(spec)
+    }).pipe(Effect.provide(layer), Effect.runPromise)
+    expect(checked).toMatchObject({
+      currentVersion: first,
+      latestVersion: second,
+      updateAvailable: true,
+    })
+
+    const updated = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.update(spec)
+    }).pipe(Effect.scoped, Effect.provide(layer), Effect.runPromise)
+    expect(updated).toMatchObject({
+      previousVersion: first,
+      currentVersion: second,
+      updated: true,
+    })
+
+    const current = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.add(spec)
+    }).pipe(Effect.scoped, Effect.provide(layer), Effect.runPromise)
+    expect(current.directory).not.toBe(installed.directory)
+    expect(current.revision).toBe(second)
+    if (!current.entrypoint) throw new Error("Updated plugin entrypoint missing")
+    expect(
+      await Bun.file(
+        current.entrypoint.startsWith("file:") ? fileURLToPath(current.entrypoint) : current.entrypoint,
+      ).text(),
+    ).toContain("second")
+
+    const unchanged = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.update(spec)
+    }).pipe(Effect.scoped, Effect.provide(layer), Effect.runPromise)
+    expect(unchanged).toMatchObject({
+      previousVersion: second,
+      currentVersion: second,
+      latestVersion: second,
+      updateAvailable: false,
+      updated: false,
+    })
+    expect(
+      await Effect.gen(function* () {
+        const npm = yield* Npm.Service
+        return yield* npm.resolve(spec)
+      }).pipe(Effect.provide(layer), Effect.runPromise),
+    ).toMatchObject({ directory: current.directory, revision: second })
+
+    await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      yield* npm.rollback(spec)
+    }).pipe(Effect.provide(layer), Effect.runPromise)
+    expect(
+      await Effect.gen(function* () {
+        const npm = yield* Npm.Service
+        return yield* npm.resolve(spec)
+      }).pipe(Effect.provide(layer), Effect.runPromise),
+    ).toMatchObject({ directory: installed.directory, revision: first })
+  })
+
+  test("resolves a Git semver selector without installing HEAD outside the configured range", async () => {
+    await using tmp = await tmpdir()
+    const repository = path.join(tmp.path, "plugin")
+    const cache = path.join(tmp.path, "cache")
+    await fs.mkdir(repository)
+    await writePlugin(repository, "1.0.0", "one")
+    await Bun.$`git init -q -b main ${repository}`
+    await commit(repository, "one")
+    await Bun.$`git -C ${repository} tag v1.0.0`
+    const first = await revision(repository)
+    const spec = `git+${pathToFileURL(repository).href}#semver:^1`
+    const layer = npmLayer(cache)
+
+    const installed = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.add(spec)
+    }).pipe(Effect.scoped, Effect.provide(layer), Effect.runPromise)
+    expect(installed.revision).toBe(first)
+
+    await writePlugin(repository, "1.1.0", "one-one")
+    await commit(repository, "one-one")
+    await Bun.$`git -C ${repository} tag v1.1.0`
+    const latest = await revision(repository)
+    await writePlugin(repository, "2.0.0", "two")
+    await commit(repository, "two")
+    await Bun.$`git -C ${repository} tag v2.0.0`
+    expect(await revision(repository)).not.toBe(latest)
+
+    const checked = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.check(spec)
+    }).pipe(Effect.provide(layer), Effect.runPromise)
+    expect(checked).toMatchObject({ currentVersion: first, latestVersion: latest, updateAvailable: true })
+
+    const updated = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      return yield* npm.update(spec)
+    }).pipe(Effect.scoped, Effect.provide(layer), Effect.runPromise)
+    expect(updated).toMatchObject({ currentVersion: latest, latestVersion: latest, updated: true })
+  })
+
+  test("fails checks for missing Git refs", async () => {
+    await using tmp = await tmpdir()
+    const repository = path.join(tmp.path, "plugin")
+    await fs.mkdir(repository)
+    await writePlugin(repository, "1.0.0", "one")
+    await Bun.$`git init -q -b main ${repository}`
+    await commit(repository, "one")
+    const layer = npmLayer(path.join(tmp.path, "cache"))
+
+    await expect(
+      Effect.gen(function* () {
+        const npm = yield* Npm.Service
+        return yield* npm.check(`git+${pathToFileURL(repository).href}#missing`)
+      }).pipe(Effect.provide(layer), Effect.runPromise),
+    ).rejects.toMatchObject({ _tag: "NpmInstallFailedError" })
+  })
+})
+
+async function writePlugin(repository: string, version: string, value: string) {
+  await Bun.write(
+    path.join(repository, "package.json"),
+    JSON.stringify({ name: "fixture-plugin", version, exports: "./index.js" }),
+  )
+  await Bun.write(path.join(repository, "index.js"), `export default '${value}'\n`)
+}
+
+async function commit(repository: string, message: string) {
+  await Bun.$`git -C ${repository} add .`
+  await Bun.$`git -C ${repository} -c user.name=fixture -c user.email=fixture@example.com commit -qm ${message}`
+}
+
+async function revision(repository: string) {
+  return Bun.$`git -C ${repository} rev-parse HEAD`.text().then((value) => value.trim())
+}

packages/core/test/plugin/fixture.ts

@@ -35,7 +35,10 @@ const npmLayer = Layer.succeed(
   Npm.Service,
   Npm.Service.of({
     add: () => Effect.succeed({ directory: "", entrypoint: undefined }),
+    check: () => Effect.succeed({ updateable: false, pinned: false, updateAvailable: false }),
     resolve: () => Effect.succeed({ directory: "", entrypoint: undefined }),
+    update: () => Effect.succeed({ updateable: false, pinned: false, updateAvailable: false, updated: false }),
+    rollback: () => Effect.void,
     which: () => Effect.undefined,
   }),
 )

packages/core/test/plugin/provider-dynamic.test.ts

@@ -23,7 +23,10 @@ const itWithAISDK = testEffect(Layer.mergeAll(PluginTestLayer, AppNodeBuilder.bu
 function npmEntrypoint(entrypoint?: string) {
   return Npm.Service.of({
     add: () => Effect.succeed({ directory: "", entrypoint }),
+    check: () => Effect.succeed({ updateable: false, pinned: false, updateAvailable: false }),
     resolve: () => Effect.succeed({ directory: "", entrypoint }),
+    update: () => Effect.succeed({ updateable: false, pinned: false, updateAvailable: false, updated: false }),
+    rollback: () => Effect.void,
     which: () => Effect.undefined,
   })
 }

packages/core/test/plugin/provider-sap-ai-core.test.ts

@@ -14,7 +14,10 @@ const fixtureProvider = new URL("./fixtures/provider-factory.ts", import.meta.ur
 const it = testEffect(PluginTestLayer)
 const npm = Npm.Service.of({
   add: () => Effect.succeed({ directory: "", entrypoint: undefined }),
+  check: () => Effect.succeed({ updateable: false, pinned: false, updateAvailable: false }),
   resolve: () => Effect.succeed({ directory: "", entrypoint: undefined }),
+  update: () => Effect.succeed({ updateable: false, pinned: false, updateAvailable: false, updated: false }),
+  rollback: () => Effect.void,
   which: () => Effect.undefined,
 })
 

packages/core/test/session-generate.test.ts

@@ -110,7 +110,7 @@ const discovery = Layer.mock(InstructionDiscovery.Service, {
 const skills = Layer.mock(SkillInstructions.Service, { load: () => Effect.succeed(Instructions.empty) })
 const references = Layer.mock(ReferenceInstructions.Service, { load: () => Effect.succeed(Instructions.empty) })
 const mcp = Layer.mock(McpInstructions.Service, { load: () => Effect.succeed(Instructions.empty) })
-const plugins = Layer.mock(PluginSupervisor.Service, { flush: Effect.void })
+const plugins = Layer.mock(PluginSupervisor.Service, { ...PluginSupervisor.noUpdates, flush: Effect.void })
 const tools = Layer.mock(Tool.Service, {
   snapshot: () =>
     Effect.succeed({

packages/core/test/session-prompt.test.ts

@@ -76,12 +76,14 @@ const locations = Layer.effect(
             Layer.mock(Snapshot.Service, {
               capture: () =>
                 ready ? Effect.undefined : Effect.die(new Error("Snapshot used before plugins were ready")),
-              restore: () =>
-                ready ? Effect.void : Effect.die(new Error("Snapshot used before plugins were ready")),
+              restore: () => (ready ? Effect.void : Effect.die(new Error("Snapshot used before plugins were ready"))),
             }),
             Layer.succeed(
               PluginSupervisor.Service,
-              PluginSupervisor.Service.of({ flush: Effect.sync(() => (ready = true)) }),
+              PluginSupervisor.Service.of({
+                ...PluginSupervisor.noUpdates,
+                flush: Effect.sync(() => (ready = true)),
+              }),
             ),
           )
         }),

packages/core/test/session-runner-recorded.test.ts

@@ -85,7 +85,10 @@ const referenceInstructions = Layer.mock(ReferenceInstructions.Service, {
 })
 const mcpInstructions = Layer.mock(McpInstructions.Service, { load: () => Effect.succeed(Instructions.empty) })
 const config = Config.testLayer()
-const pluginSupervisor = Layer.succeed(PluginSupervisor.Service, PluginSupervisor.Service.of({ flush: Effect.void }))
+const pluginSupervisor = Layer.succeed(
+  PluginSupervisor.Service,
+  PluginSupervisor.Service.of({ ...PluginSupervisor.noUpdates, flush: Effect.void }),
+)
 const promptCatalog = Layer.mock(Catalog.Service, {
   provider: {
     get: () => Effect.undefined,

packages/core/test/session-runner.test.ts

@@ -374,6 +374,7 @@ let pluginFlushHook = Effect.void
 const pluginSupervisor = Layer.succeed(
   PluginSupervisor.Service,
   PluginSupervisor.Service.of({
+    ...PluginSupervisor.noUpdates,
     flush: Effect.suspend(() => pluginFlushHook),
   }),
 )

packages/core/test/tool-shell.test.ts

@@ -125,7 +125,9 @@ const shellPluginSupervisor = makeLocationNode({
   service: PluginSupervisor.Service,
   layer: Layer.effect(
     PluginSupervisor.Service,
-    registerToolPlugin(ShellTool.Plugin).pipe(Effect.as(PluginSupervisor.Service.of({ flush: Effect.void }))),
+    registerToolPlugin(ShellTool.Plugin).pipe(
+      Effect.as(PluginSupervisor.Service.of({ ...PluginSupervisor.noUpdates, flush: Effect.void })),
+    ),
   ),
   deps: [
     Config.node,

packages/core/test/tool-subagent.test.ts

@@ -100,7 +100,9 @@ const subagentPluginSupervisor = makeLocationNode({
   service: PluginSupervisor.Service,
   layer: Layer.effect(
     PluginSupervisor.Service,
-    registerToolPlugin(SubagentTool.Plugin).pipe(Effect.as(PluginSupervisor.Service.of({ flush: Effect.void }))),
+    registerToolPlugin(SubagentTool.Plugin).pipe(
+      Effect.as(PluginSupervisor.Service.of({ ...PluginSupervisor.noUpdates, flush: Effect.void })),
+    ),
   ),
   deps: [Agent.node, Config.node, Permission.node, PluginRuntime.node, Tool.node],
 })

packages/plugin/src/effect/plugin.ts

@@ -31,7 +31,7 @@ export interface Context {
   readonly mcp: MCPDomain
   readonly generate: GenerateApi<unknown>
   readonly permission: PermissionDomain
-  readonly plugin: PluginApi<unknown>
+  readonly plugin: Pick<PluginApi<unknown>, "list">
   readonly reference: ReferenceDomain
   readonly session: SessionDomain
   readonly shell: ShellDomain

packages/plugin/src/promise/plugin.ts

@@ -30,7 +30,7 @@ export interface Context {
   readonly mcp: MCPDomain
   readonly generate: GenerateApi
   readonly permission: PermissionDomain
-  readonly plugin: PluginApi
+  readonly plugin: Pick<PluginApi, "list">
   readonly reference: ReferenceDomain
   readonly session: SessionDomain
   readonly shell: ShellDomain

packages/protocol/openapi.json

@@ -486,6 +486,306 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/update": {
+      "get": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.check",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Plugin.UpdateInfo"
+                      }
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Check configured plugins for explicitly available updates.",
+        "summary": "Check plugin updates"
+      },
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.update",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "$ref": "#/components/schemas/Plugin.UpdateResult"
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Explicitly update one configured plugin and reload plugins when it changes.",
+        "summary": "Update plugin",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "required": ["name"],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": true
+        }
+      }
+    },
+    "/api/plugin/update-all": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.updateAll",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Plugin.UpdateResult"
+                      }
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Explicitly update every updateable configured plugin and reload changed plugins.",
+        "summary": "Update plugins"
+      }
+    },
     "/api/session": {
       "get": {
         "tags": ["session"],
@@ -14846,6 +15146,9 @@
           "name": {
             "type": "string"
           },
+          "metadata": {
+            "type": "object"
+          },
           "methods": {
             "type": "array",
             "items": {
@@ -15356,6 +15659,9 @@
           "reasoningField": {
             "$ref": "#/components/schemas/Model.ReasoningField"
           },
+          "requireReasoning": {
+            "type": "boolean"
+          },
           "maxTokensField": {
             "$ref": "#/components/schemas/Model.MaxTokensField"
           },
@@ -15989,6 +16295,58 @@
           }
         ]
       },
+      "Plugin.UpdateInfo": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Plugin.Source"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["not-updateable", "pinned", "up-to-date", "available", "failed"]
+          },
+          "currentVersion": {
+            "type": "string"
+          },
+          "latestVersion": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": ["name", "source", "status"],
+        "additionalProperties": false
+      },
+      "Plugin.UpdateResult": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Plugin.Source"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["not-updateable", "pinned", "up-to-date", "updated", "failed"]
+          },
+          "previousVersion": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": ["name", "source", "status"],
+        "additionalProperties": false
+      },
       "Project": {
         "type": "object",
         "properties": {

packages/protocol/src/groups/plugin.ts

@@ -19,6 +19,49 @@ export const PluginGroup = HttpApiGroup.make("server.plugin")
         }),
       ),
   )
+  .add(
+    HttpApiEndpoint.get("plugin.check", "/api/plugin/update", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Plugin.UpdateInfo)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.plugin.check",
+          summary: "Check plugin updates",
+          description: "Check configured plugins for explicitly available updates.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("plugin.update", "/api/plugin/update", {
+      payload: Schema.Struct({ name: Schema.String }),
+      query: LocationQuery,
+      success: Location.response(Plugin.UpdateResult),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.plugin.update",
+          summary: "Update plugin",
+          description: "Explicitly update one configured plugin and reload plugins when it changes.",
+        }),
+      ),
+  )
+  .add(
+    HttpApiEndpoint.post("plugin.updateAll", "/api/plugin/update-all", {
+      query: LocationQuery,
+      success: Location.response(Schema.Array(Plugin.UpdateResult)),
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.plugin.updateAll",
+          summary: "Update plugins",
+          description: "Explicitly update every updateable configured plugin and reload changed plugins.",
+        }),
+      ),
+  )
   .annotateMerge(
     OpenApi.annotations({
       title: "plugin",

packages/schema/src/plugin.ts

@@ -32,6 +32,26 @@ export const Info = Schema.Union([
 ]).annotate({ identifier: "Plugin.Info" })
 export type Info = typeof Info.Type
 
+export interface UpdateInfo extends Schema.Schema.Type<typeof UpdateInfo> {}
+export const UpdateInfo = Schema.Struct({
+  name: Schema.String,
+  source: Source,
+  status: Schema.Literals(["not-updateable", "pinned", "up-to-date", "available", "failed"]),
+  currentVersion: Schema.String.pipe(optional),
+  latestVersion: Schema.String.pipe(optional),
+  error: Schema.String.pipe(optional),
+}).annotate({ identifier: "Plugin.UpdateInfo" })
+
+export interface UpdateResult extends Schema.Schema.Type<typeof UpdateResult> {}
+export const UpdateResult = Schema.Struct({
+  name: Schema.String,
+  source: Source,
+  status: Schema.Literals(["not-updateable", "pinned", "up-to-date", "updated", "failed"]),
+  previousVersion: Schema.String.pipe(optional),
+  version: Schema.String.pipe(optional),
+  error: Schema.String.pipe(optional),
+}).annotate({ identifier: "Plugin.UpdateResult" })
+
 const Added = ephemeral({
   type: "plugin.added",
   schema: { id: ID },

packages/server/src/handlers/plugin.ts

@@ -1,13 +1,15 @@
 import { Plugin } from "@opencode-ai/core/plugin"
-import { Effect } from "effect"
+import { PluginSupervisor } from "@opencode-ai/core/plugin/supervisor"
 import { HttpApiBuilder } from "effect/unstable/httpapi"
 import { Api } from "../api"
 import { response } from "../location"
 
 export const PluginHandler = HttpApiBuilder.group(Api, "server.plugin", (handlers) =>
-  handlers.handle("plugin.list", () =>
-    Effect.gen(function* () {
-      return yield* response(Plugin.Service.use((plugin) => plugin.list()))
-    }),
-  ),
+  handlers
+    .handle("plugin.list", () => response(Plugin.Service.use((plugin) => plugin.list())))
+    .handle("plugin.check", () => response(PluginSupervisor.Service.use((plugins) => plugins.check())))
+    .handle("plugin.update", (ctx) =>
+      response(PluginSupervisor.Service.use((plugins) => plugins.update(ctx.payload.name))),
+    )
+    .handle("plugin.updateAll", () => response(PluginSupervisor.Service.use((plugins) => plugins.updateAll()))),
 )

packages/server/test/fetch.test.ts

@@ -96,6 +96,35 @@ it.live("serves unauthenticated and answers CORS preflight when no password is c
   }).pipe(Effect.scoped),
 )
 
+it.live("serves plugin update operations through the HttpApi", () =>
+  Effect.gen(function* () {
+    const handler = yield* ServerFetch.make(options)
+    const check = yield* Effect.promise(() => handler(new Request("http://opencode.local/api/plugin/update")))
+    expect(check.status).toBe(200)
+    expect(yield* Effect.promise(() => check.json())).toMatchObject({ data: expect.any(Array) })
+
+    const update = yield* Effect.promise(() =>
+      handler(
+        new Request("http://opencode.local/api/plugin/update", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ name: "missing-plugin" }),
+        }),
+      ),
+    )
+    expect(update.status).toBe(200)
+    expect(yield* Effect.promise(() => update.json())).toMatchObject({
+      data: { name: "missing-plugin", status: "failed", error: "Plugin not found" },
+    })
+
+    const updateAll = yield* Effect.promise(() =>
+      handler(new Request("http://opencode.local/api/plugin/update-all", { method: "POST" })),
+    )
+    expect(updateAll.status).toBe(200)
+    expect(yield* Effect.promise(() => updateAll.json())).toMatchObject({ data: expect.any(Array) })
+  }).pipe(Effect.scoped),
+)
+
 it.live("cancels a stale OpenAI OAuth callback server before falling back", () =>
   Effect.gen(function* () {
     const requests: string[] = []

packages/server/test/handler-policy.test.ts

@@ -50,9 +50,12 @@ test("plugin readiness stays lazy and resolves the supervisor for every executio
     () => new ServiceUnavailableError({ message: "initialization timed out", service: "test" }),
   )
   const layer = Layer.succeed(PluginSupervisor.Service, {
+    check: () => Effect.succeed([]),
     flush: Effect.sync(() => {
       flushes++
     }),
+    update: () => Effect.die("unused"),
+    updateAll: () => Effect.succeed([]),
   })
 
   expect(flushes).toBe(0)

packages/tui/src/config/keybind.ts

@@ -258,6 +258,8 @@ export const Definitions = {
   "plugins.toggle": keybind("space", "Toggle plugin"),
   "dialog.mcp.toggle": keybind("space", "Toggle MCP server"),
   "dialog.plugins.install": keybind("shift+i", "Install plugin from plugin dialog"),
+  "dialog.plugins.update": keybind("ctrl+r", "Update selected plugin"),
+  "dialog.plugins.update_all": keybind("ctrl+shift+r", "Update all plugins"),
 
   "terminal.suspend": keybind("ctrl+z", "Suspend terminal"),
   "terminal.title.toggle": keybind("none", "Toggle terminal title"),

packages/tui/src/feature-plugins/system/plugins-model.ts

@@ -0,0 +1,19 @@
+import type { PluginInfo, PluginUpdateInfo, PluginUpdateResult } from "@opencode-ai/client"
+
+export type UpdateEntry = PluginUpdateInfo | PluginUpdateResult
+
+export function matchesPluginUpdate(plugin: PluginInfo, update: UpdateEntry) {
+  if (plugin.source.type !== update.source.type) return false
+  if (plugin.source.type === "package" && update.source.type === "package") {
+    return plugin.source.package === update.source.package
+  }
+  if (plugin.source.type === "local" && update.source.type === "local") return plugin.source.path === update.source.path
+  return plugin.id === update.name
+}
+
+export function pluginServerKey(plugin: PluginInfo) {
+  if (plugin.id) return `server:${plugin.id}`
+  if (plugin.source.type === "package") return `server:package:${plugin.source.package}`
+  if (plugin.source.type === "local") return `server:local:${plugin.source.path}`
+  return `server:${plugin.source.type}`
+}

packages/tui/src/feature-plugins/system/plugins.tsx

@@ -1,15 +1,17 @@
-import type { PluginInfo } from "@opencode-ai/client"
+import type { PluginInfo, PluginUpdateInfo, PluginUpdateResult } from "@opencode-ai/client"
 import { Plugin } from "@opencode-ai/plugin/tui"
 import { createEffect, createMemo, createResource, createSignal, onMount, Show } from "solid-js"
 import { DialogErrorDetails } from "../../component/dialog-error-details"
 import { usePlugin } from "../../plugin/context"
 import { DialogSelect, type DialogSelectOption } from "../../ui/dialog-select"
 import { useDialog } from "../../ui/dialog"
+import { errorMessage } from "../../util/error"
+import { matchesPluginUpdate, pluginServerKey, type UpdateEntry } from "./plugins-model"
 
 const id = "opencode.plugins"
 
 type Entry =
-  | { readonly key: string; readonly runtime: "server"; readonly plugin: PluginInfo }
+  | { readonly key: string; readonly runtime: "server"; readonly plugin: PluginInfo; readonly update?: UpdateEntry }
   | {
       readonly key: string
       readonly runtime: "tui"
@@ -19,21 +21,47 @@ type Entry =
       readonly error?: string
     }
 
+type PluginUpdateOperations = {
+  check(): Promise<readonly PluginUpdateInfo[]>
+  update(name: string): Promise<PluginUpdateResult>
+  updateAll(): Promise<readonly PluginUpdateResult[]>
+}
+
+export type PluginRegistry = Pick<ReturnType<typeof usePlugin>, "registered" | "list" | "activate" | "deactivate">
+
 export function PluginsDialog(props: {
   context: Plugin.Context
-  plugins: ReturnType<typeof usePlugin>
+  plugins: PluginRegistry
   server?: () => readonly PluginInfo[]
+  updates?: PluginUpdateOperations
 }) {
   const dialog = useDialog()
   const [locked, setLocked] = createSignal(false)
   const [focused, setFocused] = createSignal<string>()
   const [detail, setDetail] = createSignal<Entry>()
   const [initial, setInitial] = createSignal<string>()
-  const [server] = createResource(
-    () => (props.server ? undefined : (props.context.location ?? props.context.data.location.default())),
+  const [checking, setChecking] = createSignal(true)
+  const [operationError, setOperationError] = createSignal(false)
+  const [updateEntries, setUpdateEntries] = createSignal<readonly UpdateEntry[]>([])
+  const [updating, setUpdating] = createSignal<string>()
+  const location = () => props.context.location ?? props.context.data.location.default()
+  const operations: PluginUpdateOperations = props.updates ?? {
+    check: () => props.context.client.plugin.check({ location: location() }).then((result) => result.data),
+    update: (name) => props.context.client.plugin.update({ name, location: location() }).then((result) => result.data),
+    updateAll: () => props.context.client.plugin.updateAll({ location: location() }).then((result) => result.data),
+  }
+  const [server, { refetch: refetchServer }] = createResource(
+    () => (props.server ? undefined : location()),
     (location) => props.context.client.plugin.list({ location }).then((result) => result.data),
   )
-  onMount(() => dialog.setSize("medium"))
+  onMount(() => {
+    dialog.setSize("medium")
+    void operations
+      .check()
+      .then(setUpdateEntries)
+      .catch(() => setOperationError(true))
+      .finally(() => setChecking(false))
+  })
   const entries = createMemo<Entry[]>(() => {
     const builtins: Entry[] = props.plugins
       .registered()
@@ -56,10 +84,12 @@ export function PluginsDialog(props: {
         status: plugin.status,
         error: plugin.status === "failed" ? plugin.error : undefined,
       }))
-    const serverEntries: Entry[] = (props.server?.() ?? server() ?? []).map((plugin) => ({
-      key: `server:${plugin.id ?? source(plugin, props.context)}`,
-      runtime: "server" as const,
+    const runtime = props.server?.() ?? server() ?? []
+    const serverEntries: Entry[] = runtime.map((plugin) => ({
+      key: pluginServerKey(plugin),
+      runtime: "server",
       plugin,
+      update: updateEntries().find((update) => matchesPluginUpdate(plugin, update)),
     }))
     return [
       ...[...builtins, ...external].sort((a, b) => label(a, props.context).localeCompare(label(b, props.context))),
@@ -81,11 +111,15 @@ export function PluginsDialog(props: {
         value: entry.key,
         category: entry.runtime === "tui" ? "TUI" : "Server",
         searchText: entry.runtime === "tui" ? entry.target : source(entry.plugin, props.context),
-        footer: status(entry) === "active" ? undefined : status(entry),
+        footer: statusLabel(entry, checking(), updating()),
         footerColor:
-          status(entry) === "failed"
+          status(entry) === "failed" || updateStatus(entry) === "failed"
             ? props.context.theme.text.feedback.error.default
-            : props.context.theme.text.subdued,
+            : updateStatus(entry) === "updated" || updateStatus(entry) === "up-to-date"
+              ? props.context.theme.text.feedback.success.default
+              : updateStatus(entry) === "available"
+                ? props.context.theme.text.feedback.info.default
+                : props.context.theme.text.subdued,
         gutter:
           status(entry) === "active"
             ? () => <text fg={props.context.theme.text.feedback.success.default}>✓</text>
@@ -96,6 +130,11 @@ export function PluginsDialog(props: {
     ),
   )
   const focusedEntry = createMemo(() => entries().find((entry) => entry.key === focused()))
+  const focusedUpdate = createMemo(() => {
+    const entry = focusedEntry()
+    if (entry?.runtime !== "server") return
+    return entry.update
+  })
   const focusedTui = createMemo(() => {
     const entry = focusedEntry()
     if (entry?.runtime !== "tui" || !entry.id) return
@@ -119,11 +158,38 @@ export function PluginsDialog(props: {
       .catch((cause) => {
         props.context.ui.toast.show({
           variant: "error",
-          message: cause instanceof Error ? cause.message : String(cause),
+          message: errorMessage(cause),
         })
       })
       .finally(() => setLocked(false))
   }
+  const runUpdate = (updating: string, operation: () => Promise<void>) => {
+    if (locked()) return
+    setLocked(true)
+    setUpdating(updating)
+    setOperationError(false)
+    void operation()
+      .catch((cause) => {
+        setOperationError(true)
+        props.context.ui.toast.show({ variant: "error", message: errorMessage(cause) })
+      })
+      .finally(() => {
+        setUpdating()
+        setLocked(false)
+      })
+  }
+  const update = (name: string) =>
+    runUpdate(name, async () => {
+      const result = await operations.update(name)
+      setUpdateEntries((current) => current.map((entry) => (entry.name === name ? result : entry)))
+      if (!props.server && result.status === "updated") await refetchServer()
+    })
+  const updateAll = () =>
+    runUpdate("*", async () => {
+      const results = await operations.updateAll()
+      setUpdateEntries(results)
+      if (!props.server && results.some((result) => result.status === "updated")) await refetchServer()
+    })
 
   return (
     <box>
@@ -141,19 +207,47 @@ export function PluginsDialog(props: {
               const entry = entries().find((entry) => entry.key === option.value)
               if (pluginError(entry)) setDetail(entry)
             }}
-            actions={
-              focusedTui()
+            actions={[
+              ...(focusedTui()
                 ? [
                     {
                       title: toggleTitle(),
                       command: "plugins.toggle",
-                      onTrigger: (option) => toggle(entries().find((entry) => entry.key === option.value)),
+                      onTrigger: (option: DialogSelectOption<string>) =>
+                        toggle(entries().find((entry) => entry.key === option.value)),
                     },
                   ]
-                : []
-            }
+                : []),
+              ...(focusedUpdate()?.status === "available"
+                ? [
+                    {
+                      title: "update",
+                      command: "dialog.plugins.update",
+                      onTrigger: (_option: DialogSelectOption<string>) => update(focusedUpdate()!.name),
+                    },
+                  ]
+                : []),
+              ...(updateEntries().some((entry) => entry.status === "available")
+                ? [
+                    {
+                      title: "update all",
+                      command: "dialog.plugins.update_all",
+                      selection: "none" as const,
+                      side: "right" as const,
+                      onTrigger: updateAll,
+                    },
+                  ]
+                : []),
+            ]}
             footer={
-              <Show when={pluginError(focusedEntry())}>
+              <Show
+                when={pluginError(focusedEntry())}
+                fallback={
+                  <Show when={operationError()}>
+                    <text fg={props.context.theme.text.feedback.error.default}>Plugin update failed</text>
+                  </Show>
+                }
+              >
                 <text>
                   <span style={{ fg: props.context.theme.text.default }}>
                     <b>enter</b>
@@ -196,8 +290,35 @@ function status(entry: Entry) {
   return entry.status
 }
 
+function updateStatus(entry: Entry) {
+  if (entry.runtime !== "server") return
+  return entry.update?.status
+}
+
+function statusLabel(entry: Entry, checking: boolean, updating: string | undefined) {
+  if (entry.runtime === "tui") return status(entry) === "active" ? undefined : status(entry)
+  const update = entry.update
+  if (updating === "*" || (update && updating === update.name)) return "updating …"
+  if (entry.plugin.status === "failed") return "failed"
+  if (!update) return checking ? "checking …" : undefined
+  if (update.status === "not-updateable") return update.source.type === "local" ? "local" : undefined
+  const currentVersion =
+    "currentVersion" in update ? update.currentVersion : "version" in update ? update.version : undefined
+  if (update.status === "pinned") return currentVersion ? `${currentVersion} pinned` : "pinned"
+  if (update.status === "up-to-date") return currentVersion ? `${currentVersion} up to date` : "up to date"
+  if (update.status === "available") {
+    return `${update.currentVersion ?? "installed"} → ${update.latestVersion ?? "update available"}`
+  }
+  if (update.status === "updated") return `${update.previousVersion ?? "installed"} → ${update.version ?? "updated"} ✓`
+  return "failed"
+}
+
 function pluginError(entry: Entry | undefined) {
-  if (entry?.runtime === "server") return entry.plugin.status === "failed" ? entry.plugin.error : undefined
+  if (entry?.runtime === "server") {
+    if (entry.plugin.status === "failed") return entry.plugin.error
+    if (entry.update?.status === "failed") return entry.update.error
+    return
+  }
   return entry?.error
 }
 

packages/tui/src/feature-plugins/system/storybook/index.tsx

@@ -3,6 +3,7 @@ import { useTerminalDimensions } from "@opentui/solid"
 import { createSignal, For, type JSX } from "solid-js"
 import { StoryFooter } from "./footer"
 import { mermanLayoutsStory } from "./merman-layouts"
+import { pluginUpdatesStory } from "./plugin-updates"
 import { sessionTabsStory } from "./session-tabs"
 import { sessionLocationMissingStory } from "./session-location-missing"
 
@@ -16,7 +17,7 @@ export type Story = {
   render: (context: Plugin.Context) => JSX.Element
 }
 
-const stories: Story[] = [mermanLayoutsStory, sessionTabsStory, sessionLocationMissingStory]
+const stories: Story[] = [mermanLayoutsStory, sessionTabsStory, sessionLocationMissingStory, pluginUpdatesStory]
 
 function Commands(props: { context: Plugin.Context }) {
   props.context.keymap.layer(() => ({

packages/tui/src/feature-plugins/system/storybook/plugin-updates.tsx

@@ -0,0 +1,184 @@
+import type { PluginInfo, PluginUpdateInfo, PluginUpdateResult } from "@opencode-ai/client"
+import type { Plugin } from "@opencode-ai/plugin/tui"
+import { useTerminalDimensions } from "@opentui/solid"
+import { onMount } from "solid-js"
+import { PluginsDialog, type PluginRegistry } from "../plugins"
+import type { Story } from "./index"
+import { StoryFooter } from "./footer"
+
+const server: PluginInfo[] = [
+  {
+    id: "fixture.analytics",
+    source: { type: "package", package: "@fixture/analytics@latest" },
+    status: "active",
+    tui: false,
+  },
+  {
+    id: "fixture.theme",
+    source: { type: "package", package: "@fixture/theme@2.4.0" },
+    status: "active",
+    tui: false,
+  },
+  {
+    id: "fixture.local",
+    source: { type: "local", path: "/fixture/plugins/local.ts" },
+    status: "active",
+    tui: false,
+  },
+  {
+    source: { type: "package", package: "@fixture/broken@latest" },
+    status: "failed",
+    error: "Plugin entrypoint could not be loaded",
+    tui: false,
+  },
+]
+
+const initial = (): PluginUpdateInfo[] => [
+  {
+    name: "@fixture/analytics@latest",
+    source: { type: "package", package: "@fixture/analytics@latest" },
+    status: "available",
+    currentVersion: "1.8.0",
+    latestVersion: "1.9.0",
+  },
+  {
+    name: "@fixture/theme@2.4.0",
+    source: { type: "package", package: "@fixture/theme@2.4.0" },
+    status: "pinned",
+    currentVersion: "2.4.0",
+  },
+  {
+    name: "/fixture/plugins/local.ts",
+    source: { type: "local", path: "/fixture/plugins/local.ts" },
+    status: "not-updateable",
+  },
+  {
+    name: "@fixture/broken@latest",
+    source: { type: "package", package: "@fixture/broken@latest" },
+    status: "failed",
+    error: "Registry request failed with status 503",
+  },
+]
+
+const plugins: PluginRegistry = {
+  registered: () => [{ id: "fixture.ui", source: "builtin", active: true }],
+  list: () => [],
+  activate: async () => true,
+  deactivate: async () => true,
+}
+
+function PluginUpdatesStory(props: { context: Plugin.Context }) {
+  const dimensions = useTerminalDimensions()
+  const theme = props.context.theme.contextual.elevated
+  let fixture = initial()
+
+  const wait = () => new Promise<void>((resolve) => setTimeout(resolve, 500))
+  const open = () =>
+    props.context.ui.dialog.show(() => (
+      <PluginsDialog
+        context={props.context}
+        plugins={plugins}
+        server={() => server}
+        updates={{
+          async check() {
+            await wait()
+            return fixture
+          },
+          async update(name) {
+            await wait()
+            const current = fixture.find((entry) => entry.name === name)
+            const result: PluginUpdateResult = {
+              name,
+              source: current?.source ?? { type: "package", package: name },
+              status: "updated",
+              previousVersion: current?.currentVersion,
+              version: current?.latestVersion,
+            }
+            fixture = fixture.map((entry) =>
+              entry.name === name ? { ...entry, status: "up-to-date", currentVersion: entry.latestVersion } : entry,
+            )
+            return result
+          },
+          async updateAll() {
+            await wait()
+            const results: PluginUpdateResult[] = fixture.map((entry) =>
+              entry.status === "available"
+                ? {
+                    name: entry.name,
+                    source: entry.source,
+                    status: "updated",
+                    previousVersion: entry.currentVersion,
+                    version: entry.latestVersion,
+                  }
+                : {
+                    name: entry.name,
+                    source: entry.source,
+                    status: entry.status,
+                    version: entry.currentVersion,
+                    error: entry.error,
+                  },
+            )
+            fixture = initial().map((entry) =>
+              entry.status === "available"
+                ? { ...entry, status: "up-to-date", currentVersion: entry.latestVersion }
+                : entry,
+            )
+            return results
+          },
+        }}
+      />
+    ))
+
+  props.context.keymap.layer(() => ({
+    commands: [
+      {
+        bind: "escape",
+        title: "Back to storybook",
+        group: "Storybook",
+        run: () => props.context.ui.router.navigate({ type: "plugin", name: "storybook" }),
+      },
+      { bind: "return", title: "Open plugin controls", group: "Storybook", run: open },
+      {
+        bind: "r",
+        title: "Reset plugin controls",
+        group: "Storybook",
+        run() {
+          fixture = initial()
+          open()
+        },
+      },
+    ],
+  }))
+
+  onMount(open)
+
+  return (
+    <box
+      width={dimensions().width}
+      height={dimensions().height}
+      flexDirection="column"
+      backgroundColor={theme.background.default}
+    >
+      <box flexGrow={1} paddingLeft={2} paddingTop={1}>
+        <text fg={theme.text.default}>Plugin update controls fixture</text>
+        <text fg={theme.text.subdued}>The production Plugins dialog opens automatically.</text>
+      </box>
+      <StoryFooter
+        context={props.context}
+        title="storybook / plugin updates"
+        status="fixture API · 500ms operations"
+        controls={[
+          { shortcut: "enter", label: "open" },
+          { shortcut: "r", label: "reset" },
+          { shortcut: "esc", label: "back" },
+        ]}
+      />
+    </box>
+  )
+}
+
+export const pluginUpdatesStory: Story = {
+  id: "plugin-updates",
+  title: "Plugin update controls",
+  render: (context) => <PluginUpdatesStory context={context} />,
+}

packages/tui/test/feature-plugins/plugins.test.ts

@@ -0,0 +1,62 @@
+import type { PluginInfo, PluginUpdateInfo } from "@opencode-ai/client"
+import { describe, expect, test } from "bun:test"
+import { matchesPluginUpdate, pluginServerKey } from "../../src/feature-plugins/system/plugins-model"
+
+const builtin = (id: string): PluginInfo => ({ id, source: { type: "builtin" }, status: "active", tui: false })
+
+describe("plugin update row identity", () => {
+  test("does not join unrelated built-in plugins by source type", () => {
+    const update: PluginUpdateInfo = {
+      name: "fixture.second",
+      source: { type: "builtin" },
+      status: "not-updateable",
+    }
+
+    expect(matchesPluginUpdate(builtin("fixture.first"), update)).toBe(false)
+    expect(matchesPluginUpdate(builtin("fixture.second"), update)).toBe(true)
+  })
+
+  test("joins package and local plugins only by their exact source", () => {
+    const pkg = {
+      id: "fixture.package",
+      source: { type: "package", package: "@fixture/package@latest" },
+      status: "active",
+      tui: false,
+    } satisfies PluginInfo
+    const local = {
+      id: "fixture.local",
+      source: { type: "local", path: "/fixture/local.ts" },
+      status: "active",
+      tui: false,
+    } satisfies PluginInfo
+
+    expect(
+      matchesPluginUpdate(pkg, {
+        name: "@fixture/package@latest",
+        source: { type: "package", package: "@fixture/package@latest" },
+        status: "available",
+      }),
+    ).toBe(true)
+    expect(
+      matchesPluginUpdate(pkg, {
+        name: "fixture.package",
+        source: { type: "package", package: "@fixture/other@latest" },
+        status: "available",
+      }),
+    ).toBe(false)
+    expect(
+      matchesPluginUpdate(local, {
+        name: "/fixture/other.ts",
+        source: { type: "local", path: "/fixture/other.ts" },
+        status: "not-updateable",
+      }),
+    ).toBe(false)
+  })
+
+  test("derives stable keys only from runtime identity", () => {
+    const plugin = builtin("fixture.stable")
+
+    expect(pluginServerKey(plugin)).toBe("server:fixture.stable")
+    expect(pluginServerKey(plugin)).toBe(pluginServerKey({ ...plugin }))
+  })
+})

packages/util/package.json

@@ -53,6 +53,7 @@
     "mime-types": "3.0.2",
     "minimatch": "10.2.5",
     "npm-package-arg": "13.0.2",
+    "pacote": "21.5.1",
     "resolve.exports": "catalog:"
   },
   "devDependencies": {
@@ -62,6 +63,7 @@
     "@types/node": "catalog:",
     "@types/npm-package-arg": "6.1.4",
     "@types/npmcli__arborist": "6.3.3",
+    "@types/pacote": "11.1.8",
     "@typescript/native-preview": "catalog:"
   }
 }

packages/util/src/npm.ts

@@ -1,7 +1,7 @@
 export * as Npm from "./npm.js"
 
 import path from "path"
-import { createHash } from "node:crypto"
+import { createHash, randomUUID } from "node:crypto"
 import { Effect, Schema, Context, Layer, Option, FileSystem } from "effect"
 import { FSUtil } from "./fs-util.js"
 import { Global } from "./global.js"
@@ -22,6 +22,20 @@ export class InstallFailedError extends Schema.TaggedError<InstallFailedError>()
 export interface EntryPoint {
   readonly directory: string
   readonly entrypoint?: string
+  readonly revision?: string
+}
+
+export interface UpdateInfo {
+  readonly updateable: boolean
+  readonly pinned: boolean
+  readonly currentVersion?: string
+  readonly latestVersion?: string
+  readonly updateAvailable: boolean
+}
+
+export interface UpdateResult extends UpdateInfo {
+  readonly previousVersion?: string
+  readonly updated: boolean
 }
 
 export interface Interface {
@@ -30,6 +44,9 @@ export interface Interface {
     options?: { readonly subpaths?: readonly string[] },
   ) => Effect.Effect<EntryPoint, InstallFailedError | EffectFlock.LockError>
   readonly resolve: (pkg: string, options?: { readonly subpaths?: readonly string[] }) => Effect.Effect<EntryPoint>
+  readonly check: (pkg: string) => Effect.Effect<UpdateInfo, InstallFailedError | EffectFlock.LockError>
+  readonly update: (pkg: string) => Effect.Effect<UpdateResult, InstallFailedError | EffectFlock.LockError>
+  readonly rollback: (pkg: string) => Effect.Effect<void, InstallFailedError>
   readonly which: (pkg: string, bin?: string) => Effect.Effect<string | undefined>
 }
 
@@ -62,16 +79,33 @@ export async function isInstallablePackage(pkg: string) {
   }
 }
 
+export async function updatePolicy(pkg: string) {
+  const { default: npa } = await import("npm-package-arg")
+  try {
+    const parsed = npa(pkg)
+    const registry = ["version", "range", "tag"].includes(parsed.type)
+    const git = ["git", "hosted"].includes(parsed.type)
+    if (parsed.type === "version" || (git && /^[a-f0-9]{40,64}$/i.test(parsed.gitCommittish ?? ""))) {
+      return "pinned" as const
+    }
+    if (registry || git) return "mutable" as const
+    return "unsupported" as const
+  } catch {
+    return "unsupported" as const
+  }
+}
+
 export async function cacheKey(pkg: string) {
   const { default: npa } = await import("npm-package-arg")
   try {
-    if (npa(pkg).type === "git") return `git-${createHash("sha256").update(pkg).digest("hex")}`
+    if (npa(pkg).type === "git") {
+      return `git-${createHash("sha256").update(pkg).digest("hex")}`
+    }
   } catch {
     // Preserve the existing fallback for invalid and non-registry package strings.
   }
   return sanitize(pkg)
 }
-
 const resolveEntryPoint = (name: string, dir: string, subpaths: readonly string[] = [""]): EntryPoint => {
   const entrypoint = subpaths
     .map((subpath) => {
@@ -91,6 +125,8 @@ const resolveEntryPoint = (name: string, dir: string, subpaths: readonly string[
 interface ArboristNode {
   name: string
   path: string
+  version?: string
+  resolved?: string
 }
 
 interface ArboristTree {
@@ -98,9 +134,20 @@ interface ArboristTree {
 }
 
 const PackageJson = Schema.Struct({
+  version: Schema.optional(Schema.String),
   dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
 })
-
+const PackageLock = Schema.Struct({
+  packages: Schema.optional(
+    Schema.Record(
+      Schema.String,
+      Schema.Struct({
+        version: Schema.optional(Schema.String),
+        resolved: Schema.optional(Schema.String),
+      }),
+    ),
+  ),
+})
 const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
@@ -113,6 +160,15 @@ const layer = Layer.effect(
         Effect.promise(() => cacheKey(pkg)),
         (key) => path.join(global.cache, "packages", key),
       )
+    const activeDirectory = Effect.fnUntraced(function* (dir: string) {
+      const active = yield* afs
+        .readFileStringSafe(path.join(dir, ".opencode-active"))
+        .pipe(Effect.orElseSucceed(() => undefined))
+      if (!active) return dir
+      const resolved = path.resolve(active.trim())
+      if (!resolved.startsWith(`${dir}-revision-`)) return dir
+      return resolved
+    })
     const installedName = Effect.fnUntraced(function* (pkg: string, dir: string, parsedName?: string) {
       if (parsedName) return parsedName
       const manifest = yield* afs
@@ -124,14 +180,38 @@ const layer = Layer.effect(
       }
       return pkg
     })
-    const reify = (input: { dir: string; add?: string[] }) =>
+    const installed = Effect.fnUntraced(function* (pkg: string, dir: string, parsedName?: string, git = false) {
+      const name = yield* installedName(pkg, dir, parsedName)
+      const directory = path.join(dir, "node_modules", name)
+      const manifest = yield* afs
+        .readJson(path.join(directory, "package.json"))
+        .pipe(Effect.flatMap(Schema.decodeUnknownEffect(PackageJson)), Effect.option)
+      const version = Option.isSome(manifest) ? manifest.value.version : undefined
+      if (version && !git) return { name, directory, version }
+      const lock = yield* afs
+        .readJson(path.join(dir, "package-lock.json"))
+        .pipe(Effect.flatMap(Schema.decodeUnknownEffect(PackageLock)), Effect.option)
+      const entry = Option.isSome(lock) ? lock.value.packages?.[`node_modules/${name}`] : undefined
+      return {
+        name,
+        directory,
+        version: packageVersion({
+          name,
+          path: directory,
+          version: version ?? entry?.version,
+          resolved: entry?.resolved,
+        }),
+      }
+    })
+    const reify = (input: { dir: string; add?: string[]; update?: boolean }) =>
       Effect.gen(function* () {
         yield* flock.acquire(`npm-install:${input.dir}`)
         const { Arborist } = yield* Effect.promise(() => import("@npmcli/arborist"))
         const add = input.add ?? []
         const npmOptions = yield* NpmConfig.load(input.dir)
+        const options = input.update ? { ...npmOptions, preferOnline: true } : npmOptions
         const arborist = new Arborist({
-          ...npmOptions,
+          ...options,
           path: input.dir,
           binLinks: true,
           progress: false,
@@ -141,8 +221,9 @@ const layer = Layer.effect(
         return yield* Effect.tryPromise({
           try: () =>
             arborist.reify({
-              ...npmOptions,
+              ...options,
               add,
+              update: input.update,
               save: true,
               saveType: "prod",
             }),
@@ -159,20 +240,141 @@ const layer = Layer.effect(
         }),
       )
 
+    const parse = Effect.fnUntraced(function* (pkg: string) {
+      const { default: npa } = yield* Effect.promise(() => import("npm-package-arg"))
+      return yield* Effect.try({
+        try: () => npa(pkg),
+        catch: (cause) => new InstallFailedError({ cause, dir: path.join(global.cache, "packages") }),
+      })
+    })
+    const check = Effect.fn("Npm.check")(function* (pkg: string) {
+      const parsed = yield* parse(pkg)
+      const policy = yield* Effect.promise(() => updatePolicy(pkg))
+      if (policy !== "mutable") {
+        const version =
+          parsed.type === "version"
+            ? (parsed.fetchSpec ?? undefined)
+            : policy === "pinned"
+              ? (parsed.gitCommittish ?? undefined)
+              : undefined
+        return {
+          updateable: false,
+          pinned: policy === "pinned",
+          currentVersion: version,
+          latestVersion: version,
+          updateAvailable: false,
+        }
+      }
+
+      const root = yield* directory(pkg)
+      const dir = yield* activeDirectory(root)
+      const current = yield* installed(pkg, dir, parsed.name ?? undefined, ["git", "hosted"].includes(parsed.type))
+      const npmOptions = yield* NpmConfig.load(root)
+      const { default: pacote } = yield* Effect.promise(() => import("pacote"))
+      const latestVersion = yield* Effect.tryPromise({
+        try: async () => {
+          if (["git", "hosted"].includes(parsed.type)) {
+            const resolved = await pacote.resolve(pkg, {
+              ...npmOptions,
+              preferOnline: true,
+              noGitRevCache: true,
+            })
+            const revision = resolved.match(/#([a-f0-9]{40,64})$/i)?.[1]
+            if (!revision) throw new Error("Resolved Git package did not include a commit")
+            return revision
+          }
+          const manifest = await pacote.manifest(pkg, { ...npmOptions, preferOnline: true })
+          return manifest.version
+        },
+        catch: (cause) => new InstallFailedError({ cause, add: [pkg], dir }),
+      })
+      return {
+        updateable: true,
+        pinned: false,
+        currentVersion: current.version,
+        latestVersion,
+        updateAvailable: latestVersion !== undefined && current.version !== latestVersion,
+      }
+    })
+
+    const update = Effect.fn("Npm.update")(function* (pkg: string) {
+      const checked = yield* check(pkg)
+      if (!checked.updateAvailable) {
+        return { ...checked, previousVersion: checked.currentVersion, updated: false }
+      }
+      const parsed = yield* parse(pkg)
+      const root = yield* directory(pkg)
+      yield* flock.acquire(`npm-install:${root}`)
+      const dir = `${root}-revision-${randomUUID()}`
+      const target =
+        ["git", "hosted"].includes(parsed.type) && checked.latestVersion ? pinGitSpec(pkg, checked.latestVersion) : pkg
+      const tree = yield* reify({ dir, add: [target], update: true })
+      const node = parsed.name ? tree.edgesOut.get(parsed.name)?.to : tree.edgesOut.values().next().value?.to
+      const version = packageVersion(node)
+      if (!version || version !== checked.latestVersion) {
+        return yield* new InstallFailedError({
+          cause: new Error(`Installed package identity did not match checked update: ${version ?? "missing"}`),
+          add: [target],
+          dir,
+        })
+      }
+      const previousDirectory = yield* activeDirectory(root)
+      yield* afs
+        .writeWithDirs(path.join(root, ".opencode-previous"), previousDirectory)
+        .pipe(Effect.mapError((cause) => new InstallFailedError({ cause, dir: root })))
+      yield* afs
+        .writeWithDirs(path.join(root, ".opencode-active"), dir)
+        .pipe(Effect.mapError((cause) => new InstallFailedError({ cause, dir: root })))
+      return {
+        updateable: true,
+        pinned: false,
+        currentVersion: version,
+        latestVersion: checked.latestVersion,
+        updateAvailable: false,
+        previousVersion: checked.currentVersion,
+        updated: version !== checked.currentVersion,
+      }
+    }, Effect.scoped)
+
+    const rollback = Effect.fn("Npm.rollback")(function* (pkg: string) {
+      const root = yield* directory(pkg)
+      const previous = yield* afs
+        .readFileStringSafe(path.join(root, ".opencode-previous"))
+        .pipe(Effect.mapError((cause) => new InstallFailedError({ cause, dir: root })))
+      if (!previous) return
+      const resolved = path.resolve(previous.trim())
+      if (resolved !== root && !resolved.startsWith(`${root}-revision-`)) return
+      if (resolved === root) {
+        yield* fs
+          .remove(path.join(root, ".opencode-active"))
+          .pipe(Effect.mapError((cause) => new InstallFailedError({ cause, dir: root })))
+        return
+      }
+      yield* afs
+        .writeWithDirs(path.join(root, ".opencode-active"), resolved)
+        .pipe(Effect.mapError((cause) => new InstallFailedError({ cause, dir: root })))
+    })
+
     const add = Effect.fn("Npm.add")(function* (pkg: string, options?: { readonly subpaths?: readonly string[] }) {
       const { default: npa } = yield* Effect.promise(() => import("npm-package-arg"))
-      const parsedName = (() => {
+      const root = yield* directory(pkg)
+      const dir = yield* activeDirectory(root)
+      const parsed = (() => {
         try {
-          return npa(pkg).name ?? undefined
+          return npa(pkg)
         } catch {
           return undefined
         }
       })()
-      const dir = yield* directory(pkg)
+      const parsedName = parsed?.name ?? undefined
       const name = yield* installedName(pkg, dir, parsedName)
 
       if (yield* afs.existsSafe(path.join(dir, "node_modules", name))) {
-        return resolveEntryPoint(name, path.join(dir, "node_modules", name), options?.subpaths)
+        const result = resolveEntryPoint(name, path.join(dir, "node_modules", name), options?.subpaths)
+        return {
+          ...result,
+          revision: (yield* installed(pkg, dir, parsedName, ["git", "hosted"].includes(parsed?.type ?? ""))).version,
+        }
       }
 
       const tree = yield* reify({ dir, add: [pkg] })
@@ -183,7 +385,7 @@ const layer = Layer.effect(
         if (result.entrypoint) return result
         return yield* new InstallFailedError({ add: [pkg], dir })
       }
-      return resolveEntryPoint(first.name, first.path, options?.subpaths)
+      return { ...resolveEntryPoint(first.name, first.path, options?.subpaths), revision: packageVersion(first) }
     }, Effect.scoped)
 
     const resolve = Effect.fn("Npm.resolve")(function* (
@@ -191,22 +393,26 @@ const layer = Layer.effect(
       options?: { readonly subpaths?: readonly string[] },
     ) {
       const { default: npa } = yield* Effect.promise(() => import("npm-package-arg"))
-      const parsedName = (() => {
+      const parsed = (() => {
         try {
-          return npa(pkg).name ?? undefined
+          return npa(pkg)
         } catch {
           return undefined
         }
       })()
-      const root = yield* directory(pkg)
+      const parsedName = parsed?.name ?? undefined
+      const root = yield* activeDirectory(yield* directory(pkg))
       const name = yield* installedName(pkg, root, parsedName)
       const dir = path.join(root, "node_modules", name)
       if (!(yield* afs.existsSafe(dir))) return { directory: dir }
-      return resolveEntryPoint(name, dir, options?.subpaths)
+      return {
+        ...resolveEntryPoint(name, dir, options?.subpaths),
+        revision: (yield* installed(pkg, root, parsedName, ["git", "hosted"].includes(parsed?.type ?? ""))).version,
+      }
     })
 
     const which = Effect.fn("Npm.which")(function* (pkg: string, bin?: string) {
-      const dir = yield* directory(pkg)
+      const dir = yield* activeDirectory(yield* directory(pkg))
       const binDir = path.join(dir, "node_modules", ".bin")
 
       const pick = Effect.fnUntraced(function* () {
@@ -258,7 +464,10 @@ const layer = Layer.effect(
 
     return Service.of({
       add,
+      check,
       resolve,
+      rollback,
+      update,
       which,
     })
   }),
@@ -283,3 +492,17 @@ export async function resolve(...args: Parameters<Interface["resolve"]>) {
 export async function which(...args: Parameters<Interface["which"]>) {
   return runPromise((svc) => svc.which(...args))
 }
+
+function packageVersion(node: ArboristNode | undefined) {
+  if (!node) return undefined
+  const commit = node.resolved?.match(/#([a-f0-9]{40,64})$/i)?.[1]
+  return commit ?? node.version ?? node.resolved
+}
+
+function pinGitSpec(pkg: string, commit: string) {
+  const subdirectory = pkg.indexOf("::")
+  const source = subdirectory === -1 ? pkg : pkg.slice(0, subdirectory)
+  const suffix = subdirectory === -1 ? "" : pkg.slice(subdirectory)
+  const hash = source.lastIndexOf("#")
+  return `${hash === -1 ? `${source}#` : source.slice(0, hash + 1)}${commit}${suffix}`
+}

packages/util/test/npm.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test"
+import { cacheKey, updatePolicy } from "../src/npm.js"
+
+describe("Npm.updatePolicy", () => {
+  test.each([
+    ["example-plugin", "mutable"],
+    ["example-plugin@latest", "mutable"],
+    ["example-plugin@next", "mutable"],
+    ["example-plugin@^1.2.3", "mutable"],
+    ["example-plugin@1.x", "mutable"],
+    ["github:example/plugin", "mutable"],
+    ["github:example/plugin#main", "mutable"],
+    ["git+https://example.com/plugin.git#release", "mutable"],
+    ["example-plugin@1.2.3", "pinned"],
+    [`github:example/plugin#${"a".repeat(40)}`, "pinned"],
+    [`git+https://example.com/plugin.git#${"b".repeat(64)}`, "pinned"],
+    ["./plugin.ts", "unsupported"],
+    ["file:./plugin.ts", "unsupported"],
+  ] as const)("classifies %s as %s", async (spec, expected) => {
+    expect(await updatePolicy(spec)).toBe(expected)
+  })
+})
+
+test("hashes Git specs before using them as global cache paths", async () => {
+  const key = await cacheKey("git+https://user:secret@example.com/plugin.git#main")
+
+  expect(key).toMatch(/^git-[a-f0-9]{64}$/)
+  expect(key).not.toContain("secret")
+})

packages/www/openapi.json

@@ -486,6 +486,306 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/update": {
+      "get": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.check",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Plugin.UpdateInfo"
+                      }
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Check configured plugins for explicitly available updates.",
+        "summary": "Check plugin updates"
+      },
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.update",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "$ref": "#/components/schemas/Plugin.UpdateResult"
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Explicitly update one configured plugin and reload plugins when it changes.",
+        "summary": "Update plugin",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "required": ["name"],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": true
+        }
+      }
+    },
+    "/api/plugin/update-all": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.updateAll",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Plugin.UpdateResult"
+                      }
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Explicitly update every updateable configured plugin and reload changed plugins.",
+        "summary": "Update plugins"
+      }
+    },
     "/api/session": {
       "get": {
         "tags": ["session"],
@@ -14846,6 +15146,9 @@
           "name": {
             "type": "string"
           },
+          "metadata": {
+            "type": "object"
+          },
           "methods": {
             "type": "array",
             "items": {
@@ -15356,6 +15659,9 @@
           "reasoningField": {
             "$ref": "#/components/schemas/Model.ReasoningField"
           },
+          "requireReasoning": {
+            "type": "boolean"
+          },
           "maxTokensField": {
             "$ref": "#/components/schemas/Model.MaxTokensField"
           },
@@ -15989,6 +16295,58 @@
           }
         ]
       },
+      "Plugin.UpdateInfo": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Plugin.Source"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["not-updateable", "pinned", "up-to-date", "available", "failed"]
+          },
+          "currentVersion": {
+            "type": "string"
+          },
+          "latestVersion": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": ["name", "source", "status"],
+        "additionalProperties": false
+      },
+      "Plugin.UpdateResult": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Plugin.Source"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["not-updateable", "pinned", "up-to-date", "updated", "failed"]
+          },
+          "previousVersion": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": ["name", "source", "status"],
+        "additionalProperties": false
+      },
       "Project": {
         "type": "object",
         "properties": {

packages/www/public/openapi.json

@@ -486,6 +486,306 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/update": {
+      "get": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.check",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Plugin.UpdateInfo"
+                      }
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Check configured plugins for explicitly available updates.",
+        "summary": "Check plugin updates"
+      },
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.update",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "$ref": "#/components/schemas/Plugin.UpdateResult"
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Explicitly update one configured plugin and reload plugins when it changes.",
+        "summary": "Update plugin",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "required": ["name"],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": true
+        }
+      }
+    },
+    "/api/plugin/update-all": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.updateAll",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "location": {
+                      "$ref": "#/components/schemas/Location.InfoEncoded"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Plugin.UpdateResult"
+                      }
+                    }
+                  },
+                  "required": ["location", "data"],
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Explicitly update every updateable configured plugin and reload changed plugins.",
+        "summary": "Update plugins"
+      }
+    },
     "/api/session": {
       "get": {
         "tags": ["session"],
@@ -14846,6 +15146,9 @@
           "name": {
             "type": "string"
           },
+          "metadata": {
+            "type": "object"
+          },
           "methods": {
             "type": "array",
             "items": {
@@ -15356,6 +15659,9 @@
           "reasoningField": {
             "$ref": "#/components/schemas/Model.ReasoningField"
           },
+          "requireReasoning": {
+            "type": "boolean"
+          },
           "maxTokensField": {
             "$ref": "#/components/schemas/Model.MaxTokensField"
           },
@@ -15989,6 +16295,58 @@
           }
         ]
       },
+      "Plugin.UpdateInfo": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Plugin.Source"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["not-updateable", "pinned", "up-to-date", "available", "failed"]
+          },
+          "currentVersion": {
+            "type": "string"
+          },
+          "latestVersion": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": ["name", "source", "status"],
+        "additionalProperties": false
+      },
+      "Plugin.UpdateResult": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Plugin.Source"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["not-updateable", "pinned", "up-to-date", "updated", "failed"]
+          },
+          "previousVersion": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "error": {
+            "type": "string"
+          }
+        },
+        "required": ["name", "source", "status"],
+        "additionalProperties": false
+      },
       "Project": {
         "type": "object",
         "properties": {

packages/www/src/docs/content/cli/keybinds.mdx

@@ -308,29 +308,31 @@ Unknown command IDs are rejected.
 
 ## Dialogs And Autocomplete
 
-| ID                             | Default       | Description                         |
-| ------------------------------ | ------------- | ----------------------------------- |
-| `dialog.select.prev`           | `up,ctrl+p`   | Move to previous dialog item        |
-| `dialog.select.next`           | `down,ctrl+n` | Move to next dialog item            |
-| `dialog.select.page_up`        | `pageup`      | Move up one page in dialog          |
-| `dialog.select.page_down`      | `pagedown`    | Move down one page in dialog        |
-| `dialog.select.home`           | `home`        | Move to first dialog item           |
-| `dialog.select.end`            | `end`         | Move to last dialog item            |
-| `dialog.select.submit`         | `return`      | Submit selected dialog item         |
-| `dialog.prompt.submit`         | `return`      | Submit dialog prompt                |
-| `dialog.worktree.generate`     | `tab`         | Generate worktree name              |
-| `dialog.move_session.new`      | `ctrl+m`      | New worktree                        |
-| `dialog.move_session.delete`   | `ctrl+d`      | Delete worktree                     |
-| `dialog.move_session.refresh`  | `ctrl+r`      | Refresh worktrees                   |
-| `prompt.autocomplete.prev`     | `up,ctrl+p`   | Move to previous autocomplete item  |
-| `prompt.autocomplete.next`     | `down,ctrl+n` | Move to next autocomplete item      |
-| `prompt.autocomplete.hide`     | `escape`      | Hide autocomplete                   |
-| `prompt.autocomplete.select`   | `return`      | Select autocomplete item            |
-| `prompt.autocomplete.complete` | `tab`         | Complete autocomplete item          |
-| `permission.prompt.fullscreen` | `ctrl+f`      | Toggle permission prompt fullscreen |
-| `plugins.toggle`               | `space`       | Toggle plugin                       |
-| `dialog.mcp.toggle`            | `space`       | Toggle MCP server                   |
-| `dialog.plugins.install`       | `shift+i`     | Install plugin from plugin dialog   |
+| ID                             | Default        | Description                         |
+| ------------------------------ | -------------- | ----------------------------------- |
+| `dialog.select.prev`           | `up,ctrl+p`    | Move to previous dialog item        |
+| `dialog.select.next`           | `down,ctrl+n`  | Move to next dialog item            |
+| `dialog.select.page_up`        | `pageup`       | Move up one page in dialog          |
+| `dialog.select.page_down`      | `pagedown`     | Move down one page in dialog        |
+| `dialog.select.home`           | `home`         | Move to first dialog item           |
+| `dialog.select.end`            | `end`          | Move to last dialog item            |
+| `dialog.select.submit`         | `return`       | Submit selected dialog item         |
+| `dialog.prompt.submit`         | `return`       | Submit dialog prompt                |
+| `dialog.worktree.generate`     | `tab`          | Generate worktree name              |
+| `dialog.move_session.new`      | `ctrl+m`       | New worktree                        |
+| `dialog.move_session.delete`   | `ctrl+d`       | Delete worktree                     |
+| `dialog.move_session.refresh`  | `ctrl+r`       | Refresh worktrees                   |
+| `prompt.autocomplete.prev`     | `up,ctrl+p`    | Move to previous autocomplete item  |
+| `prompt.autocomplete.next`     | `down,ctrl+n`  | Move to next autocomplete item      |
+| `prompt.autocomplete.hide`     | `escape`       | Hide autocomplete                   |
+| `prompt.autocomplete.select`   | `return`       | Select autocomplete item            |
+| `prompt.autocomplete.complete` | `tab`          | Complete autocomplete item          |
+| `permission.prompt.fullscreen` | `ctrl+f`       | Toggle permission prompt fullscreen |
+| `plugins.toggle`               | `space`        | Toggle plugin                       |
+| `dialog.mcp.toggle`            | `space`        | Toggle MCP server                   |
+| `dialog.plugins.install`       | `shift+i`      | Install plugin from plugin dialog   |
+| `dialog.plugins.update`        | `ctrl+r`       | Update selected plugin              |
+| `dialog.plugins.update_all`    | `ctrl+shift+r` | Update all plugins                  |
 
 ## Terminal And Plugins
 

packages/www/src/docs/content/cli/plugins.mdx

@@ -6,6 +6,16 @@ Plugins configured in `opencode.json(c)` that expose a TUI component are loaded
 to build plugins, see [Building plugins](/build/plugins). You do not need to add the same package to `cli.json`. The CLI
 gets the active plugin list from the connected OpenCode server, so this also works when the server is remote.
 
+## Manage installed plugins
+
+Run `/plugins`, or open **Plugins** from the command palette, to inspect server and CLI plugins. Select an installed server
+package or Git plugin, then use the actions in the dialog footer:
+
+- `ctrl+r` updates the selected plugin when an update is available.
+- `ctrl+shift+r` updates every plugin with an available update.
+
+The dialog marks pinned and local plugins that cannot be updated automatically.
+
 Use `cli.json` for CLI-only plugins. These plugins run locally in the terminal and remain active when the CLI connects
 to a remote server:
 

packages/www/src/docs/content/plugins.mdx

@@ -93,8 +93,9 @@ opencode2 plugin add 'github:acme/plugins#main::path:packages/opencode-plugin'
 Branches, tags, complete commit hashes, and npm's `::path:` repository-subdirectory selectors are supported. Configure
 local paths directly; tarball and npm alias targets are not accepted by `plugin add`.
 
-Changes under watched config directories reload automatically. Restart OpenCode after changing an installed package
-version or an unwatched dependency.
+Changes under watched config directories reload automatically. Package and Git plugins refresh only when you explicitly
+request an update; OpenCode installs the matching revision and reloads the plugin without a restart. Changes to unwatched
+local dependencies may still require restarting OpenCode.
 
 ```sh
 touch .opencode/plugins/concise.ts