opencode-plugin-kit 1.0.0-alpha.1

package/src/currentModel.ts

@@ -0,0 +1,32 @@
+// Resolves the model a session is actually using from its last assistant
+// message. Both the usage-quota tracker and model recommender need this;
+// the defensive walk is delegated to the kit's shared walker.
+import { walkMessages } from "./messages.ts"
+import type { KitContext } from "./host.ts"
+
+export interface CurrentModel {
+  providerID: string
+  modelID: string
+}
+
+/**
+ * Resolve the current model from a session's most recent assistant message.
+ * Returns undefined when the session has no assistant messages or the
+ * shape is unreadable — callers fall back to the workspace default.
+ */
+export function resolveCurrentModel(context: KitContext, sessionID?: string): CurrentModel | undefined {
+  let found: CurrentModel | undefined
+  walkMessages(
+    context,
+    sessionID,
+    (m) => {
+      if (found) return
+      const providerID = String(m?.model?.providerID ?? m?.providerID ?? "")
+      const modelID = String(m?.model?.id ?? m?.modelID ?? m?.id ?? "")
+      if (providerID && modelID) found = { providerID, modelID }
+    },
+    {},
+    undefined,
+  )
+  return found
+}

package/src/format.ts

@@ -0,0 +1,25 @@
+// Shared number/date formatting for sidebar widgets.
+
+/** Locale integer with a safe fallback for non-finite values. */
+export function fmt(n: unknown): string {
+  return typeof n === "number" && Number.isFinite(n) ? n.toLocaleString("en-US") : "0"
+}
+
+/** Dollar cost, fixed to `precision` decimals (default 4); strings pass through untouched. */
+export function fmtCost(v: unknown, precision = 4): string {
+  if (typeof v === "number" && Number.isFinite(v)) return `$${v.toFixed(precision)}`
+  if (typeof v === "string" && v.trim() !== "") return v
+  return `$${(0).toFixed(precision)}`
+}
+
+/** ISO timestamp -> compact countdown ("2h 5m", "3d 4h"); "" when absent. */
+export function until(iso: string | undefined): string {
+  if (!iso) return ""
+  const ms = Date.parse(iso)
+  if (!Number.isFinite(ms)) return ""
+  const mins = Math.max(0, Math.round((ms - Date.now()) / 60000))
+  if (mins < 60) return `${mins}m`
+  const h = Math.floor(mins / 60)
+  if (h < 48) return `${h}h ${mins % 60}m`
+  return `${Math.floor(h / 24)}d ${h % 24}h`
+}

package/src/host.ts

@@ -0,0 +1,148 @@
+// Narrow host-contract types for opencode-plugin-kit.
+//
+// `@opencode-ai/plugin` is beta: its types ARE the spec. Kit consumes only a
+// small slice of the host context, so instead of accepting `any` everywhere
+// (which silently survives host upgrades and breaks at runtime), this module
+// defines the *structural minimum* kit needs and re-exports the exact host
+// types it hands back. Consumers get compile-time breakage when the host
+// shape drifts, not runtime surprises.
+//
+// Every interface here is structural: a real host context satisfies it
+// as long as the fields exist.
+
+// ---------------------------------------------------------------------------
+// Host types kit re-exports (single import point for consumers)
+// ---------------------------------------------------------------------------
+
+/** Toast payload — mirrored from the host's TuiToast; host drift here breaks CI. */
+export type ToastInput = {
+  message: string
+  variant?: "success" | "error" | "warning" | "info"
+}
+
+/** One selectable row in the picker dialog (only the fields kit populates). */
+export type SelectOption<Value = string> = {
+  title: string
+  value: Value
+  description?: string
+  disabled?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Structural minimum of the host context kit touches
+// ---------------------------------------------------------------------------
+
+/** `context.storage.store(key, { initial })` — the older host returns
+ * `[value, ref]` (mutating `ref` persists); the newer floating `beta` host
+ * types it as `readonly [T, (mutation: (draft: T) => void) => Promise<void>]`.
+ * Both shapes satisfy this union; kit code reads `[0]` and mutates it, which
+ * both hosts persist. */
+export interface KitStorage {
+  store<T extends object>(
+    key: string,
+    opts: { initial: T },
+  ): [T, T] | readonly [T, ((mutation: (draft: T) => void) => void | Promise<void>) | T]
+}
+
+/** Slot registration. Only `append`/`after` + a synchronous `render` are
+ * needed; the host may accept more options. */
+export interface KitSlotOptions {
+  readonly append?: string
+  readonly after?: string
+  render: () => unknown
+}
+
+export interface KitUI {
+  readonly toast: {
+    show(input: ToastInput): void
+  }
+  readonly dialog: {
+    alert(input: { title: string; message: string }): Promise<unknown>
+    select(input: {
+      title: string
+      message: string
+      current?: string
+      options: readonly SelectOption[]
+    }): Promise<unknown>
+  }
+  slot(options: KitSlotOptions): unknown
+}
+
+/** Command entry handed to `keymap.layer()`. Structural subset of the
+ * host command shape; only what the view picker registers. */
+export interface KitCommandEntry {
+  readonly id: string
+  readonly title: string
+  readonly description: string
+  readonly group: string
+  readonly palette?: boolean
+  readonly suggested?: boolean
+  readonly slash?: { name: string; aliases?: string[]; arguments?: boolean }
+  run: (input?: string) => void
+}
+
+export interface KitKeymap {
+  layer(register: () => { mode: string; priority: number; commands: KitCommandEntry[] }): void
+}
+
+/** `context.data.session.message.list(sessionID)` — messages may arrive as
+ * raw objects or `{ info }` envelopes (kit's `unwrap()` handles both). */
+export interface KitSessionData {
+  readonly session: {
+    readonly message: {
+      list(sessionID: string): readonly unknown[] | undefined
+    }
+  }
+}
+
+export interface KitClient {
+  readonly integration: {
+    list(): Promise<unknown>
+  }
+}
+
+/** The structural minimum context for every kit factory. Deliberately
+ * narrower than the host `TuiPluginApi`: kit only reads these surfaces, so
+ * consumers can pass their real context directly. */
+export interface KitContext {
+  readonly storage: KitStorage
+  readonly ui: KitUI
+  readonly keymap: KitKeymap
+  readonly data: KitSessionData
+  readonly client: KitClient
+  readonly options?: Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// Structural message/model shapes the defensive readers walk
+// ---------------------------------------------------------------------------
+
+/** A message in either of the two beta-API shapes: a discriminated
+ * `type`-tagged object or `{ info: Message }` envelope. Kit's readers
+ * (`unwrap`, `isAssistant`, `providerId`, `modelId`) accept both. */
+export interface KitMessageShape {
+  readonly type?: string
+  readonly role?: string
+  readonly providerID?: string
+  readonly modelID?: string
+  readonly id?: string
+  readonly name?: string
+  /** Message parts (tool calls, errors ride along as parts in some shapes). */
+  readonly parts?: ReadonlyArray<unknown>
+  readonly model?: { readonly providerID?: string; readonly modelID?: string; readonly id?: string }
+  readonly cost?: number
+  readonly time?: { readonly created?: number }
+  readonly timeCreated?: string | number
+  readonly createdAt?: string
+  readonly tokens?: {
+    readonly input?: number
+    readonly output?: number
+    readonly reasoning?: number
+    readonly cache?: {
+      /** v1 shapes a number; some beta payloads nest it as `{ input }`. */
+      readonly read?: number | { readonly input?: number }
+      readonly write?: number | { readonly input?: number }
+    }
+  }
+  readonly info?: KitMessageShape
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./providers.ts"
+export * from "./rows.ts"
+export * from "./format.ts"
+export * from "./cache.ts"
+export * from "./schemas.ts"
+export * from "./viewPicker.ts"
+export * from "./currentModel.ts"
+export * from "./cachedResource.ts"
+export * from "./messages.ts"
+export * from "./pollingFetcher.ts"
+export * from "./workspace.ts"
+export * from "./toast.ts"
+export * from "./commands.ts"
+export * from "./collapsible.tsx"
+export * from "./host.ts"

package/src/messages.ts

@@ -0,0 +1,118 @@
+// Defensive message traversal for sidebar widgets.
+//
+// Both the usage-quota tracker and model recommender walk session messages
+// to sum tokens/costs or find the active model. The traversal is always
+// defensive (beta API shapes change) and always scoped to assistant
+// messages from one provider. Centralize the fold so the try/catch +
+// unwrap + filter boilerplate lives in one place.
+import { isAssistant, unwrap } from "./providers.ts"
+import type { KitContext, KitMessageShape } from "./host.ts"
+
+export interface WalkOptions {
+  /** Only visit assistant messages (default true). */
+  readonly assistantOnly?: boolean
+  /** Only visit messages from this provider (providerID field). */
+  readonly provider?: string
+  /** Skip messages older than this epoch ms (for windowed walks). */
+  readonly since?: number
+}
+
+/**
+ * Fold over a session's messages defensively. Starts from the most recent
+ * message and walks backwards. The reducer receives each message (already
+ * unwrapped from `{ info: ... }` envelope). Returning a value replaces the
+ * accumulator; returning void keeps it. Never throws — unreadable shapes
+ * are skipped.
+ *
+ * @example
+ * // Sum input tokens for the "opencode" provider in the last hour.
+ * const totals = walkMessages(context, sessionID, (m, acc) => {
+ *   acc.tokens += m?.tokens?.input ?? 0
+ *   return acc
+ * }, { provider: "opencode", since: Date.now() - 3600_000 }, { tokens: 0 })
+ */
+export function walkMessages<T>(
+  context: KitContext,
+  sessionID: string | undefined,
+  reducer: (message: any, acc: T) => T | void,
+  options: WalkOptions = {},
+  initial: T,
+): T {
+  if (!sessionID) return initial
+  const { assistantOnly = true, provider, since } = options
+
+  try {
+    const messages = context.data.session.message.list(sessionID) ?? []
+    let acc = initial
+
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = unwrap(messages[i] as KitMessageShape)
+
+      // Skip non-assistant messages when filtering.
+      if (assistantOnly && !isAssistant(m)) continue
+
+      // Skip messages from other providers when scoped.
+      if (provider) {
+        const mProvider = m?.model?.providerID ?? m?.providerID ?? ""
+        if (mProvider !== provider) continue
+      }
+
+      // Skip messages before the window start.
+      if (since) {
+        const created = m?.time?.created ?? m?.timeCreated ?? m?.createdAt
+        const ts = typeof created === "string" ? Date.parse(created) : typeof created === "number" ? created : NaN
+        if (!Number.isFinite(ts) || ts < since) continue
+      }
+
+      const result = reducer(m, acc)
+      acc = result === undefined ? acc : result
+    }
+
+    return acc
+  } catch {
+    return initial
+  }
+}
+
+/**
+ * Sum token counts and cost for a provider's assistant messages.
+ * Convenience wrapper around walkMessages for the common case.
+ */
+export interface TokenTotals {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cost: number
+}
+
+/** Cache-read tokens: v1 shapes are `cache.read` (number); some beta
+ * payloads nest it as `cache.read.input`. Read defensively, typed in
+ * `KitMessageShape`. */
+export function cacheReadInput(tokens: KitMessageShape["tokens"]): number | { input?: number } | undefined {
+  return tokens?.cache?.read
+}
+
+export function sumProviderTokens(
+  context: KitContext,
+  sessionID: string | undefined,
+  provider: string,
+  since?: number,
+): TokenTotals {
+  return walkMessages<TokenTotals>(
+    context,
+    sessionID,
+    (m, acc) => {
+      const tokens = m?.tokens ?? {}
+      acc.input += Number(tokens?.input ?? 0) || 0
+      acc.output += Number(tokens?.output ?? 0) || 0
+      acc.reasoning += Number(tokens?.reasoning ?? 0) || 0
+      const read = cacheReadInput(tokens)
+      acc.cacheRead += Number(typeof read === "object" ? (read?.input ?? 0) : (read ?? 0)) || 0
+      acc.cost += Number(m?.cost ?? 0) || 0
+      return acc
+    },
+    { provider, since },
+    { input: 0, output: 0, reasoning: 0, cacheRead: 0, cost: 0 },
+  )
+}

package/src/pollingFetcher.ts

@@ -0,0 +1,81 @@
+// Polling fetcher with throttling, in-flight guard, and last-known-good
+// retention. The usage-quota tracker's fetchUsage/refreshUsage pattern,
+// generalized: any plugin polling an authenticated endpoint needs exactly
+// this — fetch on an interval, don't refetch while one is in flight, keep
+// the last success on failure.
+
+export interface PollingFetcherOptions<T> {
+  /** The async fetch function. Returns null on failure (keeps last value). */
+  readonly fetch: () => Promise<T | null>
+  /** Polling interval in ms. */
+  readonly intervalMs: number
+  /** Minimum gap between fetches in ms (throttle). Defaults to intervalMs. */
+  readonly throttleMs?: number
+  /** Called with the fresh value on successful fetch. */
+  readonly onResult?: (value: T) => void
+  /** Called on fetch error (after all retries). */
+  readonly onError?: (err: unknown) => void
+}
+
+export interface PollingFetcher {
+  /** Trigger a fetch immediately (respects throttle + in-flight). */
+  readonly refresh: () => void
+  /** Stop polling (call from cleanup). */
+  readonly stop: () => void
+  /** Whether a fetch is currently in flight. */
+  readonly inFlight: () => boolean
+}
+
+/**
+ * Create a polling fetcher. Fetches on an interval, guards against
+ * concurrent fetches, and throttles to avoid hammering the endpoint.
+ */
+export function createPollingFetcher<T>(options: PollingFetcherOptions<T>): PollingFetcher {
+  const { fetch, intervalMs, throttleMs = intervalMs, onResult, onError } = options
+
+  let lastFetch = 0
+  let inFlightFlag = false
+  let timer: ReturnType<typeof setInterval> | null = null
+
+  async function doFetch(): Promise<void> {
+    if (inFlightFlag) return
+    inFlightFlag = true
+    try {
+      const result = await fetch()
+      if (result !== null) {
+        onResult?.(result)
+      }
+    } catch (err) {
+      onError?.(err)
+    } finally {
+      inFlightFlag = false
+    }
+  }
+
+  function refresh(): void {
+    const now = Date.now()
+    if (now - lastFetch < throttleMs) return
+    lastFetch = now
+    void doFetch()
+  }
+
+  function stop(): void {
+    if (timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+  }
+
+  // Kick off the first fetch immediately. Going through refresh() records
+  // the timestamp, so the initial fetch counts toward the throttle window.
+  refresh()
+
+  // Start the polling timer.
+  timer = setInterval(refresh, intervalMs)
+
+  return {
+    refresh,
+    stop,
+    inFlight: () => inFlightFlag,
+  }
+}

package/src/providers.ts

@@ -0,0 +1,200 @@
+// Shared provider vocabulary for OpenCode sidebar widgets.
+// Provider IDs are the OpenCode workspace provider ids ("opencode" = Zen,
+// "opencode-go" = Go).
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { createSignal } from "solid-js"
+import { connectedProviderIds } from "./schemas.ts"
+import type { KitContext, KitMessageShape } from "./host.ts"
+
+export const ZEN_PROVIDER = "opencode"
+export const GO_PROVIDER = "opencode-go"
+export const DEFAULT_PROVIDERS = [ZEN_PROVIDER, GO_PROVIDER]
+
+/** Short human label for the provider column, e.g. "zen" / "go". */
+export function providerLabel(pid: string): string {
+  if (pid === ZEN_PROVIDER) return "zen"
+  if (pid === GO_PROVIDER) return "go"
+  if (pid === "google") return "google"
+  if (pid === "zai-coding-plan") return "zai"
+  if (pid === "huggingface") return "hf"
+  return pid
+}
+
+/** Full display title for a provider — picker dialogs, view headers. */
+export function providerTitle(pid: string): string {
+  if (pid === ZEN_PROVIDER) return "Zen"
+  if (pid === GO_PROVIDER) return "Go"
+  if (pid === "google") return "Google"
+  if (pid === "zai-coding-plan") return "Z.AI"
+  if (pid === "huggingface") return "Hugging Face"
+  return pid
+}
+
+/** Unwrap a beta-API message entry: `{ info: {...} }` -> the inner object. */
+export function unwrap(entry: KitMessageShape): KitMessageShape {
+  return entry?.info ?? entry
+}
+
+/**
+ * True for assistant messages. Beta schema messages discriminate by `type`
+ * tags ("assistant", "user", ...), not a `role` field — tolerate both so the
+ * filter keeps working if a client exposes `role` instead.
+ */
+export function isAssistant(m: KitMessageShape): boolean {
+  return (m?.type ?? m?.role) === "assistant"
+}
+
+/** Normalize `{ data: [...] }` API responses (or a bare array) to an array. */
+export function asArray<T = any>(out: unknown): T[] {
+  return Array.isArray(out) ? (out as T[]) : ((out as any)?.data ?? [])
+}
+
+/** Model id from either a model-list object or a message/message-part shape. */
+export function modelId(m: KitMessageShape): string {
+  return m?.model?.modelID ?? m?.modelID ?? m?.model?.id ?? m?.id ?? ""
+}
+
+/** Provider id from either a model-list object or a message/message-part shape. */
+export function providerId(m: KitMessageShape): string {
+  return m?.model?.providerID ?? m?.providerID ?? ""
+}
+
+/** Display name, falling back to the model id when the API omits `name`. */
+export function modelName(m: KitMessageShape): string {
+  return m?.name ?? modelId(m)
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic provider discovery
+// ---------------------------------------------------------------------------
+
+const AUTH_PATH = () => join(homedir(), ".local/share/opencode/auth.json")
+
+/** Single defensive read of auth.json, keyed by provider id.
+ * Every consumer shares this parse so the path and shape handling can't drift. */
+export function readAuth(): Record<string, string> {
+  try {
+    const auth = JSON.parse(readFileSync(AUTH_PATH(), "utf8"))
+    const out: Record<string, string> = {}
+    for (const [id, cfg] of Object.entries(auth)) {
+      const key = (cfg as any)?.key
+      if (typeof key === "string" && key.trim()) out[id] = key.trim()
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/** The API key for one provider, or "" when absent. */
+export function authKey(providerID: string): string {
+  return readAuth()[providerID] ?? ""
+}
+
+/** Whether the provider has a stored key (fallback when the integration
+ * list is unavailable, e.g. before the first client fetch). */
+export function hasKey(providerID: string): boolean {
+  return authKey(providerID) !== ""
+}
+
+/** Workspace keys in a preferred order, skipping missing ones.
+ * `fallbacks` are returned (still filtered) when none of `preferred` exist —
+ * used by the usage endpoint, which accepts any workspace key. */
+export function authKeys(preferred: string[], ...fallbacks: string[]): string[] {
+  const auth = readAuth()
+  const pick = (ids: string[]) => ids.map((id) => auth[id] ?? "").filter(Boolean)
+  const keys = pick(preferred)
+  return keys.length > 0 ? keys : pick(fallbacks)
+}
+
+const FALLBACK_PROVIDERS = [ZEN_PROVIDER, GO_PROVIDER] as const
+
+let _providers: string[] | null = null
+
+/**
+ * All providers that have credentials in this workspace — read from
+ * `~/.local/share/opencode/auth.json` (API keys) plus `HF_TOKEN` env
+ * (HuggingFace). Result is memoized; at most one file read per process.
+ * Falls back to Zen + Go if auth.json is unreadable. This is the sync
+ * core of provider discovery; reactive widgets use createConnectedProviders.
+ */
+export function availableProviders(): string[] {
+  if (_providers) return _providers
+
+  const ids = Object.keys(readAuth())
+
+  if (ids.length === 0) ids.push(...FALLBACK_PROVIDERS)
+  if (process.env.HF_TOKEN && !ids.includes("huggingface")) {
+    ids.push("huggingface")
+  }
+
+  _providers = ids
+  return _providers
+}
+
+// ---------------------------------------------------------------------------
+// Reactive connected-provider tracking
+// ---------------------------------------------------------------------------
+
+export interface ConnectedProvidersOptions {
+  /** Polling interval in ms. Defaults to 30_000. Set to 0 to disable. */
+  readonly pollMs?: number
+}
+
+export interface ConnectedProviders {
+  /** Reactive set of connected provider ids. */
+  readonly ids: () => Set<string>
+  /** Whether a specific provider is connected. */
+  readonly has: (providerID: string) => boolean
+  /** Force an immediate refresh. */
+  readonly refresh: () => Promise<void>
+  /** Stop polling (call from cleanup). */
+  readonly stop: () => void
+}
+
+/**
+ * Track which providers are connected, reactively — for widgets that gate
+ * views on "is this provider connected?". Polls the integration list (the
+ * source /connect writes) and unions in env-only providers (HF_TOKEN).
+ * When the client is unavailable, falls back to the sync auth.json-based
+ * `availableProviders()` discovery.
+ */
+export function createConnectedProviders(
+  context: KitContext,
+  options: ConnectedProvidersOptions = {},
+): ConnectedProviders {
+  const [ids, setIds] = createSignal<Set<string>>(new Set())
+
+  async function refresh(): Promise<void> {
+    try {
+      const next = connectedProviderIds(await context.client.integration.list())
+      if (process.env.HF_TOKEN) next.add("huggingface")
+      setIds(next)
+    } catch {
+      setIds(new Set(availableProviders()))
+    }
+  }
+
+  // Initial refresh.
+  void refresh()
+
+  const pollMs = options.pollMs ?? 30_000
+  let timer: ReturnType<typeof setInterval> | null = null
+  if (pollMs > 0) {
+    timer = setInterval(() => void refresh(), pollMs)
+  }
+
+  return {
+    ids,
+    has: (providerID: string) => ids().has(providerID),
+    refresh,
+    stop: () => {
+      if (timer !== null) {
+        clearInterval(timer)
+        timer = null
+      }
+    },
+  }
+}

package/src/rows.ts

@@ -0,0 +1,22 @@
+// Shared sidebar row builders — pure text formatting, no I/O.
+import { providerLabel } from "./providers.ts"
+
+/** Truncate a long id so a sidebar row stays on one line. */
+export function short(id: string, max = 24): string {
+  return id.length > max ? id.slice(0, max - 1) + "…" : id
+}
+
+/** A padded label/value row with a (provider) tag, e.g. `sess$  gpt-5…  (zen) $0.12`.
+ * Pass `width` to size the id column for the rows being shown. */
+export function line(label: string, id: string, providerID: string, value?: string, width = 25): string {
+  if (!id) return ""
+  const v = value ? ` ${value}` : ""
+  const tag = `(${providerLabel(providerID)})`
+  return `${label.padEnd(6)} ${short(id, width).padEnd(width)} ${tag}${v}`
+}
+
+/** Lean inline progress bar: [━━──] — half-height line glyphs keep the row slim. */
+export function bar(percent: number, cells = 10): string {
+  const filled = Math.max(0, Math.min(cells, Math.round((percent / 100) * cells)))
+  return `[${"━".repeat(filled)}${"─".repeat(cells - filled)}]`
+}