@opencode-cockpit/shell 0.1.4 → 0.1.5

package/dist/tui/store.js

@@ -0,0 +1,156 @@
+import { existsSync } from "node:fs";
+import { createEffect, createMemo, createRoot, createSignal, on, onCleanup } from "solid-js";
+import { createStore, reconcile } from "solid-js/store";
+import { order, partition } from "./view.js";
+export function createShellStore(api, client, options = {}) {
+  return createRoot(dispose => {
+    const [state, setState] = createStore({
+      list: []
+    });
+    const [connected, setConnected] = createSignal(false);
+    const [now, setNow] = createSignal(Date.now());
+    const [frame, setFrame] = createSignal(0);
+    const [selectedId, setSelectedId] = createSignal();
+    const [showAll, setShowAll] = createSignal(api.kv.get("cockpit.shells.showAll", false));
+    const project = () => api.state.path.directory;
+    const historyMs = (options.historyMinutes ?? 30) * 60_000;
+    const refresh = async () => {
+      try {
+        const list = await client.call("shell.list", {
+          owner: {
+            project: project()
+          }
+        });
+        setState("list", reconcile(list, {
+          key: "id"
+        }));
+      } catch {
+        // daemon not running yet; the reconnect loop will pick it up
+      }
+    };
+    const offs = [client.on("shell.started", () => void refresh()), client.on("shell.exited", () => void refresh()), client.on("shell.removed", () => void refresh()), client.onState(s => {
+      setConnected(s === "connected");
+      if (s === "connected") void refresh();
+    })];
+
+    // Connect only to a daemon that already exists; starting one is left to explicit actions.
+    const probe = () => {
+      if (!client.connected && existsSync(client.paths.socket)) void client.connect().catch(() => {});
+    };
+    probe();
+    const probeTimer = setInterval(probe, 3000);
+    const tick = setInterval(() => setNow(Date.now()), 1000);
+    const spin = setInterval(() => {
+      if (state.list.some(s => s.status === "running")) setFrame(f => f + 1);
+    }, 120);
+    onCleanup(() => {
+      clearInterval(probeTimer);
+      clearInterval(tick);
+      clearInterval(spin);
+      for (const off of offs) off();
+    });
+    const pick = createMemo(() => {
+      const ordered = order(state.list);
+      return ordered.find(s => s.id === selectedId()) ?? ordered[0];
+    });
+    const folded = createMemo(() => partition(state.list, {
+      showAll: showAll(),
+      historyMs,
+      now: now(),
+      keep: pick()?.id
+    }));
+    return {
+      client,
+      project,
+      shells: () => state.list,
+      visible: () => folded().visible,
+      hidden: () => folded().hidden,
+      showAll,
+      toggleAll() {
+        const next = !showAll();
+        setShowAll(next);
+        api.kv.set("cockpit.shells.showAll", next);
+      },
+      connected,
+      now,
+      frame,
+      selected: pick,
+      select: id => setSelectedId(id),
+      step(delta) {
+        const list = folded().visible;
+        if (list.length === 0) return;
+        const index = Math.max(0, list.findIndex(s => s.id === pick()?.id));
+        const next = list[(index + delta + list.length) % list.length];
+        if (next) setSelectedId(next.id);
+      },
+      refresh,
+      async clearFinished() {
+        const {
+          removed
+        } = await client.call("shell.clear", {
+          owner: {
+            project: project()
+          }
+        });
+        await refresh();
+        return removed.length;
+      },
+      dispose
+    };
+  });
+}
+
+/**
+ * Live terminal view of one shell: attaches for change notifications and re-renders the daemon's
+ * emulated screen, throttled. Must be called inside a reactive owner.
+ */
+export function useScreen(store, id) {
+  const [screen, setScreen] = createSignal();
+  let timer;
+  let current;
+  const fetch = shellId => {
+    timer = undefined;
+    void store.client.call("shell.screen", {
+      id: shellId
+    }).then(s => {
+      if (current === shellId) setScreen(s);
+    }).catch(() => {});
+  };
+  const schedule = shellId => {
+    timer ??= setTimeout(() => fetch(shellId), 80);
+  };
+  const offOutput = store.client.on("shell.output", e => {
+    if (e.id === current) schedule(e.id);
+  });
+  const offExit = store.client.on("shell.exited", info => {
+    if (info.id === current) schedule(info.id);
+  });
+  const attach = next => {
+    if (next === current) return;
+    if (current) void store.client.call("shell.detach", {
+      id: current
+    }).catch(() => {});
+    current = next;
+    setScreen(undefined);
+    if (!next) return;
+    const info = store.shells().find(s => s.id === next);
+    void store.client.call("shell.attach", {
+      id: next,
+      fromOffset: info?.bytes ?? Number.MAX_SAFE_INTEGER
+    }).catch(() => {});
+    fetch(next);
+  };
+  createEffect(on(id, next => attach(next)));
+  onCleanup(() => {
+    clearTimeout(timer);
+    offOutput();
+    offExit();
+    if (current) void store.client.call("shell.detach", {
+      id: current
+    }).catch(() => {});
+  });
+  return {
+    screen,
+    refetch: () => current && fetch(current)
+  };
+}

package/dist/tui/view.js

@@ -0,0 +1,154 @@
+import { duration } from "../tools/format.js";
+
+/** What a human cares about, derived from status + exit code so every surface agrees. */
+
+export function kindOf(s) {
+  if (s.status === "running") return "run";
+  if (s.status === "killed") return "stop";
+  if (s.status === "exited" && s.exitCode === 0) return "done";
+  return "fail";
+}
+export const BADGE_LABEL = {
+  run: "RUN",
+  fail: "FAIL",
+  stop: "STOP",
+  done: "DONE"
+};
+
+/** Braille spinner: single-width in every terminal font. */
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export function kindColor(theme, kind) {
+  switch (kind) {
+    case "run":
+      return theme.success;
+    case "fail":
+      return theme.error;
+    case "stop":
+      return theme.warning;
+    case "done":
+      return theme.textMuted;
+  }
+}
+
+/** Fixed 7-column pill so lists line up: " ⠹ RUN ", " FAIL  ". */
+export function badgeText(kind, frame = 0) {
+  if (kind === "run") return ` ${SPINNER[frame % SPINNER.length]} RUN `;
+  return ` ${BADGE_LABEL[kind].padEnd(4)}  `;
+}
+const RANK = {
+  run: 0,
+  fail: 1,
+  stop: 2,
+  done: 3
+};
+
+/** Running first (oldest first, stable tabs), then failures, stopped, done (most recent first). */
+export function order(list) {
+  return [...list].sort((a, b) => {
+    const ka = kindOf(a);
+    const kb = kindOf(b);
+    if (ka !== kb) return RANK[ka] - RANK[kb];
+    if (ka === "run") return a.startedAt - b.startedAt;
+    return (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt);
+  });
+}
+/** Default view: running shells and recent failures. Everything else folds into a "N more" chip. */
+export function partition(list, opts) {
+  const ordered = order(list);
+  if (opts.showAll) return {
+    visible: ordered,
+    hidden: []
+  };
+  const visible = [];
+  const hidden = [];
+  for (const s of ordered) {
+    const kind = kindOf(s);
+    const recent = opts.now - (s.endedAt ?? opts.now) <= opts.historyMs;
+    if (kind === "run" || kind === "fail" && recent || s.id === opts.keep) visible.push(s);else hidden.push(s);
+  }
+  return {
+    visible,
+    hidden
+  };
+}
+export function statusDetail(s, now) {
+  const kind = kindOf(s);
+  const ran = duration((s.endedAt ?? now) - s.startedAt);
+  const ago = s.endedAt ? since(now - s.endedAt) : "";
+  switch (kind) {
+    case "run":
+      return ran;
+    case "done":
+      return `took ${ran} · ${ago}`;
+    case "stop":
+      return `stopped after ${ran} · ${ago}`;
+    case "fail":
+      if (s.status === "failed") return "could not start";
+      return `exit ${s.exitCode ?? "?"} after ${ran} · ${ago}`;
+  }
+}
+
+/** Compact detail for narrow lists. */
+export function shortDetail(s, now) {
+  switch (kindOf(s)) {
+    case "run":
+      return duration(now - s.startedAt);
+    case "fail":
+      return s.status === "failed" ? "no start" : `exit ${s.exitCode ?? "?"}`;
+    case "stop":
+      return "stopped";
+    case "done":
+      return s.endedAt ? since(now - s.endedAt) : "done";
+  }
+}
+
+/** Coarse relative time: "just now", "12s ago", "9m ago", "3h ago". */
+export function since(ms) {
+  const s = Math.floor(ms / 1000);
+  if (s < 5) return "just now";
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86_400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86_400)}d ago`;
+}
+
+/** The command as the user or agent wrote it, without the `$SHELL -c` wrapper. */
+export function displayCommand(s) {
+  if (s.args.length === 2 && s.args[0] === "-c" && /(^|\/)(ba|z|fi|da|k)?sh$/.test(s.command)) return s.args[1];
+  return [s.command, ...s.args].join(" ");
+}
+
+/** Folder relative to the project: "" at the root, "./sub" inside, "~/x" elsewhere under home. */
+export function relativeCwd(cwd, project, home = process.env.HOME ?? "") {
+  const trim = p => p.replace(/\/+$/, "");
+  const c = trim(cwd);
+  const p = trim(project);
+  if (c === p) return "";
+  if (c.startsWith(`${p}/`)) return `./${c.slice(p.length + 1)}`;
+  if (home && c.startsWith(`${trim(home)}/`)) return `~/${c.slice(trim(home).length + 1)}`;
+  return c;
+}
+
+/** Hard-wraps to `width`, at most `maxLines`; the last line ends with … when text was cut. */
+export function wrapText(text, width, maxLines) {
+  const flat = text.replace(/\s*\n\s*/g, " ⏎ ");
+  const w = Math.max(4, width);
+  const lines = [];
+  for (let i = 0; i < flat.length && lines.length < maxLines; i += w) lines.push(flat.slice(i, i + w));
+  if (lines.length === 0) return [""];
+  if (flat.length > w * maxLines) {
+    const last = lines[lines.length - 1];
+    lines[lines.length - 1] = `${last.slice(0, w - 1)}…`;
+  }
+  return lines;
+}
+
+/** Last `rows` lines of screen text, each cut to `cols`. */
+export function tailLines(text, rows, cols) {
+  if (!text) return "";
+  const lines = text.split("\n");
+  return lines.slice(Math.max(0, lines.length - rows)).map(l => l.length > cols ? `${l.slice(0, Math.max(0, cols - 1))}…` : l).join("\n");
+}
+export function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/shell",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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",
@@ -24,16 +24,26 @@
     "terminal"
   ],
   "exports": {
-    "./server": "./src/server.ts",
-    "./tui": "./src/tui/index.tsx",
-    "./connect": "./src/connect.ts"
+    "./server": {
+      "types": "./types/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./tui": {
+      "types": "./types/tui/index.d.ts",
+      "default": "./dist/tui/index.js"
+    },
+    "./connect": {
+      "types": "./types/connect.d.ts",
+      "default": "./dist/connect.js"
+    }
   },
   "engines": {
     "opencode": ">=1.18.0",
     "bun": ">=1.3.5"
   },
   "files": [
-    "src",
+    "dist",
+    "types",
     "README.md",
     "LICENSE"
   ],
@@ -41,16 +51,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/client": "0.1.4",
-    "@opencode-cockpit/daemon": "0.1.4",
-    "@opencode-cockpit/protocol": "0.1.4",
-    "@opencode-ai/plugin": "1.18.31",
+    "@opencode-cockpit/client": "0.1.5",
+    "@opencode-cockpit/daemon": "0.1.5",
+    "@opencode-cockpit/protocol": "0.1.5",
+    "@opencode-ai/plugin": "1.18.31"
+  },
+  "devDependencies": {
+    "zod": "4.6.5",
     "@opentui/core": "0.4.5",
     "@opentui/keymap": "0.4.5",
     "@opentui/solid": "0.4.5",
     "solid-js": "1.9.12"
-  },
-  "devDependencies": {
-    "zod": "4.6.5"
   }
 }

package/types/connect.d.ts

@@ -0,0 +1,9 @@
+import { CockpitClient } from "@opencode-cockpit/client";
+/** Resolves the daemon entry shipped with this package. */
+export declare function daemonEntry(): string;
+/**
+ * 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 declare function createClient(name: string): CockpitClient;

package/types/server.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin, PluginModule } from "@opencode-ai/plugin";
+export declare 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 declare function createShellServer({ source }?: ShellServerOptions): Plugin;
+declare const plugin: PluginModule & {
+    id: string;
+};
+export default plugin;

package/types/tools/find.d.ts

@@ -0,0 +1,32 @@
+import type { ShellInfo } from "@opencode-cockpit/protocol/shell";
+/** The command as written, without the `$SHELL -c` wrapper. */
+export declare function commandOf(s: ShellInfo): string;
+export type StatusFilter = "running" | "failed" | "finished" | "any";
+export type SessionFilter = "this" | "others" | "any";
+export interface ShellFilter {
+    /** Case-insensitive text found in the name or the command. */
+    query?: string;
+    status?: StatusFilter;
+    session?: SessionFilter;
+    /** The asking agent's session, for `session` filtering. */
+    currentSession?: string;
+}
+export declare function isFailed(s: ShellInfo): boolean;
+export declare function filterShells(list: readonly ShellInfo[], filter: ShellFilter): ShellInfo[];
+export type NameMatch = {
+    kind: "found";
+    shell: ShellInfo;
+    alsoMatched: ShellInfo[];
+} | {
+    kind: "ambiguous";
+    candidates: ShellInfo[];
+} | {
+    kind: "none";
+    available: ShellInfo[];
+};
+/**
+ * Finds the shell a name refers to. Exact names (ignoring case) beat partial matches on name or
+ * command. When several match, a single running shell is the obvious intent (earlier finished
+ * shells with the same name are history); otherwise the caller must choose.
+ */
+export declare function matchByName(list: readonly ShellInfo[], name: string): NameMatch;

package/types/tools/format.d.ts

@@ -0,0 +1,8 @@
+import type { LogLine, ReadResult, ShellInfo, WaitResult } from "@opencode-cockpit/protocol/shell";
+/** Compact log lines for a model: numbered, long lines cut, consecutive repeats collapsed. */
+export declare function formatLines(lines: LogLine[]): string;
+export declare function describeStatus(info: ShellInfo): string;
+export declare function header(info: ShellInfo): string;
+export declare function formatRead(info: ShellInfo, page: ReadResult, empty?: string): string;
+export declare function formatWait(result: WaitResult, timeoutSeconds: number): string;
+export declare function duration(ms: number): string;

package/types/tools/index.d.ts

@@ -0,0 +1,17 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { CockpitClient } from "@opencode-cockpit/client";
+export interface ToolDeps {
+    client: CockpitClient;
+    /** Identifies this OpenCode instance so only it notifies the owning session. */
+    instance: string;
+    /** Shells whose exit should not message the agent (it stopped them itself, or opted out). */
+    quiet: Set<string>;
+    shellCommand(command: string): {
+        command: string;
+        args: string[];
+    };
+    env(): Record<string, string>;
+    /** Human title of an OpenCode session, for telling agents which session started a shell. */
+    sessionTitle?(sessionID: string): Promise<string | undefined>;
+}
+export declare function createTools(deps: ToolDeps): Record<string, ToolDefinition>;

package/types/tools/keys.d.ts

@@ -0,0 +1,3 @@
+/** Translates named keys (`enter`, `ctrl+c`, `up`) into the bytes a terminal would send. */
+export declare function encodeKey(name: string): string;
+export declare const KEY_NAMES: string[];

package/types/tui/badge.d.ts

@@ -0,0 +1,9 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { ShellInfo } from "@opencode-cockpit/protocol/shell";
+/** Status pill: label on a coloured background, readable in any font and colour scheme. */
+export declare function Badge(props: {
+    api: TuiPluginApi;
+    shell: ShellInfo;
+    frame: number;
+}): import("solid-js").JSX.Element;

package/types/tui/console.d.ts

@@ -0,0 +1,16 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import { type ShellStore } from "./store.ts";
+export interface ConsoleProps {
+    api: TuiPluginApi;
+    store: ShellStore;
+    /** Start in typing mode. */
+    typing?: boolean;
+    onClose: () => void;
+    onNewShell: () => void;
+}
+/**
+ * Keyboard-first shell console in an overlay. Normal mode: single-key actions. Typing mode:
+ * every key goes to the program (ctrl+c included); ctrl+] returns to normal mode.
+ */
+export declare function Console(props: ConsoleProps): import("solid-js").JSX.Element;

package/types/tui/dock.d.ts

@@ -0,0 +1,12 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { ShellStore } from "./store.ts";
+export interface DockProps {
+    api: TuiPluginApi;
+    store: ShellStore;
+    height: number;
+    hint: () => string;
+    onOpenConsole: (id: string) => void;
+}
+/** Split pane under the chat: status tabs for shells and the selected shell's live screen. */
+export declare function Dock(props: DockProps): import("solid-js").JSX.Element;

package/types/tui/index.d.ts

@@ -0,0 +1,19 @@
+/** @jsxImportSource @opentui/solid */
+import { type TuiPlugin, type TuiPluginModule } from "@opencode-ai/plugin/tui";
+export interface ShellTuiOptions {
+    dockHeight?: number;
+    /** Shell rows the sidebar shows before folding the rest away (default 5). */
+    sidebarRows?: number;
+    /** Failures stay visible this long after they end (default 30). */
+    historyMinutes?: number;
+    dockOpen?: boolean;
+    keybinds?: Record<string, string>;
+}
+/** Shell's TUI half as a factory, so bundles such as `opencode-cockpit` can include it. */
+export declare function createShellTui({ source }?: {
+    source?: string;
+}): TuiPlugin;
+declare const plugin: TuiPluginModule & {
+    id: string;
+};
+export default plugin;

package/types/tui/keys.d.ts

@@ -0,0 +1,8 @@
+import type { KeyEvent } from "@opentui/core";
+/**
+ * Re-encodes a parsed key as legacy terminal bytes. The TUI may receive keys via the kitty
+ * protocol, whose raw form programs in the PTY would not understand.
+ */
+export declare function keyToBytes(e: KeyEvent): string | undefined;
+/** ctrl+] releases typing mode (the telnet escape), since esc and ctrl+c belong to the program. */
+export declare function isReleaseKey(e: KeyEvent): boolean;

package/types/tui/sidebar.d.ts

@@ -0,0 +1,14 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { ShellStore } from "./store.ts";
+export interface SidebarProps {
+    api: TuiPluginApi;
+    store: ShellStore;
+    /** Rows shown before the rest folds away; the sidebar is a narrow, shared column. */
+    rows?: number;
+    /** Rows shown while expanded, so a hundred shells can never push the sidebar over. */
+    expandedRows?: number;
+    onOpen: (id: string) => void;
+    consoleShortcut: () => string;
+}
+export declare function SidebarShells(props: SidebarProps): import("solid-js").JSX.Element;

package/types/tui/store.d.ts

@@ -0,0 +1,46 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { CockpitClient } from "@opencode-cockpit/client";
+import type { ShellInfo } from "@opencode-cockpit/protocol/shell";
+import { type Accessor } from "solid-js";
+export interface ShellStore {
+    client: CockpitClient;
+    project: () => string;
+    /** Every shell in the project, unordered. */
+    shells: Accessor<ShellInfo[]>;
+    /** Ordered and folded for display: running, recent failures, plus the selection. */
+    visible: Accessor<ShellInfo[]>;
+    hidden: Accessor<ShellInfo[]>;
+    showAll: Accessor<boolean>;
+    toggleAll(): void;
+    connected: Accessor<boolean>;
+    now: Accessor<number>;
+    /** Spinner frame index; advances only while something is running. */
+    frame: Accessor<number>;
+    selected: Accessor<ShellInfo | undefined>;
+    select(id: string): void;
+    step(delta: number): void;
+    refresh(): Promise<void>;
+    clearFinished(): Promise<number>;
+    dispose(): void;
+}
+export interface StoreOptions {
+    /** Failures stay in the default view this long after they end. */
+    historyMinutes?: number;
+}
+export declare function createShellStore(api: TuiPluginApi, client: CockpitClient, options?: StoreOptions): ShellStore;
+/**
+ * Live terminal view of one shell: attaches for change notifications and re-renders the daemon's
+ * emulated screen, throttled. Must be called inside a reactive owner.
+ */
+export declare function useScreen(store: ShellStore, id: Accessor<string | undefined>): {
+    screen: Accessor<{
+        text: string;
+        cols: number;
+        rows: number;
+        cursor: {
+            x: number;
+            y: number;
+        };
+    } | undefined>;
+    refetch: () => void | "" | undefined;
+};

package/types/tui/view.d.ts

@@ -0,0 +1,67 @@
+import type { TuiThemeCurrent } from "@opencode-ai/plugin/tui";
+import type { ShellInfo } from "@opencode-cockpit/protocol/shell";
+/** What a human cares about, derived from status + exit code so every surface agrees. */
+export type Kind = "run" | "fail" | "stop" | "done";
+export declare function kindOf(s: ShellInfo): Kind;
+export declare const BADGE_LABEL: Record<Kind, string>;
+/** Braille spinner: single-width in every terminal font. */
+export declare const SPINNER: string[];
+export declare function kindColor(theme: TuiThemeCurrent, kind: Kind): import("@opentui/core").RGBA;
+/** Fixed 7-column pill so lists line up: " ⠹ RUN ", " FAIL  ". */
+export declare function badgeText(kind: Kind, frame?: number): string;
+/** Running first (oldest first, stable tabs), then failures, stopped, done (most recent first). */
+export declare function order(list: readonly ShellInfo[]): ShellInfo[];
+export interface PartitionOptions {
+    showAll: boolean;
+    /** Failures stay visible this long after they end. */
+    historyMs: number;
+    now: number;
+    /** Always visible, so the selection never disappears under the user. */
+    keep?: string;
+}
+/** Default view: running shells and recent failures. Everything else folds into a "N more" chip. */
+export declare function partition(list: readonly ShellInfo[], opts: PartitionOptions): {
+    visible: {
+        id: string;
+        title: string;
+        command: string;
+        args: string[];
+        cwd: string;
+        owner: {
+            project: string;
+            session?: string | undefined;
+            instance?: string | undefined;
+        };
+        status: "exited" | "failed" | "killed" | "running";
+        run: number;
+        pid?: number | undefined;
+        exitCode?: number | undefined;
+        signal?: string | undefined;
+        error?: string | undefined;
+        summary?: string | undefined;
+        startedAt: number;
+        endedAt?: number | undefined;
+        cols: number;
+        rows: number;
+        lines: {
+            first: number;
+            last: number;
+        };
+        bytes: number;
+    }[];
+    hidden: ShellInfo[];
+};
+export declare function statusDetail(s: ShellInfo, now: number): string;
+/** Compact detail for narrow lists. */
+export declare function shortDetail(s: ShellInfo, now: number): string;
+/** Coarse relative time: "just now", "12s ago", "9m ago", "3h ago". */
+export declare function since(ms: number): string;
+/** The command as the user or agent wrote it, without the `$SHELL -c` wrapper. */
+export declare function displayCommand(s: ShellInfo): string;
+/** Folder relative to the project: "" at the root, "./sub" inside, "~/x" elsewhere under home. */
+export declare function relativeCwd(cwd: string, project: string, home?: string): string;
+/** Hard-wraps to `width`, at most `maxLines`; the last line ends with … when text was cut. */
+export declare function wrapText(text: string, width: number, maxLines: number): string[];
+/** Last `rows` lines of screen text, each cut to `cols`. */
+export declare function tailLines(text: string | undefined, rows: number, cols: number): string;
+export declare function truncate(text: string, max: number): string;