@opencode-cockpit/protocol 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,12 +1,12 @@
 import { daemonContract } from "./daemon.js";
-import { shellContract, shellEvents } from "./shell.js";
+import { shellContract, shellEvents } from "./shell/index.js";
 export * from "./build.js";
 export * from "./contract.js";
 export * from "./daemon.js";
 export * from "./framing.js";
 export * from "./paths.js";
 export * from "./rpc.js";
-export * as shell from "./shell.js";
+export * as shell from "./shell/index.js";
 
 /** Every method the daemon serves. Adding a module means spreading its contract here. */
 export const contract = {

package/dist/rpc.js

@@ -3,7 +3,7 @@
 /** Bump MAJOR on breaking changes to methods, events or framing. */
 export const PROTOCOL_VERSION = {
   major: 1,
-  minor: 1
+  minor: 2
 };
 export const ErrorCode = {
   ParseError: -32700,

package/dist/shell/common.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+/** Identity and ownership, shared by every shell message. */
+export const ShellId = z.string().regex(/^sh_[a-z2-7]{8}$/, "expected sh_ followed by 8 base32 chars");
+export const Owner = z.object({
+  /** Absolute project directory the shell belongs to. */
+  project: z.string().min(1),
+  /** OpenCode session that started it, when started by an agent. */
+  session: z.string().min(1).optional(),
+  /** Opaque id of the client instance that started it; used to route notifications to one place. */
+  instance: z.string().min(1).optional()
+});
+export const ShellStatus = z.enum(["running", "exited", "killed", "failed"]);

package/dist/shell/contract.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { method } from "../contract.js";
+import { ShellId } from "./common.js";
+import { ShellInfo } from "./info.js";
+import { AttachParams, ClearParams, IdParams, ListParams, ReadParams, ReadResult, ResizeParams, ScreenResult, StartParams, StopParams, WaitParams, WaitResult, WriteParams } from "./params.js";
+import { WatchParams, WatchRule, WatchStatus } from "./watch.js";
+export const shellContract = {
+  "shell.start": method(StartParams, ShellInfo),
+  "shell.list": method(ListParams, z.array(ShellInfo)),
+  "shell.get": method(IdParams, ShellInfo),
+  "shell.read": method(ReadParams, ReadResult),
+  "shell.screen": method(IdParams, ScreenResult),
+  "shell.write": method(WriteParams, z.object({
+    bytes: z.number().int()
+  })),
+  "shell.resize": method(ResizeParams, z.object({})),
+  "shell.wait": method(WaitParams, WaitResult),
+  "shell.stop": method(StopParams, ShellInfo),
+  "shell.restart": method(IdParams, ShellInfo),
+  "shell.remove": method(IdParams, z.object({})),
+  "shell.clear": method(ClearParams, z.object({
+    removed: z.array(ShellId)
+  })),
+  "shell.watch": method(WatchParams, ShellInfo),
+  "shell.unwatch": method(IdParams, ShellInfo),
+  "shell.presets": method(z.object({}).optional(), z.array(z.object({
+    name: z.string(),
+    match: z.string().optional(),
+    rule: WatchRule
+  }))),
+  "shell.attach": method(AttachParams, z.object({
+    offset: z.number().int(),
+    replay: z.string()
+  })),
+  "shell.detach": method(IdParams, z.object({}))
+};
+export const shellEvents = {
+  "shell.started": ShellInfo,
+  "shell.exited": ShellInfo,
+  "shell.removed": z.object({
+    id: ShellId
+  }),
+  "shell.output": z.object({
+    id: ShellId,
+    offset: z.number().int(),
+    data: z.string()
+  }),
+  /** Emitted only when a watcher's status changes, never per line. */
+  "shell.watch": z.object({
+    info: ShellInfo,
+    previous: WatchStatus,
+    current: WatchStatus,
+    summary: z.string().optional()
+  })
+};

package/dist/shell/index.js

@@ -0,0 +1,6 @@
+/** The shell capability's wire types, split by concern. Import from "@opencode-cockpit/protocol/shell". */
+export * from "./common.js";
+export * from "./contract.js";
+export * from "./info.js";
+export * from "./params.js";
+export * from "./watch.js";

package/dist/shell/info.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { Owner, ShellId, ShellStatus } from "./common.js";
+import { WatchState } from "./watch.js";
+export const ShellInfo = z.object({
+  id: ShellId,
+  title: z.string(),
+  command: z.string(),
+  args: z.array(z.string()),
+  cwd: z.string(),
+  owner: Owner,
+  status: ShellStatus,
+  run: z.number().int().positive(),
+  pid: z.number().int().optional(),
+  exitCode: z.number().int().optional(),
+  signal: z.string().optional(),
+  error: z.string().optional(),
+  /** Set when a run ends: the last error-looking line of the run, else its last line. */
+  summary: z.string().optional(),
+  startedAt: z.number(),
+  endedAt: z.number().optional(),
+  cols: z.number().int(),
+  rows: z.number().int(),
+  lines: z.object({
+    first: z.number().int(),
+    last: z.number().int()
+  }),
+  /** Absolute raw byte offset written so far (for UI attach/replay). */
+  bytes: z.number().int(),
+  /** Health reported by this shell's watcher, when one is attached. */
+  watch: WatchState.optional(),
+  /** File this shell's clean log is written to, when logging was requested. */
+  logFile: z.string().optional()
+});

package/dist/{shell.js → shell/params.js}

@@ -1,41 +1,6 @@
 import { z } from "zod";
-import { method } from "./contract.js";
-export const ShellId = z.string().regex(/^sh_[a-z2-7]{8}$/, "expected sh_ followed by 8 base32 chars");
-export const Owner = z.object({
-  /** Absolute project directory the shell belongs to. */
-  project: z.string().min(1),
-  /** OpenCode session that started it, when started by an agent. */
-  session: z.string().min(1).optional(),
-  /** Opaque id of the client instance that started it; used to route notifications to one place. */
-  instance: z.string().min(1).optional()
-});
-export const ShellStatus = z.enum(["running", "exited", "killed", "failed"]);
-export const ShellInfo = z.object({
-  id: ShellId,
-  title: z.string(),
-  command: z.string(),
-  args: z.array(z.string()),
-  cwd: z.string(),
-  owner: Owner,
-  status: ShellStatus,
-  run: z.number().int().positive(),
-  pid: z.number().int().optional(),
-  exitCode: z.number().int().optional(),
-  signal: z.string().optional(),
-  error: z.string().optional(),
-  /** Set when a run ends: the last error-looking line of the run, else its last line. */
-  summary: z.string().optional(),
-  startedAt: z.number(),
-  endedAt: z.number().optional(),
-  cols: z.number().int(),
-  rows: z.number().int(),
-  lines: z.object({
-    first: z.number().int(),
-    last: z.number().int()
-  }),
-  /** Absolute raw byte offset written so far (for UI attach/replay). */
-  bytes: z.number().int()
-});
+import { Owner, ShellId, ShellStatus } from "./common.js";
+import { ShellInfo } from "./info.js";
 const Dimension = z.number().int().min(2).max(1000);
 export const StartParams = z.object({
   command: z.string().min(1),
@@ -46,8 +11,15 @@ export const StartParams = z.object({
   cols: Dimension.default(120),
   rows: Dimension.default(32),
   owner: Owner,
-  /** Stop the shell automatically after this long. */
+  /** Stop the shell automatically after this long, however busy it is. */
   timeoutMs: z.number().int().positive().optional(),
+  /**
+   * Stop the shell after this much silence. Never a default: a dev server is idle by definition,
+   * and killing one for being quiet would be wrong.
+   */
+  idleTimeoutMs: z.number().int().positive().optional(),
+  /** Also write the clean log to a file, for debugging after the buffer has evicted old lines. */
+  logFile: z.boolean().default(false),
   /**
    * Restart a finished shell with the same command, args, cwd, project and session instead of
    * creating a new one. Repeated runs then share one id and one log.
@@ -94,6 +66,18 @@ export const ReadResult = z.object({
   hasMore: z.boolean(),
   status: ShellStatus
 });
+
+/** A run of characters sharing one style, so a UI can repaint colour without parsing escapes. */
+export const ScreenRun = z.object({
+  text: z.string(),
+  /** Resolved "#rrggbb"; absent means the viewer's default foreground. */
+  fg: z.string().optional(),
+  bg: z.string().optional(),
+  bold: z.boolean().optional(),
+  dim: z.boolean().optional(),
+  italic: z.boolean().optional(),
+  underline: z.boolean().optional()
+});
 export const ScreenResult = z.object({
   text: z.string(),
   cols: z.number().int(),
@@ -101,7 +85,9 @@ export const ScreenResult = z.object({
   cursor: z.object({
     x: z.number().int(),
     y: z.number().int()
-  })
+  }),
+  /** The same rows as `text`, carrying colour. */
+  styled: z.array(z.array(ScreenRun)).optional()
 });
 export const WriteParams = z.object({
   id: ShellId,
@@ -143,39 +129,4 @@ export const StopParams = z.object({
 export const AttachParams = z.object({
   id: ShellId,
   fromOffset: z.number().int().min(0).optional()
-});
-export const shellContract = {
-  "shell.start": method(StartParams, ShellInfo),
-  "shell.list": method(ListParams, z.array(ShellInfo)),
-  "shell.get": method(IdParams, ShellInfo),
-  "shell.read": method(ReadParams, ReadResult),
-  "shell.screen": method(IdParams, ScreenResult),
-  "shell.write": method(WriteParams, z.object({
-    bytes: z.number().int()
-  })),
-  "shell.resize": method(ResizeParams, z.object({})),
-  "shell.wait": method(WaitParams, WaitResult),
-  "shell.stop": method(StopParams, ShellInfo),
-  "shell.restart": method(IdParams, ShellInfo),
-  "shell.remove": method(IdParams, z.object({})),
-  "shell.clear": method(ClearParams, z.object({
-    removed: z.array(ShellId)
-  })),
-  "shell.attach": method(AttachParams, z.object({
-    offset: z.number().int(),
-    replay: z.string()
-  })),
-  "shell.detach": method(IdParams, z.object({}))
-};
-export const shellEvents = {
-  "shell.started": ShellInfo,
-  "shell.exited": ShellInfo,
-  "shell.removed": z.object({
-    id: ShellId
-  }),
-  "shell.output": z.object({
-    id: ShellId,
-    offset: z.number().int(),
-    data: z.string()
-  })
-};
+});

package/dist/shell/watch.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { ShellId } from "./common.js";
+
+/**
+ * A watch rule is three regexes over a shell's log, not a parser: `done` marks the end of a run
+ * (a compile, a test pass), `fail` and `ok` say how it went. Presets are just named rules, so a
+ * new tool is a table entry or a rule in the caller's config — never new code.
+ */
+export const WatchRule = z.object({
+  /** A run finished, e.g. "Found 3 errors." Without it, `idleSeconds` ends the run. */
+  done: z.string().min(1).max(500).optional(),
+  /** Something in this run failed. */
+  fail: z.string().min(1).max(500).optional(),
+  /** This run was clean; beats `fail` only when `fail` never matched. */
+  ok: z.string().min(1).max(500).optional(),
+  ignoreCase: z.boolean().optional(),
+  /** Treat this much silence as the end of a run when `done` is absent. */
+  idleSeconds: z.number().positive().max(3600).optional()
+});
+export const WatchStatus = z.enum(["ok", "fail", "pending", "unknown"]);
+export const WatchState = z.object({
+  /** Preset that produced the rule, when one was used. */
+  preset: z.string().optional(),
+  status: WatchStatus,
+  /** Line that decided the current status. */
+  summary: z.string().optional(),
+  /** Completed runs seen since watching started. */
+  runs: z.number().int(),
+  /** When the status last changed. */
+  since: z.number()
+});
+export const WatchParams = z.object({
+  id: ShellId,
+  /** Named rule, or "auto" to pick one from the command. Ignored when `rule` is given. */
+  preset: z.string().min(1).optional(),
+  rule: WatchRule.optional()
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/protocol",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Wire protocol, method and event contracts for cockpitd (opencode-cockpit)",
   "type": "module",
   "license": "MIT",
@@ -25,8 +25,8 @@
       "default": "./dist/index.js"
     },
     "./shell": {
-      "types": "./types/shell.d.ts",
-      "default": "./dist/shell.js"
+      "types": "./types/shell/index.d.ts",
+      "default": "./dist/shell/index.js"
     }
   },
   "files": [