feat(experimental): add hot reload API trigger

Author: benjaminshafii

packages/opencode/src/file/watcher.ts

@@ -46,7 +46,7 @@ export namespace FileWatcher {
 
   const state = Instance.state(
     async () => {
-      if (Instance.project.vcs !== "git" && !Flag.OPENCODE_HOT_RELOAD) return {}
+      if (Instance.project.vcs !== "git" && !Flag.OPENCODE_EXPERIMENTAL_HOT_RELOAD) return {}
       log.info("init")
       const cfg = await Config.get()
       const backend = (() => {
@@ -75,7 +75,7 @@ export namespace FileWatcher {
       const subs: ParcelWatcher.AsyncSubscription[] = []
       const cfgIgnores = cfg.watcher?.ignore ?? []
 
-      if (Flag.OPENCODE_EXPERIMENTAL_FILEWATCHER || Flag.OPENCODE_HOT_RELOAD) {
+      if (Flag.OPENCODE_EXPERIMENTAL_FILEWATCHER || Flag.OPENCODE_EXPERIMENTAL_HOT_RELOAD) {
         const pending = w.subscribe(Instance.directory, subscribe, {
           ignore: [...FileIgnore.PATTERNS, ...cfgIgnores],
           backend,

packages/opencode/src/flag/flag.ts

@@ -30,12 +30,13 @@ export namespace Flag {
   export declare const OPENCODE_CLIENT: string
   export const OPENCODE_SERVER_PASSWORD = process.env["OPENCODE_SERVER_PASSWORD"]
   export const OPENCODE_SERVER_USERNAME = process.env["OPENCODE_SERVER_USERNAME"]
+  // Experimental
+  export const OPENCODE_EXPERIMENTAL = truthy("OPENCODE_EXPERIMENTAL")
   export const OPENCODE_HOT_RELOAD = truthy("OPENCODE_HOT_RELOAD")
+  export const OPENCODE_EXPERIMENTAL_HOT_RELOAD =
+    OPENCODE_EXPERIMENTAL || OPENCODE_HOT_RELOAD || truthy("OPENCODE_EXPERIMENTAL_HOT_RELOAD")
   export const OPENCODE_HOT_RELOAD_DEBOUNCE_MS = number("OPENCODE_HOT_RELOAD_DEBOUNCE_MS")
   export const OPENCODE_HOT_RELOAD_COOLDOWN_MS = number("OPENCODE_HOT_RELOAD_COOLDOWN_MS")
-
-  // Experimental
-  export const OPENCODE_EXPERIMENTAL = truthy("OPENCODE_EXPERIMENTAL")
   export const OPENCODE_EXPERIMENTAL_FILEWATCHER = truthy("OPENCODE_EXPERIMENTAL_FILEWATCHER")
   export const OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER = truthy("OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER")
   export const OPENCODE_EXPERIMENTAL_ICON_DISCOVERY =

packages/opencode/src/project/hotreload.ts

@@ -109,7 +109,7 @@ export namespace HotReload {
 
   const state = Instance.state(
     () => {
-      if (!Flag.OPENCODE_HOT_RELOAD) return {}
+      if (!Flag.OPENCODE_EXPERIMENTAL_HOT_RELOAD) return {}
 
       const debounce = Flag.OPENCODE_HOT_RELOAD_DEBOUNCE_MS ?? 700
       const cooldown = Flag.OPENCODE_HOT_RELOAD_COOLDOWN_MS ?? 1500
@@ -134,12 +134,17 @@ export namespace HotReload {
         await Command.reset()
       }
 
-      const flush = (reason: "timer" | "session") => {
+      const schedule = () => {
+        if (timer) clearTimeout(timer)
+        timer = setTimeout(() => flush("timer"), debounce)
+      }
+
+      const flush = (reason: "timer" | "session" | "api") => {
         timer = undefined
-        if (busy) return
+        if (busy) return { ok: true, queued, sessions: active() }
 
         const hit = latest
-        if (!hit) return
+        if (!hit) return { ok: true, queued, sessions: active() }
 
         const sessions = active()
         if (sessions > 0) {
@@ -151,14 +156,14 @@ export namespace HotReload {
             })
           }
           queued = true
-          return
+          return { ok: true, queued: true, sessions }
         }
 
         const now = Date.now()
         const wait = cooldown - (now - last)
         if (wait > 0) {
           timer = setTimeout(() => flush(reason), wait)
-          return
+          return { ok: true, queued: false, sessions, wait }
         }
 
         busy = true
@@ -182,21 +187,26 @@ export namespace HotReload {
             if (timer) clearTimeout(timer)
             timer = setTimeout(() => flush("timer"), debounce)
           })
+        return { ok: true, queued: false, sessions }
       }
 
-      const schedule = () => {
-        if (timer) clearTimeout(timer)
-        timer = setTimeout(() => flush("timer"), debounce)
+      const request = (hit: { file: string; event: "add" | "change" | "unlink" }, mode: "file" | "api") => {
+        latest = hit
+        if (mode === "api") return flush("api")
+        schedule()
+        return { ok: true, queued, sessions: active() }
       }
 
       const unsubFile = Bus.subscribe(FileWatcher.Event.Updated, (event) => {
         const rel = classify(Instance.directory, event.properties.file)
         if (!rel) return
-        latest = {
-          file: rel,
-          event: event.properties.event,
-        }
-        schedule()
+        void request(
+          {
+            file: rel,
+            event: event.properties.event,
+          },
+          "file",
+        )
       })
 
       const unsubSession = Bus.subscribe(SessionStatus.Event.Status, () => {
@@ -209,6 +219,7 @@ export namespace HotReload {
       return {
         unsubFile,
         unsubSession,
+        request,
         clear() {
           if (!timer) return
           clearTimeout(timer)
@@ -226,4 +237,16 @@ export namespace HotReload {
   export function init() {
     state()
   }
+
+  export function request(input?: { file?: string; event?: "add" | "change" | "unlink" }) {
+    const entry = state()
+    const req = "request" in entry ? entry.request : undefined
+    if (!req) {
+      return { ok: false, enabled: false }
+    }
+    const file = input?.file?.trim() || "api"
+    const event = input?.event || "change"
+    const result = req({ file, event }, "api")
+    return { ...result, enabled: true }
+  }
 }

packages/opencode/src/server/routes/experimental.ts

@@ -6,12 +6,60 @@ import { Worktree } from "../../worktree"
 import { Instance } from "../../project/instance"
 import { Project } from "../../project/project"
 import { MCP } from "../../mcp"
+import { HotReload } from "../../project/hotreload"
+import { Flag } from "../../flag/flag"
 import { zodToJsonSchema } from "zod-to-json-schema"
 import { errors } from "../error"
 import { lazy } from "../../util/lazy"
 
 export const ExperimentalRoutes = lazy(() =>
   new Hono()
+    .post(
+      "/hotreload",
+      describeRoute({
+        summary: "Apply hot reload",
+        description:
+          "Trigger an in-place reload of cached config/skills/agents/commands for the current instance. This is experimental and session-aware.",
+        operationId: "experimental.hotreload.apply",
+        responses: {
+          200: {
+            description: "Hot reload scheduled",
+            content: {
+              "application/json": {
+                schema: resolver(
+                  z
+                    .object({
+                      ok: z.boolean(),
+                      enabled: z.boolean(),
+                      queued: z.boolean().optional(),
+                      sessions: z.number().optional(),
+                      wait: z.number().optional(),
+                    })
+                    .meta({ ref: "ExperimentalHotReloadResult" }),
+                ),
+              },
+            },
+          },
+          ...errors(400),
+        },
+      }),
+      validator(
+        "json",
+        z
+          .object({
+            file: z.string().optional(),
+            event: z.enum(["add", "change", "unlink"]).optional(),
+          })
+          .optional(),
+      ),
+      async (c) => {
+        if (!Flag.OPENCODE_EXPERIMENTAL_HOT_RELOAD) {
+          return c.json({ ok: false, enabled: false }, 400)
+        }
+        const body = c.req.valid("json")
+        return c.json(HotReload.request(body ?? undefined))
+      },
+    )
     .get(
       "/tool/ids",
       describeRoute({