opencode-crosstalk 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,323 @@
+/**
+ * @fileoverview OpenCode plugin entry point.
+ *
+ * `setup` wires four things and returns the cleanup that undoes all of them:
+ *
+ * 1. a `Mesh` (presence registry, mailboxes, claim table) built on the plugin
+ *    location, seeded from a persisted snapshot when one exists;
+ * 2. a subscription to the server event stream, which is the only way a plugin
+ *    learns that other sessions exist — the plugin context has no
+ *    `session.list()`;
+ * 3. the seven `crosstalk_*` tools, registered under one namespace and one
+ *    permission action;
+ * 4. a `context` hook that tells the model the channel exists — in every
+ *    session, including one that is currently alone — so the tools get used
+ *    without the user having to ask.
+ *
+ * The OpenCode-specific types are imported through the published package, but
+ * only as types plus `Plugin.define`, keeping the core free of host coupling.
+ */
+
+import { readFileSync } from "node:fs"
+import { Plugin } from "@opencode/plugin"
+import { parseOptions } from "./config.ts"
+import { type AvatarEntry } from "./core/avatar.ts"
+import { systemClock } from "./core/clock.ts"
+import { directoryPayload } from "./core/directory.ts"
+import { Mesh } from "./core/mesh.ts"
+import { createSessionDeliverer, type SessionLike } from "./deliverer.ts"
+import { pumpEvents } from "./events.ts"
+import { CrosstalkRpc } from "./rpc.ts"
+import { MeshStore, type StorageLike } from "./storage.ts"
+import { registerTools } from "./tools/index.ts"
+
+/** Plugin identity. Also the `plugins: ["-opencode.crosstalk"]` disable key. */
+export const id = "opencode.crosstalk"
+
+/** Debounce window for snapshot writes triggered by event traffic. */
+const PERSIST_DEBOUNCE_MS = 2_000
+
+/** Debounce window for RPC directory pushes triggered by mesh mutations. */
+const RPC_DEBOUNCE_MS = 500
+
+/**
+ * Bridge the real session domain to the narrow shape the deliverer needs.
+ * `Session.ID` is a branded string and the metadata index signature is typed
+ * as the server's `JsonValue`; the mesh works in plain strings and plain JSON,
+ * so both are narrowed once, here, instead of throughout the plugin.
+ */
+function toSessionLike(session: Plugin.Context["session"]): SessionLike {
+  return {
+    synthetic: ({ sessionID, text, description, delivery, metadata }) =>
+      session.synthetic({
+        sessionID: sessionID as never,
+        text,
+        ...(description === undefined ? {} : { description }),
+        ...(delivery === undefined ? {} : { delivery }),
+        ...(metadata === undefined ? {} : { metadata: metadata as never }),
+      }),
+  }
+}
+
+/**
+ * The lone-session briefing. Every session has to learn that the channel
+ * exists: a session that never declares a name or role is not addressable when
+ * a peer appears later, and the first session in a project always starts alone.
+ * Short on purpose — it is repeated until a peer or a lease shows up.
+ */
+function soloBriefing(): string {
+  return [
+    "Crosstalk is installed in this workspace, so other OpenCode sessions here can coordinate with you.",
+    "Declare once — briefly — with `crosstalk_status`: a unique human name (so peers can address you), your role,",
+    "a goal of a few words, and a one-line `summary` of what you are doing now.",
+    "`crosstalk_peers` shows who else is here; work that does not overlap theirs needs no coordination.",
+    "No other session is on this channel right now.",
+  ].join(" ")
+}
+
+function briefing(peers: number, claims: number): string {
+  if (peers === 0 && claims === 0) return soloBriefing()
+  return [
+    "Other OpenCode sessions can be working in this repository with you.",
+    "Coordinate in English only and keep it token-tight: one short sentence per status, message, or claim.",
+    "Declare once — briefly — then keep moving: `crosstalk_status` sets a unique human name (so the user can say",
+    '"tell George…" and peers can address you) plus your role and a goal of a few words; `crosstalk_peers` shows',
+    "active sessions and their leases, and work that does not overlap theirs needs no coordination.",
+    "Write `summary` — one or two short sentences on what you are doing right now — and refresh it when your",
+    "task changes: it shows under your avatar in the sidebar and peers read it.",
+    "Talk before you collide — as a notice, not an essay: `crosstalk_send` one short precise sentence addressed by",
+    "session id or name and continue elsewhere; replies are injected into live turns (`crosstalk_inbox` to catch up).",
+    "Never force a claim. Lease what you are editing now with `crosstalk_claim` (it refuses if another session already",
+    "holds it), renew if the work runs long, release when done. Only sessions in this project are reachable — peers",
+    "marked not addressable cannot receive mail.",
+    `Right now ${peers} other session${peers === 1 ? " is" : "s are"} on this channel` +
+      (claims > 0 ? ` and ${claims} file${claims === 1 ? " is" : "s are"} already leased.` : "."),
+  ].join(" ")
+}
+
+/** The session id an event is about, when it carries one. */
+function eventSessionID(event: { data?: Readonly<Record<string, unknown>> }): string | undefined {
+  const value = event.data?.sessionID
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
+
+/** The bundled Personas pool; empty when the art is missing or unreadable. */
+function loadAvatars(): AvatarEntry[] {
+  try {
+    const parsed = JSON.parse(readFileSync(new URL("../assets/avatars/manifest.json", import.meta.url), "utf8")) as {
+      entries?: AvatarEntry[]
+    }
+    return Array.isArray(parsed.entries) ? parsed.entries : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Which setup instance owns each location. `globalThis` rather than a module
+ * variable because the same plugin can be installed twice (a global link plus
+ * a config path to the same checkout), and two loads can get two module
+ * instances while sharing one process — the location guard must still see the
+ * whole truth.
+ */
+interface CrosstalkGuard {
+  owners: Map<string, { token: symbol; source: string }>
+  /**
+   * Loads the guard refused because the location already had an owner. The
+   * status self-check surfaces it: a duplicate install is otherwise only
+   * visible in logs nobody reads.
+   */
+  refused: number
+}
+
+function crosstalkGuard(): CrosstalkGuard {
+  const holder = globalThis as { __crosstalk?: Partial<CrosstalkGuard> }
+  const guard = (holder.__crosstalk ??= {}) as CrosstalkGuard
+  guard.owners ??= new Map()
+  guard.refused ??= 0
+  return guard
+}
+
+export default Plugin.define({
+  id,
+  async setup(ctx) {
+    const { options, warnings } = parseOptions(ctx.options)
+    for (const warning of warnings) console.warn(`[crosstalk] ${warning}`)
+
+    const projectID = ctx.location.project?.id
+    const directory = ctx.location.directory
+
+    // One live instance per location. The same plugin can be installed twice
+    // (a global link plus a config path) and the host will happily load both;
+    // two meshes would serve tools and RPC from split state while clobbering
+    // one snapshot key. The first load owns the location, later ones stay
+    // inert and say so.
+    const place = directory ?? "__unknown__"
+    const guard = crosstalkGuard()
+    const owner = guard.owners.get(place)
+    if (owner) {
+      guard.refused += 1
+      console.warn(
+        `[crosstalk] ${id} is already loaded for ${place} by ${owner.source}; this copy (${import.meta.url}) registers nothing. Load the plugin from exactly one location.`,
+      )
+      return async () => {}
+    }
+    const ownerToken = Symbol(place)
+    guard.owners.set(place, { token: ownerToken, source: import.meta.url })
+
+    const mesh = new Mesh({
+      options: {
+        scope: options.scope,
+        staleAfterMs: options.staleAfterMs,
+        evictAfterMs: options.evictAfterMs,
+        maxMessages: options.maxMessages,
+        messageTtlMs: options.messageTtlMs,
+        claimTtlMs: options.claimTtlMs,
+        maxWaitMs: options.maxWaitMs,
+        pollMs: options.pollMs,
+      },
+      clock: systemClock,
+      deliverer: createSessionDeliverer(toSessionLike(ctx.session)),
+      defaults: { ...(projectID ? { projectID } : {}), ...(directory ? { directory } : {}) },
+      avatars: loadAvatars(),
+    })
+
+    // `ctx.storage` is JSON-typed; snapshots are plain JSON by construction,
+    // and a round trip guarantees nothing unserializable reaches it.
+    const storage: StorageLike = {
+      get: (key) => ctx.storage.get(key),
+      set: (key, value) => ctx.storage.set(key, JSON.parse(JSON.stringify(value))),
+      remove: (key) => ctx.storage.remove(key),
+      scan: async (query) => {
+        const page = await ctx.storage.scan({ prefix: query.prefix, after: query.after, limit: query.limit })
+        return { entries: page.entries, next: page.next }
+      },
+    }
+    const store = options.persist ? new MeshStore(storage, { key: options.storageKey }) : undefined
+    if (store) {
+      const snapshot = await store.load(projectID)
+      if (snapshot) mesh.restore(snapshot)
+    }
+    // Sessions that declared a task before the portrait feature existed (or
+    // whose snapshot predates it) get one now — the only place a portrait is
+    // assigned outside `declare`.
+    mesh.assignPortraits()
+
+    // Persist after quiet periods: the event stream is chatty and a write per
+    // event would hammer storage for state that is identical.
+    let persistTimer: ReturnType<typeof setTimeout> | undefined
+    const schedulePersist = () => {
+      if (!store || persistTimer) return
+      persistTimer = setTimeout(() => {
+        persistTimer = undefined
+        void store.save(mesh.snapshot(), projectID).catch((error) => {
+          console.warn(`[crosstalk] could not persist mesh state: ${String(error)}`)
+        })
+      }, PERSIST_DEBOUNCE_MS)
+      persistTimer.unref?.()
+    }
+
+    const controller = new AbortController()
+
+    // A session that started before the plugin loaded never emits
+    // `session.created` at us, so its record would stay without a project and
+    // be unaddressable under strict scope. Heal each such record once by
+    // reading it from the host.
+    const enrichAttempted = new Set<string>()
+    const enrichSession = async (sessionID: string) => {
+      try {
+        const info = await ctx.session.get({ sessionID: sessionID as never })
+        if (controller.signal.aborted) return
+        mesh.registry.update(sessionID, {
+          projectID: info.projectID,
+          directory: info.location?.directory,
+          title: info.title,
+          agent: info.agent,
+          parentID: info.parentID,
+          created: info.time?.created,
+        })
+        schedulePersist()
+        scheduleRpc()
+      } catch {
+        // A session owned by another location may not be readable; leave it.
+      }
+    }
+
+    const streaming = pumpEvents(ctx.event, controller.signal, {
+      onEvent: (event) => {
+        mesh.applyEvent(event)
+        schedulePersist()
+        const sessionID = eventSessionID(event)
+        if (
+          sessionID !== undefined &&
+          mesh.registry.get(sessionID)?.projectID === undefined &&
+          !enrichAttempted.has(sessionID)
+        ) {
+          enrichAttempted.add(sessionID)
+          void enrichSession(sessionID)
+        }
+      },
+      onError: (error) => {
+        console.warn(`[crosstalk] event stream: ${String(error)}`)
+      },
+    })
+
+    // Declarations are rare but precious: snapshot them like event traffic
+    // instead of waiting for the next event to happen by.
+    const unsubscribePersist = mesh.subscribe(schedulePersist)
+
+    const toolRegistration = await ctx.tool.transform((editor) => {
+      registerTools(editor, { mesh, options })
+    })
+
+    const briefingRegistration = options.announce
+      ? await ctx.session.hook("context", (event) => {
+          const peers = mesh.peers(event.sessionID).length
+          const claims = mesh.claims.list({ includeExpired: false }).length
+          event.system.push({ type: "text", text: briefing(peers, claims) })
+        })
+      : undefined
+
+    // The TUI plugin reads this directory over RPC. Pushes are debounced so a
+    // chatty event stream does not become a chatty channel.
+    const rpcRegistration = await ctx.rpc.register(CrosstalkRpc, {
+      directory: async () => directoryPayload(mesh),
+    })
+    let rpcTimer: ReturnType<typeof setTimeout> | undefined
+    const scheduleRpc = () => {
+      if (rpcTimer) return
+      rpcTimer = setTimeout(() => {
+        rpcTimer = undefined
+        void rpcRegistration.events.emit("changed", directoryPayload(mesh)).catch((error) => {
+          console.warn(`[crosstalk] could not emit directory update: ${String(error)}`)
+        })
+      }, RPC_DEBOUNCE_MS)
+      rpcTimer.unref?.()
+    }
+    const unsubscribeRpc = mesh.subscribe(scheduleRpc)
+
+    return async () => {
+      if (guard.owners.get(place)?.token === ownerToken) guard.owners.delete(place)
+      controller.abort()
+      await streaming
+      unsubscribeRpc()
+      unsubscribePersist()
+      if (rpcTimer) clearTimeout(rpcTimer)
+      await briefingRegistration?.dispose()
+      await rpcRegistration.dispose()
+      await toolRegistration.dispose()
+      if (persistTimer) clearTimeout(persistTimer)
+      if (store) {
+        await store.save(mesh.snapshot(), projectID).catch(() => {})
+      }
+    }
+  },
+})
+
+export { parseOptions, DEFAULTS } from "./config.ts"
+export { Mesh } from "./core/mesh.ts"
+export { MeshStore } from "./storage.ts"
+export { pumpEvents, asCrosstalkEvent } from "./events.ts"
+export { createSessionDeliverer, renderDelivery } from "./deliverer.ts"
+export { registerTools, toolFactories, NAMESPACE_DESCRIPTION } from "./tools/index.ts"
+export type * from "./types.ts"

package/src/rpc.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview The RPC contract shared by the server plugin and the TUI plugin.
+ *
+ * Only a type is imported: `Rpc.define` is an identity function, so this plain
+ * object works on both sides and the TUI process never resolves a runtime
+ * plugin module for it. Keep the schemas in step with `DirectoryEntry`.
+ */
+
+import type { Rpc } from "@opencode/plugin/rpc"
+
+const sessionSchema = {
+  type: "object",
+  properties: {
+    sessionID: { type: "string" },
+    status: { type: "string" },
+    title: { type: "string" },
+    name: { type: "string" },
+    role: { type: "string" },
+    goal: { type: "string" },
+    summary: { type: "string" },
+    summaryAt: { type: "number" },
+    avatar: { type: "string" },
+    directory: { type: "string" },
+    projectID: { type: "string" },
+    portrait: { type: "string" },
+  },
+  required: ["sessionID", "status"],
+  additionalProperties: false,
+} as const
+
+const directorySchema = {
+  type: "object",
+  properties: {
+    sessions: { type: "array", items: sessionSchema },
+  },
+  required: ["sessions"],
+  additionalProperties: false,
+} as const
+
+/** Method + event surface the TUI uses; the server registers the handlers. */
+export const CrosstalkRpc = {
+  id: "crosstalk",
+  methods: {
+    directory: {
+      input: { type: "object", properties: {}, additionalProperties: false },
+      output: directorySchema,
+    },
+  },
+  events: {
+    changed: { schema: directorySchema },
+  },
+} as const satisfies Rpc.Definition

package/src/storage.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Durable mesh state through the plugin storage domain.
+ *
+ * `ctx.storage` is a plugin-scoped JSON key/value store with prefix scan, which
+ * is enough to keep peers and leases across a plugin reload. Messages are
+ * deliberately not persisted: a mailbox is a live coordination channel, and
+ * replaying stale mail after a restart is worse than an empty inbox.
+ */
+
+import type { MeshSnapshot } from "./types.ts"
+import { SNAPSHOT_VERSION, LEGACY_SNAPSHOT_VERSION } from "./core/mesh.ts"
+
+export interface StorageScanPage {
+  entries: ReadonlyArray<{ key: string; value: unknown }>
+  next?: string
+}
+
+/** Structural subset of `ctx.storage`. */
+export interface StorageLike {
+  get(key: string): Promise<unknown>
+  set(key: string, value: unknown): Promise<void>
+  remove(key: string): Promise<void>
+  scan(options: { prefix: string; limit?: number; after?: string }): Promise<StorageScanPage>
+}
+
+export interface MeshStoreOptions {
+  /** Key prefix; per-project keys are appended. */
+  key: string
+}
+
+/**
+ * The one storage-key formula, shared by the store and the status self-check
+ * so the line the model reads names the key the state actually lives under.
+ */
+export function meshStorageKey(prefix: string, projectID: string | undefined): string {
+  return `${prefix}/${projectID ?? "global"}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export class MeshStore {
+  readonly #storage: StorageLike
+  readonly #key: string
+
+  constructor(storage: StorageLike, options: MeshStoreOptions) {
+    this.#storage = storage
+    this.#key = options.key
+  }
+
+  keyFor(projectID: string | undefined): string {
+    return meshStorageKey(this.#key, projectID)
+  }
+
+  async save(snapshot: MeshSnapshot, projectID?: string): Promise<void> {
+    await this.#storage.set(this.keyFor(projectID), snapshot)
+  }
+
+  /**
+   * Read a snapshot, tolerating anything unusable. A missing, malformed,
+   * unknown-version, or JSON-unserializable payload yields `undefined` rather
+   * than an error: a broken cache must never stop a plugin from loading. The
+   * legacy v1 version passes through untouched for `Mesh.restore` to migrate.
+   */
+  async load(projectID?: string): Promise<MeshSnapshot | undefined> {
+    let raw: unknown
+    try {
+      raw = await this.#storage.get(this.keyFor(projectID))
+    } catch {
+      return undefined
+    }
+    if (!isRecord(raw)) return undefined
+    const version = raw.version
+    if (version !== SNAPSHOT_VERSION && version !== LEGACY_SNAPSHOT_VERSION) return undefined
+    if (!Array.isArray(raw.peers) || !Array.isArray(raw.claims)) return undefined
+    if (typeof raw.savedAt !== "number") return undefined
+    return {
+      version: version === LEGACY_SNAPSHOT_VERSION ? LEGACY_SNAPSHOT_VERSION : SNAPSHOT_VERSION,
+      savedAt: raw.savedAt,
+      peers: raw.peers.filter(isRecord) as unknown as MeshSnapshot["peers"],
+      claims: raw.claims.filter(isRecord) as unknown as MeshSnapshot["claims"],
+    }
+  }
+
+  async remove(projectID?: string): Promise<void> {
+    try {
+      await this.#storage.remove(this.keyFor(projectID))
+    } catch {
+      // Removing a key that was never written is not a failure worth raising.
+    }
+  }
+
+  /** Every stored project key, for diagnostics and cleanup. */
+  async listProjectKeys(): Promise<string[]> {
+    try {
+      const page = await this.#storage.scan({ prefix: `${this.#key}/` })
+      return page.entries
+        .map((entry) => entry.key.slice(this.#key.length + 1))
+        .filter((id): id is string => id.length > 0)
+    } catch {
+      return []
+    }
+  }
+}

package/src/tools/args.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Minimal runtime reader for tool input.
+ *
+ * Tool `execute` receives `any` (the JSON Schema shape is not a TypeScript
+ * type), so every tool narrows and validates its own arguments here instead of
+ * trusting the model. A rejected argument returns a message the model can act
+ * on rather than a thrown stack trace.
+ */
+
+export class ArgError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ArgError"
+  }
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>
+  return {}
+}
+
+export function readString(input: unknown, key: string, options: { required: true; max?: number }): string
+export function readString(
+  input: unknown,
+  key: string,
+  options?: { required?: false; max?: number; fallback?: string },
+): string | undefined
+export function readString(
+  input: unknown,
+  key: string,
+  options: { required?: boolean; max?: number; fallback?: string } = {},
+): string | undefined {
+  const raw = record(input)[key]
+  if (raw === undefined || raw === null) {
+    if (options.required) throw new ArgError(`"${key}" is required`)
+    return options.fallback
+  }
+  if (typeof raw !== "string") throw new ArgError(`"${key}" must be a string`)
+  const value = raw.trim()
+  if (value === "") {
+    if (options.required) throw new ArgError(`"${key}" must not be empty`)
+    return options.fallback
+  }
+  if (options.max !== undefined && value.length > options.max) {
+    throw new ArgError(`"${key}" is ${value.length} characters; the limit is ${options.max}`)
+  }
+  return value
+}
+
+export function readNumber(input: unknown, key: string, options: { required: true; min?: number; max?: number }): number
+export function readNumber(
+  input: unknown,
+  key: string,
+  options?: { required?: false; min?: number; max?: number; fallback?: number },
+): number | undefined
+export function readNumber(
+  input: unknown,
+  key: string,
+  options: { required?: boolean; min?: number; max?: number; fallback?: number } = {},
+): number | undefined {
+  const raw = record(input)[key]
+  if (raw === undefined || raw === null) {
+    if (options.required) throw new ArgError(`"${key}" is required`)
+    return options.fallback
+  }
+  const value = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : Number.NaN
+  if (!Number.isFinite(value)) throw new ArgError(`"${key}" must be a number`)
+  if (options.min !== undefined && value < options.min) throw new ArgError(`"${key}" must be >= ${options.min}`)
+  if (options.max !== undefined && value > options.max) throw new ArgError(`"${key}" must be <= ${options.max}`)
+  return value
+}
+
+export function readBoolean(input: unknown, key: string, fallback?: boolean): boolean | undefined {
+  const raw = record(input)[key]
+  if (raw === undefined || raw === null) return fallback
+  if (typeof raw === "boolean") return raw
+  if (raw === "true") return true
+  if (raw === "false") return false
+  throw new ArgError(`"${key}" must be true or false`)
+}
+
+export function readEnum<T extends string>(
+  input: unknown,
+  key: string,
+  allowed: readonly T[],
+  fallback?: T,
+): T | undefined {
+  const raw = record(input)[key]
+  if (raw === undefined || raw === null) return fallback
+  if (typeof raw !== "string" || !(allowed as readonly string[]).includes(raw)) {
+    throw new ArgError(`"${key}" must be one of: ${allowed.join(", ")}`)
+  }
+  return raw as T
+}
+
+export function readStringArray(
+  input: unknown,
+  key: string,
+  options: { required: true; max?: number; maxLength?: number },
+): string[]
+export function readStringArray(
+  input: unknown,
+  key: string,
+  options?: { required?: false; max?: number; maxLength?: number; fallback?: string[] },
+): string[] | undefined
+export function readStringArray(
+  input: unknown,
+  key: string,
+  options: { required?: boolean; max?: number; maxLength?: number; fallback?: string[] } = {},
+): string[] | undefined {
+  const raw = record(input)[key]
+  if (raw === undefined || raw === null) {
+    if (options.required) throw new ArgError(`"${key}" is required`)
+    return options.fallback
+  }
+  const values = Array.isArray(raw) ? raw : [raw]
+  const out: string[] = []
+  for (const value of values) {
+    if (typeof value !== "string") throw new ArgError(`"${key}" must be a list of strings`)
+    const trimmed = value.trim()
+    if (trimmed === "") continue
+    if (options.maxLength !== undefined && trimmed.length > options.maxLength) {
+      throw new ArgError(`"${key}" entries must be at most ${options.maxLength} characters`)
+    }
+    out.push(trimmed)
+  }
+  if (options.required && out.length === 0) throw new ArgError(`"${key}" must list at least one value`)
+  if (options.max !== undefined && out.length > options.max) {
+    throw new ArgError(`"${key}" accepts at most ${options.max} entries`)
+  }
+  return out
+}