@opencode-cockpit/daemon 0.2.0 → 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/methods.js

@@ -4,6 +4,9 @@ import { waitFor } from "./wait.js";
 import { PRESETS, presetByName, presetForCommand } from "./watch/presets.js";
 import { compileRule, Watcher } from "./watch/watcher.js";
 
+/** Preset name for a watcher with no patterns: it only reports the process dying. */
+const EXIT_ONLY = "exit";
+
 /**
  * The `shell.*` methods, kept apart from the module's lifecycle and bookkeeping so each file has
  * one job: this one maps protocol calls onto the module, `module.ts` owns the shells.
@@ -71,18 +74,28 @@ export function shellMethods(module) {
       id,
       signal,
       graceMs
+    }, {
+      peer
     }) => {
       const shell = module.require(id);
-      await shell.stop(signal, graceMs);
+      await shell.stop(signal, graceMs, {
+        reason: "request",
+        by: peer.name
+      });
       await shell.exited;
       return shell.info();
     },
     restart: async ({
       id
+    }, {
+      peer
     }) => {
       const shell = module.require(id);
       if (shell.running) {
-        await shell.stop("SIGTERM", 3000);
+        await shell.stop("SIGTERM", 3000, {
+          reason: "request",
+          by: peer.name
+        });
         await shell.exited;
       }
       module.spawn(shell);
@@ -90,10 +103,15 @@ export function shellMethods(module) {
     },
     remove: async ({
       id
+    }, {
+      peer
     }) => {
       const shell = module.require(id);
       if (shell.running) {
-        await shell.stop("SIGTERM", 3000);
+        await shell.stop("SIGTERM", 3000, {
+          reason: "request",
+          by: peer.name
+        });
         await shell.exited;
       }
       module.forget(shell);
@@ -140,14 +158,14 @@ export function shellMethods(module) {
     }) => {
       const shell = module.require(id);
       const command = [shell.spec.command, ...shell.spec.args].join(" ");
-      const chosen = rule ? undefined : preset && preset !== "auto" ? presetByName(preset) ?? invalidParams(`unknown preset "${preset}"; call shell.presets for the list`) : presetForCommand(command);
+      const named = preset && preset !== "auto" && preset !== EXIT_ONLY;
+      const chosen = rule ? undefined : named ? presetByName(preset) ?? invalidParams(`no watch preset named "${preset}". Call shell.presets for the list, or pass your own rule (done/fail/ok patterns).`) : preset === EXIT_ONLY ? undefined : presetForCommand(command);
       if (chosen instanceof Error) throw chosen;
-      const watchRule = rule ?? chosen?.rule;
-      if (!watchRule) {
-        throw invalidParams(`no watch preset matches "${command.slice(0, 80)}"; pass a rule (done/fail/ok patterns) or a preset name`);
-      }
+      // No pattern fits a command like `sleep 300`, and that is still worth watching: an empty rule
+      // reports nothing until the process dies, which is exactly crash detection.
+      const watchRule = rule ?? chosen?.rule ?? {};
       try {
-        shell.watcher = new Watcher(compileRule(watchRule), chosen?.name);
+        shell.watcher = new Watcher(compileRule(watchRule), chosen?.name ?? (rule ? undefined : EXIT_ONLY));
       } catch (err) {
         throw invalidParams(`invalid watch pattern: ${err instanceof Error ? err.message : String(err)}`);
       }

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,13 +49,61 @@ 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).catch(() => {})));
+    await Promise.all([...this.shells.values()].map(s => s.stop("SIGTERM", 2000, {
+      reason: "shutdown"
+    }).catch(() => {})));
     for (const detach of this.attachments.values()) detach();
     for (const shell of this.shells.values()) shell.dispose();
     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;
@@ -64,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();
@@ -83,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

@@ -64,6 +64,8 @@ export class Shell {
     }
     this.runStartLine = this.log.lastLine + 1;
     this.stoppedBecause = undefined;
+    this.stopReason = undefined;
+    this.stoppedBy = undefined;
     if (this.spec.logFile && !this.logWriter) {
       mkdirSync(dirname(this.spec.logFile), {
         recursive: true
@@ -111,6 +113,7 @@ export class Shell {
     if (this.spec.timeoutMs) {
       this.timeout = setTimeout(() => {
         this.stoppedBecause = `reached its ${Math.round((this.spec.timeoutMs ?? 0) / 1000)}s time limit`;
+        this.stopReason = "timeout";
         void this.stop("SIGTERM", 3000);
       }, this.spec.timeoutMs);
     }
@@ -119,6 +122,7 @@ export class Shell {
       this.idleTimer = setInterval(() => {
         if (!this.running || Date.now() - this.lastOutputAt < idleMs) return;
         this.stoppedBecause = `produced no output for ${Math.round(idleMs / 1000)}s`;
+        this.stopReason = "idle";
         void this.stop("SIGTERM", 3000);
       }, Math.max(500, Math.floor(idleMs / 4)));
     }
@@ -134,11 +138,19 @@ export class Shell {
     if (this.running) this.pty?.resize(cols, rows);
   }
 
-  /** Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. */
-  async stop(signal = "SIGTERM", graceMs = 3000) {
+  /**
+   * Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. `cause` says who
+   * asked, so an exit can be reported as a stop rather than as an unexplained kill.
+   */
+  async stop(signal = "SIGTERM", graceMs = 3000, cause = {
+    reason: "request"
+  }) {
     const pty = this.pty;
     if (!pty || !this.running) return;
     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) {
@@ -174,6 +186,8 @@ export class Shell {
     if (this.exit?.signal) info.signal = this.exit.signal;
     if (this.error) info.error = this.error;
     if (this.summary) info.summary = this.summary;
+    if (this.stopReason) info.stopReason = this.stopReason;
+    if (this.stoppedBy) info.stoppedBy = this.stoppedBy;
     if (this.spec.logFile) info.logFile = this.spec.logFile;
     if (this.watcher) info.watch = this.watcher.state();
     if (this.endedAt) info.endedAt = this.endedAt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/daemon",
-  "version": "0.2.0",
+  "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.0",
+    "@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

@@ -1,4 +1,4 @@
-import type { LogLine, Owner, ScreenResult, ShellInfo, ShellStatus } from "@opencode-cockpit/protocol/shell";
+import type { LogLine, Owner, ScreenResult, ShellInfo, ShellStatus, StopReason } from "@opencode-cockpit/protocol/shell";
 import { LineLog } from "./output/line-log.ts";
 import { RawRing } from "./output/raw-ring.ts";
 import { Screen } from "./output/screen.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;
@@ -59,6 +63,8 @@ export declare class Shell {
     private error;
     /** Why the daemon stopped it, when it was not a user or agent request. */
     private stoppedBecause;
+    private stopReason;
+    private stoppedBy;
     private summary;
     private stopRequested;
     private timeout;
@@ -76,8 +82,15 @@ export declare class Shell {
     start(): void;
     write(data: string): number;
     resize(cols: number, rows: number): void;
-    /** Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. */
-    stop(signal?: NodeJS.Signals, graceMs?: number): Promise<void>;
+    /**
+     * Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. `cause` says who
+     * asked, so an exit can be reported as a stop rather than as an unexplained kill.
+     */
+    stop(signal?: NodeJS.Signals, graceMs?: number, cause?: {
+        reason: StopReason;
+        by?: string;
+        because?: string;
+    }): Promise<void>;
     snapshot(): Promise<ScreenResult>;
     info(): ShellInfo;
     dispose(): void;