@opencode-cockpit/daemon 0.1.4 → 0.1.5

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

@@ -0,0 +1,43 @@
+import type { MethodTable, Module, ModuleContext } from "../../core/module.ts";
+import { type PtyBackend } from "./pty.ts";
+import { type ShellLimits } from "./shell.ts";
+export interface ShellModuleOptions {
+    backend?: PtyBackend;
+    limits?: Partial<ShellLimits>;
+    /** Oldest finished shells are forgotten beyond this many. */
+    maxFinished?: number;
+    /** Base environment for spawned processes (defaults to the daemon's). */
+    baseEnv?: Record<string, string | undefined>;
+    /** Coalesce output events per attached peer for this long. */
+    outputFlushMs?: number;
+    /** Where to record owned process groups so a restarted daemon can reap orphans. */
+    registryFile?: string;
+}
+export declare class ShellModule implements Module<"shell"> {
+    private readonly options;
+    readonly name: "shell";
+    private readonly shells;
+    private readonly attachments;
+    private readonly backend;
+    private readonly limits;
+    private log;
+    private registry;
+    private emit;
+    constructor(options?: ShellModuleOptions);
+    start(ctx: ModuleContext): Promise<void>;
+    stop(): Promise<void>;
+    busy(): boolean;
+    readonly methods: MethodTable<"shell">;
+    private startShell;
+    private findReusable;
+    private spawn;
+    private onExit;
+    private attachStream;
+    private detach;
+    private forget;
+    private pruneFinished;
+    private require;
+    private uniqueId;
+    private environment;
+}
+export declare function compilePattern(pattern: string, ignoreCase: boolean): RegExp;

package/types/modules/shell/output/line-log.d.ts

@@ -0,0 +1,36 @@
+import type { LogLine } from "@opencode-cockpit/protocol/shell";
+export interface ReadQuery {
+    after?: number;
+    tail: number;
+    limit: number;
+    grep?: RegExp;
+}
+export interface ReadPage {
+    lines: LogLine[];
+    firstLine: number;
+    lastLine: number;
+    nextCursor: number;
+    truncated: boolean;
+    hasMore: boolean;
+}
+/**
+ * Committed lines with monotonic numbering (1-based) and a character budget.
+ * Eviction drops the oldest lines and advances `firstLine`; numbers are never reused, so cursors
+ * held by clients stay meaningful after eviction.
+ */
+export declare class LineLog {
+    private readonly maxChars;
+    private lines;
+    private head;
+    private chars;
+    private first;
+    constructor(maxChars?: number);
+    /** Number of the oldest retained line (equals `lastLine + 1` when empty). */
+    get firstLine(): number;
+    /** Number of the newest line, or `firstLine - 1` when empty. */
+    get lastLine(): number;
+    append(text: string): LogLine;
+    get(n: number): string | undefined;
+    read(query: ReadQuery): ReadPage;
+    private evict;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Streaming terminal-output normalizer (ADR 0003).
+ *
+ * Turns a PTY byte stream into committed plain-text lines, applying the parts of terminal
+ * semantics that matter for a single line: carriage return and backspace overwrite, tabs, erase
+ * in line, and horizontal cursor moves. Escape sequences are consumed and dropped. Anything that
+ * moves between lines (cursor up, scroll regions) is out of scope; the screen view handles those.
+ */
+export interface NormalizerOptions {
+    /** Force a commit when a line grows past this many characters. */
+    maxLineLength?: number;
+}
+export declare class OutputNormalizer {
+    private readonly commit;
+    private readonly decoder;
+    private readonly maxLineLength;
+    private state;
+    private csiParams;
+    private cells;
+    private col;
+    constructor(commit: (text: string) => void, options?: NormalizerOptions);
+    /** Text of the line currently being written (not yet terminated by a newline). */
+    get partial(): string;
+    push(chunk: Uint8Array | string): void;
+    /** Commit the partial line, if any. Call when the stream ends. */
+    flush(): void;
+    private step;
+    private ground;
+    private csi;
+    private put;
+    private render;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Bounded store of raw PTY bytes addressed by absolute offset, for replaying output to UIs that
+ * attach after the fact. Evicts whole chunks from the front.
+ */
+export declare class RawRing {
+    private readonly maxBytes;
+    private chunks;
+    private size;
+    private start;
+    constructor(maxBytes?: number);
+    /** 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. */
+    since(offset?: number): {
+        offset: number;
+        bytes: Uint8Array;
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { ScreenResult } from "@opencode-cockpit/protocol/shell";
+/** Full VT emulation of a shell's output: what a human would see right now (ADR 0003). */
+export declare class Screen {
+    private readonly term;
+    constructor(cols: number, rows: number, scrollback?: number);
+    write(chunk: Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    reset(): void;
+    /** Waits until every pending write has been parsed, then renders the viewport. */
+    snapshot(): Promise<ScreenResult>;
+    dispose(): void;
+}

package/types/modules/shell/port-probe.d.ts

@@ -0,0 +1,2 @@
+/** Resolves true once something accepts TCP connections on host:port. */
+export declare function probePort(port: number, host?: string, timeoutMs?: number): Promise<boolean>;

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

@@ -0,0 +1,33 @@
+/**
+ * PTY backend seam. The shell module depends only on these interfaces so the process layer can be
+ * swapped (Windows ConPTY, remote hosts, test fakes) without touching session logic.
+ */
+export interface PtySpawnOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    cols: number;
+    rows: number;
+    onData: (chunk: Uint8Array) => void;
+}
+export interface PtyExit {
+    exitCode: number | null;
+    signal: string | null;
+}
+export interface PtyProcess {
+    readonly pid: number;
+    readonly exited: Promise<PtyExit>;
+    write(data: string | Uint8Array): number;
+    resize(cols: number, rows: number): void;
+    /** Signal the whole process group; falls back to the leader. */
+    signal(signal: NodeJS.Signals): void;
+    /** True while any member of the process group is alive. */
+    groupAlive(): boolean;
+    close(): void;
+}
+export interface PtyBackend {
+    spawn(options: PtySpawnOptions): PtyProcess;
+}
+/** Native PTY via `Bun.spawn({ terminal })` (Bun ≥ 1.3.5). The child leads its own session and group. */
+export declare const bunPtyBackend: PtyBackend;

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

@@ -0,0 +1,17 @@
+import type { Logger } from "../../core/logger.ts";
+/**
+ * On-disk record of process groups the daemon owns. If the daemon dies without stopping its
+ * shells, the next daemon kills whatever is still alive from that list.
+ */
+export declare class ProcessRegistry {
+    private readonly file;
+    private readonly log;
+    private entries;
+    constructor(file: string, log: Logger);
+    /** Kill leftovers from a previous daemon. Returns how many process groups were reaped. */
+    reap(): number;
+    add(id: string, pid: number, command: string): void;
+    remove(id: string): void;
+    private flush;
+}
+export declare function processStartTime(pid: number): string | undefined;

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

@@ -0,0 +1,77 @@
+import type { LogLine, Owner, ScreenResult, ShellInfo, ShellStatus } 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";
+import type { PtyBackend } from "./pty.ts";
+export interface ShellSpec {
+    id: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    title: string;
+    cols: number;
+    rows: number;
+    owner: Owner;
+    timeoutMs?: number;
+}
+export interface ShellLimits {
+    logChars: number;
+    rawBytes: number;
+    scrollback: number;
+}
+export interface ShellListener {
+    data?(offset: number, chunk: Uint8Array): void;
+    line?(line: LogLine): void;
+    /** The in-progress line changed (prompts that never end in a newline). */
+    partial?(text: string): void;
+    exit?(info: ShellInfo): void;
+}
+/**
+ * One shell: a command, its PTY, and the three output views (ADR 0003).
+ * Survives restarts: `run` increments and output views continue, separated by a marker line.
+ */
+export declare class Shell {
+    readonly spec: ShellSpec;
+    private readonly backend;
+    readonly log: LineLog;
+    readonly raw: RawRing;
+    readonly screen: Screen;
+    status: ShellStatus;
+    run: number;
+    /** First log line number belonging to the current run. */
+    runStartLine: number;
+    lastOutputAt: number;
+    private pty;
+    private normalizer;
+    private listeners;
+    private startedAt;
+    private endedAt;
+    private exit;
+    private error;
+    private summary;
+    private stopRequested;
+    private timeout;
+    private exitPromise;
+    constructor(spec: ShellSpec, backend: PtyBackend, limits: ShellLimits);
+    get id(): string;
+    /** The line currently being written (e.g. a prompt awaiting input); empty when none. */
+    get partialLine(): string;
+    get running(): boolean;
+    /** Resolves when the current run has fully exited and been accounted for. */
+    get exited(): Promise<void>;
+    subscribe(listener: ShellListener): () => void;
+    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>;
+    snapshot(): Promise<ScreenResult>;
+    info(): ShellInfo;
+    dispose(): void;
+    /** Last error-looking line of the current run, else its last non-empty line. */
+    private summarize;
+    private createNormalizer;
+    private onData;
+    private onExit;
+}

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

@@ -0,0 +1,12 @@
+import type { LogLine, WaitParams, WaitReason } from "@opencode-cockpit/protocol/shell";
+import type { Shell } from "./shell.ts";
+export interface WaitOutcome {
+    reason: WaitReason;
+    match?: LogLine;
+}
+export declare const PORT_POLL_MS = 250;
+/**
+ * Races every condition in `until` plus the timeout. Exit always ends a wait: once the process is
+ * gone no pattern, port or idle condition can still become true.
+ */
+export declare function waitFor(shell: Shell, params: WaitParams, compile: (p: string, i: boolean) => RegExp): Promise<WaitOutcome>;

package/src/core/daemon.ts

@@ -1,197 +0,0 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
-import {
-  type CockpitPaths,
-  daemonBuildId,
-  ErrorCode,
-  PROTOCOL_VERSION,
-  RpcError,
-} from "@opencode-cockpit/protocol"
-import pkg from "../../package.json" with { type: "json" }
-import { createLogger, type Level, type Logger } from "./logger.ts"
-import type { Module } from "./module.ts"
-import { Router } from "./router.ts"
-import { RpcServer } from "./server.ts"
-
-export interface DaemonOptions {
-  paths: CockpitPaths
-  modules: Module[]
-  /** Shut down after this long with no clients and no busy module. 0 disables. */
-  idleTimeoutMs?: number
-  logLevel?: Level
-  /** Log to the log file (default) or stderr. */
-  logToFile?: boolean
-}
-
-export const DAEMON_VERSION: string = pkg.version
-
-/** Build id of this daemon's own code; computed once, matches what clients compute for the entry. */
-export const DAEMON_BUILD: string = daemonBuildId(
-  Bun.fileURLToPath(new URL("../main.ts", import.meta.url)),
-  DAEMON_VERSION,
-)
-
-export class Daemon {
-  readonly log: Logger
-  private readonly router = new Router()
-  private readonly server: RpcServer
-  private readonly startedAt = Date.now()
-  private idleTimer: ReturnType<typeof setTimeout> | undefined
-  private idleCheck: ReturnType<typeof setInterval> | undefined
-  private stopping: Promise<void> | undefined
-  private resolveStopped!: () => void
-  /** Resolves once the daemon has fully shut down. */
-  readonly stopped = new Promise<void>((resolve) => {
-    this.resolveStopped = resolve
-  })
-
-  constructor(private readonly options: DaemonOptions) {
-    this.log = createLogger(options.logToFile === false ? undefined : options.paths.logFile, options.logLevel)
-    this.server = new RpcServer(
-      this.router,
-      {
-        onConnect: () => this.refreshIdle(),
-        onDisconnect: () => this.refreshIdle(),
-      },
-      this.log.child("rpc"),
-    )
-    this.registerCore()
-    for (const module of options.modules) this.router.addModule(module)
-  }
-
-  async start(): Promise<void> {
-    const { paths } = this.options
-    mkdirSync(paths.home, { recursive: true, mode: 0o700 })
-    chmodSync(paths.home, 0o700)
-    await this.claimSocket(paths.socket)
-
-    for (const module of this.options.modules) {
-      await module.start({
-        log: this.log.child(module.name),
-        emit: (topic, data) => {
-          this.server.broadcast(topic, data)
-          // Module state changes (a shell exiting) can make the daemon idle.
-          this.refreshIdle()
-        },
-      })
-    }
-    this.server.listen(paths.socket)
-    chmodSync(paths.socket, 0o600)
-    writeFileSync(paths.pidFile, String(process.pid), { mode: 0o600 })
-    this.idleCheck = setInterval(() => this.refreshIdle(), 30_000)
-    this.refreshIdle()
-    this.log.info("daemon started", { pid: process.pid, build: DAEMON_BUILD, socket: paths.socket })
-  }
-
-  stop(reason = "requested"): Promise<void> {
-    this.stopping ??= (async () => {
-      this.log.info("daemon stopping", { reason })
-      clearTimeout(this.idleTimer)
-      clearInterval(this.idleCheck)
-      this.server.stop()
-      for (const module of [...this.options.modules].reverse()) {
-        try {
-          await module.stop()
-        } catch (err) {
-          this.log.error("module stop failed", { module: module.name, err: String(err) })
-        }
-      }
-      const { paths } = this.options
-      if (readPid(paths.pidFile) === process.pid) rmSync(paths.pidFile, { force: true })
-      rmSync(paths.socket, { force: true })
-      this.log.info("daemon stopped")
-      this.resolveStopped()
-    })()
-    return this.stopping
-  }
-
-  private busy(): boolean {
-    return this.options.modules.some((m) => m.busy())
-  }
-
-  private refreshIdle(): void {
-    const timeout = this.options.idleTimeoutMs ?? 0
-    if (timeout <= 0 || this.stopping) return
-    const idle = this.server.clientCount === 0 && !this.busy()
-    if (!idle) {
-      clearTimeout(this.idleTimer)
-      this.idleTimer = undefined
-    } else if (!this.idleTimer) {
-      this.idleTimer = setTimeout(() => {
-        if (this.server.clientCount === 0 && !this.busy()) void this.stop("idle")
-        else this.idleTimer = undefined
-      }, timeout)
-    }
-  }
-
-  /** Refuse to start if a live daemon owns the socket; otherwise clear a stale one. */
-  private async claimSocket(socket: string): Promise<void> {
-    if (!existsSync(socket)) return
-    const alive = await new Promise<boolean>((resolve) => {
-      Bun.connect({
-        unix: socket,
-        socket: {
-          open(s) {
-            s.end()
-            resolve(true)
-          },
-          data() {},
-          connectError: () => resolve(false),
-          error: () => resolve(false),
-        },
-      }).catch(() => resolve(false))
-    })
-    if (alive) throw new Error(`another daemon is listening on ${socket}`)
-    rmSync(socket, { force: true })
-  }
-
-  private registerCore(): void {
-    this.router.add("daemon.hello", (raw, { peer }) => {
-      const params = raw as { client: { name: string }; protocol: { major: number } }
-      if (params.protocol.major !== PROTOCOL_VERSION.major) {
-        throw new RpcError(ErrorCode.ProtocolMismatch, "protocol major version mismatch", {
-          daemon: PROTOCOL_VERSION,
-          client: params.protocol,
-          busy: this.busy(),
-        })
-      }
-      peer.greet(params.client.name)
-      return {
-        daemonVersion: DAEMON_VERSION,
-        build: DAEMON_BUILD,
-        protocol: PROTOCOL_VERSION,
-        modules: this.options.modules.map((m) => m.name),
-        pid: process.pid,
-        startedAt: this.startedAt,
-      }
-    })
-    this.router.add("daemon.status", () => ({
-      pid: process.pid,
-      uptimeMs: Date.now() - this.startedAt,
-      clients: this.server.clientCount,
-      modules: this.options.modules.map((m) => ({ name: m.name, busy: m.busy() })),
-    }))
-    this.router.add("daemon.shutdown", (raw) => {
-      const force = (raw as { force?: boolean } | undefined)?.force === true
-      if (this.busy() && !force) return { accepted: false }
-      setTimeout(() => void this.stop(force ? "forced shutdown" : "shutdown"), 10)
-      return { accepted: true }
-    })
-    const topics =
-      (on: boolean) =>
-      (raw: unknown, { peer }: { peer: { topics: Set<string> } }) => {
-        const list = (raw as { topics: string[] }).topics
-        for (const t of list) on ? peer.topics.add(t) : peer.topics.delete(t)
-        return { topics: [...peer.topics] }
-      }
-    this.router.add("events.subscribe", topics(true))
-    this.router.add("events.unsubscribe", topics(false))
-  }
-}
-
-function readPid(file: string): number | undefined {
-  try {
-    return Number.parseInt(readFileSync(file, "utf8"), 10)
-  } catch {
-    return undefined
-  }
-}

package/src/core/errors.ts

@@ -1,6 +0,0 @@
-import { ErrorCode, RpcError } from "@opencode-cockpit/protocol"
-
-export const notFound = (what: string) => new RpcError(ErrorCode.NotFound, `${what} not found`)
-export const invalidState = (message: string) => new RpcError(ErrorCode.InvalidState, message)
-export const invalidParams = (message: string, data?: unknown) =>
-  new RpcError(ErrorCode.InvalidParams, message, data)

package/src/core/logger.ts

@@ -1,44 +0,0 @@
-import { appendFileSync } from "node:fs"
-
-export type Level = "debug" | "info" | "warn" | "error"
-const order: Record<Level, number> = { debug: 10, info: 20, warn: 30, error: 40 }
-
-export interface Logger {
-  debug(msg: string, fields?: Record<string, unknown>): void
-  info(msg: string, fields?: Record<string, unknown>): void
-  warn(msg: string, fields?: Record<string, unknown>): void
-  error(msg: string, fields?: Record<string, unknown>): void
-  child(scope: string): Logger
-}
-
-/** JSON-lines logger. Writes synchronously so the last lines survive a crash. */
-export function createLogger(file: string | undefined, level: Level = "info", scope = "cockpitd"): Logger {
-  const write = (lvl: Level, msg: string, fields?: Record<string, unknown>) => {
-    if (order[lvl] < order[level]) return
-    const line = `${JSON.stringify({ t: new Date().toISOString(), lvl, scope, msg, ...fields })}\n`
-    if (file) {
-      try {
-        appendFileSync(file, line, { mode: 0o600 })
-      } catch {
-        process.stderr.write(line)
-      }
-    } else if (lvl !== "debug") {
-      process.stderr.write(line)
-    }
-  }
-  return {
-    debug: (m, f) => write("debug", m, f),
-    info: (m, f) => write("info", m, f),
-    warn: (m, f) => write("warn", m, f),
-    error: (m, f) => write("error", m, f),
-    child: (s) => createLogger(file, level, `${scope}:${s}`),
-  }
-}
-
-export const silentLogger: Logger = {
-  debug() {},
-  info() {},
-  warn() {},
-  error() {},
-  child: () => silentLogger,
-}

package/src/core/module.ts

@@ -1,45 +0,0 @@
-import type { MethodName, Methods, ParsedParamsOf, ResultOf } from "@opencode-cockpit/protocol"
-import type { Logger } from "./logger.ts"
-
-/** A connected client as seen by modules. */
-export interface Peer {
-  readonly id: number
-  readonly name: string
-  /** 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
-}
-
-export interface CallContext {
-  peer: Peer
-}
-
-export interface ModuleContext {
-  log: Logger
-  /** Broadcast to every peer subscribed to `topic`. */
-  emit(topic: string, data: unknown): void
-}
-
-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. */
-export type MethodTable<NS extends string> = {
-  [M in MethodName as M extends `${NS}.${infer Rest}` ? Rest : never]: Handler<M>
-}
-
-export interface Module<NS extends string = string> {
-  readonly name: NS
-  /** Typed per namespace; erased to a plain record when modules are handled generically. */
-  readonly methods: string extends NS ? object : MethodTable<NS>
-  start(ctx: ModuleContext): Promise<void>
-  stop(): Promise<void>
-  /** While true the daemon will not shut down for idleness. */
-  busy(): boolean
-}

package/src/core/router.ts

@@ -1,40 +0,0 @@
-import { contract, ErrorCode, RpcError } from "@opencode-cockpit/protocol"
-import type { CallContext, Module } from "./module.ts"
-
-type AnyHandler = (params: unknown, call: CallContext) => unknown
-
-/** Validates params against the protocol contract and dispatches to module handlers. */
-export class Router {
-  private readonly handlers = new Map<string, AnyHandler>()
-
-  add(name: string, handler: AnyHandler): void {
-    if (!(name in contract)) throw new Error(`method ${name} is not declared in the protocol contract`)
-    if (this.handlers.has(name)) throw new Error(`method ${name} registered twice`)
-    this.handlers.set(name, handler)
-  }
-
-  addModule(module: Module): void {
-    for (const [short, handler] of Object.entries(module.methods as Record<string, AnyHandler>)) {
-      this.add(`${module.name}.${short}`, handler.bind(module.methods))
-    }
-  }
-
-  has(name: string): boolean {
-    return this.handlers.has(name)
-  }
-
-  async dispatch(name: string, params: unknown, call: CallContext): Promise<unknown> {
-    const handler = this.handlers.get(name)
-    const spec = contract[name as keyof typeof contract]
-    if (!handler || !spec) throw new RpcError(ErrorCode.MethodNotFound, `unknown method ${name}`)
-    const parsed = spec.params.safeParse(params)
-    if (!parsed.success) {
-      throw new RpcError(
-        ErrorCode.InvalidParams,
-        `invalid params for ${name}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
-        { issues: parsed.error.issues.map((i) => ({ path: i.path, message: i.message })) },
-      )
-    }
-    return handler(parsed.data, call)
-  }
-}