@opencode-cockpit/shell 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codestz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @opencode-cockpit/shell
+
+[![npm](https://img.shields.io/npm/v/@opencode-cockpit/shell)](https://www.npmjs.com/package/@opencode-cockpit/shell)
+
+Background terminals for [OpenCode](https://opencode.ai) that the agent starts, waits on and
+drives, and that you watch and control without leaving the chat. Part of
+[opencode-cockpit](https://github.com/Codestz/opencode-cockpit).
+
+- **The agent stops sleeping and polling.** It starts a dev server and blocks until the port
+  opens, runs a slow test suite and gets a message when it finishes, drives REPLs and prompts.
+- **Logs that don't waste tokens.** Colours are stripped, progress-bar redraws collapse to their
+  final frame, repeated lines fold, and reads continue from a cursor.
+- **You see everything.** A docked panel under the chat, a sidebar section, and a keyboard-first
+  console with a real typing mode.
+- **Shells outlive OpenCode.** They run in a small daemon, `cockpitd`, shared by every OpenCode
+  window and upgraded automatically when the plugin updates.
+
+## Install
+
+```sh
+opencode plugin @opencode-cockpit/shell --global
+```
+
+Restart OpenCode. Requires OpenCode 1.18 or newer on macOS or Linux.
+
+Shell is also included in [`opencode-cockpit`](https://www.npmjs.com/package/opencode-cockpit),
+which installs every cockpit feature. Install one or the other: if both are configured, the first
+one loaded is used and OpenCode shows a warning.
+
+## For the agent
+
+| Tool | What it does |
+|---|---|
+| `shell_start` | Run a command in a background PTY. Optional `waitFor` blocks until a port opens, a pattern prints, output goes idle, or the process exits. Rerunning the same command in the same session reuses the shell. |
+| `shell_wait` | Block on a condition instead of sleeping. |
+| `shell_read` | Clean log from a cursor, with `grep`; or `view: "screen"` for full-screen programs. |
+| `shell_send` | Type text or keys (`ctrl+c`, `up`, `enter`) and get the reply. |
+| `shell_list` · `shell_stop` · `shell_restart` | Manage shells. |
+
+The agent is messaged when a shell it started exits on its own.
+
+Things to ask:
+
+- *"Start the dev server in a background shell and wait until it's ready."*
+- *"Run the test suite in the background, keep working on the parser, tell me if it fails."*
+- *"Open a node REPL in a shell and check what `new URL('..', import.meta.url)` returns."*
+
+## For you
+
+| Key / command | Does |
+|---|---|
+| `ctrl+x o` · `/shells` | Toggle the shells panel under the chat |
+| `ctrl+x i` · `/shell` | Open the shell console |
+| `/shell-new` | Start a shell yourself |
+| `/shells-clear` | Remove finished shells |
+| `/shells-restart-daemon` | Restart `cockpitd` (asks first when shells are running) |
+
+Status reads the same everywhere: `RUN` (with a spinner), `FAIL`, `STOP`, `DONE`. Running shells
+and recent failures stay visible; everything else folds into `▸ N more`.
+
+**Console keys.** Running shell: `i` type (every key goes to the program, `ctrl+]` to stop typing),
+`c` ctrl+c, `r` restart, `x` stop. Finished shell: `r` run again, `d` remove. Always: `tab`
+screen or log, `?` details, `[` `]` switch, `D` clear finished, `a` show all, `esc` close.
+
+## Configuration
+
+Options go on the plugin entry in `tui.json`:
+
+```json
+{
+  "plugin": [
+    ["@opencode-cockpit/shell", {
+      "dockHeight": 16,
+      "dockOpen": true,
+      "historyMinutes": 60,
+      "keybinds": { "cockpit.shells.dock": "<leader>j", "cockpit.shells.console": "<leader>k" }
+    }]
+  ]
+}
+```
+
+Using `opencode-cockpit` instead? Put the same options under `"shell"`:
+`["opencode-cockpit", { "shell": { "dockHeight": 16 } }]`.
+
+| Environment variable | Default | Purpose |
+|---|---|---|
+| `COCKPIT_HOME` | `~/.cache/opencode-cockpit` | Socket, logs, process registry |
+| `COCKPIT_IDLE_TIMEOUT_MS` | `600000` | Daemon exits after this long with no clients and no running shells |
+| `COCKPIT_LOG_LEVEL` | `info` | `debug` for verbose daemon logs |
+
+## Troubleshooting
+
+| Problem | Look at |
+|---|---|
+| Tools fail with "did not start" | `~/.cache/opencode-cockpit/cockpitd.log` |
+| Plugin not loading | newest file in `~/.local/share/opencode/log/` |
+| Warning: "Shell is configured twice" | Remove either `opencode-cockpit` or `@opencode-cockpit/shell` from `opencode.json` and `tui.json` |
+| Panel says the daemon runs older code | `/shells-restart-daemon` once your shells are done |
+
+## How it works
+
+OpenCode runs its interface and its server in separate threads, so the plugin's two halves can't
+share memory. Both talk to `cockpitd`, which owns every process. Each shell's output feeds a line
+normalizer (the agent's log), a headless terminal emulator (the screen you see) and a raw ring
+buffer (replay for late viewers). See
+[CONTRIBUTING.md](https://github.com/Codestz/opencode-cockpit/blob/main/CONTRIBUTING.md).
+
+License: MIT

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@opencode-cockpit/shell",
+  "version": "0.1.2",
+  "description": "Background shells for OpenCode: the agent starts, waits on and drives PTYs; you watch them in a docked TUI panel",
+  "type": "module",
+  "license": "MIT",
+  "author": "Codestz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Codestz/opencode-cockpit.git",
+    "directory": "packages/shell"
+  },
+  "homepage": "https://github.com/Codestz/opencode-cockpit#readme",
+  "bugs": {
+    "url": "https://github.com/Codestz/opencode-cockpit/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "pty",
+    "shell",
+    "background",
+    "tui",
+    "terminal"
+  ],
+  "exports": {
+    "./server": "./src/server.ts",
+    "./tui": "./src/tui/index.tsx",
+    "./connect": "./src/connect.ts"
+  },
+  "engines": {
+    "opencode": ">=1.18.0",
+    "bun": ">=1.3.5"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode-cockpit/client": "0.1.2",
+    "@opencode-cockpit/daemon": "0.1.2",
+    "@opencode-cockpit/protocol": "0.1.2",
+    "@opencode-ai/plugin": "1.18.31"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.4.5",
+    "@opentui/keymap": ">=0.4.5",
+    "@opentui/solid": ">=0.4.5",
+    "solid-js": ">=1.9"
+  },
+  "devDependencies": {
+    "@opentui/core": "0.4.5",
+    "@opentui/keymap": "0.4.5",
+    "@opentui/solid": "0.4.5",
+    "solid-js": "1.9.15",
+    "zod": "4.1.8"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/keymap": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  }
+}

package/src/connect.ts

@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url"
+import { CockpitClient } from "@opencode-cockpit/client"
+import daemonPkg from "@opencode-cockpit/daemon/package.json" with { type: "json" }
+import { daemonBuildId } from "@opencode-cockpit/protocol"
+import pkg from "../package.json" with { type: "json" }
+
+/** Resolves the daemon entry shipped with this package. */
+export function daemonEntry(): string {
+  return fileURLToPath(import.meta.resolve("@opencode-cockpit/daemon/main"))
+}
+
+/**
+ * Inside OpenCode `process.execPath` is the OpenCode binary; the client starts the daemon with
+ * BUN_BE_BUN=1 so it runs on OpenCode's embedded Bun (ADR 0001). The expected build lets the
+ * client replace a daemon left running from older plugin code.
+ */
+export function createClient(name: string): CockpitClient {
+  const entry = daemonEntry()
+  return new CockpitClient({
+    client: { name, version: pkg.version, pid: process.pid },
+    spawn: { entry, execPath: process.execPath },
+    expectedBuild: daemonBuildId(entry, daemonPkg.version),
+  })
+}

package/src/server.ts

@@ -0,0 +1,137 @@
+import type { Hooks, Plugin, PluginInput, PluginModule } from "@opencode-ai/plugin"
+import { claimFeature, duplicateFeatureMessage } from "@opencode-cockpit/client"
+import type { ShellInfo } from "@opencode-cockpit/protocol/shell"
+import { createClient } from "./connect.ts"
+import { describeStatus, formatLines } from "./tools/format.ts"
+import { createTools } from "./tools/index.ts"
+
+const GUIDANCE = `## Background shells (opencode-cockpit)
+Long-running or interactive commands (dev servers, watchers, slow builds/tests, REPLs) go in shell_start, not bash with "&".
+Block with shell_wait (pattern, port, idle, exit) instead of sleeping; follow output with shell_read(after=cursor).
+You are messaged when a shell you started exits.`
+
+export const SHELL_PACKAGE = "@opencode-cockpit/shell"
+
+export interface ShellServerOptions {
+  /** Package that loaded Shell, reported when a duplicate copy is skipped. */
+  source?: string
+}
+
+/** Shell's server half as a factory, so bundles such as `opencode-cockpit` can include it. */
+export function createShellServer({ source = SHELL_PACKAGE }: ShellServerOptions = {}): Plugin {
+  return async (input) => {
+    const claim = claimFeature(input, "shell", source)
+    if (!claim.active) {
+      // Logging through the server during plugin initialisation could wait on ourselves; defer it.
+      setTimeout(() => {
+        void input.client.app
+          .log({
+            body: {
+              service: "opencode-cockpit",
+              level: "warn",
+              message: duplicateFeatureMessage("Shell", claim.owner, source),
+            },
+          })
+          .catch(() => {})
+      }, 0)
+      return {}
+    }
+    const hooks = await shellHooks(input)
+    const dispose = hooks.dispose
+    return {
+      ...hooks,
+      dispose: async () => {
+        claim.release()
+        await dispose?.()
+      },
+    }
+  }
+}
+
+async function shellHooks({ client: opencode, directory }: PluginInput): Promise<Hooks> {
+  const cockpit = createClient("opencode-cockpit/server")
+  const instance = crypto.randomUUID()
+  const quiet = new Set<string>()
+
+  const userShell =
+    process.env.SHELL && /(bash|zsh|fish|sh)$/.test(process.env.SHELL) ? process.env.SHELL : "/bin/bash"
+  const env = () => {
+    const out: Record<string, string> = {}
+    for (const [k, v] of Object.entries(process.env))
+      if (v !== undefined && !k.startsWith("OPENCODE_")) out[k] = v
+    return out
+  }
+
+  // Wake the agent when a shell it owns ends on its own.
+  cockpit.on("shell.exited", (info) => {
+    if (info.owner.instance !== instance || !info.owner.session) return
+    if (quiet.delete(info.id)) return
+    void notifyExit(info).catch(() => {})
+  })
+
+  async function notifyExit(info: ShellInfo): Promise<void> {
+    const session = info.owner.session as string
+    const page = await cockpit.call("shell.read", { id: info.id, tail: 15 })
+    const failed =
+      info.status === "failed" ||
+      (info.status === "exited" && info.exitCode !== 0) ||
+      info.status === "killed"
+    const text = [
+      `<shell_exited id="${info.id}" title="${info.title}">`,
+      describeStatus(info),
+      page.lines.length > 0 ? `last output:\n${formatLines(page.lines)}` : "(no output)",
+      "</shell_exited>",
+      failed
+        ? `Investigate with shell_read id=${info.id} grep="error|fail" if the failure matters to the task.`
+        : `Full output: shell_read id=${info.id}.`,
+    ].join("\n")
+    await opencode.session.promptAsync({
+      path: { id: session },
+      body: { parts: [{ type: "text", text, synthetic: true } as never] },
+    })
+  }
+
+  return {
+    tool: createTools({
+      client: cockpit,
+      instance,
+      quiet,
+      env,
+      shellCommand: (command) => ({ command: userShell, args: ["-c", command] }),
+    }),
+
+    "experimental.chat.system.transform": async (_input, output) => {
+      output.system.push(GUIDANCE)
+      const running = await cockpit
+        .call("shell.list", { owner: { project: directory }, includeExited: false })
+        .catch(() => [] as ShellInfo[])
+      if (running.length > 0) {
+        output.system.push(
+          `Background shells currently running in this project:\n${running
+            .slice(0, 15)
+            .map((s) => `- ${s.id} ${s.title} (${describeStatus(s)})`)
+            .join("\n")}`,
+        )
+      }
+    },
+
+    event: async ({ event }) => {
+      if (event.type !== "session.deleted") return
+      const sessionID = event.properties.info.id
+      const owned = await cockpit
+        .call("shell.list", { owner: { session: sessionID } })
+        .catch(() => [] as ShellInfo[])
+      for (const shell of owned) {
+        quiet.add(shell.id)
+        await cockpit.call("shell.remove", { id: shell.id }).catch(() => {})
+      }
+    },
+
+    dispose: async () => {
+      cockpit.close()
+    },
+  }
+}
+
+const plugin: PluginModule & { id: string } = { id: "opencode-cockpit.shell", server: createShellServer() }
+export default plugin

package/src/tools/format.ts

@@ -0,0 +1,78 @@
+import type { LogLine, ReadResult, ShellInfo, WaitResult } from "@opencode-cockpit/protocol/shell"
+
+const MAX_LINE = 2000
+
+/** Compact log lines for a model: numbered, long lines cut, consecutive repeats collapsed. */
+export function formatLines(lines: LogLine[]): string {
+  const out: string[] = []
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i] as LogLine
+    let j = i + 1
+    while (j < lines.length && (lines[j] as LogLine).text === line.text) j++
+    const repeats = j - i
+    const text =
+      line.text.length > MAX_LINE
+        ? `${line.text.slice(0, MAX_LINE)}… [${line.text.length - MAX_LINE} chars cut]`
+        : line.text
+    out.push(
+      repeats > 1
+        ? `${line.n}| ${text}  (×${repeats}, lines ${line.n}-${line.n + repeats - 1})`
+        : `${line.n}| ${text}`,
+    )
+    i = j
+  }
+  return out.join("\n")
+}
+
+export function describeStatus(info: ShellInfo): string {
+  switch (info.status) {
+    case "running":
+      return `running (pid ${info.pid}, up ${duration(Date.now() - info.startedAt)})`
+    case "exited":
+      return `exited with code ${info.exitCode ?? "?"} after ${duration((info.endedAt ?? Date.now()) - info.startedAt)}`
+    case "killed":
+      return `killed${info.signal ? ` by ${info.signal}` : ""} after ${duration((info.endedAt ?? Date.now()) - info.startedAt)}`
+    case "failed":
+      return `failed to start: ${info.error ?? "unknown error"}`
+  }
+}
+
+export function header(info: ShellInfo): string {
+  const run = info.run > 1 ? ` run=${info.run}` : ""
+  return `<shell id="${info.id}" title="${info.title.replaceAll('"', "'")}" status="${info.status}"${run}>`
+}
+
+export function formatRead(info: ShellInfo, page: ReadResult, empty = "(no output yet)"): string {
+  const parts = [header(info), `status: ${describeStatus(info)}`]
+  if (page.truncated)
+    parts.push(`(older lines were dropped from the buffer; oldest kept is ${page.firstLine})`)
+  parts.push(page.lines.length > 0 ? formatLines(page.lines) : empty)
+  if (page.hasMore) parts.push(`(more lines available: call shell_read with after=${page.nextCursor})`)
+  parts.push("</shell>", `cursor: ${page.nextCursor}`)
+  return parts.join("\n")
+}
+
+export function formatWait(result: WaitResult, timeoutSeconds: number): string {
+  switch (result.reason) {
+    case "pattern":
+      return `condition met: pattern matched on line ${result.match?.n}: ${result.match?.text}`
+    case "port":
+      return "condition met: port is accepting connections"
+    case "idle":
+      return "condition met: no output for the idle window (the program may be waiting for input)"
+    case "exit":
+      return `process ended: ${describeStatus(result.info)}`
+    case "timeout":
+      return `timed out after ${timeoutSeconds}s without the condition being met; the shell is still ${result.info.status}`
+  }
+}
+
+export function duration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000))
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  if (m < 60) return `${m}m${s % 60 ? `${s % 60}s` : ""}`
+  const h = Math.floor(m / 60)
+  return `${h}h${m % 60 ? `${m % 60}m` : ""}`
+}