@opencode-cockpit/protocol 0.1.4 → 0.1.5

package/dist/build.js

@@ -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 directory
+ * the entry lives in. 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, version) {
+  const hash = createHash("sha256").update(version);
+  // A checkout runs from `src/`, a published install from `dist/`. Hash that whole directory so
+  // any change to the daemon's code yields a new id, and accept either the directory itself or a
+  // file inside it, so daemon and client always agree.
+  const root = statSync(entry).isDirectory() ? entry : dirname(entry);
+  const files = walk(root);
+  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) {
+  const out = [];
+  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/dist/contract.js

@@ -0,0 +1,6 @@
+export const method = (params, result) => ({
+  params,
+  result
+});
+
+/** Params after schema parsing (defaults applied): what handlers receive. */

package/dist/daemon.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { method } from "./contract.js";
+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())
+  }))
+};

package/dist/framing.js

@@ -0,0 +1,27 @@
+/** NDJSON framing shared by daemon and client. */
+
+const encoder = new TextEncoder();
+export function encodeFrame(message) {
+  return encoder.encode(`${JSON.stringify(message)}\n`);
+}
+
+/** Accumulates chunks and yields complete lines. Bounded to protect against runaway peers. */
+export class LineDecoder {
+  decoder = new TextDecoder();
+  pending = "";
+  constructor(maxLineBytes = 16 * 1024 * 1024) {
+    this.maxLineBytes = maxLineBytes;
+  }
+  push(chunk) {
+    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/dist/index.js

@@ -0,0 +1,19 @@
+import { daemonContract } from "./daemon.js";
+import { shellContract, shellEvents } from "./shell.js";
+export * from "./build.js";
+export * from "./contract.js";
+export * from "./daemon.js";
+export * from "./framing.js";
+export * from "./paths.js";
+export * from "./rpc.js";
+export * as shell from "./shell.js";
+
+/** Every method the daemon serves. Adding a module means spreading its contract here. */
+export const contract = {
+  ...daemonContract,
+  ...shellContract
+};
+/** Every event topic the daemon emits. */
+export const events = {
+  ...shellEvents
+};

package/dist/paths.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * 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 = process.env) {
+  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/dist/rpc.js

@@ -0,0 +1,53 @@
+/** 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
+};
+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
+};
+export class RpcError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = "RpcError";
+  }
+  toShape() {
+    return this.data === undefined ? {
+      code: this.code,
+      message: this.message
+    } : {
+      code: this.code,
+      message: this.message,
+      data: this.data
+    };
+  }
+  static from(shape) {
+    return new RpcError(shape.code, shape.message, shape.data);
+  }
+}
+
+/** Method name for daemon → client notifications. */
+export const EVENT_METHOD = "event";
+export function isRequest(msg) {
+  return "method" in msg && "id" in msg && msg.id !== undefined;
+}
+export function isNotification(msg) {
+  return "method" in msg && !("id" in msg);
+}
+export function isResponse(msg) {
+  return !("method" in msg) && ("result" in msg || "error" in msg);
+}

package/{src/shell.ts → dist/shell.js}

@@ -1,19 +1,15 @@
-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")
-
+import { z } from "zod";
+import { method } from "./contract.js";
+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"])
-
+  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(),
@@ -33,13 +29,14 @@ export const ShellInfo = z.object({
   endedAt: z.number().optional(),
   cols: z.number().int(),
   rows: z.number().int(),
-  lines: z.object({ first: z.number().int(), last: 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)
-
+  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([]),
@@ -55,28 +52,26 @@ export const StartParams = z.object({
    * 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() })
-
+  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. */
@@ -85,9 +80,8 @@ export const ReadParams = z.object({
   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),
-})
-
+  ignoreCase: z.boolean().default(false)
+});
 export const ReadResult = z.object({
   lines: z.array(LogLine),
   firstLine: z.number().int(),
@@ -98,90 +92,90 @@ export const ReadResult = z.object({
   truncated: z.boolean(),
   /** True when more lines exist beyond `limit`. */
   hasMore: z.boolean(),
-  status: ShellStatus,
-})
-
+  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(),
+  cursor: z.object({
+    x: z.number().int(),
+    y: z.number().int()
   })
-  .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 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"])
-
+  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,
-})
-
+  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() })
-
+  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.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({})),
-}
-
+  "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>
+  "shell.removed": z.object({
+    id: ShellId
+  }),
+  "shell.output": z.object({
+    id: ShellId,
+    offset: z.number().int(),
+    data: z.string()
+  })
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/protocol",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Wire protocol, method and event contracts for cockpitd (opencode-cockpit)",
   "type": "module",
   "license": "MIT",
@@ -20,11 +20,18 @@
     "protocol"
   ],
   "exports": {
-    ".": "./src/index.ts",
-    "./shell": "./src/shell.ts"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./shell": {
+      "types": "./types/shell.d.ts",
+      "default": "./dist/shell.js"
+    }
   },
   "files": [
-    "src",
+    "dist",
+    "types",
     "README.md",
     "LICENSE"
   ],

package/types/build.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Identity of the daemon code that `entry` would run: a hash of every source file in the directory
+ * the entry lives in. Daemon and client compute it the same way, so a client can tell when a
+ * running daemon was started from different code.
+ */
+export declare function daemonBuildId(entry: string, version: string): string;

package/{src/contract.ts → types/contract.d.ts}

@@ -1,20 +1,13 @@
-import type { z } from "zod"
-
+import type { z } from "zod";
 export interface MethodSpec<P extends z.ZodType = z.ZodType, R extends z.ZodType = z.ZodType> {
-  params: P
-  result: R
+    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]>
+export declare const method: <P extends z.ZodType, R extends z.ZodType>(params: P, result: R) => MethodSpec<P, R>;
+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"]>
+export type ParsedParamsOf<C extends Contract, M extends keyof C> = z.output<C[M]["params"]>;

package/types/daemon.d.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+export declare const ClientInfo: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    pid: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const Version: z.ZodObject<{
+    major: z.ZodNumber;
+    minor: z.ZodNumber;
+}, z.core.$strip>;
+export declare const HelloResult: z.ZodObject<{
+    daemonVersion: z.ZodString;
+    build: z.ZodOptional<z.ZodString>;
+    protocol: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strip>;
+    modules: z.ZodArray<z.ZodString>;
+    pid: z.ZodNumber;
+    startedAt: z.ZodNumber;
+}, z.core.$strip>;
+export declare const StatusResult: z.ZodObject<{
+    pid: z.ZodNumber;
+    uptimeMs: z.ZodNumber;
+    clients: z.ZodNumber;
+    modules: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        busy: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const daemonContract: {
+    "daemon.hello": import("./contract.ts").MethodSpec<z.ZodObject<{
+        client: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+            pid: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        protocol: z.ZodObject<{
+            major: z.ZodNumber;
+            minor: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        daemonVersion: z.ZodString;
+        build: z.ZodOptional<z.ZodString>;
+        protocol: z.ZodObject<{
+            major: z.ZodNumber;
+            minor: z.ZodNumber;
+        }, z.core.$strip>;
+        modules: z.ZodArray<z.ZodString>;
+        pid: z.ZodNumber;
+        startedAt: z.ZodNumber;
+    }, z.core.$strip>>;
+    "daemon.status": import("./contract.ts").MethodSpec<z.ZodOptional<z.ZodObject<{}, z.core.$strip>>, z.ZodObject<{
+        pid: z.ZodNumber;
+        uptimeMs: z.ZodNumber;
+        clients: z.ZodNumber;
+        modules: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            busy: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    "daemon.shutdown": import("./contract.ts").MethodSpec<z.ZodOptional<z.ZodObject<{
+        force: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>, z.ZodObject<{
+        accepted: z.ZodBoolean;
+    }, z.core.$strip>>;
+    "events.subscribe": import("./contract.ts").MethodSpec<z.ZodObject<{
+        topics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        topics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    "events.unsubscribe": import("./contract.ts").MethodSpec<z.ZodObject<{
+        topics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        topics: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+};
+export type HelloResult = z.output<typeof HelloResult>;
+export type StatusResult = z.output<typeof StatusResult>;
+export type ClientInfo = z.output<typeof ClientInfo>;

package/types/framing.d.ts

@@ -0,0 +1,10 @@
+/** NDJSON framing shared by daemon and client. */
+export declare function encodeFrame(message: unknown): Uint8Array;
+/** Accumulates chunks and yields complete lines. Bounded to protect against runaway peers. */
+export declare class LineDecoder {
+    private readonly maxLineBytes;
+    private readonly decoder;
+    private pending;
+    constructor(maxLineBytes?: number);
+    push(chunk: Uint8Array): string[];
+}