opencode-codeops 2.1.1 → 2.2.1

package/bin/lib/codeops-rpc.d.mts

@@ -0,0 +1,160 @@
+/**
+ * Type declarations for the CodeOps RPC helper.
+ *
+ * The helper is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entries typed access. The
+ * definition carries the status method, the progress method, and the
+ * updated/cleared events.
+ */
+
+import type {
+  CodeOpsProgressRuntime,
+  CodeOpsRunClearedSchema,
+  CodeOpsRunState,
+  CodeOpsRunStateSchema,
+} from "./codeops-progress.mjs"
+
+/** JSON-Schema shape of the empty input accepted by the `status` method. */
+export type CodeOpsRpcStatusInput = {
+  readonly type: "object"
+  readonly additionalProperties: false
+}
+
+/** JSON-Schema shape of the payload the `status` method returns. */
+export type CodeOpsRpcStatusOutput = {
+  readonly type: "object"
+  readonly additionalProperties: false
+  readonly required: readonly ["pluginVersion", "openCodeVersion", "directory"]
+  readonly properties: {
+    readonly pluginVersion: { readonly type: "string" }
+    readonly openCodeVersion: { readonly type: "string" }
+    readonly directory: { readonly type: "string" }
+  }
+}
+
+/** The status payload after runtime validation. */
+export interface CodeOpsStatus {
+  readonly pluginVersion: string
+  readonly openCodeVersion: string
+  readonly directory: string
+}
+
+/** JSON-Schema shape of the empty input accepted by the `progress` method. */
+export type CodeOpsRpcProgressInput = {
+  readonly type: "object"
+  readonly additionalProperties: false
+}
+
+/** JSON-Schema shape of the `progress` method's payload: a snapshot or null. */
+export type CodeOpsRpcProgressOutput = {
+  readonly anyOf: readonly [CodeOpsRunStateSchema, { readonly type: "null" }]
+}
+
+/** The `updated` event of the codeops RPC: the full run snapshot. */
+export interface CodeOpsRpcUpdatedEvent {
+  readonly schema: CodeOpsRunStateSchema
+}
+
+/** The `cleared` event of the codeops RPC: the cleared run's identity. */
+export interface CodeOpsRpcClearedEvent {
+  readonly schema: CodeOpsRunClearedSchema
+}
+
+/** The portable RPC definition shared by the server plugin and the TUI entry. */
+export interface CodeOpsRpcDefinition {
+  readonly id: "codeops"
+  readonly methods: {
+    readonly status: {
+      readonly input: CodeOpsRpcStatusInput
+      readonly output: CodeOpsRpcStatusOutput
+    }
+    readonly progress: {
+      readonly input: CodeOpsRpcProgressInput
+      readonly output: CodeOpsRpcProgressOutput
+    }
+  }
+  readonly events: {
+    readonly updated: CodeOpsRpcUpdatedEvent
+    readonly cleared: CodeOpsRpcClearedEvent
+  }
+}
+
+/** The shared definition object; plain data with no runtime imports. */
+export declare const CodeOpsRpc: CodeOpsRpcDefinition
+
+/** Options accepted by {@link registerCodeOpsRpc}. */
+export interface RegisterCodeOpsRpcOptions {
+  /** Version of the installed package, reported by the status method. */
+  pluginVersion?: string
+  /** The run-state runtime the progress method serves and binds emission from. */
+  runtime?: CodeOpsProgressRuntime
+}
+
+/**
+ * Feature-detect `ctx.rpc.register`, register the codeops RPC when present,
+ * and report success. Never throws.
+ */
+export declare function registerCodeOpsRpc(
+  ctx: unknown,
+  options?: RegisterCodeOpsRpcOptions
+): Promise<boolean>
+
+/** Validate an unknown RPC payload as a complete CodeOps status record. */
+export declare function isCodeOpsStatus(value: unknown): value is CodeOpsStatus
+
+/** The location a status call is scoped to. */
+export interface CodeOpsLocation {
+  readonly directory: string
+  readonly workspaceID?: string
+}
+
+/** Call options forwarded to the status call. */
+export interface CodeOpsCallOptions {
+  readonly location?: CodeOpsLocation
+}
+
+/** Structural client shape {@link requestStatus} consumes. */
+export interface CodeOpsStatusClient {
+  readonly rpc: (definition: CodeOpsRpcDefinition) => {
+    readonly status: (
+      input: Record<string, never>,
+      options?: CodeOpsCallOptions
+    ) => Promise<unknown>
+  }
+}
+
+/**
+ * Request the raw status payload from a host client, converting every
+ * transport failure into `undefined`.
+ *
+ * Pass the calling session's location in `options`: the host resolves RPC
+ * calls against it, and a call without one can miss the plugin's registration
+ * when the session's project differs from the host's default location.
+ */
+export declare function requestStatus(
+  client: CodeOpsStatusClient,
+  options?: CodeOpsCallOptions
+): Promise<unknown>
+
+/** Structural client shape {@link requestProgress} consumes. */
+export interface CodeOpsProgressClient {
+  readonly rpc: (definition: CodeOpsRpcDefinition) => {
+    readonly progress: (
+      input: Record<string, never>,
+      options?: CodeOpsCallOptions
+    ) => Promise<unknown>
+  }
+}
+
+/**
+ * Request the current run snapshot from a host client, converting every
+ * transport failure into `null`.
+ *
+ * Pass the calling session's location in `options`: the host resolves RPC
+ * calls against it, and a call without one can miss the plugin's registration
+ * when the session's project differs from the host's default location.
+ */
+export declare function requestProgress(
+  client: CodeOpsProgressClient,
+  options?: CodeOpsCallOptions
+): Promise<CodeOpsRunState | null>

package/bin/lib/codeops-rpc.mjs

@@ -0,0 +1,177 @@
+/**
+ * The CodeOps RPC: definition, registration guard, payload guard, and the
+ * progress snapshot helper.
+ *
+ * The definition is plain data — the SDK's `Rpc.define` performs identity and
+ * reserved-name validation only — so this module needs no runtime import of
+ * the SDK and `node --test` can exercise it directly. The definition carries
+ * the `status` method, the `progress` method that answers with the current run
+ * snapshot, and the `updated`/`cleared` events the sidebar follows. The
+ * registration guard keeps the surface safe on builds that do not implement
+ * custom RPCs: it never throws and reports success with a boolean. When the
+ * host returns a registration exposing `events.emit`, the guard binds the
+ * runtime's emission through it, so accepted reports push live updates.
+ *
+ * @module codeops-rpc
+ */
+
+import { RunClearedSchema, RunStateSchema, isCodeOpsRunState } from "./codeops-progress.mjs"
+
+/**
+ * The portable `codeops` RPC definition shared by the server plugin and the
+ * TUI entry: a `status` method with an empty-object input and a three-string
+ * payload, a `progress` method answering with the current run snapshot (or
+ * `null`), and the `updated`/`cleared` events that push every accepted change.
+ */
+export const CodeOpsRpc = {
+  id: "codeops",
+  methods: {
+    status: {
+      input: { type: "object", additionalProperties: false },
+      output: {
+        type: "object",
+        additionalProperties: false,
+        required: ["pluginVersion", "openCodeVersion", "directory"],
+        properties: {
+          pluginVersion: { type: "string" },
+          openCodeVersion: { type: "string" },
+          directory: { type: "string" },
+        },
+      },
+    },
+    progress: {
+      input: { type: "object", additionalProperties: false },
+      output: { anyOf: [RunStateSchema, { type: "null" }] },
+    },
+  },
+  events: {
+    updated: { schema: RunStateSchema },
+    cleared: { schema: RunClearedSchema },
+  },
+}
+
+/**
+ * Coerce an optional host value to the string form the payload requires.
+ *
+ * @param value - Value reported by the host context.
+ * @returns The value as a string, or an empty string when it is absent.
+ */
+function asText(value) {
+  return value === undefined || value === null ? "" : String(value)
+}
+
+/**
+ * Register the codeops RPC on a plugin context, feature-detected and
+ * never-throwing.
+ *
+ * When a runtime is supplied, the `progress` method answers with its current
+ * snapshot and — if the returned registration exposes `events.emit` — the
+ * runtime binds its emission through that function, so every accepted report
+ * or clear pushes a live event.
+ *
+ * @param ctx - Server plugin context; only `rpc.register`, `app.version`, and
+ *   `location.directory` are read.
+ * @param {{ pluginVersion?: string, runtime?: object }} [options] -
+ *   Registration options.
+ * @returns `true` when the registration call completed, `false` when the host
+ *   lacks the RPC API or the registration failed. Never throws.
+ */
+export async function registerCodeOpsRpc(ctx, { pluginVersion, runtime } = {}) {
+  if (typeof ctx?.rpc?.register !== "function") return false
+  try {
+    const registration = await ctx.rpc.register(CodeOpsRpc, {
+      async status() {
+        return {
+          pluginVersion: asText(pluginVersion),
+          openCodeVersion: asText(ctx?.app?.version),
+          directory: asText(ctx?.location?.directory),
+        }
+      },
+      // The host adapter requires handlers to return promises; a synchronous
+      // return fails the call. async even though nothing is awaited.
+      async progress() {
+        return runtime?.snapshot() ?? null
+      },
+    })
+    if (
+      runtime &&
+      typeof runtime.bindEmit === "function" &&
+      typeof registration?.events?.emit === "function"
+    ) {
+      runtime.bindEmit(registration.events.emit)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Validate an unknown RPC payload as a complete CodeOps status record.
+ *
+ * @param value - Value received from the RPC.
+ * @returns `true` only for a plain object carrying exactly the three string
+ *   fields of the contract.
+ */
+export function isCodeOpsStatus(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  if (Object.keys(value).length !== 3) return false
+  return (
+    typeof value.pluginVersion === "string" &&
+    typeof value.openCodeVersion === "string" &&
+    typeof value.directory === "string"
+  )
+}
+
+/**
+ * Request the codeops status payload from a host client, converting every
+ * transport failure into `undefined`.
+ *
+ * A caller can therefore render from the result without a `catch`: a host
+ * without the RPC, a server plugin that failed to register, and a failed call
+ * all collapse into the same "no status" outcome. The payload is returned as
+ * received; narrow it with {@link isCodeOpsStatus} before use.
+ *
+ * Pass the calling session's location in `options`. The host resolves RPC
+ * calls against a location, and a call without one can miss the plugin's
+ * registration — the default location does not necessarily match a project
+ * opened through a path argument.
+ *
+ * @param client - Host client exposing `rpc(definition).status({}, options)`.
+ * @param {{ location?: { directory?: string, workspaceID?: string } }} [options]
+ *   - Call options forwarded to the status call.
+ * @returns The raw status payload, or `undefined` when the call fails.
+ */
+export async function requestStatus(client, options) {
+  try {
+    return await client.rpc(CodeOpsRpc).status({}, options)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Request the current run snapshot from a host client, converting every
+ * failure into `null`.
+ *
+ * Pass the calling session's location in `options`, for the same reason as
+ * {@link requestStatus}: the host resolves RPC calls against a location, and
+ * a call without one can miss the plugin's registration. The payload is
+ * validated before it is returned, so an invalid payload, a "no run" answer,
+ * and any transport failure all collapse into `null` and the caller can
+ * render without a `catch`.
+ *
+ * @param client - Host client exposing `rpc(definition).progress({}, options)`.
+ * @param {{ location?: { directory?: string, workspaceID?: string } }} [options]
+ *   - Call options forwarded to the progress call.
+ * @returns The validated snapshot, or `null` when no run is active or the
+ *   call failed. Never throws.
+ */
+export async function requestProgress(client, options) {
+  try {
+    const payload = await client.rpc(CodeOpsRpc).progress({}, options)
+    return isCodeOpsRunState(payload) ? payload : null
+  } catch {
+    return null
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {
@@ -10,13 +10,15 @@
   "main": "./plugin/index.ts",
   "exports": {
     ".": "./plugin/index.ts",
-    "./server": "./plugin/index.ts"
+    "./server": "./plugin/index.ts",
+    "./tui": "./plugin/tui.js"
   },
   "bin": {
     "opencode-codeops": "bin/index.mjs"
   },
   "scripts": {
     "test": "node --test",
+    "build:tui": "node scripts/build-tui.mjs",
     "typecheck": "tsc --noEmit",
     "check:version": "node scripts/check-version.mjs",
     "verify": "npm run typecheck && npm run test && npm run check:version",
@@ -24,6 +26,8 @@
   },
   "files": [
     "plugin/",
+    "!plugin/*.test.mjs",
+    "!plugin/*.spec.test.mjs",
     "skills/",
     "_shared/",
     "standards/",
@@ -68,7 +72,26 @@
     "@opencode/plugin": "^2.0.24"
   },
   "devDependencies": {
+    "@opentui/core": "0.5.17",
+    "@opentui/solid": "0.5.17",
     "@types/node": "^22.20.2",
+    "solid-js": "1.9.12",
     "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.14",
+    "@opentui/solid": ">=0.5.14",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": {
+      "optional": true
+    },
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
   }
 }

package/plugin/index.ts

@@ -9,6 +9,11 @@ import {
   cleanStaleTmpDirs,
   ensureSessionTmpDir,
 } from "../bin/lib/tmp-hygiene.mjs"
+import {
+  createCodeOpsProgress,
+  registerCodeOpsProgressTool,
+} from "../bin/lib/codeops-progress.mjs"
+import { registerCodeOpsRpc } from "../bin/lib/codeops-rpc.mjs"
 import {
   appendEffortTrace,
   applyEffort,
@@ -223,6 +228,11 @@ export default Plugin.define({
     const warnedEffortLevels = new Set<string>()
     const effortTraceEnabled = isEffortTraceEnabled(process.env.CODEOPS_EFFORT_TRACE)
 
+    // The live run state is memory-only, for the lifetime of this plugin
+    // instance: it is never persisted and clears when the reporting session
+    // ends, so it can never outlive the run it describes.
+    const progress = createCodeOpsProgress()
+
     // Sweep scratch directories abandoned by earlier interrupted runs, once.
     // Cleanup is best effort: a failure must never block a session.
     try {
@@ -234,8 +244,9 @@ export default Plugin.define({
     warnOnVersionSkew(directory)
 
     // ---------------------------------------------------------------------
-    // Session lifecycle: drop captured markers when a session is deleted, so
-    // a long-lived runtime does not remember ended sessions.
+    // Session lifecycle: drop captured markers and the session's live run
+    // when a session is deleted, so a long-lived runtime does not remember
+    // ended sessions.
     // ---------------------------------------------------------------------
     const controller = new AbortController()
     void (async () => {
@@ -243,6 +254,7 @@ export default Plugin.define({
         for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
           if (event.type === "session.deleted") {
             effortMarkers.delete(event.data.sessionID)
+            progress.clearSession(event.data.sessionID)
           }
         }
       } catch {
@@ -384,6 +396,47 @@ export default Plugin.define({
       }
     })
 
+    // ---------------------------------------------------------------------
+    // CodeOps RPC: expose the plugin identity and the live run snapshot for
+    // the sidebar. Registration is feature-detected and never blocks the
+    // plugin: builds without custom RPCs keep working unchanged, and the
+    // sidebar simply stays hidden. When the host hands back an event emitter,
+    // the registration binds it into the runtime, so accepted reports and
+    // clears push live events to connected clients.
+    // ---------------------------------------------------------------------
+    try {
+      const registered = await registerCodeOpsRpc(ctx, {
+        pluginVersion: packageVersion,
+        runtime: progress,
+      })
+      if (!registered) {
+        warnContentFree(
+          "The codeops status RPC is unavailable in this OpenCode build; " +
+            "the sidebar status stays hidden."
+        )
+      }
+    } catch {
+      warnContentFree("Could not register the codeops status RPC.")
+    }
+
+    // ---------------------------------------------------------------------
+    // Progress tool: let the agent report live task progress for the sidebar.
+    // The tool registers behind feature-detection; on every failure the
+    // plugin, the agent loop, and the Markdown execution plan keep working
+    // exactly as before.
+    // ---------------------------------------------------------------------
+    try {
+      const registered = await registerCodeOpsProgressTool(ctx, progress)
+      if (!registered) {
+        warnContentFree(
+          "The codeops progress tool is unavailable in this OpenCode build; " +
+            "the sidebar stays hidden."
+        )
+      }
+    } catch {
+      warnContentFree("Could not register the codeops progress tool.")
+    }
+
     // ---------------------------------------------------------------------
     // Plugin cleanup: stop listening for events. The runtime's scratch
     // directory is deliberately left in place — other sessions may still be

package/plugin/tui.js

@@ -0,0 +1,113 @@
+// Generated from plugin/tui.tsx — do not edit; run `npm run build:tui` to regenerate.
+import { insert as _$insert } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+import { memo as _$memo } from "@opentui/solid";
+import { createComponent as _$createComponent } from "@opentui/solid";
+/**
+ * The CodeOps TUI entry: the live run-progress view in the session sidebar.
+ *
+ * The view is deliberately honest: it shows only reported values from the
+ * server's run state, always with an as-of time, and it renders nothing when
+ * there is no run, when the host lacks the events API, or when every call
+ * fails. There are no timers — the text recomputes whenever the component
+ * re-renders — and no file access; all display and merge logic lives in the
+ * shared helper module so it can be tested under plain Node.
+ *
+ * @module tui
+ */
+
+import { Plugin, usePlugin } from "@opencode/plugin/tui";
+import { createEffect, createResource, createSignal, onCleanup, Show } from "solid-js";
+import { acceptRunCleared, acceptRunUpdate, describeRun, mergeRunState } from "../bin/lib/codeops-progress.mjs";
+import { CodeOpsRpc, requestProgress } from "../bin/lib/codeops-rpc.mjs";
+
+/**
+ * The live run-progress view.
+ *
+ * Resolves the session's location once, subscribes to the `updated` and
+ * `cleared` events before requesting an initial snapshot, and merges both
+ * delivery paths monotonically. A clear records its server-stamped
+ * `clearedAt`; both merge paths ignore deliveries at or before it, so a late
+ * snapshot or update can never resurrect a cleared run. Every failure path is
+ * silent: a host without the events API still renders from the snapshot, and
+ * an invalid or missing snapshot renders nothing.
+ *
+ * @returns The three display lines, or nothing when no run is known.
+ */
+function CodeOpsProgress() {
+  const context = usePlugin();
+  const location = context.location ?? context.data.location.default();
+  const directory = location?.directory ?? "";
+  const [run, setRun] = createSignal(null);
+  const [clearedAt, setClearedAt] = createSignal(0);
+
+  // Subscribe BEFORE the snapshot: events are live-only, so a snapshot
+  // fetched first could miss an update arriving in between. Guarded: a host
+  // without the events API still renders from the snapshot below.
+  const stops = [];
+  try {
+    const events = context.client.rpc(CodeOpsRpc).events;
+    const stopUpdated = events.on("updated", event => {
+      const snapshot = acceptRunUpdate(event, directory);
+      if (snapshot && snapshot.updatedAt > clearedAt()) {
+        setRun(current => mergeRunState(current, snapshot));
+      }
+    });
+    stops.push(stopUpdated);
+    const stopCleared = events.on("cleared", event => {
+      const cleared = acceptRunCleared(event, directory);
+      if (!cleared) return;
+      // Record the clear time for every accepted clear, before the identity
+      // gate: a clear that arrives before the initial snapshot must still
+      // suppress that snapshot, or a cleared run could reappear.
+      setClearedAt(cleared.clearedAt);
+      const current = run();
+      if (current && cleared.plan === current.plan && cleared.sessionID === current.sessionID) {
+        setRun(null);
+      }
+    });
+    stops.push(stopCleared);
+  } catch {
+    // Events unavailable: the snapshot-only view below still renders.
+  }
+  onCleanup(() => stops.forEach(stop => stop()));
+
+  // Initial snapshot; null or a failure means "nothing known". The clear
+  // guard applies here too: a snapshot at or before the last clear is ignored.
+  const [initial] = createResource(async () => requestProgress(context.client, {
+    location
+  }));
+  createEffect(() => {
+    const snapshot = initial();
+    if (snapshot && snapshot.updatedAt > clearedAt()) {
+      setRun(current => mergeRunState(current, snapshot));
+    }
+  });
+  return _$createComponent(Show, {
+    get when() {
+      return run();
+    },
+    children: snapshot => {
+      const view = () => describeRun(snapshot(), Date.now());
+      return _$memo(() => view().lines.map(line => (() => {
+        var _el$ = _$createElement("text");
+        _$insert(_el$, line);
+        return _el$;
+      })()));
+    }
+  });
+}
+
+/**
+ * The opencode-codeops TUI plugin: claims the sidebar content slot with the
+ * live run view. The host disposes the claim when the plugin unloads.
+ */
+export default Plugin.define({
+  id: "opencode-codeops-tui",
+  setup(context) {
+    return context.ui.slot({
+      append: "sidebar.content",
+      render: () => _$createComponent(CodeOpsProgress, {})
+    });
+  }
+});