@opencode-cockpit/shell 0.1.2 → 0.1.3

package/README.md

@@ -35,7 +35,17 @@ one loaded is used and OpenCode shows a warning.
 | `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. |
+| `shell_list` | Find shells: filter by text (`query`), `status` (running, failed, finished) and `session` (this, others). Each shows which session started it. |
+| `shell_stop` · `shell_restart` | Manage shells. |
+
+Every tool that acts on a shell takes its `id` **or its name** (the description it was started
+with), so you can ask about shells naturally, including ones started in other sessions:
+
+- *"How is DB Monitoring doing?"* → `shell_read name="DB Monitoring"`
+- *"Did any shell from my other session fail?"* → `shell_list status="failed" session="others"`
+
+Names match ignoring case, then partially on name or command. If a name fits several shells the
+agent gets the candidates instead of a guess.
 
 The agent is messaged when a shell it started exits on its own.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/shell",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -41,36 +41,16 @@
     "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": {
+    "@opencode-cockpit/client": "0.1.3",
+    "@opencode-cockpit/daemon": "0.1.3",
+    "@opencode-cockpit/protocol": "0.1.3",
+    "@opencode-ai/plugin": "1.18.31",
     "@opentui/core": "0.4.5",
     "@opentui/keymap": "0.4.5",
     "@opentui/solid": "0.4.5",
-    "solid-js": "1.9.15",
-    "zod": "4.1.8"
+    "solid-js": "1.9.15"
   },
-  "peerDependenciesMeta": {
-    "@opentui/core": {
-      "optional": true
-    },
-    "@opentui/keymap": {
-      "optional": true
-    },
-    "@opentui/solid": {
-      "optional": true
-    },
-    "solid-js": {
-      "optional": true
-    }
+  "devDependencies": {
+    "zod": "4.6.5"
   }
 }

package/src/server.ts

@@ -62,6 +62,17 @@ async function shellHooks({ client: opencode, directory }: PluginInput): Promise
     return out
   }
 
+  // Session titles rarely change; cache them so listing shells stays one round trip.
+  const titles = new Map<string, { title: string | undefined; at: number }>()
+  const sessionTitle = async (sessionID: string): Promise<string | undefined> => {
+    const hit = titles.get(sessionID)
+    if (hit && Date.now() - hit.at < 60_000) return hit.title
+    const result = await opencode.session.get({ path: { id: sessionID } }).catch(() => undefined)
+    const title = (result?.data as { title?: string } | undefined)?.title
+    titles.set(sessionID, { title, at: Date.now() })
+    return title
+  }
+
   // 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
@@ -97,10 +108,11 @@ async function shellHooks({ client: opencode, directory }: PluginInput): Promise
       instance,
       quiet,
       env,
+      sessionTitle,
       shellCommand: (command) => ({ command: userShell, args: ["-c", command] }),
     }),
 
-    "experimental.chat.system.transform": async (_input, output) => {
+    "experimental.chat.system.transform": async (input, output) => {
       output.system.push(GUIDANCE)
       const running = await cockpit
         .call("shell.list", { owner: { project: directory }, includeExited: false })
@@ -109,7 +121,14 @@ async function shellHooks({ client: opencode, directory }: PluginInput): Promise
         output.system.push(
           `Background shells currently running in this project:\n${running
             .slice(0, 15)
-            .map((s) => `- ${s.id} ${s.title} (${describeStatus(s)})`)
+            .map((s) => {
+              const from = !s.owner.session
+                ? ", started by the user"
+                : s.owner.session === input.sessionID
+                  ? ""
+                  : ", another session"
+              return `- ${s.id} "${s.title}" (${describeStatus(s)}${from})`
+            })
             .join("\n")}`,
         )
       }

package/src/tools/find.ts

@@ -0,0 +1,80 @@
+import type { ShellInfo } from "@opencode-cockpit/protocol/shell"
+
+/** The command as written, without the `$SHELL -c` wrapper. */
+export function commandOf(s: ShellInfo): string {
+  return s.args.length === 2 && s.args[0] === "-c" ? (s.args[1] as string) : [s.command, ...s.args].join(" ")
+}
+
+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 function isFailed(s: ShellInfo): boolean {
+  return s.status === "failed" || (s.status === "exited" && s.exitCode !== 0)
+}
+
+export function filterShells(list: readonly ShellInfo[], filter: ShellFilter): ShellInfo[] {
+  const query = filter.query?.trim().toLowerCase()
+  return list.filter((s) => {
+    if (query && !s.title.toLowerCase().includes(query) && !commandOf(s).toLowerCase().includes(query)) {
+      return false
+    }
+    switch (filter.status ?? "any") {
+      case "running":
+        if (s.status !== "running") return false
+        break
+      case "failed":
+        if (!isFailed(s)) return false
+        break
+      case "finished":
+        if (s.status === "running") return false
+        break
+    }
+    switch (filter.session ?? "any") {
+      case "this":
+        return s.owner.session === filter.currentSession
+      case "others":
+        return s.owner.session !== filter.currentSession
+      default:
+        return true
+    }
+  })
+}
+
+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 function matchByName(list: readonly ShellInfo[], name: string): NameMatch {
+  const wanted = name.trim().toLowerCase()
+  const exact = list.filter((s) => s.title.trim().toLowerCase() === wanted)
+  const matches =
+    exact.length > 0
+      ? exact
+      : list.filter(
+          (s) => s.title.toLowerCase().includes(wanted) || commandOf(s).toLowerCase().includes(wanted),
+        )
+
+  if (matches.length === 0) return { kind: "none", available: [...list] }
+  if (matches.length === 1) return { kind: "found", shell: matches[0] as ShellInfo, alsoMatched: [] }
+  const running = matches.filter((s) => s.status === "running")
+  if (running.length === 1) {
+    const shell = running[0] as ShellInfo
+    return { kind: "found", shell, alsoMatched: matches.filter((s) => s !== shell) }
+  }
+  return { kind: "ambiguous", candidates: matches }
+}

package/src/tools/index.ts

@@ -2,6 +2,7 @@ import { type ToolContext, type ToolDefinition, tool } from "@opencode-ai/plugin
 import type { CockpitClient } from "@opencode-cockpit/client"
 import { RpcError } from "@opencode-cockpit/protocol"
 import type { ShellInfo } from "@opencode-cockpit/protocol/shell"
+import { commandOf, filterShells, matchByName, type SessionFilter, type StatusFilter } from "./find.ts"
 import { describeStatus, formatLines, formatRead, formatWait, header } from "./format.ts"
 import { encodeKey, KEY_NAMES } from "./keys.ts"
 
@@ -13,10 +14,21 @@ export interface ToolDeps {
   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>
 }
 
 const z = tool.schema
-const ID = z.string().describe("Shell id from shell_start or shell_list, e.g. sh_ab12cd34")
+/** Every per-shell tool takes either an id or a name. */
+const TARGET = {
+  id: z.string().optional().describe("Shell id from shell_start or shell_list, e.g. sh_ab12cd34"),
+  name: z
+    .string()
+    .optional()
+    .describe(
+      'Instead of id: the shell\'s name (the description it was started with), e.g. "DB Monitoring". Partial names and command text also match.',
+    ),
+}
 
 const START = `Start a command in a background terminal (PTY) that keeps running while you continue working.
 
@@ -67,6 +79,51 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
     return formatRead(current, page)
   }
 
+  const sessionLabel = async (s: ShellInfo, ctx: ToolContext): Promise<string> => {
+    const session = s.owner.session
+    if (!session) return "started by the user"
+    if (session === ctx.sessionID) return "this session"
+    const title = await deps.sessionTitle?.(session).catch(() => undefined)
+    return title ? `session "${title}"` : `another session (${session})`
+  }
+
+  /** Turns `{ id }` or `{ name }` into a shell id, or explains why it cannot. */
+  const resolve = async (
+    args: { id?: string | null; name?: string | null },
+    ctx: ToolContext,
+  ): Promise<{ id: string; note: string }> => {
+    if (args.id) return { id: args.id, note: "" }
+    if (!args.name) throw new Error("pass the shell's id or name")
+    const shells = await client.call("shell.list", { owner: { project: ctx.directory } })
+    const match = matchByName(shells, args.name)
+    const describe = async (list: ShellInfo[]) =>
+      (
+        await Promise.all(
+          list.map(
+            async (s) =>
+              `- ${s.id} "${s.title}" · ${s.status} · ${await sessionLabel(s, ctx)} · $ ${commandOf(s).slice(0, 80)}`,
+          ),
+        )
+      ).join("\n")
+    if (match.kind === "found") {
+      const note =
+        match.alsoMatched.length > 0
+          ? `(name "${args.name}" also matched ${match.alsoMatched.length} finished shell${match.alsoMatched.length === 1 ? "" : "s"}; using the running one, ${match.shell.id})\n`
+          : ""
+      return { id: match.shell.id, note }
+    }
+    if (match.kind === "ambiguous") {
+      throw new Error(
+        `"${args.name}" matches several shells; pass one of these ids:\n${await describe(match.candidates)}`,
+      )
+    }
+    throw new Error(
+      match.available.length === 0
+        ? `no shell matches "${args.name}": there are no shells in this project`
+        : `no shell matches "${args.name}". Shells in this project:\n${await describe(match.available.slice(0, 15))}`,
+    )
+  }
+
   return {
     shell_start: tool({
       description: START,
@@ -154,7 +211,7 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
     shell_read: tool({
       description: READ,
       args: {
-        id: ID,
+        ...TARGET,
         view: z.enum(["log", "screen"]).default("log"),
         after: z
           .number()
@@ -173,12 +230,13 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
         ignoreCase: z.boolean().default(false),
         limit: z.number().int().positive().max(2000).default(300),
       },
-      async execute(args) {
-        const info = await client.call("shell.get", { id: args.id })
+      async execute(args, ctx) {
+        const { id, note } = await resolve(args, ctx)
+        const info = await client.call("shell.get", { id })
         if (args.view === "screen") {
-          const screen = await client.call("shell.screen", { id: args.id })
+          const screen = await client.call("shell.screen", { id })
           return [
-            header(info),
+            `${note}${header(info)}`,
             `status: ${describeStatus(info)}`,
             `screen ${screen.cols}x${screen.rows}:`,
             screen.text || "(blank)",
@@ -186,21 +244,21 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
           ].join("\n")
         }
         const page = await client.call("shell.read", {
-          id: args.id,
+          id,
           after: args.after ?? undefined,
           tail: args.tail ?? 60,
           grep: args.grep ?? undefined,
           ignoreCase: args.ignoreCase ?? false,
           limit: args.limit ?? 300,
         })
-        return formatRead(info, page, args.after !== undefined ? "(no new output)" : "(no output yet)")
+        return note + formatRead(info, page, args.after != null ? "(no new output)" : "(no output yet)")
       },
     }),
 
     shell_send: tool({
       description: SEND,
       args: {
-        id: ID,
+        ...TARGET,
         text: z.string().optional(),
         keys: z.array(z.string()).optional(),
         submit: z.boolean().default(false).describe("Press enter after text"),
@@ -211,26 +269,30 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
         let data = args.text ?? ""
         for (const key of args.keys ?? []) data += encodeKey(key)
         if (args.submit === true) data += "\r"
-        const before = await client.call("shell.get", { id: args.id })
-        await client.call("shell.write", { id: args.id, data })
+        const { id, note } = await resolve(args, ctx)
+        const before = await client.call("shell.get", { id })
+        await client.call("shell.write", { id, data })
         const waitSeconds = args.waitSeconds ?? 1
         if (waitSeconds > 0) {
           await abortable(
             ctx,
             client.call("shell.wait", {
-              id: args.id,
+              id,
               until: { idleMs: 400, exit: true },
               timeoutMs: Math.round(waitSeconds * 1000),
               after: before.lines.last,
             }),
           )
         }
-        const info = await client.call("shell.get", { id: args.id })
-        const page = await client.call("shell.read", { id: args.id, after: before.lines.last, limit: 300 })
-        return formatRead(
-          info,
-          page,
-          "(no new output lines; if this is a full-screen program use shell_read view=screen)",
+        const info = await client.call("shell.get", { id })
+        const page = await client.call("shell.read", { id, after: before.lines.last, limit: 300 })
+        return (
+          note +
+          formatRead(
+            info,
+            page,
+            "(no new output lines; if this is a full-screen program use shell_read view=screen)",
+          )
         )
       },
     }),
@@ -238,7 +300,7 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
     shell_wait: tool({
       description: WAIT,
       args: {
-        id: ID,
+        ...TARGET,
         pattern: z.string().optional(),
         ignoreCase: z.boolean().optional(),
         port: z.number().int().min(1).max(65535).optional(),
@@ -248,11 +310,12 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
         timeoutSeconds: z.number().positive().max(3600).default(300),
       },
       async execute(args, ctx) {
-        const start = await client.call("shell.get", { id: args.id })
+        const { id, note } = await resolve(args, ctx)
+        const start = await client.call("shell.get", { id })
         const result = await abortable(
           ctx,
           client.call("shell.wait", {
-            id: args.id,
+            id,
             until: {
               pattern: args.pattern ?? undefined,
               ignoreCase: args.ignoreCase ?? undefined,
@@ -268,8 +331,8 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
         const newLines = result.info.lines.last - start.lines.last
         const page =
           newLines > 80
-            ? await client.call("shell.read", { id: args.id, tail: 80 })
-            : await client.call("shell.read", { id: args.id, after: start.lines.last, limit: 80 })
+            ? await client.call("shell.read", { id, tail: 80 })
+            : await client.call("shell.read", { id, after: start.lines.last, limit: 80 })
         const recent = page.lines
         if (newLines > 80)
           recent.unshift({
@@ -277,7 +340,7 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
             text: `… ${newLines - 80} earlier lines omitted (shell_read after=${start.lines.last})`,
           })
         return [
-          formatWait(result, args.timeoutSeconds ?? 300),
+          note + formatWait(result, args.timeoutSeconds ?? 300),
           header(result.info),
           recent.length > 0 ? formatLines(recent) : "(no new output during the wait)",
           "</shell>",
@@ -287,30 +350,50 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
     }),
 
     shell_list: tool({
-      description: "List background shells for this project with status, uptime and last output line.",
+      description: `List background shells in this project: name, status, which session started it, and the last output line.
+
+Filter to find the one you need instead of reading them all:
+- query: text in the name or command, e.g. "db" or "vitest"
+- status: running, failed, finished
+- session: this (started by you in this session), others (other sessions or the user)`,
       args: {
+        query: z.string().optional().describe("Case-insensitive text in the shell name or command"),
+        status: z.enum(["running", "failed", "finished", "any"]).default("any"),
+        session: z.enum(["this", "others", "any"]).default("any"),
         all: z.boolean().default(false).describe("Include shells from other projects"),
       },
       async execute(args, ctx) {
-        const shells = await client.call(
+        const everything = await client.call(
           "shell.list",
           args.all === true ? {} : { owner: { project: ctx.directory } },
         )
-        if (shells.length === 0) return "No background shells."
+        const shells = filterShells(everything, {
+          query: args.query ?? undefined,
+          status: (args.status ?? "any") as StatusFilter,
+          session: (args.session ?? "any") as SessionFilter,
+          currentSession: ctx.sessionID,
+        })
+        if (everything.length === 0) return "No background shells."
+        if (shells.length === 0)
+          return `No shells match those filters (${everything.length} shell${everything.length === 1 ? "" : "s"} in total).`
         const rows = await Promise.all(
           shells.map(async (s) => {
             const last = await client.call("shell.read", { id: s.id, tail: 1 }).catch(() => undefined)
             const tail = last?.lines[0]?.text ?? ""
-            const command =
-              s.args[0] === "-c" && s.args.length === 2
-                ? (s.args[1] as string)
-                : [s.command, ...s.args].join(" ")
             const failure =
               s.summary && s.status !== "running" ? `\n    summary: ${s.summary.slice(0, 200)}` : ""
-            return `${s.id}  ${s.status.padEnd(7)}  ${s.title}${s.run > 1 ? ` (run ${s.run})` : ""}\n    $ ${command.slice(0, 200)}${failure}\n    ${describeStatus(s)}${tail ? `\n    last: ${tail.slice(0, 200)}` : ""}`
+            return [
+              `${s.id}  ${s.status.padEnd(7)}  "${s.title}"${s.run > 1 ? ` (run ${s.run})` : ""} · ${await sessionLabel(s, ctx)}`,
+              `    $ ${commandOf(s).slice(0, 200)}${failure}`,
+              `    ${describeStatus(s)}${tail ? `\n    last: ${tail.slice(0, 200)}` : ""}`,
+            ].join("\n")
           }),
         )
-        return rows.join("\n")
+        const hidden = everything.length - shells.length
+        return (
+          rows.join("\n") +
+          (hidden > 0 ? `\n(${hidden} more shell${hidden === 1 ? "" : "s"} hidden by filters)` : "")
+        )
       },
     }),
 
@@ -318,34 +401,36 @@ export function createTools(deps: ToolDeps): Record<string, ToolDefinition> {
       description:
         "Stop a background shell (SIGTERM to its whole process group, then SIGKILL after a grace period). Set remove=true to also forget it.",
       args: {
-        id: ID,
+        ...TARGET,
         remove: z.boolean().default(false),
         force: z.boolean().default(false).describe("Send SIGKILL immediately"),
       },
-      async execute(args) {
-        deps.quiet.add(args.id)
+      async execute(args, ctx) {
+        const { id, note } = await resolve(args, ctx)
+        deps.quiet.add(id)
         const info = await client.call("shell.stop", {
-          id: args.id,
+          id,
           signal: args.force === true ? "SIGKILL" : "SIGTERM",
           graceMs: 3000,
         })
-        if (args.remove === true) await client.call("shell.remove", { id: args.id })
-        return `${info.id} ${describeStatus(info)}${args.remove === true ? " and removed" : ""}`
+        if (args.remove === true) await client.call("shell.remove", { id })
+        return `${note}${info.id} ${describeStatus(info)}${args.remove === true ? " and removed" : ""}`
       },
     }),
 
     shell_restart: tool({
       description:
         "Restart a background shell with the same command. Keeps the id; output continues after a restart marker.",
-      args: { id: ID },
+      args: { ...TARGET },
       async execute(args, ctx) {
-        const info = await client.call("shell.restart", { id: args.id })
-        deps.quiet.delete(args.id)
+        const { id, note } = await resolve(args, ctx)
+        const info = await client.call("shell.restart", { id })
+        deps.quiet.delete(id)
         await abortable(
           ctx,
           client.call("shell.wait", { id: info.id, until: { idleMs: 700, exit: true }, timeoutMs: 2500 }),
         )
-        return `Restarted ${info.id} (run ${info.run})\n${await peek(info)}`
+        return `${note}Restarted ${info.id} (run ${info.run})\n${await peek(info)}`
       },
     }),
   }

package/src/tui/console.tsx

@@ -73,7 +73,7 @@ export function Console(props: ConsoleProps) {
   })
   const failure = createMemo(() => {
     const s = shell()
-    if (!s || !s.summary) return undefined
+    if (!s?.summary) return undefined
     const kind = kindOf(s)
     return kind === "fail" || kind === "stop" ? s.summary : undefined
   })