opencode-crosstalk 0.0.0-stage → 0.2.0

package/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Host directory entrypoint.
+ *
+ * OpenCode resolves a plugin directory through a root `index.ts`/`index.js`
+ * file — it does not read `package.json` `main`/`exports` for plugin
+ * directories. `src/index.ts` remains the real entry; installed directories
+ * (the `npm run setup` symlink, or a copy under `.opencode/plugins/`) reach it
+ * through this re-export.
+ */
+
+export { default } from "./src/index.ts"

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "opencode-crosstalk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenCode plugin that lets sessions on the same server see each other, talk to each other, and lease the files they are editing",
+  "type": "module",
+  "license": "MIT",
+  "author": "Christoph Döllinger <christoph@christoph.cx>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrDoe/opencode-crosstalk.git"
+  },
+  "homepage": "https://github.com/MrDoe/opencode-crosstalk#readme",
+  "bugs": {
+    "url": "https://github.com/MrDoe/opencode-crosstalk/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "agents",
+    "coordination",
+    "multi-agent"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/mesh.ts",
+    "./rpc": "./src/rpc.ts",
+    "./tui": "./tui.ts"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "tui.ts",
+    "assets",
+    "README.md"
+  ],
+  "scripts": {
+    "setup": "node scripts/setup.mjs",
+    "uninstall": "node scripts/setup.mjs uninstall",
+    "test": "node --test test/*.test.ts",
+    "test:e2e": "OPENCODE_E2E=1 node --test test/e2e/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "node scripts/check.mjs"
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": "^2.0.0"
+  },
+  "devDependencies": {
+    "@opentui/core": "^0.5.10",
+    "@opentui/solid": "^0.5.10",
+    "@types/node": "^22.20.0",
+    "solid-js": "^1.9.12",
+    "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "@babel/core": "^7.29.7",
+    "seroval": "^1.6.8",
+    "seroval-plugins": "^1.6.8"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/src/config.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Plugin option parsing.
+ *
+ * Options come from `opencode.jsonc` and are untrusted, so every field is
+ * validated and clamped. Bad values degrade to a documented default and emit a
+ * warning instead of failing plugin setup — a typo should not take an agent's
+ * coordination tools away mid-session.
+ */
+
+import type { Scope } from "./types.ts"
+
+export interface CrosstalkOptions {
+  /** Tool namespace. Defaults to `crosstalk`. */
+  namespace: string
+  /** Permission action guarding every tool. Defaults to `crosstalk`. */
+  permission: string
+  /** Expose the tools through Code Mode instead of directly. */
+  codemode: boolean
+  /** Which peers are visible: same project, same directory, or whole server. */
+  scope: Scope
+  /** A peer with no event for this long is reported as stale. */
+  staleAfterMs: number
+  /** A peer with no event for this long is dropped from the registry. */
+  evictAfterMs: number
+  /** Maximum retained messages per mailbox; oldest read messages go first. */
+  maxMessages: number
+  /** Messages older than this are pruned. */
+  messageTtlMs: number
+  /** Default lease duration for `crosstalk_claim`. */
+  claimTtlMs: number
+  /** Upper bound for any blocking tool call. */
+  maxWaitMs: number
+  /** Poll interval for the barrier waits. */
+  pollMs: number
+  /** Progress heartbeat interval while blocked; `0` disables heartbeats. */
+  heartbeatMs: number
+  /** Persist peers and claims through `ctx.storage`. */
+  persist: boolean
+  /** Storage key prefix. */
+  storageKey: string
+  /** Append a short briefing to the agent's system prompt. */
+  announce: boolean
+}
+
+export const DEFAULTS: CrosstalkOptions = {
+  namespace: "crosstalk",
+  permission: "crosstalk",
+  codemode: false,
+  scope: "project",
+  staleAfterMs: 600_000,
+  evictAfterMs: 3_600_000,
+  maxMessages: 100,
+  messageTtlMs: 86_400_000,
+  claimTtlMs: 300_000,
+  maxWaitMs: 120_000,
+  pollMs: 1_000,
+  heartbeatMs: 10_000,
+  persist: true,
+  storageKey: "crosstalk",
+  announce: true,
+}
+
+const SCOPES: readonly Scope[] = ["project", "location", "server"]
+
+export interface ParsedOptions {
+  options: CrosstalkOptions
+  warnings: string[]
+}
+
+/** Read a finite number, clamped to `[min, max]`. */
+function numberOption(
+  raw: Record<string, unknown>,
+  key: string,
+  fallback: number,
+  min: number,
+  max: number,
+  warnings: string[],
+): number {
+  const value = raw[key]
+  if (value === undefined) return fallback
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    warnings.push(`option "${key}" must be a finite number; using ${fallback}`)
+    return fallback
+  }
+  if (value < min) {
+    warnings.push(`option "${key}" (${value}) is below ${min}; clamped`)
+    return min
+  }
+  if (value > max) {
+    warnings.push(`option "${key}" (${value}) is above ${max}; clamped`)
+    return max
+  }
+  return value
+}
+
+function booleanOption(raw: Record<string, unknown>, key: string, fallback: boolean, warnings: string[]): boolean {
+  const value = raw[key]
+  if (value === undefined) return fallback
+  if (typeof value !== "boolean") {
+    warnings.push(`option "${key}" must be a boolean; using ${fallback}`)
+    return fallback
+  }
+  return value
+}
+
+function stringOption(
+  raw: Record<string, unknown>,
+  key: string,
+  fallback: string,
+  pattern: RegExp,
+  warnings: string[],
+): string {
+  const value = raw[key]
+  if (value === undefined) return fallback
+  if (typeof value !== "string" || value.length === 0) {
+    warnings.push(`option "${key}" must be a non-empty string; using ${fallback}`)
+    return fallback
+  }
+  if (!pattern.test(value)) {
+    warnings.push(`option "${key}" (${JSON.stringify(value)}) has unsupported characters; using ${fallback}`)
+    return fallback
+  }
+  return value
+}
+
+/**
+ * Validate raw plugin options. Unknown keys are reported once so typos are
+ * visible without being fatal.
+ */
+export function parseOptions(raw: unknown): ParsedOptions {
+  const warnings: string[] = []
+  if (raw === undefined || raw === null) return { options: { ...DEFAULTS }, warnings }
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { options: { ...DEFAULTS }, warnings: ["plugin options must be an object; using defaults"] }
+  }
+
+  const input = raw as Record<string, unknown>
+  for (const key of Object.keys(input)) {
+    if (!(key in DEFAULTS)) warnings.push(`unknown option "${key}" ignored`)
+  }
+
+  const scopeInput = input.scope
+  let scope: Scope = DEFAULTS.scope
+  if (scopeInput !== undefined) {
+    if (typeof scopeInput === "string" && (SCOPES as readonly string[]).includes(scopeInput)) {
+      scope = scopeInput as Scope
+    } else {
+      warnings.push(`option "scope" must be one of ${SCOPES.join(", ")}; using ${DEFAULTS.scope}`)
+    }
+  }
+
+  const staleAfterMs = numberOption(input, "staleAfterMs", DEFAULTS.staleAfterMs, 1_000, 86_400_000, warnings)
+  const evictRaw = numberOption(input, "evictAfterMs", DEFAULTS.evictAfterMs, 1_000, 604_800_000, warnings)
+
+  return {
+    warnings,
+    options: {
+      namespace: stringOption(input, "namespace", DEFAULTS.namespace, /^[A-Za-z0-9_-]+$/, warnings),
+      permission: stringOption(input, "permission", DEFAULTS.permission, /^[A-Za-z0-9_*-]+$/, warnings),
+      codemode: booleanOption(input, "codemode", DEFAULTS.codemode, warnings),
+      scope,
+      staleAfterMs,
+      // Eviction can never be more eager than the stale threshold.
+      evictAfterMs: Math.max(evictRaw, staleAfterMs),
+      maxMessages: numberOption(input, "maxMessages", DEFAULTS.maxMessages, 1, 10_000, warnings),
+      messageTtlMs: numberOption(input, "messageTtlMs", DEFAULTS.messageTtlMs, 1_000, 2_592_000_000, warnings),
+      claimTtlMs: numberOption(input, "claimTtlMs", DEFAULTS.claimTtlMs, 1_000, 86_400_000, warnings),
+      maxWaitMs: numberOption(input, "maxWaitMs", DEFAULTS.maxWaitMs, 1_000, 600_000, warnings),
+      pollMs: numberOption(input, "pollMs", DEFAULTS.pollMs, 50, 30_000, warnings),
+      heartbeatMs: numberOption(input, "heartbeatMs", DEFAULTS.heartbeatMs, 0, 600_000, warnings),
+      persist: booleanOption(input, "persist", DEFAULTS.persist, warnings),
+      storageKey: stringOption(input, "storageKey", DEFAULTS.storageKey, /^[A-Za-z0-9_./-]+$/, warnings),
+      announce: booleanOption(input, "announce", DEFAULTS.announce, warnings),
+    },
+  }
+}

package/src/core/avatar.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Avatar selection: map a session to one of the bundled Personas.
+ *
+ * Host-free and shared. The server plugin runs it once, the first time a
+ * session declares a task, and freezes the result on the peer record — the
+ * artwork never changes afterwards. The TUI only renders what it is given.
+ * Unit tests hand it small entry arrays, so no manifest has to be on disk.
+ */
+
+/** One entry of `assets/avatars/manifest.json`. */
+export interface AvatarEntry {
+  file: string
+  pool: string
+  role: string
+  skin?: string
+  mouth?: string
+  hair?: string
+  eyes?: string
+  clothes?: string
+  nose?: string
+  hairColor?: string
+  clothingColor?: string
+}
+
+export type AvatarPool = "female" | "male"
+
+/** The declared fields a portrait is derived from. */
+export interface AvatarSession {
+  sessionID: string
+  name?: string
+  role?: string
+  avatar?: string
+}
+
+/**
+ * Gender hint from the declared avatar emoji. Personas are hand-curated into
+ * two pools, so the emoji only steers the pool; the tone is baked into the art.
+ */
+export function poolHint(avatar: string | undefined): AvatarPool | undefined {
+  if (!avatar) return undefined
+  if (avatar.includes("👩") || avatar.includes("👧") || avatar.includes("👵")) return "female"
+  if (avatar.includes("👨") || avatar.includes("👦") || avatar.includes("👴") || avatar.includes("🧔")) return "male"
+  return undefined
+}
+
+/** FNV-1a, so a session's avatar is stable across reloads and processes. */
+export function hash(input: string): number {
+  let value = 2166136261
+  for (let index = 0; index < input.length; index += 1) {
+    value ^= input.charCodeAt(index)
+    value = Math.imul(value, 16777619)
+  }
+  return value >>> 0
+}
+
+/**
+ * Pick the avatar for one session:
+ *
+ * 1. the declared emoji picks a pool when it names a gender;
+ * 2. a role that matches a seed wins inside that pool;
+ * 3. otherwise the name (or session id) hashes to a stable entry.
+ */
+export function chooseAvatar(
+  entries: readonly AvatarEntry[],
+  session: AvatarSession,
+): AvatarEntry | undefined {
+  if (entries.length === 0) return undefined
+  const pool = poolHint(session.avatar)
+  const pooled = pool ? entries.filter((entry) => entry.pool === pool) : entries
+  const role = session.role?.toLowerCase()
+  const byRole = role ? pooled.filter((entry) => entry.role.toLowerCase() === role) : []
+  const candidates = byRole.length > 0 ? byRole : pooled.length > 0 ? pooled : entries
+  return candidates[hash(session.name ?? session.sessionID) % candidates.length]
+}
+
+/**
+ * Whether a declaration carries work: a role, a goal, or a current summary. A
+ * bare name is a nickname, not a task — a session that only named itself has
+ * none yet.
+ */
+export function hasTask(declared: { role?: string; goal?: string; summary?: string } | undefined): boolean {
+  return declared?.role !== undefined || declared?.goal !== undefined || declared?.summary !== undefined
+}
+
+/**
+ * The frozen portrait path (`pool/file` inside `assets/avatars/`) for one
+ * session, or `undefined` when there is no pool to pick from.
+ */
+export function portraitFor(entries: readonly AvatarEntry[], session: AvatarSession): string | undefined {
+  const entry = chooseAvatar(entries, session)
+  return entry === undefined ? undefined : `${entry.pool}/${entry.file}`
+}

package/src/core/claims.ts

@@ -0,0 +1,302 @@
+/**
+ * @fileoverview Resource leases.
+ *
+ * Two agents editing the same file is the coordination failure that actually
+ * bites in a shared repository, so a claim is a hard, exclusive, expiring
+ * lease rather than a convention. Keys are normalized paths (or any named
+ * resource string) so `"./src/a.ts"`, `"src//a.ts"` and `"src/a.ts/"` all
+ * collide, and relative paths resolve against the holder's directory so two
+ * worktrees of the same project do not shadow each other.
+ *
+ * Keys are compared exactly — there is no pattern matching, so `*` and `**`
+ * are ordinary characters inside a segment. Leasing a directory covers only
+ * that key, never its children; the tool text says so to the model.
+ */
+
+import type { Claim, ClaimConflict, ClaimOutcome } from "../types.ts"
+
+export interface ClaimOptions {
+  now(): number
+  defaultTtlMs: number
+}
+
+export interface ClaimRequest {
+  holder: string
+  resources: readonly string[]
+  ttlMs?: number
+  note?: string
+  /** Steal leases held by others. */
+  force?: boolean
+  /** Default true: one conflict aborts the whole request. */
+  atomic?: boolean
+  baseDir?: string
+}
+
+export interface ListFilter {
+  holder?: string
+  /** Only claims whose key matches this resource. */
+  resource?: string
+  includeExpired?: boolean
+  baseDir?: string
+}
+
+/**
+ * Normalize a resource string into a comparison key.
+ *
+ * Windows-looking paths (drive letter or backslashes) are case-folded because
+ * that filesystem is; POSIX paths keep their case. Glob metacharacters carry
+ * no meaning here: `src/auth/**` normalizes to the literal `src/auth/**`.
+ */
+export function normalizeResource(raw: string, baseDir?: string): string {
+  const original = raw.trim()
+  if (original === "") return ""
+  const windows = original.includes("\\") || /^[a-zA-Z]:/.test(original)
+  const slashed = original.replaceAll("\\", "/")
+  // A base directory can make a relative resource absolute, so `absolute` has
+  // to be decided from the combined path, not from the raw input.
+  const source = slashed.startsWith("/")
+    ? slashed
+    : baseDir
+      ? `${baseDir.replaceAll("\\", "/").replace(/\/+$/, "")}/${slashed}`
+      : slashed
+  const absolute = source.startsWith("/")
+
+  const out: string[] = []
+  for (const segment of source.split("/")) {
+    if (segment === "" || segment === ".") continue
+    if (segment === "..") {
+      const last = out.at(-1)
+      if (last !== undefined && last !== "..") out.pop()
+      else if (!absolute) out.push("..")
+      continue
+    }
+    out.push(segment)
+  }
+
+  const joined = out.join("/")
+  const result = absolute ? `/${joined}` : joined
+  return windows ? result.toLowerCase() : result
+}
+
+export class ClaimTable {
+  readonly #claims = new Map<string, Claim>()
+  readonly #now: () => number
+  readonly #defaultTtlMs: number
+
+  constructor(options: ClaimOptions) {
+    this.#now = options.now
+    this.#defaultTtlMs = Math.max(1, options.defaultTtlMs)
+  }
+
+  get size(): number {
+    return this.#claims.size
+  }
+
+  normalize(raw: string, baseDir?: string): string {
+    return normalizeResource(raw, baseDir)
+  }
+
+  /**
+   * Take leases.
+   *
+   * Two phases on purpose: the whole request is planned against current state
+   * before anything is written, so an atomic request that hits one conflict
+   * leaves the table exactly as it found it — including keys it had already
+   * staged earlier in the same call.
+   */
+  claim(request: ClaimRequest): ClaimOutcome {
+    const atomic = request.atomic !== false
+    const ttl = this.#resolveTtl(request.ttlMs)
+    const now = this.#now()
+
+    type Step =
+      | { action: "take"; key: string; raw: string; previous: Claim | undefined }
+      | { action: "renew"; key: string; previous: Claim }
+      | { action: "skip" }
+
+    const outcome: ClaimOutcome = {
+      claimed: [],
+      renewed: [],
+      released: [],
+      stolen: [],
+      conflicts: [],
+      rolledBack: false,
+    }
+    const plan: Step[] = []
+    const seen = new Set<string>()
+
+    for (const raw of request.resources) {
+      const key = this.normalize(raw, request.baseDir)
+      if (key === "" || seen.has(key)) continue
+      seen.add(key)
+
+      const existing = this.#claims.get(key)
+      const live = existing !== undefined && existing.expires > now
+      const mine = live && existing.holder === request.holder
+
+      if (live && !mine && !request.force) {
+        outcome.conflicts.push(this.#conflict(key, raw, existing))
+        if (atomic) {
+          outcome.rolledBack = true
+          return outcome
+        }
+        plan.push({ action: "skip" })
+        continue
+      }
+
+      if (live && !mine) outcome.stolen.push(key)
+
+      if (mine && existing) {
+        plan.push({ action: "renew", key, previous: existing })
+        continue
+      }
+
+      // Not live, or ours to take: a lapsed lease is not a conflict, because
+      // the previous holder let it expire.
+      plan.push({ action: "take", key, raw, previous: existing })
+    }
+
+    for (const step of plan) {
+      if (step.action === "skip") continue
+      if (step.action === "renew") {
+        step.previous.expires = now + ttl
+        step.previous.note = request.note ?? step.previous.note
+        outcome.renewed.push(step.key)
+        continue
+      }
+      const acquired = step.previous?.holder === request.holder ? (step.previous.acquired ?? now) : now
+      this.#claims.set(step.key, {
+        key: step.key,
+        raw: step.raw,
+        holder: request.holder,
+        note: request.note,
+        acquired,
+        expires: now + ttl,
+      })
+      outcome.claimed.push(step.key)
+    }
+
+    return outcome
+  }
+
+  /** Extend leases the caller already holds. Unknown or foreign keys are reported. */
+  renew(request: ClaimRequest): ClaimOutcome {
+    const now = this.#now()
+    const ttl = this.#resolveTtl(request.ttlMs)
+    const outcome: ClaimOutcome = { claimed: [], renewed: [], released: [], stolen: [], conflicts: [], rolledBack: false }
+    const atomic = request.atomic !== false
+
+    for (const raw of request.resources) {
+      const key = this.normalize(raw, request.baseDir)
+      if (key === "") continue
+      const existing = this.#claims.get(key)
+      if (!existing || existing.expires <= now) {
+        outcome.conflicts.push({ key, raw, holder: existing?.holder ?? "", expires: existing?.expires ?? 0 })
+        if (atomic) {
+          outcome.rolledBack = true
+          return outcome
+        }
+        continue
+      }
+      if (existing.holder !== request.holder) {
+        outcome.conflicts.push(this.#conflict(key, raw, existing))
+        if (atomic) {
+          outcome.rolledBack = true
+          return outcome
+        }
+        continue
+      }
+      existing.expires = now + ttl
+      existing.note = request.note ?? existing.note
+      outcome.renewed.push(key)
+    }
+
+    return outcome
+  }
+
+  /** Release leases. Only the holder may release, unless `force` is set. */
+  release(request: ClaimRequest): ClaimOutcome {
+    const now = this.#now()
+    const outcome: ClaimOutcome = { claimed: [], renewed: [], released: [], stolen: [], conflicts: [], rolledBack: false }
+
+    for (const raw of request.resources) {
+      const key = this.normalize(raw, request.baseDir)
+      if (key === "") continue
+      const existing = this.#claims.get(key)
+      if (!existing || existing.expires <= now) {
+        this.#claims.delete(key)
+        continue
+      }
+      if (existing.holder !== request.holder && !request.force) {
+        outcome.conflicts.push(this.#conflict(key, raw, existing))
+        continue
+      }
+      if (existing.holder !== request.holder) outcome.stolen.push(key)
+      this.#claims.delete(key)
+      outcome.released.push(key)
+    }
+
+    return outcome
+  }
+
+  list(filter: ListFilter = {}): Claim[] {
+    const now = this.#now()
+    const resourceKey = filter.resource === undefined ? undefined : this.normalize(filter.resource, filter.baseDir)
+    const claims: Claim[] = []
+    for (const claim of this.#claims.values()) {
+      if (claim.expires <= now && !filter.includeExpired) continue
+      if (filter.holder !== undefined && claim.holder !== filter.holder) continue
+      if (resourceKey !== undefined && claim.key !== resourceKey) continue
+      claims.push(claim)
+    }
+    claims.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    return claims
+  }
+
+  /** Keys currently held by a session. */
+  heldBy(holder: string): string[] {
+    return this.list({ holder }).map((claim) => claim.key)
+  }
+
+  /** True when nothing live holds the resource. */
+  isFree(raw: string, baseDir?: string): boolean {
+    const key = this.normalize(raw, baseDir)
+    if (key === "") return true
+    const existing = this.#claims.get(key)
+    return !existing || existing.expires <= this.#now()
+  }
+
+  /** Delete expired leases. Returns how many were removed. */
+  prune(): number {
+    const now = this.#now()
+    let removed = 0
+    for (const [key, claim] of this.#claims) {
+      if (claim.expires <= now) {
+        this.#claims.delete(key)
+        removed += 1
+      }
+    }
+    return removed
+  }
+
+  /** Every live claim, for snapshotting. */
+  entries(): Claim[] {
+    return this.list({ includeExpired: false })
+  }
+
+  /**
+   * Re-insert a claim verbatim, used when restoring a snapshot where the key
+   * has already been normalized. Callers must check `isFree` first.
+   */
+  adopt(claim: Claim): void {
+    this.#claims.set(claim.key, { ...claim })
+  }
+
+  #resolveTtl(ttlMs: number | undefined): number {
+    return Math.max(1, ttlMs ?? this.#defaultTtlMs)
+  }
+
+  #conflict(key: string, raw: string, claim: Claim): ClaimConflict {
+    return { key, raw, holder: claim.holder, note: claim.note, expires: claim.expires }
+  }
+}

package/src/core/clock.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Injectable time source and an abortable sleep.
+ *
+ * Every time-dependent code path in `src/core` takes a `now()` function so TTL
+ * and long-poll behaviour is deterministic under test instead of timer-bound.
+ */
+
+export interface Clock {
+  now(): number
+}
+
+export const systemClock: Clock = { now: () => Date.now() }
+
+/** Sleep that resolves early (without throwing) when `signal` aborts. */
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal?.aborted || ms <= 0) {
+      resolve()
+      return
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      resolve()
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener("abort", onAbort, { once: true })
+  })
+}