opencode-crosstalk 0.0.0-stage → 0.2.0

package/src/tui/index.tsx

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview CLI (TUI) plugin: the session avatar in the sidebar, with the
+ * session's live status summary under it.
+ *
+ * The server plugin owns the directory (who declared what); this side renders
+ * it. The RPC contract is shared as a plain object, so that no runtime plugin
+ * module has to resolve in the TUI process.
+ */
+
+import { readFileSync } from "node:fs"
+import { Plugin, usePlugin } from "@opencode/plugin/tui"
+import { Show, createMemo, createSignal } from "solid-js"
+import { TextAttributes } from "@opentui/core"
+import type { DirectoryEntry, DirectoryPayload } from "../core/directory.ts"
+import { normalizeResource } from "../core/claims.ts"
+import { CrosstalkRpc } from "../rpc.ts"
+import { emoticonFor, entryForPortrait, isSummaryStale, summaryText, titleWithEmoticon, type AvatarEntry } from "./avatar.ts"
+
+const manifestUrl = new URL("../../assets/avatars/manifest.json", import.meta.url)
+
+/** Width of the avatar art, and so of the column the summary wraps inside. */
+const AVATAR_WIDTH = 29
+
+/**
+ * How often the sidebar re-checks whether a summary went stale. The directory
+ * is only rebuilt on mesh mutations, and a session nobody talks to emits
+ * none — without this tick an untouched summary could stay undimmed forever.
+ */
+const SUMMARY_TICK_MS = 30_000
+
+function loadEntries(): AvatarEntry[] {
+  try {
+    const parsed = JSON.parse(readFileSync(manifestUrl, "utf8")) as { entries?: AvatarEntry[] }
+    return Array.isArray(parsed.entries) ? parsed.entries : []
+  } catch {
+    return []
+  }
+}
+
+const sourceCache = new Map<string, URL>()
+
+function sourceFor(entry: AvatarEntry): URL {
+  const key = `${entry.pool}/${entry.file}`
+  let url = sourceCache.get(key)
+  if (!url) {
+    url = new URL(`../../assets/avatars/${key}`, import.meta.url)
+    sourceCache.set(key, url)
+  }
+  return url
+}
+
+function asPayload(value: unknown): DirectoryPayload {
+  const sessions = (value as { sessions?: unknown } | undefined)?.sessions
+  return { sessions: Array.isArray(sessions) ? (sessions as DirectoryEntry[]) : [] }
+}
+
+/**
+ * Whether a session sits in this TUI's directory or below it, compared with the
+ * same normalisation claims use so a Windows worktree does not look like a
+ * different place because of a separator or a letter case.
+ */
+function inPlace(candidate: string | undefined, home: string): boolean {
+  if (candidate === undefined) return false
+  const base = normalizeResource(home)
+  const other = normalizeResource(candidate)
+  return other === base || other.startsWith(`${base}/`)
+}
+
+function AvatarLine(props: {
+  sessionID: string
+  directory: () => DirectoryPayload
+  entries: readonly AvatarEntry[]
+  /** Starts a fresh staleness evaluation; see `SUMMARY_TICK_MS`. */
+  tick: () => number
+}) {
+  const context = usePlugin()
+  const [failed, setFailed] = createSignal(false)
+  const session = () => props.directory().sessions.find((entry) => entry.sessionID === props.sessionID)
+  // The live status line under the art: one or two short sentences on what the
+  // session is doing right now, re-read from the directory so every refreshed
+  // declaration shows up without a reload.
+  const summary = () => summaryText(session())
+  // Dimmed once the summary stops being refreshed: read on the tick so the dim
+  // arrives on its own, without waiting for the next directory push.
+  const stale = createMemo(() => {
+    props.tick()
+    return isSummaryStale(session()?.summaryAt, Date.now())
+  })
+  // The server froze the portrait when the session first declared a task;
+  // a session without one has no task and shows no avatar. A portrait whose
+  // art left the manifest is not swapped for another — it shows nothing.
+  const picked = createMemo(() => entryForPortrait(props.entries, session()?.portrait))
+  // Stable source: a fresh URL on every directory update would make the
+  // renderable re-decode the PNG on each change event.
+  const source = createMemo(() => {
+    const entry = picked()
+    return entry ? sourceFor(entry) : undefined
+  })
+
+  return (
+    <Show when={picked()}>
+      {() => (
+        <box flexDirection="column" alignItems="center" gap={0}>
+          {/*
+            Blocks on purpose: the sidebar sits in a scrollbox and the terminal
+            we target (VS Code) announces sixel but does not paint it, so cell
+            drawing is the portable path. On kitty-graphics terminals this can
+            be switched to "auto".
+          */}
+          <image
+            source={source()}
+            width={AVATAR_WIDTH}
+            height={15}
+            fit="cover"
+            protocol="blocks"
+            onError={() => setFailed(true)}
+          />
+          <text fg={context.theme.text.base}>{`${emoticonFor(picked())} ${session()?.name ?? "crosstalk"}`}</text>
+          <text fg={context.theme.text.muted}>{session()?.role ?? ""}</text>
+          <Show when={summary()}>
+            {() => (
+              <text
+                fg={context.theme.text.muted}
+                width={AVATAR_WIDTH}
+                wrapMode="word"
+                attributes={stale() ? TextAttributes.DIM : TextAttributes.NONE}
+              >
+                {summary()}
+              </text>
+            )}
+          </Show>
+          <Show when={failed()}>
+            <text fg={context.theme.text.muted}>[image failed]</text>
+          </Show>
+        </box>
+      )}
+    </Show>
+  )
+}
+
+export default Plugin.define({
+  id: "opencode.crosstalk.tui",
+  async setup(context) {
+    const entries = loadEntries()
+    const [directory, setDirectory] = createSignal<DirectoryPayload>({ sessions: [] })
+    // Slow tick for the summary's staleness dim; see `SUMMARY_TICK_MS`.
+    const [tick, setTick] = createSignal(0)
+    const summaryClock = setInterval(() => setTick((value) => value + 1), SUMMARY_TICK_MS)
+    summaryClock.unref?.()
+    const rpc = context.client.rpc(CrosstalkRpc)
+    const location = context.location ?? context.data.location.default()
+
+    /**
+     * The tab header has no slot a plugin can render into — its label is the
+     * session title — so the emoticon is written there instead.
+     *
+     * Deliberately narrow: only a session that declared a crosstalk name, and
+     * only one in this TUI's directory or below it, may be renamed; `titleWithEmoticon`
+     * returns nothing to write once the title already carries the glyph, so the
+     * `session.renamed` event this triggers comes back as a no-op instead of a
+     * loop. Anything the user titled themselves is left as they wrote it.
+     */
+    const written = new Map<string, string>()
+    async function decorate(payload: DirectoryPayload): Promise<void> {
+      const home = location?.directory
+      if (home === undefined) return
+      for (const entry of payload.sessions) {
+        if (entry.name === undefined || !inPlace(entry.directory, home)) continue
+        // The glyph freezes with the portrait: a later role change never
+        // silently rewrites the user's tab title.
+        const portrait = entryForPortrait(entries, entry.portrait)
+        if (portrait === undefined) continue
+        const wanted = titleWithEmoticon(entry.title, emoticonFor(portrait), entry.name)
+        if (wanted === undefined || written.get(entry.sessionID) === wanted) continue
+        written.set(entry.sessionID, wanted)
+        try {
+          await context.client.session.update({ sessionID: entry.sessionID, title: wanted })
+        } catch {
+          // Gone, or not ours to rename: forget the attempt and let the next
+          // directory update retry it.
+          written.delete(entry.sessionID)
+        }
+      }
+    }
+
+    const apply = (payload: unknown) => {
+      const next = asPayload(payload)
+      setDirectory(next)
+      void decorate(next)
+    }
+
+    try {
+      apply(await rpc.directory({}, { location }))
+    } catch {
+      // The sidebar stays empty until the next change event arrives.
+    }
+    const unsubscribe = rpc.events.on("changed", (event) => {
+      const eventDirectory = (event as { location?: { directory?: string } }).location?.directory
+      if (location?.directory !== undefined && eventDirectory !== location.directory) return
+      apply(event.data)
+    })
+
+    const unregister = context.ui.slot({
+      append: "sidebar.content",
+      render: (input) => (
+        <AvatarLine sessionID={input.sessionID} directory={directory} entries={entries} tick={tick} />
+      ),
+    })
+
+    return () => {
+      unsubscribe()
+      unregister()
+      clearInterval(summaryClock)
+    }
+  },
+})

package/src/types.ts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Shared value types for the crosstalk mesh.
+ *
+ * Nothing in `src/core` imports an OpenCode package: the host adapter in
+ * `src/index.ts` translates OpenCode events and tool calls into these plain
+ * shapes, which keeps the coordination logic unit-testable in isolation.
+ */
+
+/** Coarse liveness of a peer session, derived from the server event stream. */
+export type PeerStatus = "running" | "idle" | "unknown"
+
+export type Scope = "project" | "location" | "server"
+
+/** What a session told the mesh about itself through `crosstalk_status`. */
+export interface Declared {
+  /**
+   * A unique human name chosen by the session, so the user can say "tell
+   * George…" and peers can address it in `crosstalk_send`. Optional; the
+   * session id stays the authoritative identity.
+   */
+  name?: string
+  role?: string
+  goal?: string
+  /**
+   * What the session is doing *right now*: one or two short sentences, kept
+   * current as the work moves. Unlike `goal` — the overall objective, declared
+   * once — this is the live status line shown under the avatar in the TUI
+   * sidebar and read by peers through `crosstalk_peers`, so it is meant to be
+   * re-declared whenever the task changes.
+   */
+  summary?: string
+  /**
+   * When `summary` was last declared, in ms. Refreshing any other declared
+   * field leaves it alone, so it ages the *summary* rather than the
+   * declaration. Absent for summaries restored from a snapshot written by an
+   * older version — those are neither annotated nor dimmed, just shown.
+   */
+  summaryAt?: number
+  workingOn?: string[]
+  note?: string
+  /**
+   * Optional avatar hint (an emoji such as `👩` or `👨`) that steers which
+   * character pool the portrait is drawn from. The concrete artwork is chosen
+   * by the mesh on the session's first task-bearing declaration and then
+   * frozen on the peer record — see `Peer.portrait`.
+   */
+  avatar?: string
+  updatedAt?: number
+}
+
+/** One session the mesh knows about. */
+export interface Peer {
+  sessionID: string
+  title?: string
+  agent?: string
+  /** Human readable `provider/model#variant` label. */
+  model?: string
+  parentID?: string
+  projectID?: string
+  directory?: string
+  status: PeerStatus
+  created?: number
+  /** Timestamp of the most recent event seen for this session. */
+  lastSeen: number
+  declared?: Declared
+  /**
+   * Frozen portrait: `pool/file` inside `assets/avatars/`, assigned by the
+   * mesh when the session first declares a task and never changed again —
+   * re-declaring a different role, name, or avatar hint cannot move it.
+   */
+  portrait?: string
+}
+
+/** A peer enriched with mesh-derived state, as returned to tools. */
+export interface PeerView extends Peer {
+  isSelf: boolean
+  /** No event for longer than the stale threshold. */
+  stale: boolean
+  unread: number
+  claims: string[]
+  /**
+   * Provably within the configured communication scope. Only addressable
+   * peers can be messaged or awaited; the rest are listed for visibility but
+   * marked "not addressable".
+   */
+  addressable: boolean
+}
+
+export type MessageKind = "message" | "status" | "request" | "answer" | "system"
+
+export type Delivery = "steer" | "queue"
+
+/** A message delivered into one recipient's mailbox. */
+export interface CrosstalkMessage {
+  id: string
+  seq: number
+  from: string
+  /** The sender's declared human name, stamped at send time. */
+  fromName?: string
+  fromRole?: string
+  to: string
+  text: string
+  topic?: string
+  kind: MessageKind
+  delivery: Delivery
+  created: number
+  readAt?: number
+  meta?: Record<string, unknown>
+}
+
+/** An exclusive lease on a path or named resource. */
+export interface Claim {
+  /** Normalized comparison key. */
+  key: string
+  /** The resource string as the holder wrote it. */
+  raw: string
+  holder: string
+  note?: string
+  acquired: number
+  expires: number
+}
+
+export interface ClaimConflict {
+  key: string
+  raw: string
+  holder: string
+  note?: string
+  expires: number
+}
+
+export interface ClaimOutcome {
+  claimed: string[]
+  renewed: string[]
+  released: string[]
+  stolen: string[]
+  conflicts: ClaimConflict[]
+  /** True when a single conflict aborted the whole request. */
+  rolledBack: boolean
+}
+
+/** Serialized mesh state. Messages are intentionally not persisted. */
+export interface MeshSnapshot {
+  version: number
+  savedAt: number
+  peers: Peer[]
+  claims: Claim[]
+}

package/tui.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Host entrypoint for the CLI (TUI) plugin.
+ *
+ * The host discovers a TUI entrypoint beside the server entrypoint (`index.ts`),
+ * so this file only re-exports the implementation.
+ */
+
+export { default } from "./src/tui/index.tsx"