@opencode-cockpit/daemon 0.2.1 → 0.2.2

package/README.md

@@ -1,11 +1,132 @@
 # @opencode-cockpit/daemon
 
-`cockpitd`, the long-lived process host. Owns PTY shells (each its own process group), normalizes output into clean logs, emulates the screen, implements wait conditions, reaps orphans after crashes and shuts down when idle. Capabilities are modules with a namespace, a method table and a lifecycle.
+**`cockpitd` — the process host that everything else in Cockpit talks to.**
 
-Part of [opencode-cockpit](https://github.com/Codestz/opencode-cockpit). Install the plugin, not this package, unless you are building your own front end:
+OpenCode runs its interface and its server in separate threads that cannot share memory, and neither
+survives a restart. Anything long-lived — a process, a watcher, a subscription — has nowhere to
+live. This package is that home.
+
+One daemon per machine, shared by every OpenCode window, started on demand and gone when idle.
+
+> Installing the plugin is what you usually want. This package matters if you are building your own
+> front end, writing a capability, or debugging the daemon itself.
+>
+> ```sh
+> opencode plugin opencode-cockpit --global
+> ```
+
+---
+
+## What it does
+
+| | |
+| --- | --- |
+| **Owns processes** | Every shell runs in a real PTY as its own process group, so a stop kills the children too |
+| **Normalizes output** | Carriage returns, progress bars and cursor moves collapse into clean numbered lines |
+| **Emulates a screen** | A headless terminal keeps what a human would see, for the interface |
+| **Answers conditions** | Wait for a port, a pattern, silence or exit — without polling |
+| **Watches health** | Rules turn an endless log into transitions: ok → fail, and back |
+| **Cleans up** | Process groups are recorded, so a daemon that starts after a crash reaps what was left |
+| **Gets out of the way** | Exits after ten idle minutes with no clients and nothing running |
+
+## Running it
+
+Normally the client spawns it for you. To run it by hand:
 
 ```sh
-opencode plugin opencode-cockpit --global
+bun packages/daemon/src/main.ts
+# or, from an installed plugin, on OpenCode's embedded runtime:
+BUN_BE_BUN=1 "$(which opencode)" node_modules/@opencode-cockpit/daemon/dist/main.js
 ```
 
-Requires Bun ≥ 1.3.5 (OpenCode's embedded runtime qualifies). License: MIT.
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `COCKPIT_HOME` | `~/.cache/opencode-cockpit` | Socket, logs, process registry, per-shell log files |
+| `COCKPIT_IDLE_TIMEOUT_MS` | `600000` | Time with no clients and nothing running before it exits; `0` never exits |
+| `COCKPIT_LOG_LEVEL` | `info` | `debug` for verbose logs |
+
+The socket lives at `$COCKPIT_HOME/cockpitd.sock`, mode `0600`, inside a `0700` directory. Logs go to
+`$COCKPIT_HOME/cockpitd.log` as one JSON object per line.
+
+## How a capability plugs in
+
+A capability is a **module**: a namespace, a typed method table, and a lifecycle. The daemon owns
+connections, framing, validation, subscriptions and shutdown; the module owns its own state.
+
+```ts
+import type { Module, ModuleContext, MethodTable } from "@opencode-cockpit/daemon"
+
+export class ClockModule implements Module<"clock"> {
+  readonly name = "clock" as const
+  private timer: ReturnType<typeof setInterval> | undefined
+  private emit: ModuleContext["emit"] = () => {}
+
+  readonly methods: MethodTable<"clock"> = {
+    // Params are already parsed and typed from the protocol contract.
+    now: () => ({ iso: new Date().toISOString() }),
+  }
+
+  async start(ctx: ModuleContext) {
+    this.emit = ctx.emit
+    this.timer = setInterval(() => this.emit("clock.tick", { at: Date.now() }), 1000)
+    ctx.log.info("clock started")
+  }
+
+  async stop() {
+    clearInterval(this.timer)
+  }
+
+  /** While this is true the daemon refuses to shut down for idleness. */
+  busy() {
+    return false
+  }
+}
+```
+
+Methods are named `<namespace>.<method>` and their shapes come from
+[`@opencode-cockpit/protocol`](../protocol) — add the contract there first and the handler is typed
+for you. Events are broadcast to peers that subscribed to the topic.
+
+## Transport
+
+JSON-RPC 2.0 over NDJSON on a unix socket. One line per message, requests and responses correlated
+by id, plus server-initiated notifications for events.
+
+Each build has an id derived from the daemon's own code. When a client connects carrying a **newer**
+build than the running daemon, and nothing is busy, the daemon shuts down so the newer one can take
+over. If work is in flight it stays, and the client is told — nothing is killed behind your back.
+Only forwards: an older client never replaces a newer daemon.
+
+## Public API
+
+| Export | Use |
+| --- | --- |
+| `Daemon`, `DaemonOptions` | Construct and run a daemon with your own module set |
+| `createModules`, `ModuleOptions` | The modules that ship with Cockpit |
+| `Module`, `ModuleContext`, `MethodTable`, `CallContext`, `Peer` | Types for writing one |
+| `ShellModule`, `ShellModuleOptions` | The shell capability, if you want it on its own |
+| `PtyBackend`, `PtyProcess`, `PtySpawnOptions` | Swap the PTY implementation, e.g. in tests |
+
+```ts
+import { Daemon, createModules } from "@opencode-cockpit/daemon"
+import { resolvePaths } from "@opencode-cockpit/protocol"
+
+const daemon = new Daemon({
+  paths: resolvePaths(),
+  modules: createModules({ shell: { maxFinished: 50 } }),
+  idleTimeoutMs: 600_000,
+})
+await daemon.start()
+```
+
+## Requirements
+
+Bun ≥ 1.3.5 — OpenCode's embedded runtime qualifies, so no separate install. macOS and Linux.
+
+## More
+
+[Architecture](https://codestz.github.io/opencode-cockpit/platform/architecture/) ·
+[Repository](https://github.com/Codestz/opencode-cockpit) ·
+[Contributing](https://github.com/Codestz/opencode-cockpit/blob/main/CONTRIBUTING.md)
+
+MIT

package/dist/core/daemon.js

@@ -21,7 +21,12 @@ export class Daemon {
     this.log = createLogger(options.logToFile === false ? undefined : options.paths.logFile, options.logLevel);
     this.server = new RpcServer(this.router, {
       onConnect: () => this.refreshIdle(),
-      onDisconnect: () => this.refreshIdle()
+      onDisconnect: (_count, peer) => {
+        // A window may keep working through its other half, so modules are told who is left.
+        const remaining = this.server.instances;
+        for (const module of this.options.modules) module.peerClosed?.(peer, remaining);
+        this.refreshIdle();
+      }
     }, this.log.child("rpc"));
     this.registerCore();
     for (const module of options.modules) this.router.addModule(module);
@@ -43,7 +48,8 @@ export class Daemon {
           this.server.broadcast(topic, data);
           // Module state changes (a shell exiting) can make the daemon idle.
           this.refreshIdle();
-        }
+        },
+        instances: () => this.server.instances
       });
     }
     this.server.listen(paths.socket);
@@ -142,7 +148,7 @@ export class Daemon {
           busy: this.busy()
         });
       }
-      peer.greet(params.client.name);
+      peer.greet(params.client.name, params.client.instance);
       return {
         daemonVersion: DAEMON_VERSION,
         build: DAEMON_BUILD,

package/dist/core/server.js

@@ -2,6 +2,8 @@ import { ErrorCode, EVENT_METHOD, encodeFrame, LineDecoder, RpcError } from "@op
 const MAX_QUEUED_BYTES = 32 * 1024 * 1024;
 class PeerImpl {
   name = "unknown";
+  /** The OpenCode window this connection belongs to; both halves of a plugin share one. */
+
   greeted = false;
   topics = new Set();
   closers = [];
@@ -13,8 +15,9 @@ class PeerImpl {
     this.socket = socket;
     this.log = log;
   }
-  greet(name) {
+  greet(name, instance) {
     this.name = name;
+    this.instance = instance;
     this.greeted = true;
   }
   onClose(fn) {
@@ -95,6 +98,13 @@ export class RpcServer {
   get clientCount() {
     return this.peers.size;
   }
+
+  /** The OpenCode windows currently connected, by instance id. */
+  get instances() {
+    const ids = new Set();
+    for (const peer of this.peers) if (peer.instance) ids.add(peer.instance);
+    return ids;
+  }
   listen(path) {
     const decoders = new WeakMap();
     this.listener = Bun.listen({
@@ -150,7 +160,7 @@ export class RpcServer {
   drop(peer) {
     if (!this.peers.delete(peer)) return;
     peer.close();
-    this.hooks.onDisconnect(this.peers.size);
+    this.hooks.onDisconnect(this.peers.size, peer);
   }
   async handleLine(peer, line) {
     let message;

package/dist/modules/shell/module.js

@@ -19,6 +19,9 @@ export class ShellModule {
   attachments = new Map(); // `${peer.id}:${shellId}` → detach
 
   log = silentLogger;
+  /** When each absent window was last seen, for the orphan sweep. */
+  goneSince = new Map();
+  connected = () => new Set();
   idleTimers = new Map();
   /** @internal */
   emit = () => {};
@@ -33,6 +36,10 @@ export class ShellModule {
   async start(ctx) {
     this.log = ctx.log;
     this.emit = ctx.emit;
+    this.connected = ctx.instances;
+    // A shell whose window never comes back should not outlive the day. Checked rarely: the
+    // decision is a timestamp comparison, and only shells that asked for it are considered.
+    this.sweepTimer = setInterval(() => this.sweepOrphans(), this.options.orphanSweepMs ?? 60_000);
     if (this.options.registryFile) {
       this.registry = new ProcessRegistry(this.options.registryFile, ctx.log);
       const reaped = this.registry.reap();
@@ -42,6 +49,7 @@ export class ShellModule {
     }
   }
   async stop() {
+    clearInterval(this.sweepTimer);
     for (const id of [...this.idleTimers.keys()]) this.clearIdle(id);
     await Promise.all([...this.shells.values()].map(s => s.stop("SIGTERM", 2000, {
       reason: "shutdown"
@@ -51,6 +59,51 @@ export class ShellModule {
     this.attachments.clear();
     this.shells.clear();
   }
+
+  /**
+   * An OpenCode window disconnected. Both halves of a plugin share an instance id, so this only
+   * counts as "the window is gone" once neither half is connected any more.
+   */
+  peerClosed(peer, remaining) {
+    const instance = peer.instance;
+    if (!instance || remaining.has(instance)) return;
+    this.goneSince.set(instance, Date.now());
+    for (const shell of this.shells.values()) {
+      if (!shell.spec.stopOnExit || shell.spec.owner.instance !== instance || !shell.running) continue;
+      this.log.info("stopping shell with its window", {
+        id: shell.id,
+        instance
+      });
+      void shell.stop("SIGTERM", 2000, {
+        reason: "shutdown",
+        because: "the OpenCode window that started it closed"
+      }).catch(() => {});
+    }
+  }
+
+  /** Shells whose window has been gone longer than they allow. */
+  sweepOrphans() {
+    const live = this.connected();
+    for (const instance of [...this.goneSince.keys()]) if (live.has(instance)) this.goneSince.delete(instance);
+    const now = Date.now();
+    for (const shell of this.shells.values()) {
+      const limit = shell.spec.orphanAfterMs;
+      const instance = shell.spec.owner.instance;
+      if (!limit || !instance || !shell.running || live.has(instance)) continue;
+      const gone = this.goneSince.get(instance) ?? now;
+      this.goneSince.set(instance, gone);
+      if (now - gone < limit) continue;
+      this.log.info("stopping orphaned shell", {
+        id: shell.id,
+        instance,
+        afterMs: now - gone
+      });
+      void shell.stop("SIGTERM", 2000, {
+        reason: "shutdown",
+        because: `nothing watched it for ${Math.round((now - gone) / 60_000)} minutes`
+      }).catch(() => {});
+    }
+  }
   busy() {
     for (const shell of this.shells.values()) if (shell.running) return true;
     return false;
@@ -66,7 +119,9 @@ export class ShellModule {
           env: this.environment(params.env),
           title: params.title ?? previous.spec.title,
           timeoutMs: params.timeoutMs,
-          owner: params.owner
+          owner: params.owner,
+          stopOnExit: params.stopOnExit,
+          orphanAfterMs: params.orphanAfterMs
         });
         this.spawn(previous);
         return previous.info();
@@ -85,7 +140,9 @@ export class ShellModule {
       owner: params.owner,
       timeoutMs: params.timeoutMs,
       idleTimeoutMs: params.idleTimeoutMs,
-      logFile: params.logFile ? join(this.options.logDir ?? "/tmp", `${id}.log`) : undefined
+      logFile: params.logFile ? join(this.options.logDir ?? "/tmp", `${id}.log`) : undefined,
+      stopOnExit: params.stopOnExit,
+      orphanAfterMs: params.orphanAfterMs
     }, this.backend, this.limits);
     this.shells.set(shell.id, shell);
     shell.subscribe({

package/dist/modules/shell/output/raw-ring.js

@@ -26,9 +26,12 @@ export class RawRing {
     return offset;
   }
 
-  /** Bytes from `offset` (clamped to what is retained) to the end. */
+  /**
+   * Bytes from `offset` to the end, clamped to what is retained. An offset past the end asks for
+   * nothing but future output — a UI that only wants what comes next — and must not be an error.
+   */
   since(offset = 0) {
-    const from = Math.max(offset, this.start);
+    const from = Math.min(Math.max(offset, this.start), this.end);
     const out = new Uint8Array(this.end - from);
     let cursor = this.start;
     let written = 0;

package/dist/modules/shell/shell.js

@@ -150,6 +150,7 @@ export class Shell {
     this.stopRequested = true;
     this.stopReason ??= cause.reason;
     this.stoppedBy ??= cause.by;
+    this.stoppedBecause ??= cause.because;
     pty.signal(signal);
     const exited = await Promise.race([this.exitPromise.then(() => true), Bun.sleep(graceMs).then(() => false)]);
     if (!exited) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/daemon",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "cockpitd: the process host behind opencode-cockpit (PTY shells, clean logs, wait conditions)",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/protocol": "0.2.1",
+    "@opencode-cockpit/protocol": "0.2.2",
     "@xterm/headless": "6.0.0"
   },
   "engines": {

package/types/core/module.d.ts

@@ -4,13 +4,15 @@ import type { Logger } from "./logger.ts";
 export interface Peer {
     readonly id: number;
     readonly name: string;
+    /** The OpenCode window this connection belongs to, when the client said. */
+    readonly instance: string | undefined;
     /** Send an event to this peer only, regardless of its subscriptions. */
     send(topic: string, data: unknown): void;
     /** Run when the peer disconnects. */
     onClose(fn: () => void): void;
     /** Topic patterns: exact (`shell.exited`), namespace (`shell.*`) or everything (`*`). */
     readonly topics: Set<string>;
-    greet(name: string): void;
+    greet(name: string, instance?: string): void;
 }
 export interface CallContext {
     peer: Peer;
@@ -19,6 +21,8 @@ export interface ModuleContext {
     log: Logger;
     /** Broadcast to every peer subscribed to `topic`. */
     emit(topic: string, data: unknown): void;
+    /** OpenCode windows currently connected, by instance id. */
+    instances(): Set<string>;
 }
 type Handler<M extends MethodName> = (params: ParsedParamsOf<Methods, M>, call: CallContext) => Promise<ResultOf<Methods, M>> | ResultOf<Methods, M>;
 /** Handlers for the methods under one namespace, typed from the protocol contract. */
@@ -31,6 +35,8 @@ export interface Module<NS extends string = string> {
     readonly methods: string extends NS ? object : MethodTable<NS>;
     start(ctx: ModuleContext): Promise<void>;
     stop(): Promise<void>;
+    /** A connection went away. The window may still be here through its other half. */
+    peerClosed?(peer: Peer, remaining: Set<string>): void;
     /** While true the daemon will not shut down for idleness. */
     busy(): boolean;
 }

package/types/core/server.d.ts

@@ -10,6 +10,8 @@ declare class PeerImpl implements Peer {
     private readonly socket;
     private readonly log;
     name: string;
+    /** The OpenCode window this connection belongs to; both halves of a plugin share one. */
+    instance: string | undefined;
     greeted: boolean;
     readonly topics: Set<string>;
     private readonly closers;
@@ -17,7 +19,7 @@ declare class PeerImpl implements Peer {
     private queued;
     closed: boolean;
     constructor(id: number, socket: Socket<ConnState>, log: Logger);
-    greet(name: string): void;
+    greet(name: string, instance?: string): void;
     onClose(fn: () => void): void;
     send(topic: string, data: unknown): void;
     subscribed(topic: string): boolean;
@@ -28,7 +30,7 @@ declare class PeerImpl implements Peer {
 }
 export interface RpcServerHooks {
     onConnect(count: number): void;
-    onDisconnect(count: number): void;
+    onDisconnect(count: number, peer: Peer): void;
 }
 export declare class RpcServer {
     private readonly router;
@@ -39,6 +41,8 @@ export declare class RpcServer {
     private nextId;
     constructor(router: Router, hooks: RpcServerHooks, log: Logger);
     get clientCount(): number;
+    /** The OpenCode windows currently connected, by instance id. */
+    get instances(): Set<string>;
     listen(path: string): void;
     broadcast(topic: string, data: unknown): void;
     stop(): void;

package/types/modules/shell/module.d.ts

@@ -15,6 +15,8 @@ export interface ShellModuleOptions {
     registryFile?: string;
     /** Directory for per-shell log files, when a caller asks for one. */
     logDir?: string;
+    /** How often to look for shells whose window is gone for good. */
+    orphanSweepMs?: number;
 }
 export declare class ShellModule implements Module<"shell"> {
     private readonly options;
@@ -26,6 +28,10 @@ export declare class ShellModule implements Module<"shell"> {
     private readonly backend;
     private readonly limits;
     private log;
+    /** When each absent window was last seen, for the orphan sweep. */
+    private readonly goneSince;
+    private sweepTimer;
+    private connected;
     private registry;
     private readonly idleTimers;
     /** @internal */
@@ -33,6 +39,15 @@ export declare class ShellModule implements Module<"shell"> {
     constructor(options?: ShellModuleOptions);
     start(ctx: ModuleContext): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * An OpenCode window disconnected. Both halves of a plugin share an instance id, so this only
+     * counts as "the window is gone" once neither half is connected any more.
+     */
+    peerClosed(peer: {
+        instance?: string;
+    }, remaining: Set<string>): void;
+    /** Shells whose window has been gone longer than they allow. */
+    private sweepOrphans;
     busy(): boolean;
     readonly methods: MethodTable<"shell">;
     /** @internal used by methods.ts */

package/types/modules/shell/output/raw-ring.d.ts

@@ -11,7 +11,10 @@ export declare class RawRing {
     /** Absolute offset one past the last byte ever written. */
     get end(): number;
     append(chunk: Uint8Array): number;
-    /** Bytes from `offset` (clamped to what is retained) to the end. */
+    /**
+     * Bytes from `offset` to the end, clamped to what is retained. An offset past the end asks for
+     * nothing but future output — a UI that only wants what comes next — and must not be an error.
+     */
     since(offset?: number): {
         offset: number;
         bytes: Uint8Array;

package/types/modules/shell/shell.d.ts

@@ -18,6 +18,10 @@ export interface ShellSpec {
     idleTimeoutMs?: number;
     /** Absolute path the clean log is appended to, when logging was requested. */
     logFile?: string;
+    /** Stop when the OpenCode window that started it goes away. */
+    stopOnExit?: boolean;
+    /** Stop after this long with that window gone. */
+    orphanAfterMs?: number;
 }
 export interface ShellLimits {
     logChars: number;
@@ -85,6 +89,7 @@ export declare class Shell {
     stop(signal?: NodeJS.Signals, graceMs?: number, cause?: {
         reason: StopReason;
         by?: string;
+        because?: string;
     }): Promise<void>;
     snapshot(): Promise<ScreenResult>;
     info(): ShellInfo;