@opencode-cockpit/protocol 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/protocol
+
+Wire protocol for cockpitd: JSON-RPC 2.0 over NDJSON on a unix socket. Zod schemas for every method and event, error codes, filesystem layout and the daemon build id. No runtime I/O beyond path and hash helpers.
+
+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,40 @@
+{
+  "name": "@opencode-cockpit/protocol",
+  "version": "0.1.0",
+  "description": "Wire protocol, method and event contracts for cockpitd (opencode-cockpit)",
+  "type": "module",
+  "license": "MIT",
+  "author": "Codestz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Codestz/opencode-cockpit.git",
+    "directory": "packages/protocol"
+  },
+  "homepage": "https://github.com/Codestz/opencode-cockpit#readme",
+  "bugs": {
+    "url": "https://github.com/Codestz/opencode-cockpit/issues"
+  },
+  "keywords": [
+    "opencode",
+    "json-rpc",
+    "protocol"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./shell": "./src/shell.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.1.8"
+  },
+  "engines": {
+    "bun": ">=1.3.5"
+  }
+}

package/src/build.ts

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto"
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { dirname, join, relative } from "node:path"
+
+const SOURCE = /\.(ts|tsx|js|mjs|json)$/
+const SKIP = new Set(["node_modules", "test", "dist"])
+
+/**
+ * Identity of the daemon code that `entry` would run: a hash of every source file in the entry's
+ * package (its `src` directory, or the entry file itself when bundled). Daemon and client compute
+ * it the same way, so a client can tell when a running daemon was started from different code.
+ */
+export function daemonBuildId(entry: string, version: string): string {
+  const hash = createHash("sha256").update(version)
+  const root = dirname(entry)
+  const files = /[\\/]src$/.test(root) ? walk(root) : [entry]
+  for (const file of files.sort()) {
+    hash.update(relative(root, file)).update("\0").update(readFileSync(file)).update("\0")
+  }
+  return `${version}+${hash.digest("hex").slice(0, 12)}`
+}
+
+function walk(dir: string): string[] {
+  const out: string[] = []
+  for (const name of readdirSync(dir)) {
+    if (SKIP.has(name)) continue
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) out.push(...walk(path))
+    else if (SOURCE.test(name)) out.push(path)
+  }
+  return out
+}

package/src/contract.ts

@@ -0,0 +1,20 @@
+import type { z } from "zod"
+
+export interface MethodSpec<P extends z.ZodType = z.ZodType, R extends z.ZodType = z.ZodType> {
+  params: P
+  result: R
+}
+
+export const method = <P extends z.ZodType, R extends z.ZodType>(params: P, result: R): MethodSpec<P, R> => ({
+  params,
+  result,
+})
+
+export type Contract = Record<string, MethodSpec>
+export type EventContract = Record<string, z.ZodType>
+
+export type ParamsOf<C extends Contract, M extends keyof C> = z.input<C[M]["params"]>
+export type ResultOf<C extends Contract, M extends keyof C> = z.output<C[M]["result"]>
+export type EventOf<E extends EventContract, T extends keyof E> = z.output<E[T]>
+/** Params after schema parsing (defaults applied): what handlers receive. */
+export type ParsedParamsOf<C extends Contract, M extends keyof C> = z.output<C[M]["params"]>

package/src/daemon.ts

@@ -0,0 +1,48 @@
+import { z } from "zod"
+import { method } from "./contract.ts"
+
+export const ClientInfo = z.object({
+  name: z.string().min(1),
+  version: z.string().min(1),
+  pid: z.number().int().optional(),
+})
+
+export const Version = z.object({ major: z.number().int(), minor: z.number().int() })
+
+export const HelloResult = z.object({
+  daemonVersion: z.string(),
+  /** Content identity of the running daemon code (see daemonBuildId). */
+  build: z.string().optional(),
+  protocol: Version,
+  modules: z.array(z.string()),
+  pid: z.number().int(),
+  startedAt: z.number(),
+})
+
+export const StatusResult = z.object({
+  pid: z.number().int(),
+  uptimeMs: z.number(),
+  clients: z.number().int(),
+  modules: z.array(z.object({ name: z.string(), busy: z.boolean() })),
+})
+
+export const daemonContract = {
+  "daemon.hello": method(z.object({ client: ClientInfo, protocol: Version }), HelloResult),
+  "daemon.status": method(z.object({}).optional(), StatusResult),
+  "daemon.shutdown": method(
+    z.object({ force: z.boolean().optional() }).optional(),
+    z.object({ accepted: z.boolean() }),
+  ),
+  "events.subscribe": method(
+    z.object({ topics: z.array(z.string().min(1)).min(1) }),
+    z.object({ topics: z.array(z.string()) }),
+  ),
+  "events.unsubscribe": method(
+    z.object({ topics: z.array(z.string().min(1)).min(1) }),
+    z.object({ topics: z.array(z.string()) }),
+  ),
+}
+
+export type HelloResult = z.output<typeof HelloResult>
+export type StatusResult = z.output<typeof StatusResult>
+export type ClientInfo = z.output<typeof ClientInfo>

package/src/framing.ts

@@ -0,0 +1,26 @@
+/** NDJSON framing shared by daemon and client. */
+
+const encoder = new TextEncoder()
+
+export function encodeFrame(message: unknown): Uint8Array {
+  return encoder.encode(`${JSON.stringify(message)}\n`)
+}
+
+/** Accumulates chunks and yields complete lines. Bounded to protect against runaway peers. */
+export class LineDecoder {
+  private readonly decoder = new TextDecoder()
+  private pending = ""
+
+  constructor(private readonly maxLineBytes = 16 * 1024 * 1024) {}
+
+  push(chunk: Uint8Array): string[] {
+    this.pending += this.decoder.decode(chunk, { stream: true })
+    const parts = this.pending.split("\n")
+    this.pending = parts.pop() ?? ""
+    if (this.pending.length > this.maxLineBytes) {
+      this.pending = ""
+      throw new Error(`frame exceeds ${this.maxLineBytes} bytes`)
+    }
+    return parts.filter((line) => line.length > 0)
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import type { EventContract } from "./contract.ts"
+import { daemonContract } from "./daemon.ts"
+import { shellContract, shellEvents } from "./shell.ts"
+
+export * from "./build.ts"
+export * from "./contract.ts"
+export * from "./daemon.ts"
+export * from "./framing.ts"
+export * from "./paths.ts"
+export * from "./rpc.ts"
+export * as shell from "./shell.ts"
+
+/** Every method the daemon serves. Adding a module means spreading its contract here. */
+export const contract = { ...daemonContract, ...shellContract }
+export type Methods = typeof contract
+export type MethodName = keyof Methods
+
+/** Every event topic the daemon emits. */
+export const events = { ...shellEvents } satisfies EventContract
+export type Events = typeof events
+export type Topic = keyof Events

package/src/paths.ts

@@ -0,0 +1,25 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export interface CockpitPaths {
+  home: string
+  socket: string
+  pidFile: string
+  lockFile: string
+  logFile: string
+}
+
+/**
+ * Filesystem layout shared by daemon and clients. Pure: creates nothing.
+ * Kept short because unix socket paths are limited to 104 bytes on macOS.
+ */
+export function resolvePaths(env: Record<string, string | undefined> = process.env): CockpitPaths {
+  const home = env.COCKPIT_HOME ?? join(env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "opencode-cockpit")
+  return {
+    home,
+    socket: join(home, "cockpitd.sock"),
+    pidFile: join(home, "cockpitd.pid"),
+    lockFile: join(home, "spawn.lock"),
+    logFile: join(home, "cockpitd.log"),
+  }
+}

package/src/rpc.ts

@@ -0,0 +1,96 @@
+/** Wire envelope: JSON-RPC 2.0, one JSON object per line (ADR 0002). */
+
+/** Bump MAJOR on breaking changes to methods, events or framing. */
+export const PROTOCOL_VERSION = { major: 1, minor: 1 } as const
+
+export type RequestId = number | string
+
+export interface RpcRequest {
+  jsonrpc: "2.0"
+  id: RequestId
+  method: string
+  params?: unknown
+}
+
+export interface RpcNotification {
+  jsonrpc: "2.0"
+  method: string
+  params?: unknown
+}
+
+export interface RpcSuccess {
+  jsonrpc: "2.0"
+  id: RequestId
+  result: unknown
+}
+
+export interface RpcFailure {
+  jsonrpc: "2.0"
+  id: RequestId | null
+  error: RpcErrorShape
+}
+
+export type RpcMessage = RpcRequest | RpcNotification | RpcSuccess | RpcFailure
+
+export interface RpcErrorShape {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export const ErrorCode = {
+  ParseError: -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams: -32602,
+  InternalError: -32603,
+  // Application range
+  NotFound: -32001,
+  InvalidState: -32002,
+  ProtocolMismatch: -32003,
+  SpawnFailed: -32004,
+  ShuttingDown: -32005,
+} as const
+
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode]
+
+export class RpcError extends Error {
+  constructor(
+    readonly code: number,
+    message: string,
+    readonly data?: unknown,
+  ) {
+    super(message)
+    this.name = "RpcError"
+  }
+
+  toShape(): RpcErrorShape {
+    return this.data === undefined
+      ? { code: this.code, message: this.message }
+      : { code: this.code, message: this.message, data: this.data }
+  }
+
+  static from(shape: RpcErrorShape): RpcError {
+    return new RpcError(shape.code, shape.message, shape.data)
+  }
+}
+
+/** Method name for daemon → client notifications. */
+export const EVENT_METHOD = "event"
+
+export interface EventEnvelope<T extends string = string, D = unknown> {
+  topic: T
+  data: D
+}
+
+export function isRequest(msg: RpcMessage): msg is RpcRequest {
+  return "method" in msg && "id" in msg && msg.id !== undefined
+}
+
+export function isNotification(msg: RpcMessage): msg is RpcNotification {
+  return "method" in msg && !("id" in msg)
+}
+
+export function isResponse(msg: RpcMessage): msg is RpcSuccess | RpcFailure {
+  return !("method" in msg) && ("result" in msg || "error" in msg)
+}

package/src/shell.ts

@@ -0,0 +1,187 @@
+import { z } from "zod"
+import { method } from "./contract.ts"
+
+export const ShellId = z.string().regex(/^sh_[a-z2-7]{8}$/, "expected sh_ followed by 8 base32 chars")
+
+export const Owner = z.object({
+  /** Absolute project directory the shell belongs to. */
+  project: z.string().min(1),
+  /** OpenCode session that started it, when started by an agent. */
+  session: z.string().min(1).optional(),
+  /** Opaque id of the client instance that started it; used to route notifications to one place. */
+  instance: z.string().min(1).optional(),
+})
+
+export const ShellStatus = z.enum(["running", "exited", "killed", "failed"])
+
+export const ShellInfo = z.object({
+  id: ShellId,
+  title: z.string(),
+  command: z.string(),
+  args: z.array(z.string()),
+  cwd: z.string(),
+  owner: Owner,
+  status: ShellStatus,
+  run: z.number().int().positive(),
+  pid: z.number().int().optional(),
+  exitCode: z.number().int().optional(),
+  signal: z.string().optional(),
+  error: z.string().optional(),
+  /** Set when a run ends: the last error-looking line of the run, else its last line. */
+  summary: z.string().optional(),
+  startedAt: z.number(),
+  endedAt: z.number().optional(),
+  cols: z.number().int(),
+  rows: z.number().int(),
+  lines: z.object({ first: z.number().int(), last: z.number().int() }),
+  /** Absolute raw byte offset written so far (for UI attach/replay). */
+  bytes: z.number().int(),
+})
+
+const Dimension = z.number().int().min(2).max(1000)
+
+export const StartParams = z.object({
+  command: z.string().min(1),
+  args: z.array(z.string()).default([]),
+  cwd: z.string().min(1),
+  env: z.record(z.string(), z.string()).optional(),
+  title: z.string().min(1).max(200).optional(),
+  cols: Dimension.default(120),
+  rows: Dimension.default(32),
+  owner: Owner,
+  /** Stop the shell automatically after this long. */
+  timeoutMs: z.number().int().positive().optional(),
+  /**
+   * Restart a finished shell with the same command, args, cwd, project and session instead of
+   * creating a new one. Repeated runs then share one id and one log.
+   */
+  reuse: z.boolean().default(false),
+})
+
+export const ClearParams = z
+  .object({
+    owner: Owner.partial().optional(),
+    /** Only remove shells that finished at least this long ago. */
+    finishedBeforeMs: z.number().int().min(0).optional(),
+  })
+  .default({})
+
+export const ListParams = z
+  .object({
+    owner: Owner.partial().optional(),
+    includeExited: z.boolean().default(true),
+  })
+  .default({ includeExited: true })
+
+export const IdParams = z.object({ id: ShellId })
+
+export const LogLine = z.object({ n: z.number().int(), text: z.string() })
+
+export const ReadParams = z.object({
+  id: ShellId,
+  /** Cursor: return only lines numbered strictly greater than this. */
+  after: z.number().int().min(0).optional(),
+  /** When no cursor is given, return the last N lines. */
+  tail: z.number().int().positive().max(10_000).default(100),
+  limit: z.number().int().positive().max(10_000).default(500),
+  grep: z.string().min(1).max(500).optional(),
+  ignoreCase: z.boolean().default(false),
+})
+
+export const ReadResult = z.object({
+  lines: z.array(LogLine),
+  firstLine: z.number().int(),
+  lastLine: z.number().int(),
+  /** Pass as `after` to continue. */
+  nextCursor: z.number().int(),
+  /** True when requested lines were already evicted. */
+  truncated: z.boolean(),
+  /** True when more lines exist beyond `limit`. */
+  hasMore: z.boolean(),
+  status: ShellStatus,
+})
+
+export const ScreenResult = z.object({
+  text: z.string(),
+  cols: z.number().int(),
+  rows: z.number().int(),
+  cursor: z.object({ x: z.number().int(), y: z.number().int() }),
+})
+
+export const WriteParams = z.object({ id: ShellId, data: z.string().max(1_000_000) })
+
+export const ResizeParams = z.object({ id: ShellId, cols: Dimension, rows: Dimension })
+
+export const WaitUntil = z
+  .object({
+    pattern: z.string().min(1).max(500).optional(),
+    ignoreCase: z.boolean().optional(),
+    exit: z.boolean().optional(),
+    idleMs: z.number().int().positive().optional(),
+    port: z.number().int().min(1).max(65_535).optional(),
+    host: z.string().optional(),
+  })
+  .refine((u) => u.pattern !== undefined || u.exit || u.idleMs !== undefined || u.port !== undefined, {
+    message: "until needs at least one of pattern, exit, idleMs, port",
+  })
+
+export const WaitParams = z.object({
+  id: ShellId,
+  until: WaitUntil,
+  timeoutMs: z.number().int().positive().max(3_600_000),
+  /** Only consider lines after this cursor for `pattern`. Defaults to the current last line. */
+  after: z.number().int().min(0).optional(),
+})
+
+export const WaitReason = z.enum(["pattern", "exit", "idle", "port", "timeout"])
+
+export const WaitResult = z.object({
+  reason: WaitReason,
+  match: LogLine.optional(),
+  info: ShellInfo,
+})
+
+export const StopParams = z.object({
+  id: ShellId,
+  signal: z.enum(["SIGTERM", "SIGINT", "SIGHUP", "SIGKILL"]).default("SIGTERM"),
+  graceMs: z.number().int().min(0).max(60_000).default(3000),
+})
+
+export const AttachParams = z.object({ id: ShellId, fromOffset: z.number().int().min(0).optional() })
+
+export const shellContract = {
+  "shell.start": method(StartParams, ShellInfo),
+  "shell.list": method(ListParams, z.array(ShellInfo)),
+  "shell.get": method(IdParams, ShellInfo),
+  "shell.read": method(ReadParams, ReadResult),
+  "shell.screen": method(IdParams, ScreenResult),
+  "shell.write": method(WriteParams, z.object({ bytes: z.number().int() })),
+  "shell.resize": method(ResizeParams, z.object({})),
+  "shell.wait": method(WaitParams, WaitResult),
+  "shell.stop": method(StopParams, ShellInfo),
+  "shell.restart": method(IdParams, ShellInfo),
+  "shell.remove": method(IdParams, z.object({})),
+  "shell.clear": method(ClearParams, z.object({ removed: z.array(ShellId) })),
+  "shell.attach": method(AttachParams, z.object({ offset: z.number().int(), replay: z.string() })),
+  "shell.detach": method(IdParams, z.object({})),
+}
+
+export const shellEvents = {
+  "shell.started": ShellInfo,
+  "shell.exited": ShellInfo,
+  "shell.removed": z.object({ id: ShellId }),
+  "shell.output": z.object({ id: ShellId, offset: z.number().int(), data: z.string() }),
+}
+
+export type Owner = z.output<typeof Owner>
+export type ShellStatus = z.output<typeof ShellStatus>
+export type ShellInfo = z.output<typeof ShellInfo>
+export type StartParams = z.output<typeof StartParams>
+export type ReadParams = z.output<typeof ReadParams>
+export type ReadResult = z.output<typeof ReadResult>
+export type ScreenResult = z.output<typeof ScreenResult>
+export type WaitParams = z.output<typeof WaitParams>
+export type WaitResult = z.output<typeof WaitResult>
+export type WaitReason = z.output<typeof WaitReason>
+export type StopParams = z.output<typeof StopParams>
+export type LogLine = z.output<typeof LogLine>