@opencode-cockpit/protocol 0.2.1 → 0.3.0

package/README.md

@@ -1,11 +1,88 @@
 # @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.
+**The contract between `cockpitd` and everything that talks to it.** Zod schemas for every method
+and event, the types generated from them, the socket paths, the framing, and the build identity used
+to decide which daemon should be running.
 
-Part of [opencode-cockpit](https://github.com/Codestz/opencode-cockpit). Install the plugin, not this package, unless you are building your own front end:
+Client and daemon import the *same* file, so a change to a shape is a compile error on both sides
+rather than a runtime surprise in one of them.
 
-```sh
-opencode plugin opencode-cockpit --global
+> Installing the plugin is what you usually want. This package matters if you are writing a
+> capability, or a client of your own.
+
+---
+
+## What is in it
+
+| Export | What it gives you |
+| --- | --- |
+| `contract`, `Methods`, `MethodName` | Every method, its params and its result |
+| `events`, `Events`, `Topic` | Every event topic and its payload |
+| `PROTOCOL_VERSION` | `{ major, minor }` — the wire version |
+| `shell` | The shell capability's schemas: `ShellInfo`, `StartParams`, `WatchRule`, `ReadResult`, … |
+| `resolvePaths`, `CockpitPaths` | Where the socket, logs and registry live |
+| `daemonBuildId` | Content identity of a daemon build |
+| `encodeFrame`, `decodeFrames` | NDJSON framing |
+| `RpcError`, `ErrorCode` | The error shape both sides speak |
+
+## The shape of a call
+
+```ts
+import { contract, shell } from "@opencode-cockpit/protocol"
+
+// Every method is params → result, both zod schemas:
+contract["shell.start"].params   // StartParams
+contract["shell.start"].result   // ShellInfo
+
+// Schemas are usable on their own, so a UI can parse what it receives:
+const info = shell.ShellInfo.parse(payload)
+```
+
+Requests and responses are JSON-RPC 2.0, one object per line (NDJSON) over a unix socket. Events are
+notifications, delivered only to peers subscribed to the topic.
+
+## Versioning
+
+`PROTOCOL_VERSION` is `major.minor`:
+
+- **Minor** goes up when something is added — a new method, a new optional field. Old clients keep
+  working, so a daemon may serve a client that predates the addition.
+- **Major** goes up when something existing changes meaning or disappears. A mismatch is refused at
+  the handshake with a message naming both versions, instead of failing halfway through a call.
+
+The handshake carries the version, so both ends know where they stand before any work starts.
+
+## Build identity
+
+```ts
+import { daemonBuildId } from "@opencode-cockpit/protocol"
+
+daemonBuildId(entry, version) // → "0.2.1+4eac93214393"
 ```
 
-Requires Bun ≥ 1.3.5 (OpenCode's embedded runtime qualifies). License: MIT.
+A hash of the daemon's own files plus its version. Equal versions with different hashes are how a
+development build is recognised as newer than the daemon already running — which is what lets a
+plugin under active work replace an idle daemon without a version bump.
+
+## Adding a method
+
+1. Add the schema to the capability's contract file (`src/shell/contract.ts`, or a new namespace).
+2. Bump `PROTOCOL_VERSION.minor`.
+3. Implement the handler in the daemon module — it is typed from the contract, so a missing or
+   mis-shaped handler will not compile.
+4. Call it from the client. No client-side wiring: `call` picks up the new name.
+
+Schemas are split by concern rather than piled into one file — for shell that is `common`, `info`,
+`params`, `watch` and `contract` — so a capability's surface stays readable as it grows.
+
+## Requirements
+
+Bun ≥ 1.3.5 or Node ≥ 20 for the schemas alone. Runs anywhere zod runs.
+
+## More
+
+[Architecture](https://codestz.github.io/opencode-cockpit/platform/architecture/) ·
+[Daemon](../daemon) · [Client](../client) ·
+[Repository](https://github.com/Codestz/opencode-cockpit)
+
+MIT

package/dist/daemon.js

@@ -3,7 +3,12 @@ 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()
+  pid: z.number().int().optional(),
+  /**
+   * Opaque id of the OpenCode window this client belongs to. Both halves of a plugin share one, so
+   * the daemon can tell "this window went away" from "one of its two connections dropped".
+   */
+  instance: z.string().min(1).optional()
 });
 export const Version = z.object({
   major: z.number().int(),

package/dist/rpc.js

@@ -3,7 +3,7 @@
 /** Bump MAJOR on breaking changes to methods, events or framing. */
 export const PROTOCOL_VERSION = {
   major: 1,
-  minor: 3
+  minor: 4
 };
 export const ErrorCode = {
   ParseError: -32700,

package/dist/shell/params.js

@@ -20,6 +20,13 @@ export const StartParams = z.object({
   idleTimeoutMs: z.number().int().positive().optional(),
   /** Also write the clean log to a file, for debugging after the buffer has evicted old lines. */
   logFile: z.boolean().default(false),
+  /** Stop this shell when the OpenCode window that started it goes away. */
+  stopOnExit: z.boolean().optional(),
+  /**
+   * Stop it after this long with nothing from its window connected. The answer to a shell that
+   * would otherwise run for a week because everyone who knew about it has gone.
+   */
+  orphanAfterMs: 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/protocol",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Wire protocol, method and event contracts for cockpitd (opencode-cockpit)",
   "type": "module",
   "license": "MIT",

package/types/daemon.d.ts

@@ -3,6 +3,7 @@ export declare const ClientInfo: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
     pid: z.ZodOptional<z.ZodNumber>;
+    instance: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const Version: z.ZodObject<{
     major: z.ZodNumber;
@@ -34,6 +35,7 @@ export declare const daemonContract: {
             name: z.ZodString;
             version: z.ZodString;
             pid: z.ZodOptional<z.ZodNumber>;
+            instance: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
         protocol: z.ZodObject<{
             major: z.ZodNumber;

package/types/index.d.ts

@@ -12,6 +12,7 @@ export declare const contract: {
             name: import("zod").ZodString;
             version: import("zod").ZodString;
             pid: import("zod").ZodOptional<import("zod").ZodNumber>;
+            instance: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strip>;
         protocol: import("zod").ZodObject<{
             major: import("zod").ZodNumber;
@@ -68,6 +69,8 @@ export declare const contract: {
         timeoutMs: import("zod").ZodOptional<import("zod").ZodNumber>;
         idleTimeoutMs: import("zod").ZodOptional<import("zod").ZodNumber>;
         logFile: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        stopOnExit: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        orphanAfterMs: import("zod").ZodOptional<import("zod").ZodNumber>;
         reuse: import("zod").ZodDefault<import("zod").ZodBoolean>;
     }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
         id: import("zod").ZodString;

package/types/rpc.d.ts

@@ -2,7 +2,7 @@
 /** Bump MAJOR on breaking changes to methods, events or framing. */
 export declare const PROTOCOL_VERSION: {
     readonly major: 1;
-    readonly minor: 3;
+    readonly minor: 4;
 };
 export type RequestId = number | string;
 export interface RpcRequest {

package/types/shell/contract.d.ts

@@ -16,6 +16,8 @@ export declare const shellContract: {
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         idleTimeoutMs: z.ZodOptional<z.ZodNumber>;
         logFile: z.ZodDefault<z.ZodBoolean>;
+        stopOnExit: z.ZodOptional<z.ZodBoolean>;
+        orphanAfterMs: z.ZodOptional<z.ZodNumber>;
         reuse: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;

package/types/shell/params.d.ts

@@ -15,6 +15,8 @@ export declare const StartParams: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     idleTimeoutMs: z.ZodOptional<z.ZodNumber>;
     logFile: z.ZodDefault<z.ZodBoolean>;
+    stopOnExit: z.ZodOptional<z.ZodBoolean>;
+    orphanAfterMs: z.ZodOptional<z.ZodNumber>;
     reuse: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const ClearParams: z.ZodDefault<z.ZodObject<{