@opencode-cockpit/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codestz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @opencode-cockpit/client
+
+Typed client for cockpitd. Starts the daemon when needed (one per machine, even under concurrent first calls), reconnects and restores subscriptions, replays read-only calls after a lost connection, and replaces a daemon running outdated code when it is idle.
+
+Part of [opencode-cockpit](https://github.com/Codestz/opencode-cockpit). Install the plugin, not this package, unless you are building your own front end:
+
+```sh
+opencode plugin opencode-cockpit --global
+```
+
+Requires Bun ≥ 1.3.5 (OpenCode's embedded runtime qualifies). License: MIT.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@opencode-cockpit/client",
+  "version": "0.1.0",
+  "description": "Auto-spawning, reconnecting, typed client for cockpitd",
+  "type": "module",
+  "license": "MIT",
+  "author": "Codestz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Codestz/opencode-cockpit.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/Codestz/opencode-cockpit#readme",
+  "bugs": {
+    "url": "https://github.com/Codestz/opencode-cockpit/issues"
+  },
+  "keywords": [
+    "opencode",
+    "client",
+    "json-rpc"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode-cockpit/protocol": "0.0.1"
+  },
+  "devDependencies": {
+    "@opencode-cockpit/daemon": "0.0.1"
+  },
+  "engines": {
+    "bun": ">=1.3.5"
+  }
+}

package/src/client.ts

@@ -0,0 +1,306 @@
+import { existsSync } from "node:fs"
+import {
+  type ClientInfo,
+  type CockpitPaths,
+  ErrorCode,
+  type EventEnvelope,
+  type EventOf,
+  type Events,
+  type HelloResult,
+  type MethodName,
+  type Methods,
+  type ParamsOf,
+  PROTOCOL_VERSION,
+  type ResultOf,
+  RpcError,
+  resolvePaths,
+  type Topic,
+} from "@opencode-cockpit/protocol"
+import { Connection } from "./connection.ts"
+import { releaseSpawnLock, type SpawnOptions, spawnDaemon } from "./spawn.ts"
+
+export interface ClientOptions {
+  client: ClientInfo
+  paths?: CockpitPaths
+  /** Start the daemon when it is not running. Omit to only connect. */
+  spawn?: SpawnOptions
+  /** How long to wait for a freshly spawned daemon. */
+  connectTimeoutMs?: number
+  /**
+   * Build id of the daemon code this client ships with (see `daemonBuildId`). When the running
+   * daemon differs, an idle daemon is replaced automatically; a busy one is kept and reported
+   * through `onOutdated` so running shells are never killed behind the user's back.
+   */
+  expectedBuild?: string
+}
+
+export interface OutdatedDaemon {
+  running: string | undefined
+  expected: string
+}
+
+const IDEMPOTENT = new Set<string>([
+  "daemon.hello",
+  "daemon.status",
+  "shell.list",
+  "shell.get",
+  "shell.read",
+  "shell.screen",
+  "shell.wait",
+])
+
+type Listener = (data: unknown, topic: string) => void
+export type ConnectionState = "connected" | "disconnected"
+
+/**
+ * Typed, reconnecting client for cockpitd. Calls transparently (re)connect and, when allowed,
+ * start the daemon. Subscriptions survive reconnects.
+ */
+export class CockpitClient {
+  readonly paths: CockpitPaths
+  private connection: Connection | undefined
+  private connecting: Promise<Connection> | undefined
+  private readonly listeners = new Map<string, Set<Listener>>()
+  private readonly stateListeners = new Set<(state: ConnectionState) => void>()
+  private hello: HelloResult | undefined
+  private closed = false
+  private outdatedInfo: OutdatedDaemon | undefined
+  private readonly outdatedListeners = new Set<(info: OutdatedDaemon | undefined) => void>()
+
+  constructor(private readonly options: ClientOptions) {
+    this.paths = options.paths ?? resolvePaths()
+  }
+
+  get daemon(): HelloResult | undefined {
+    return this.hello
+  }
+
+  get connected(): boolean {
+    return this.connection !== undefined && !this.connection.closed
+  }
+
+  async call<M extends MethodName>(method: M, ...args: ParamsArg<M>): Promise<ResultOf<Methods, M>> {
+    const conn = await this.ensure()
+    try {
+      return (await conn.request(method, args[0])) as ResultOf<Methods, M>
+    } catch (err) {
+      // The daemon went away under us. Methods without side effects are safe to replay once.
+      const lost =
+        err instanceof RpcError && err.code === ErrorCode.ShuttingDown && conn.closed && !this.closed
+      if (!lost || !IDEMPOTENT.has(method)) throw err
+      const next = await this.ensure()
+      return (await next.request(method, args[0])) as ResultOf<Methods, M>
+    }
+  }
+
+  /** Listen to a topic. Returns an unsubscribe function. */
+  on<T extends Topic>(topic: T, listener: (data: EventOf<Events, T>) => void): () => void {
+    let set = this.listeners.get(topic)
+    const isNew = !set
+    if (!set) {
+      set = new Set()
+      this.listeners.set(topic, set)
+    }
+    set.add(listener as Listener)
+    if (isNew && this.connected)
+      void this.connection?.request("events.subscribe", { topics: [topic] }).catch(() => {})
+    else if (isNew) void this.ensure().catch(() => {})
+    return () => {
+      set.delete(listener as Listener)
+      if (set.size === 0) {
+        this.listeners.delete(topic)
+        if (this.connected)
+          void this.connection?.request("events.unsubscribe", { topics: [topic] }).catch(() => {})
+      }
+    }
+  }
+
+  /** Set while connected to a daemon running different code than `expectedBuild`. */
+  get outdated(): OutdatedDaemon | undefined {
+    return this.outdatedInfo
+  }
+
+  onOutdated(listener: (info: OutdatedDaemon | undefined) => void): () => void {
+    this.outdatedListeners.add(listener)
+    return () => this.outdatedListeners.delete(listener)
+  }
+
+  /**
+   * Stop the daemon and start a fresh one from this client's code. Without `force` it refuses
+   * while shells are running. Returns false when refused.
+   */
+  async restartDaemon(options: { force?: boolean } = {}): Promise<boolean> {
+    const conn = await this.ensure()
+    const { accepted } = (await conn.request("daemon.shutdown", { force: options.force === true })) as {
+      accepted: boolean
+    }
+    if (!accepted) return false
+    await this.waitForSocketGone()
+    await this.ensure()
+    return true
+  }
+
+  onState(listener: (state: ConnectionState) => void): () => void {
+    this.stateListeners.add(listener)
+    return () => this.stateListeners.delete(listener)
+  }
+
+  /** Connect now (spawning if configured). Useful to surface errors early. */
+  async connect(): Promise<HelloResult> {
+    await this.ensure()
+    return this.hello as HelloResult
+  }
+
+  close(): void {
+    this.closed = true
+    this.connection?.close()
+    this.connection = undefined
+  }
+
+  private ensure(): Promise<Connection> {
+    if (this.closed) return Promise.reject(new RpcError(ErrorCode.ShuttingDown, "client closed"))
+    if (this.connection && !this.connection.closed) return Promise.resolve(this.connection)
+    this.connecting ??= this.establish().finally(() => {
+      this.connecting = undefined
+    })
+    return this.connecting
+  }
+
+  private async establish(replaced = false): Promise<Connection> {
+    let conn = await this.tryOpen()
+    if (!conn) {
+      if (!this.options.spawn) {
+        throw new RpcError(ErrorCode.ShuttingDown, `cockpitd is not running (${this.paths.socket})`)
+      }
+      const spawned = spawnDaemon(this.paths, this.options.spawn)
+      try {
+        conn = await this.waitForSocket(this.options.connectTimeoutMs ?? 8000)
+      } finally {
+        if (spawned) releaseSpawnLock(this.paths)
+      }
+    }
+
+    try {
+      this.hello = (await conn.request("daemon.hello", {
+        client: this.options.client,
+        protocol: PROTOCOL_VERSION,
+      })) as HelloResult
+    } catch (err) {
+      conn.close()
+      if (
+        err instanceof RpcError &&
+        err.code === ErrorCode.ProtocolMismatch &&
+        this.options.spawn &&
+        !replaced
+      ) {
+        return this.replaceIncompatibleDaemon(err)
+      }
+      throw err
+    }
+
+    const expected = this.options.expectedBuild
+    if (expected && this.hello.build !== expected) {
+      const status = (await conn.request("daemon.status", {})) as { modules: { busy: boolean }[] }
+      const busy = status.modules.some((m) => m.busy)
+      if (!busy && this.options.spawn && !replaced) {
+        await conn.request("daemon.shutdown", {}).catch(() => {})
+        conn.close()
+        await this.waitForSocketGone()
+        return this.establish(true)
+      }
+      this.setOutdated({ running: this.hello.build, expected })
+    } else {
+      this.setOutdated(undefined)
+    }
+
+    this.connection = conn
+    const topics = [...this.listeners.keys()]
+    if (topics.length > 0) await conn.request("events.subscribe", { topics })
+    for (const l of this.stateListeners) l("connected")
+    return conn
+  }
+
+  /** An older daemon speaks another protocol. Replace it only if nothing is running in it. */
+  private async replaceIncompatibleDaemon(err: RpcError): Promise<Connection> {
+    const data = err.data as { busy?: boolean } | undefined
+    if (data?.busy) {
+      throw new RpcError(
+        ErrorCode.ProtocolMismatch,
+        "cockpitd is running an incompatible version and has running shells; stop them or restart the daemon",
+        err.data,
+      )
+    }
+    const pid = await Bun.file(this.paths.pidFile)
+      .text()
+      .then((t) => Number.parseInt(t, 10))
+      .catch(() => Number.NaN)
+    if (Number.isFinite(pid)) {
+      try {
+        process.kill(pid, "SIGTERM")
+      } catch {
+        // already gone
+      }
+    }
+    await this.waitForSocketGone()
+    return this.establish(true)
+  }
+
+  private async waitForSocketGone(timeoutMs = 5000): Promise<void> {
+    const deadline = Date.now() + timeoutMs
+    // Bun.file().exists() reports false for unix sockets; use a stat-based check.
+    while (Date.now() < deadline && existsSync(this.paths.socket)) await Bun.sleep(50)
+  }
+
+  private setOutdated(info: OutdatedDaemon | undefined): void {
+    const changed =
+      info?.running !== this.outdatedInfo?.running ||
+      (info === undefined) !== (this.outdatedInfo === undefined)
+    this.outdatedInfo = info
+    if (changed) for (const l of this.outdatedListeners) l(info)
+  }
+
+  private async tryOpen(): Promise<Connection | undefined> {
+    try {
+      return await Connection.open(
+        this.paths.socket,
+        (event) => this.dispatch(event),
+        () => this.handleDisconnect(),
+      )
+    } catch {
+      return undefined
+    }
+  }
+
+  private async waitForSocket(timeoutMs: number): Promise<Connection> {
+    const deadline = Date.now() + timeoutMs
+    let delay = 25
+    while (Date.now() < deadline) {
+      const conn = await this.tryOpen()
+      if (conn) return conn
+      await Bun.sleep(delay)
+      delay = Math.min(delay * 2, 250)
+    }
+    throw new RpcError(
+      ErrorCode.ShuttingDown,
+      `cockpitd did not start within ${timeoutMs}ms; see ${this.paths.logFile}`,
+    )
+  }
+
+  private handleDisconnect(): void {
+    this.connection = undefined
+    for (const l of this.stateListeners) l("disconnected")
+  }
+
+  private dispatch(event: EventEnvelope): void {
+    for (const listener of this.listeners.get(event.topic) ?? []) {
+      try {
+        listener(event.data, event.topic)
+      } catch {
+        // a listener's failure must not break delivery to others
+      }
+    }
+  }
+}
+
+type ParamsArg<M extends MethodName> =
+  undefined extends ParamsOf<Methods, M> ? [params?: ParamsOf<Methods, M>] : [params: ParamsOf<Methods, M>]

package/src/connection.ts

@@ -0,0 +1,132 @@
+import {
+  ErrorCode,
+  EVENT_METHOD,
+  type EventEnvelope,
+  encodeFrame,
+  LineDecoder,
+  type RequestId,
+  RpcError,
+  type RpcMessage,
+} from "@opencode-cockpit/protocol"
+import type { Socket } from "bun"
+
+interface Pending {
+  resolve(value: unknown): void
+  reject(err: unknown): void
+}
+
+/** One socket to the daemon: request/response correlation, events, write backpressure. */
+export class Connection {
+  private readonly pending = new Map<RequestId, Pending>()
+  private readonly decoder = new LineDecoder()
+  private queue: Uint8Array[] = []
+  private nextId = 1
+  private closedFlag = false
+
+  private constructor(
+    private socket: Socket<undefined>,
+    private readonly onEvent: (event: EventEnvelope) => void,
+    private readonly onClose: () => void,
+  ) {}
+
+  static open(path: string, onEvent: (e: EventEnvelope) => void, onClose: () => void): Promise<Connection> {
+    return new Promise((resolve, reject) => {
+      let conn: Connection | undefined
+      Bun.connect<undefined>({
+        unix: path,
+        socket: {
+          open(socket) {
+            conn = new Connection(socket, onEvent, onClose)
+            resolve(conn)
+          },
+          data(_socket, chunk) {
+            conn?.receive(chunk)
+          },
+          drain() {
+            conn?.drain()
+          },
+          close() {
+            conn?.handleClose()
+          },
+          error(_socket, err) {
+            if (conn) conn.handleClose()
+            else reject(err)
+          },
+          connectError(_socket, err) {
+            reject(err)
+          },
+        },
+      }).catch(reject)
+    })
+  }
+
+  get closed(): boolean {
+    return this.closedFlag
+  }
+
+  request(method: string, params: unknown): Promise<unknown> {
+    if (this.closedFlag) return Promise.reject(new RpcError(ErrorCode.ShuttingDown, "connection closed"))
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.write({ jsonrpc: "2.0", id, method, params })
+    })
+  }
+
+  close(): void {
+    this.socket.end()
+    this.handleClose()
+  }
+
+  private write(message: unknown): void {
+    const frame = encodeFrame(message)
+    if (this.queue.length > 0) {
+      this.queue.push(frame)
+      return
+    }
+    const written = this.socket.write(frame)
+    if (written < frame.byteLength) this.queue.push(frame.subarray(Math.max(0, written)))
+  }
+
+  private drain(): void {
+    while (this.queue.length > 0) {
+      const head = this.queue[0] as Uint8Array
+      const written = this.socket.write(head)
+      if (written < head.byteLength) {
+        this.queue[0] = head.subarray(Math.max(0, written))
+        return
+      }
+      this.queue.shift()
+    }
+  }
+
+  private receive(chunk: Uint8Array): void {
+    for (const line of this.decoder.push(chunk)) {
+      let message: RpcMessage
+      try {
+        message = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if ("method" in message) {
+        if (message.method === EVENT_METHOD) this.onEvent(message.params as EventEnvelope)
+        continue
+      }
+      if (message.id === null) continue
+      const pending = this.pending.get(message.id)
+      if (!pending) continue
+      this.pending.delete(message.id)
+      if ("error" in message) pending.reject(RpcError.from(message.error))
+      else pending.resolve(message.result)
+    }
+  }
+
+  private handleClose(): void {
+    if (this.closedFlag) return
+    this.closedFlag = true
+    const error = new RpcError(ErrorCode.ShuttingDown, "connection to cockpitd closed")
+    for (const pending of this.pending.values()) pending.reject(error)
+    this.pending.clear()
+    this.onClose()
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { type ClientOptions, CockpitClient, type ConnectionState, type OutdatedDaemon } from "./client.ts"
+export type { SpawnOptions } from "./spawn.ts"

package/src/spawn.ts

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process"
+import { closeSync, mkdirSync, openSync, rmSync, statSync, writeSync } from "node:fs"
+import type { CockpitPaths } from "@opencode-cockpit/protocol"
+
+export interface SpawnOptions {
+  /** Path to the daemon entry script (`@opencode-cockpit/daemon/main`). */
+  entry: string
+  /** Runtime used to run it. Inside OpenCode this is the OpenCode binary, run with BUN_BE_BUN=1. */
+  execPath?: string
+  env?: Record<string, string | undefined>
+}
+
+const LOCK_STALE_MS = 15_000
+
+/**
+ * Takes an exclusive spawn lock so concurrent first calls start one daemon. Returns false when
+ * another process holds a fresh lock (it is spawning; the caller should just wait and connect).
+ */
+export function spawnDaemon(paths: CockpitPaths, options: SpawnOptions): boolean {
+  mkdirSync(paths.home, { recursive: true, mode: 0o700 })
+  if (!acquireLock(paths.lockFile)) return false
+  try {
+    const child = spawn(options.execPath ?? process.execPath, [options.entry], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, ...options.env, BUN_BE_BUN: "1", COCKPIT_HOME: paths.home },
+    })
+    child.unref()
+  } catch (err) {
+    releaseLock(paths.lockFile)
+    throw err
+  }
+  // The lock is released after the caller connects or times out; see releaseSpawnLock.
+  return true
+}
+
+export function releaseSpawnLock(paths: CockpitPaths): void {
+  releaseLock(paths.lockFile)
+}
+
+function acquireLock(file: string): boolean {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(file, "wx", 0o600)
+      writeSync(fd, String(process.pid))
+      closeSync(fd)
+      return true
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err
+      try {
+        if (Date.now() - statSync(file).mtimeMs > LOCK_STALE_MS) {
+          rmSync(file, { force: true })
+          continue
+        }
+      } catch {
+        continue // vanished between calls; retry
+      }
+      return false
+    }
+  }
+  return false
+}
+
+function releaseLock(file: string): void {
+  rmSync(file, { force: true })
+}