@opencode-cockpit/shell 0.2.0 → 0.2.1

package/README.md

@@ -74,12 +74,17 @@ A watch rule is three regexes, not a parser: `done` (a run ended), `fail` and `o
 tsc, eslint, biome, prettier, mypy, ruff, vitest, jest, mocha, bun test, deno test, pytest, rspec,
 phpunit, playwright, cypress, vite, next, nuxt, astro, angular, webpack/rspack, esbuild, tsup,
 turbo, metro, storybook, cargo, go, dotnet, gradle, maven, docker compose and terraform. Anything
-else takes its own patterns:
+else takes its own patterns, at `shell_start` or later:
 
 ```
+shell_start command="./deploy.sh" description="deploy" watch={ fail: "FAILED", ok: "SUCCEEDED", idleSeconds: 5 }
 shell_watch name="deploy" rule={ fail: "FAILED", ok: "SUCCEEDED", idleSeconds: 5 }
 ```
 
+When no preset fits and no rule is given — `sleep 300`, a plain script, anything that prints nothing
+recognizable — watching still works: the shell is watched for **dying** (preset `exit`), which is
+crash detection with no patterns to write.
+
 Things to ask:
 
 - *"Start the dev server in a background shell and wait until it's ready."*

package/dist/agent/tools/start.js

@@ -48,7 +48,13 @@ export function shellStart(kit) {
         timeoutSeconds: z.number().positive().max(3600).default(120)
       }).optional().describe("Block until ready. Same conditions as shell_wait."),
       notifyOnExit: z.boolean().default(true).describe("Message you when the process exits"),
-      watch: z.union([z.boolean(), z.string()]).optional().describe('Watch this shell\'s health and message you only when it changes: true or "auto" picks a preset from the command, or name one (tsc, vitest, cargo…). For processes that never exit.'),
+      watch: z.union([z.boolean(), z.string(), z.object({
+        done: z.string().optional().describe("A run finished, e.g. 'Found \\d+ errors'"),
+        fail: z.string().optional(),
+        ok: z.string().optional(),
+        ignoreCase: z.boolean().optional(),
+        idleSeconds: z.number().positive().optional()
+      })]).optional().describe('Watch this shell\'s health and message you only when it changes. true or "auto" picks a preset from the command (tsc, vitest, cargo…) and falls back to reporting the process dying; a name picks that preset; an object is your own rule, e.g. { done: "\\d+ (passed|failed)", fail: "\\d+ failed" }.'),
       timeoutSeconds: z.number().int().positive().optional().describe("Stop the process after this long, busy or not. Good for bounded jobs and probes."),
       idleTimeoutSeconds: z.number().int().positive().optional().describe("Stop the process after this much silence. Never use it for dev servers, which are idle when healthy."),
       logFile: z.boolean().default(false).describe("Also write the clean log to a file, so old lines survive the in-memory buffer")
@@ -91,11 +97,10 @@ export function shellStart(kit) {
       if (info.status === "failed") return `${header(info)}\n${describeStatus(info)}\n</shell>`;
       const lines = [info.run > 1 ? `Restarted ${info.id} (run ${info.run}): same command as an earlier finished shell in this session. Earlier output is above line ${info.lines.last}.` : `Started ${info.id}: ${args.command}`];
       if (watch) {
-        const preset = typeof watch === "string" ? watch : "auto";
         await client.call("shell.watch", {
           id: info.id,
-          ...watchArgs(preset, config)
-        }).then(watched => lines.push(`watching health (${watched.watch?.preset ?? "custom rule"}); changes will be messaged to you`)).catch(err => lines.push(`could not watch: ${err instanceof Error ? err.message : String(err)}`));
+          ...watchArgs(watch, config)
+        }).then(watched => lines.push(describeWatch(watched))).catch(err => lines.push(`could not watch: ${err instanceof Error ? err.message : String(err)}`));
       }
       if (args.waitFor) {
         const {
@@ -134,6 +139,13 @@ export function shellStart(kit) {
   });
 }
 
+/** What was actually attached: a preset, your own rule, or plain crash reporting. */
+function describeWatch(info) {
+  const preset = info.watch?.preset;
+  if (preset === "exit") return "watching: no health patterns fit this command, so you will be messaged if it dies";
+  return `watching health (${preset ?? "custom rule"}); changes will be messaged to you`;
+}
+
 /** Milliseconds from an option in seconds, or undefined when unset. */
 function seconds(value) {
   return value ? Math.round(value * 1000) : undefined;

package/dist/agent/tools/watch-args.js

@@ -1,12 +1,60 @@
+/** A backslash that JSON does not allow — `\d`, `\s`, `\(` — i.e. someone wrote a regex in here. */
+const LONE_ESCAPE = /\\(?!["\\/bfnrtu])/g;
+
 /**
- * Turns a preset name into what `shell.watch` needs. A preset defined in config is sent as an
- * explicit rule, so users can add tools or correct a built-in without touching the daemon.
+ * Rules are regexes, and a regex written inside JSON text is usually under-escaped (`"\d+ passed"`
+ * is not valid JSON). Parse it as written first, then again with those backslashes escaped, so a
+ * model's JSON does not have to be perfect for its patterns to survive.
  */
-export function watchArgs(preset, config) {
+function parseLoosely(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    try {
+      return JSON.parse(text.replace(LONE_ESCAPE, "\\\\"));
+    } catch {
+      return undefined; // not JSON at all: treated as a preset name, which says so downstream
+    }
+  }
+}
+
+/** The keys a rule may carry; anything else in an object is not a rule. */
+const RULE_KEYS = new Set(["done", "fail", "ok", "ignoreCase", "idleSeconds"]);
+
+/**
+ * Turns whatever the model passed for `watch` into what `shell.watch` needs.
+ *
+ * `true`/`"auto"` asks the daemon to pick a preset, a name picks that preset — and a preset defined
+ * in config travels as an explicit rule, so users can add tools without touching the daemon. Rule
+ * objects arrive as JSON *strings* often enough (models write one, and tool args are not always
+ * parsed the way the schema says) that a string which looks like an object is parsed rather than
+ * handed on as a preset name nobody has.
+ */
+export function watchArgs(watch, config) {
+  const rule = asWatchRule(watch);
+  if (rule) return {
+    rule
+  };
+  const preset = watch === true || watch == null ? "auto" : String(watch);
   const custom = config.watch?.presets?.[preset];
   return custom ? {
     rule: custom
   } : {
     preset
   };
+}
+
+/** A rule from an object, or from the JSON string a model sometimes writes instead. */
+export function asWatchRule(value) {
+  let candidate = value;
+  if (typeof candidate === "string") {
+    const text = candidate.trim();
+    if (!text.startsWith("{")) return undefined;
+    const parsed = parseLoosely(text);
+    if (parsed === undefined) return undefined;
+    candidate = parsed;
+  }
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) return undefined;
+  const entries = Object.entries(candidate).filter(([k, v]) => RULE_KEYS.has(k) && v != null);
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }

package/dist/agent/tools/watch.js

@@ -1,13 +1,15 @@
 import { tool } from "@opencode-ai/plugin";
-import { watchArgs } from "./watch-args.js";
+import { asWatchRule, watchArgs } from "./watch-args.js";
 const WATCH = `Keep an eye on a long-running shell and be told only when its health changes.
 
 For processes that never exit (tsc --watch, vitest --watch, dev servers) this replaces re-reading
 the log: you get one message when it breaks, and one when it is fixed, and nothing while it repeats
 the same result.
 
-- preset: a named rule ("auto" picks one from the command). Presets exist for tsc, vitest, jest,
-  eslint, biome, cargo, go, gradle, pytest, vite, next, docker-compose and more.
+- preset: a named rule ("auto" picks one from the command, and falls back to reporting the process
+  dying when no patterns fit). Presets exist for tsc, vitest, jest, eslint, biome, cargo, go,
+  gradle, pytest, vite, next, docker-compose and more; "exit" watches only for the process dying,
+  which is how you get crash detection for a command that prints nothing useful.
 - rule: your own patterns when no preset fits: done (a run ended), fail, ok, idleSeconds.
 - off: stop watching.
 
@@ -56,17 +58,13 @@ export function shellWatch(kit) {
         return `${note}stopped watching ${stopped.id}`;
       }
       // A preset defined in config travels as an explicit rule; the daemon knows only the built-ins.
+      // Both arguments absorb a rule written as JSON, rather than failing on a preset name nobody has.
       const chosen = args.preset ? watchArgs(args.preset, config) : {};
+      const rule = asWatchRule(args.rule) ?? chosen.rule;
       const info = await client.call("shell.watch", {
         id,
-        preset: chosen.preset,
-        rule: args.rule ? {
-          done: args.rule.done ?? undefined,
-          fail: args.rule.fail ?? undefined,
-          ok: args.rule.ok ?? undefined,
-          ignoreCase: args.rule.ignoreCase ?? undefined,
-          idleSeconds: args.rule.idleSeconds ?? undefined
-        } : chosen.rule
+        preset: rule ? undefined : chosen.preset,
+        rule
       });
       return `${note}watching ${info.id} (${info.watch?.preset ?? "custom rule"}). You will be messaged when its health changes; no need to poll.`;
     }

package/dist/core/format.js

@@ -16,17 +16,42 @@ export function formatLines(lines) {
   return out.join("\n");
 }
 export function describeStatus(info) {
+  const ran = () => duration((info.endedAt ?? Date.now()) - info.startedAt);
   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)}`;
+      return info.exitCode === 0 ? `exited cleanly after ${ran()}` : `crashed with exit code ${info.exitCode ?? "?"} after ${ran()}`;
     case "killed":
-      return `killed${info.signal ? ` by ${info.signal}` : ""} after ${duration((info.endedAt ?? Date.now()) - info.startedAt)}`;
+      return `${stopPhrase(info)} after ${ran()}`;
     case "failed":
       return `failed to start: ${info.error ?? "unknown error"}`;
   }
 }
+
+/** Who ended a shell, and why — "killed by SIGTERM" alone never said which of us did it. */
+function stopPhrase(info) {
+  switch (info.stopReason) {
+    case "timeout":
+      return "stopped: hit its time limit";
+    case "idle":
+      return "stopped: no output for its idle limit";
+    case "shutdown":
+      return "stopped because the shell daemon shut down";
+    case "request":
+      return `stopped by ${actor(info.stoppedBy)}`;
+    default:
+      return info.exitCode != null && info.exitCode !== 0 ? `crashed (exit code ${info.exitCode})` : `killed${info.signal ? ` by ${info.signal}` : ""} from outside`;
+  }
+}
+
+/** Client names are wire identifiers; say them the way a person would. */
+function actor(client) {
+  if (!client) return "a request";
+  if (client.includes("tui")) return "you, from the shells panel";
+  if (client.includes("server")) return "the agent";
+  return client;
+}
 export function header(info) {
   const run = info.run > 1 ? ` run=${info.run}` : "";
   return `<shell id="${info.id}" title="${info.title.replaceAll('"', "'")}" status="${info.status}"${run}>`;

package/dist/tui/lib/view.js

@@ -81,13 +81,29 @@ export function statusDetail(s, now) {
     case "done":
       return `took ${ran} · ${ago}`;
     case "stop":
-      return `stopped after ${ran} · ${ago}`;
+      return `${stopWord(s)} after ${ran} · ${ago}`;
     case "fail":
       if (s.status === "failed") return "could not start";
       return `exit ${s.exitCode ?? "?"} after ${ran} · ${ago}`;
   }
 }
 
+/** Why it stopped, in one word, because the panel has room for exactly that. */
+function stopWord(s) {
+  switch (s.stopReason) {
+    case "timeout":
+      return "timed out";
+    case "idle":
+      return "idle-stopped";
+    case "shutdown":
+      return "daemon stopped it";
+    case "request":
+      return s.stoppedBy?.includes("tui") ? "you stopped it" : "agent stopped it";
+    default:
+      return "stopped";
+  }
+}
+
 /** Short health label for a watched shell, e.g. "tsc ✗" — empty when nothing is watching it. */
 export function watchLabel(s) {
   const watch = s.watch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/shell",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
@@ -51,9 +51,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/client": "0.2.0",
-    "@opencode-cockpit/daemon": "0.2.0",
-    "@opencode-cockpit/protocol": "0.2.0",
+    "@opencode-cockpit/client": "0.2.1",
+    "@opencode-cockpit/daemon": "0.2.1",
+    "@opencode-cockpit/protocol": "0.2.1",
     "@opencode-ai/plugin": "1.18.31"
   },
   "devDependencies": {

package/types/agent/tools/watch-args.d.ts

@@ -1,10 +1,18 @@
 import type { WatchRule } from "@opencode-cockpit/protocol/shell";
 import type { CockpitConfig } from "../../core/config.ts";
-/**
- * Turns a preset name into what `shell.watch` needs. A preset defined in config is sent as an
- * explicit rule, so users can add tools or correct a built-in without touching the daemon.
- */
-export declare function watchArgs(preset: string, config: CockpitConfig): {
+export type WatchRequest = {
     preset?: string;
     rule?: WatchRule;
 };
+/**
+ * Turns whatever the model passed for `watch` into what `shell.watch` needs.
+ *
+ * `true`/`"auto"` asks the daemon to pick a preset, a name picks that preset — and a preset defined
+ * in config travels as an explicit rule, so users can add tools without touching the daemon. Rule
+ * objects arrive as JSON *strings* often enough (models write one, and tool args are not always
+ * parsed the way the schema says) that a string which looks like an object is parsed rather than
+ * handed on as a preset name nobody has.
+ */
+export declare function watchArgs(watch: unknown, config: CockpitConfig): WatchRequest;
+/** A rule from an object, or from the JSON string a model sometimes writes instead. */
+export declare function asWatchRule(value: unknown): WatchRule | undefined;

package/types/core/config.d.ts

@@ -20,7 +20,8 @@ export interface CockpitConfig {
     kinds?: Record<string, string>;
     /** Applied to every shell the agent starts, unless the call says otherwise. */
     defaults?: {
-        watch?: boolean | string;
+        /** true/"auto", a preset name, or your own rule. */
+        watch?: boolean | string | WatchRule;
         logFile?: boolean;
         idleTimeoutSeconds?: number;
         timeoutSeconds?: number;

package/types/tui/lib/view.d.ts

@@ -39,6 +39,8 @@ export declare function partition(list: readonly ShellInfo[], opts: PartitionOpt
         signal?: string | undefined;
         error?: string | undefined;
         summary?: string | undefined;
+        stopReason?: "idle" | "request" | "shutdown" | "timeout" | undefined;
+        stoppedBy?: string | undefined;
         startedAt: number;
         endedAt?: number | undefined;
         cols: number;