opencode-ghost 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-09-24
+
+### Added
+
+- Optional Left-arrow navigation back to the home screen from an empty prompt.
+- Recovery of abandoned hidden suggestion sessions via a periodic sweep that
+  needs no configuration (an optional marker directory adds extra
+  crash-recovery tracking).
+
+### Fixed
+
+- Prevent suggestions from repeating the user's previous message.
+- Trigger suggestions from the current session-status idle event.
+- Remove hidden suggestion sessions and their markers when generation fails:
+  deletion now passes the session directory, and a periodic sweep retries
+  abandoned sessions (including corrupt or zero-byte markers) instead of
+  leaving them behind for the life of the TUI process.
+- Delete hidden suggestion sessions reliably: every hidden-session call is
+  scoped to the visible session's project directory, hidden sessions carry a
+  metadata tag that survives the server's automatic title generation, a
+  configuration-free sweep reaps leftovers by listing sessions, and shutdown
+  deletes in-flight generations. Marker-tracked sessions are removed even
+  after being retitled.
+## [0.1.0] - 2026-09-21
+
+### Added
+
+- Next-prompt suggestions for the opencode TUI: after each turn a model reads
+  the recent conversation and writes one short message in the user's voice.
+- The suggestion renders under the prompt and is accepted with `Tab` or `→`,
+  dropping it into the input to edit or send.
+- `/suggest` toggles suggestions on and off; the state is persisted in the
+  plugin KV.
+- Options for `model`, `acceptKeys`, `maxChars`, `idleDelayMs`,
+  `recentMessages` and `system`.
+
+[Unreleased]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/ozandogrultan/opencode-ghost/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/ozandogrultan/opencode-ghost/releases/tag/v0.1.0

package/README.md

@@ -87,6 +87,8 @@ Pass an options object as the second element of the plugin tuple:
 | `idleDelayMs`    | `number`   | `500`                 | Debounce after a turn finishes before generating.                     |
 | `recentMessages` | `number`   | `10`                  | How many recent messages feed the suggestion prompt.                  |
 | `system`         | `string`   | built-in              | Override the system prompt sent to the suggestion model.              |
+| `backOnEmptyLeft` | `boolean`  | `false`               | Return to the home screen with Left when the prompt is empty.         |
+| `internalSessionMarkerDir` | `string` | unset       | Optional extra crash-recovery tracking. A configuration-free sweep already reaps leftover hidden sessions, so this is only an additional safety net. |
 
 ## Commands
 
@@ -100,7 +102,11 @@ When enabling, a suggestion is generated immediately for the current session.
   session's recent messages.
 - Asks a model (your `small_model` by default) for one short next user message,
   in a throwaway hidden session with tools disabled; the session is deleted
-  immediately afterwards.
+  immediately afterwards. Every hidden-session call is scoped to the current
+  session's project directory, hidden sessions carry a metadata tag that
+  survives the server's automatic title generation, and a periodic sweep (plus
+  shutdown cleanup) reaps any leftovers — including sessions orphaned by a
+  crash — with no configuration required.
 - Renders the result through the `session_prompt` host slot into the prompt's
   `hint` row, and accepts it into the input via the prompt ref.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ghost",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Claude Code-style next-prompt suggestions in the opencode TUI, shown as dimmed ghost text and accepted with Tab. An opencode plugin.",
   "type": "module",
   "license": "MIT",
@@ -18,12 +18,19 @@
   },
   "files": [
     "src",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test"
+    "test": "bun test && bash tests/changelog.sh",
+    "test:unit": "bun test",
+    "test:changelog": "bash tests/changelog.sh",
+    "prepublishOnly": "bun run test && bun run typecheck"
   },
   "engines": {
     "opencode": ">=1.18.0"

package/src/options.ts

@@ -2,6 +2,8 @@ export type PromptSuggestOptions = {
   enabled?: boolean
   model?: string
   acceptKeys?: string[]
+  backOnEmptyLeft?: boolean
+  internalSessionMarkerDir?: string
   maxChars?: number
   idleDelayMs?: number
   recentMessages?: number
@@ -12,6 +14,8 @@ export type ResolvedOptions = {
   enabled: boolean
   model: string | undefined
   acceptKeys: string[]
+  backOnEmptyLeft: boolean
+  internalSessionMarkerDir: string | undefined
   maxChars: number
   idleDelayMs: number
   recentMessages: number
@@ -20,11 +24,23 @@ export type ResolvedOptions = {
 
 export const DEFAULT_SYSTEM = [
   "You write the next message that the USER of a coding agent would send.",
-  "It must sound like the user, not the assistant: short and direct.",
-  "Never restate or summarize the assistant's reply.",
-  'If the assistant proposed a next step, a brief affirmation such as "Yes." or "Go ahead." is best.',
-  "If the assistant asked a question, answer it briefly.",
-  "Output one line, plain text only: no markdown, no quotes, no backticks, no preamble.",
+  "Write what the user says AFTER the assistant's latest reply.",
+  "",
+  "Rules:",
+  "- Move the conversation forward. Never repeat, quote, or paraphrase the user's own previous message.",
+  "- Sound like the user: short and direct, one line, plain text only.",
+  '- If the assistant proposed a next step, a brief affirmation such as "Yes." or "Go ahead." is best.',
+  "- If the assistant asked a question, answer it briefly.",
+  "- No markdown, no quotes, no backticks, no preamble.",
+  "",
+  "Examples:",
+  "Assistant: I ran the tests - 13 passed, 0 failed.",
+  "Next user message: great, thanks",
+  "Assistant: That changes the hook contract. Want me to proceed?",
+  "Next user message: yes, go ahead",
+  "Assistant: Which model should the small tasks use?",
+  "Next user message: the fast free one",
+  "",
   "If no reply makes sense, output exactly: NONE",
 ].join("\n")
 
@@ -48,6 +64,11 @@ export function resolveOptions(options: PromptSuggestOptions | undefined): Resol
       Array.isArray(input.acceptKeys) && input.acceptKeys.length > 0
         ? input.acceptKeys
         : [...DEFAULTS.acceptKeys],
+    backOnEmptyLeft: input.backOnEmptyLeft ?? false,
+    internalSessionMarkerDir:
+      typeof input.internalSessionMarkerDir === "string" && input.internalSessionMarkerDir.trim()
+        ? input.internalSessionMarkerDir.trim()
+        : undefined,
     maxChars: typeof maxChars === "number" && maxChars > 0 ? maxChars : DEFAULTS.maxChars,
     idleDelayMs:
       typeof idleDelayMs === "number" && idleDelayMs >= 0 ? idleDelayMs : DEFAULTS.idleDelayMs,

package/src/text.ts

@@ -32,3 +32,19 @@ export function normalize(raw: string, maxChars: number): string | undefined {
   if (cleaned.length <= maxChars) return cleaned
   return cleaned.slice(0, maxChars - 1).trimEnd() + "…"
 }
+
+export function isEcho(suggestion: string, previous: string): boolean {
+  const strip = (value: string) =>
+    value
+      .replace(/\s+/g, " ")
+      .trim()
+      .toLowerCase()
+      .replace(/[.!?,;:]+$/, "")
+  const next = strip(suggestion)
+  const last = strip(previous)
+  if (!next || !last) return false
+  if (next === last) return true
+  if (next.length >= 12 && last.includes(next)) return true
+  if (last.length >= 12 && next.includes(last)) return true
+  return false
+}

package/src/tui.tsx

@@ -1,10 +1,18 @@
 /** @jsxImportSource @opentui/solid */
 import type { TuiPlugin, TuiPromptRef } from "@opencode-ai/plugin/tui"
 import { createSignal } from "solid-js"
+import * as fs from "node:fs"
+import * as path from "node:path"
 import { resolveOptions, type PromptSuggestOptions } from "./options"
-import { clip, normalize, parseModel } from "./text"
+import { clip, isEcho, normalize, parseModel } from "./text"
 
 const HIDDEN_TITLE = "ghost-hidden"
+// Survives the server's automatic title generation, which renames the hidden
+// session after the first prompt and would otherwise make it invisible to a
+// title-based sweep.
+const GHOST_METADATA = { ghost: "opencode-ghost" } as const
+const ORPHAN_SWEEP_INTERVAL_MS = 30_000
+const ORPHAN_MIN_AGE_MS = 15_000
 const MAX_MESSAGE_CHARS = 800
 const MAX_TRANSCRIPT_CHARS = 6000
 const ENABLED_KEY = "ghost.enabled"
@@ -30,8 +38,226 @@ const HIDDEN_TOOLS = {
   lsp: false,
 }
 
+function markPending(dir: string, pending: string) {
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(pending, "")
+  } catch {
+    // best effort
+  }
+}
+
+function markSession(dir: string, pending: string, id: string, directory: string | undefined) {
+  try {
+    fs.writeFileSync(
+      path.join(dir, `id-${id}`),
+      JSON.stringify(directory ? { directory, pid: process.pid } : { pid: process.pid }),
+    )
+    fs.rmSync(pending, { force: true })
+  } catch {
+    // best effort
+  }
+}
+
+function unmarkSession(dir: string, pending: string, id: string | undefined, deleted: boolean) {
+  try {
+    fs.rmSync(pending, { force: true })
+  } catch {
+    // best effort
+  }
+  if (!id || !deleted) return
+  try {
+    fs.rmSync(path.join(dir, `id-${id}`), { force: true })
+  } catch {
+    // best effort
+  }
+}
+
+function isGhostSession(session: { title?: unknown; metadata?: unknown }): boolean {
+  if ((session as { title?: unknown }).title === HIDDEN_TITLE) return true
+  const metadata = (session as { metadata?: Record<string, unknown> }).metadata
+  return (
+    typeof metadata === "object" &&
+    metadata !== null &&
+    (metadata as Record<string, unknown>).ghost === GHOST_METADATA.ghost
+  )
+}
+
+function processIsRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH"
+  }
+}
+
+function isNotFound(error: unknown): boolean {
+  const candidate = error as { status?: number; response?: { status?: number }; message?: string }
+  const status = candidate?.status ?? candidate?.response?.status
+  if (status === 404) return true
+  return typeof candidate?.message === "string" && /not found/i.test(candidate.message)
+}
+
 const tui: TuiPlugin = async (api, rawOptions) => {
   const opts = resolveOptions(rawOptions as PromptSuggestOptions | undefined)
+  // In-flight hidden sessions (id -> directory). A Map so dispose and the
+  // sweep can scope get/delete calls even while a generation is running.
+  const activeHidden = new Map<string, string | undefined>()
+
+  // Directory of the visible session the suggestion belongs to, falling back
+  // to the TUI working directory. Every hidden-session call is scoped with it:
+  // the server resolves sessions per directory, and an unscoped call is the
+  // historical reason failed generations left sessions behind.
+  const resolveParentDirectory = (visibleSessionID: string): string | undefined => {
+    try {
+      const local = api.state.session.get(visibleSessionID) as { directory?: unknown } | undefined
+      if (typeof local?.directory === "string" && local.directory) return local.directory
+    } catch {
+      // fall through to the cwd
+    }
+    try {
+      const cwd = (api.state as { path?: { directory?: unknown } }).path?.directory
+      if (typeof cwd === "string" && cwd) return cwd
+    } catch {
+      // unavailable in some test harnesses; callers fall back to the
+      // server-reported directory instead.
+    }
+    return undefined
+  }
+
+  const markerPaths = () => {
+    const dir = opts.internalSessionMarkerDir
+    if (!dir) return [] as { entry: string; marker: string; ageMs: number }[]
+    let names: string[]
+    try {
+      names = fs.readdirSync(dir).filter((entry) => /^id-ses_[\w-]+$/.test(entry))
+    } catch {
+      return [] as { entry: string; marker: string; ageMs: number }[]
+    }
+    const now = Date.now()
+    return names.map((entry) => {
+      const marker = path.join(dir, entry)
+      let ageMs = Number.POSITIVE_INFINITY
+      try {
+        ageMs = now - fs.statSync(marker).mtimeMs
+      } catch {
+        // Unreadable mtime: treat as old so it gets swept.
+      }
+      return { entry, marker, ageMs }
+    })
+  }
+
+  // Deletes a ghost session and reports whether it is confirmed gone. A
+  // `directory` is passed whenever known: the server scopes deletion by it, and
+  // omitting it is why failed generations left sessions behind. A non-true
+  // delete response is re-checked by existence rather than assumed to have
+  // failed, so a session already removed (or removed concurrently) still counts
+  // as gone and its marker is not kept forever.
+  const removeHiddenSession = async (sessionID: string, directory?: string): Promise<boolean> => {
+    const target = directory ? { sessionID, directory } : { sessionID }
+    try {
+      const result = await api.client.session.delete(target)
+      if (result.data === true) return true
+    } catch (error) {
+      // Only a definitive "not found" means it is gone; anything else (server
+      // down, permissions) must keep the marker so a later sweep retries.
+      return isNotFound(error)
+    }
+    try {
+      await api.client.session.get(target)
+      return false
+    } catch (error) {
+      return isNotFound(error)
+    }
+  }
+
+  // Reaps abandoned ghost sessions in this process and from crashed ones. Two
+  // phases:
+  //
+  // - Marker files (when `internalSessionMarkerDir` is configured) are
+  //   authoritative proof this plugin created the session, so they are deleted
+  //   regardless of title: the server auto-titles the hidden session after the
+  //   first prompt, and the old title check let every retitled orphan live
+  //   forever. It deliberately does not skip markers by owner pid anymore: a
+  //   failed delete in a still-running TUI left its own markers behind forever,
+  //   because the old startup-only recovery treated a live pid as
+  //   "not orphaned". Fresh markers (younger than ORPHAN_MIN_AGE_MS) whose
+  //   owner is still running are left alone so an in-flight generation in
+  //   another process is not swept mid-write.
+  // - A list-based sweep needs no configuration and catches everything the
+  //   markers miss (default setup, older versions, deleted marker dirs). Only
+  //   sessions still identifiable as ghost (title or metadata tag) and quiet
+  //   past the grace window are deleted, and never in-flight generations of
+  //   this process.
+  const sweepOrphans = async () => {
+    for (const { entry, marker, ageMs } of markerPaths()) {
+      const sessionID = entry.slice(3)
+      if (activeHidden.has(sessionID)) continue
+      let directory: string | undefined
+      let pid: number | undefined
+      try {
+        const parsed = JSON.parse(fs.readFileSync(marker, "utf8")) as {
+          directory?: string
+          pid?: number
+        }
+        if (typeof parsed?.directory === "string" && parsed.directory) directory = parsed.directory
+        if (Number.isInteger(parsed?.pid) && (parsed.pid as number) > 0) pid = parsed.pid as number
+      } catch {
+        // Corrupt/empty marker: no directory or pid; still attempt cleanup.
+      }
+      // A fresh marker whose owner is still running may be an in-flight
+      // generation in another TUI. A dead owner, or one quiet past the grace
+      // window, is an orphan.
+      if (pid !== undefined && ageMs < ORPHAN_MIN_AGE_MS && processIsRunning(pid)) continue
+
+      if (await removeHiddenSession(sessionID, directory)) {
+        try {
+          fs.rmSync(marker, { force: true })
+        } catch {
+          // best effort
+        }
+      }
+    }
+
+    try {
+      const listed = await api.client.session.list()
+      const sessions = (listed as { data?: unknown }).data
+      if (!Array.isArray(sessions)) return
+      const now = Date.now()
+      for (const session of sessions) {
+        const candidate = session as {
+          id?: unknown
+          title?: unknown
+          metadata?: unknown
+          directory?: unknown
+          time?: { created?: unknown; updated?: unknown }
+        }
+        if (typeof candidate.id !== "string" || !candidate.id) continue
+        if (activeHidden.has(candidate.id)) continue
+        if (!isGhostSession(candidate)) continue
+        const updated =
+          typeof candidate.time?.updated === "number"
+            ? candidate.time.updated
+            : typeof candidate.time?.created === "number"
+              ? candidate.time.created
+              : undefined
+        if (updated !== undefined && now - updated < ORPHAN_MIN_AGE_MS) continue
+        const directory =
+          typeof candidate.directory === "string" && candidate.directory
+            ? candidate.directory
+            : undefined
+        await removeHiddenSession(candidate.id, directory)
+      }
+    } catch {
+      // Listing is best effort (server down, older SDK): markers and the
+      // generation finally-block still cover the common cases.
+    }
+  }
+  void sweepOrphans()
+  const sweepTimer = setInterval(() => void sweepOrphans(), ORPHAN_SWEEP_INTERVAL_MS)
+  sweepTimer.unref?.()
+
   const [ghost, setGhost] = createSignal<{ sessionID: string; text: string } | undefined>()
   let promptRef: TuiPromptRef | undefined
   let timer: ReturnType<typeof setTimeout> | undefined
@@ -96,17 +322,49 @@ const tui: TuiPlugin = async (api, rawOptions) => {
     return `${lines.join("\n").slice(-MAX_TRANSCRIPT_CHARS)}\n\nTask: write the user's next message.`
   }
 
+  const lastUserText = (sessionID: string) => {
+    const message = api.state.session.messages(sessionID).filter((m) => m.role === "user").at(-1)
+    if (!message) return ""
+    return api.state
+      .part(message.id)
+      .filter((part) => part.type === "text")
+      .map((part) => (part.type === "text" ? part.text : ""))
+      .join(" ")
+  }
+
   const generate = async (sessionID: string): Promise<string | undefined> => {
     const transcript = buildTranscript(sessionID)
     if (!transcript) return undefined
 
-    const created = await api.client.session.create({ title: HIDDEN_TITLE })
-    const tempID = created.data?.id
-    if (!tempID) return undefined
+    const markerDir = opts.internalSessionMarkerDir
+    const pending = markerDir ? path.join(markerDir, "pending") : undefined
+    if (markerDir && pending) markPending(markerDir, pending)
 
+    let tempID: string | undefined
+    let createdDirectory: string | undefined
+    // Scope every hidden-session call to the visible session's project: the
+    // server resolves sessions per directory, and unscoped calls left orphans
+    // behind whenever the default differed.
+    const parentDirectory = resolveParentDirectory(sessionID)
     try {
+      const created = await api.client.session.create({
+        title: HIDDEN_TITLE,
+        metadata: { ...GHOST_METADATA },
+        ...(parentDirectory ? { directory: parentDirectory } : {}),
+      })
+      tempID = created.data?.id
+      if (!tempID) return undefined
+      createdDirectory =
+        typeof created.data?.directory === "string" && created.data.directory
+          ? created.data.directory
+          : parentDirectory
+      activeHidden.set(tempID, createdDirectory)
+      if (markerDir && pending)
+        markSession(markerDir, pending, tempID, createdDirectory ?? parentDirectory ?? "")
+
       const result = await api.client.session.prompt({
         sessionID: tempID,
+        ...(createdDirectory ? { directory: createdDirectory } : {}),
         system: opts.system,
         tools: { ...HIDDEN_TOOLS },
         model: resolveModel(),
@@ -117,9 +375,21 @@ const tui: TuiPlugin = async (api, rawOptions) => {
         .filter((part) => part.type === "text")
         .map((part) => (part.type === "text" ? part.text : ""))
         .join("\n")
-      return normalize(raw, opts.maxChars)
+      const suggestion = normalize(raw, opts.maxChars)
+      if (!suggestion) return undefined
+      const previous = lastUserText(sessionID)
+      if (previous && isEcho(suggestion, previous)) return undefined
+      return suggestion
     } finally {
-      await api.client.session.delete({ sessionID: tempID }).catch(() => undefined)
+      let deleted = false
+      if (tempID) {
+        activeHidden.delete(tempID)
+        // Pass the directory and retry-based confirmation so a failed
+        // generation still removes its hidden session. If the session truly
+        // cannot be removed yet, the marker is kept and sweepOrphans retries.
+        deleted = await removeHiddenSession(tempID, createdDirectory)
+      }
+      if (markerDir && pending) unmarkSession(markerDir, pending, tempID, deleted)
     }
   }
 
@@ -197,6 +467,35 @@ const tui: TuiPlugin = async (api, rawOptions) => {
     schedule(id)
   })
 
+  // session.idle is deprecated upstream; the live signal is session.status.
+  const offStatus = api.event.on("session.status", (event) => {
+    const props = event.properties
+    if (props?.status?.type !== "idle") return
+    if (!props.sessionID) return
+    schedule(props.sessionID)
+  })
+
+  const backLayer = api.keymap.registerLayer({
+    mode: "base",
+    priority: 40,
+    bindings: [
+      {
+        key: "left",
+        desc: "Return to the home screen when the prompt is empty",
+        preventDefault: false,
+        fallthrough: true,
+        cmd: () => {
+          if (!opts.backOnEmptyLeft) return false
+          if (api.route.current.name !== "session") return false
+          if (!promptRef) return false
+          if (currentInput().trim().length > 0) return false
+          api.route.navigate("home")
+          return true
+        },
+      },
+    ],
+  })
+
   api.slots.register({
     order: 60,
     slots: {
@@ -263,8 +562,19 @@ const tui: TuiPlugin = async (api, rawOptions) => {
 
   api.lifecycle.onDispose(() => {
     if (timer) clearTimeout(timer)
+    clearInterval(sweepTimer)
     offIdle()
+    offStatus()
+    backLayer()
     disableAccept()
+    // A generation in flight at shutdown would otherwise leak its hidden
+    // session: the finally-block still runs for the awaiting caller, but if
+    // the host drops pending work, fire one last scoped delete per session.
+    // The periodic sweep (markers + list) retries anything this misses.
+    for (const [sessionID, directory] of activeHidden) {
+      void removeHiddenSession(sessionID, directory).catch(() => {})
+    }
+    activeHidden.clear()
   })
 }