opencode-crosstalk 0.0.0-stage → 0.2.0

package/src/tools/status.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview `crosstalk_status` — declare who you are, see who else is here.
+ */
+
+import { SNAPSHOT_VERSION } from "../core/mesh.ts"
+import { meshStorageKey } from "../storage.ts"
+import { formatStatus, SUMMARY_STALE_MS, relativeAge } from "../core/format.ts"
+import { ArgError, readString, readStringArray } from "./args.ts"
+import { jsonSchema, run, type ToolDeps, type CrosstalkToolInfo } from "./types.ts"
+
+/**
+ * Health of the instance guard `src/index.ts` keeps on `globalThis` (same
+ * process, shared by every plugin load): the locations live instances own and
+ * the loads it refused. Both are the twin-install trace a log-less model
+ * cannot otherwise see; the read is strict — anything but the exact promised
+ * shape yields `undefined`, so a refactor there costs a line, not a lie.
+ */
+function guardHealth(): { locations: number; refused: number } | undefined {
+  const guard = (globalThis as { __crosstalk?: { owners?: unknown; refused?: unknown } }).__crosstalk
+  if (!(guard?.owners instanceof Map) || typeof guard.refused !== "number") return undefined
+  return { locations: guard.owners.size, refused: guard.refused }
+}
+
+/** A human name is a nickname: letters, digits, spaces, `-`, `_`; 1-32 chars. */
+const NAME_PATTERN = /^[A-Za-z][A-Za-z0-9 _-]{0,31}$/
+
+export function statusTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "status",
+    description: [
+      "Declare what this session is working on and see every other session on this channel.",
+      "Call this early in a task: peers use your role to route messages, and it is how two agents",
+      "on one repository discover each other. Give yourself a unique human name so the user and",
+      "peers can address you (\"tell George…\"). Fields you leave out keep their previous value.",
+      "Set `summary` — one or two short sentences on what you are doing right now — and refresh it",
+      "whenever your task changes: it is shown under your avatar in the sidebar and read by peers.",
+      "Returns your own record plus the peer list with each peer's status, activity age, unread mail,",
+      "and any files they have already leased.",
+      "The output carries a self-check line (snapshot format, storage key, live plugin locations)",
+      "so an install problem is visible without reading server logs.",
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: 'Unique human name others can address you by, e.g. "George" (letters, digits, spaces, - and _)',
+        },
+        role: { type: "string", description: "Short noun for your job, e.g. reviewer, migrator, tester" },
+        goal: { type: "string", description: "What you are trying to accomplish in this session" },
+        summary: {
+          type: "string",
+          description:
+            "What you are doing right now: 1-2 short sentences, shown under your avatar and read by peers. Refresh it when your task changes",
+        },
+        workingOn: {
+          type: "array",
+          items: { type: "string" },
+          description: "Files or areas you expect to touch, e.g. src/auth/session.ts",
+        },
+        note: { type: "string", description: "Anything peers should know (a blocker, a hand-off)" },
+        avatar: {
+          type: "string",
+          description:
+            'Optional avatar hint for the TUI, e.g. an emoji like "👩" or "👨" that picks the character pool',
+        },
+      },
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(() => {
+        const selfID = context.sessionID
+        const name = readString(input, "name", { max: 32 })
+        if (name !== undefined && !NAME_PATTERN.test(name)) {
+          throw new ArgError('"name" must start with a letter and contain only letters, digits, spaces, "-" or "_"')
+        }
+        const role = readString(input, "role", { max: 64 })
+        const goal = readString(input, "goal", { max: 400 })
+        // One or two short sentences: the live status line under the avatar.
+        const summary = readString(input, "summary", { max: 200 })
+        const note = readString(input, "note", { max: 400 })
+        const avatar = readString(input, "avatar", { max: 32 })
+        const workingOn = readStringArray(input, "workingOn", { max: 32, maxLength: 200 })
+
+        const declared =
+          name || role || goal || note || avatar || workingOn || summary
+            ? deps.mesh.declare(selfID, { name, role, goal, summary, note, avatar, workingOn })
+            : { view: deps.mesh.view(selfID) }
+        if (declared.nameConflict) {
+          return (
+            `crosstalk: the name "${declared.nameConflict.name}" is already used by ${declared.nameConflict.holder}` +
+            ` — pick another, or address them with crosstalk_send { to: "${declared.nameConflict.holder}" }`
+          )
+        }
+        const self = declared.view
+
+        const peers = deps.mesh.peers(selfID)
+        const claimsHeld = self.claims.length
+        const now = deps.mesh.now()
+        const hints: string[] = []
+        if (peers.some((peer) => peer.claims.length > 0)) {
+          hints.push("some peers hold leases — use crosstalk_claim before editing their files")
+        }
+        if (peers.some((peer) => !peer.addressable)) {
+          hints.push("some peers are outside the communication wall and cannot be messaged")
+        }
+        if (self.unread > 0) hints.push(`you have ${self.unread} unread message(s) — crosstalk_inbox`)
+        if (claimsHeld === 0 && peers.length > 0) {
+          hints.push("claim what you are about to edit: crosstalk_claim { resources: [...] }")
+        }
+        if (self.declared?.summary === undefined && peers.length > 0) {
+          hints.push('tell peers what you are doing right now: crosstalk_status { summary: "…" }')
+        }
+        // A summary nobody refreshes reads as a promise: the sidebar dims it
+        // after the same window, so the agent hears about it at the same moment
+        // the user starts seeing it.
+        if (self.declared?.summaryAt !== undefined && now - self.declared.summaryAt > SUMMARY_STALE_MS) {
+          hints.push(
+            `your summary is ${relativeAge(self.declared.summaryAt, now)} old — refresh it: crosstalk_status { summary: … }`,
+          )
+        }
+
+        // Diagnostics for the calling location, through the store's own key
+        // formula so the line can never name a key state does not live under.
+        const health = guardHealth()
+        const selfCheck = {
+          snapshot: `v${SNAPSHOT_VERSION}`,
+          persist: deps.options.persist,
+          ...(deps.options.persist ? { storageKey: meshStorageKey(deps.options.storageKey, self.projectID) } : {}),
+          ...(health ? { locations: health.locations, refused: health.refused } : {}),
+        }
+
+        return formatStatus({ self, peers, scope: deps.options.scope, now, hints, selfCheck })
+      })
+    },
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Shared plumbing for the crosstalk tools.
+ *
+ * Tool definitions use plain JSON Schema (no Zod) so the plugin has no runtime
+ * dependency beyond `@opencode/plugin`, and every executor narrows its input
+ * through `src/tools/args.ts`.
+ */
+
+import type { Info, ToolContext, ToolEditor } from "@opencode/plugin/promise/tool"
+import type { CrosstalkOptions } from "../config.ts"
+import type { Mesh } from "../core/mesh.ts"
+import { ArgError } from "./args.ts"
+
+export { ArgError }
+
+export type CrosstalkToolInfo = Parameters<ToolEditor["add"]>[0]
+export type ToolInputSchema = CrosstalkToolInfo["input"]
+export type { Info, ToolContext }
+
+export interface ToolDeps {
+  mesh: Mesh
+  options: CrosstalkOptions
+}
+
+/**
+ * Tool input schemas accept a JSON Schema literal, or an Effect / Standard
+ * Schema codec. This plugin only ever writes JSON Schema, so the single cast
+ * lives here instead of in every tool.
+ */
+export function jsonSchema(value: Record<string, unknown>): ToolInputSchema {
+  return value as unknown as ToolInputSchema
+}
+
+/**
+ * Wrap executor bodies: the result becomes tool content, and a bad argument
+ * comes back as readable output the model can correct itself from. Any other
+ * failure is a real bug and is left to propagate.
+ */
+export async function run(fn: () => Promise<string> | string): Promise<{ content: string }> {
+  try {
+    return { content: await fn() }
+  } catch (error) {
+    if (error instanceof ArgError) return { content: `crosstalk: ${error.message}` }
+    throw error
+  }
+}
+
+/**
+ * Call `context.progress` every `intervalMs` while a long call is blocked, so
+ * the TUI shows liveness instead of a frozen tool. `intervalMs === 0` disables
+ * it, which is what the tests use.
+ */
+export function startHeartbeat(
+  context: ToolContext,
+  intervalMs: number,
+  status: () => Record<string, unknown>,
+): () => void {
+  if (intervalMs <= 0) return () => {}
+  const timer = setInterval(() => {
+    void context.progress(status()).catch(() => {})
+  }, intervalMs)
+  // Never hold the process open for a heartbeat.
+  timer.unref?.()
+  const stop = () => clearInterval(timer)
+  context.signal.addEventListener("abort", stop, { once: true })
+  return stop
+}
+
+/** Clamp a requested wait to the configured ceiling. */
+export function clampWait(ms: number, options: CrosstalkOptions): number {
+  return Math.min(Math.max(0, ms), options.maxWaitMs)
+}

package/src/tools/wait.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview `crosstalk_wait` — block on a peer or a lease.
+ *
+ * Mail waiting is covered by `crosstalk_inbox { wait }`; this tool is the
+ * barrier between two agents that have to take turns — one waits for the other
+ * to stop touching the code, or for a file to be released.
+ */
+
+import { formatWait } from "../core/format.ts"
+import { readNumber, readString } from "./args.ts"
+import { clampWait, jsonSchema, run, startHeartbeat, type CrosstalkToolInfo, type ToolDeps } from "./types.ts"
+
+export function waitTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "wait",
+    description: [
+      "Block until another session is no longer working, or until a claimed resource is released.",
+      "Use it instead of sleeping or re-checking by hand when two sessions are taking turns on the",
+      "same code. Returns as soon as the condition holds, or reports a timeout you can act on.",
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        for: {
+          type: "string",
+          enum: ["peer_idle", "claim_free"],
+          description: "Wait for a peer to go idle, or for a resource to become unclaimed",
+        },
+        sessionID: { type: "string", description: "Peer to wait for. Required for peer_idle." },
+        resource: { type: "string", description: "File path or named resource. Required for claim_free." },
+        timeoutSeconds: { type: "number", description: "Give up after this many seconds (default 30)" },
+      },
+      required: ["for"],
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(async () => {
+        const forWhat = readString(input, "for", { required: true })
+        if (forWhat !== "peer_idle" && forWhat !== "claim_free") {
+          return 'crosstalk: "for" must be "peer_idle" or "claim_free"'
+        }
+        const sessionID = readString(input, "sessionID", { max: 200 })
+        const resource = readString(input, "resource", { max: 400 })
+        const timeoutSeconds = readNumber(input, "timeoutSeconds", { min: 0, max: 600, fallback: 30 })
+        const timeoutMs = clampWait((timeoutSeconds ?? 30) * 1000, deps.options)
+
+        if (forWhat === "peer_idle" && sessionID === undefined) {
+          return 'crosstalk: waiting for a peer needs "sessionID" (see crosstalk_peers)'
+        }
+        if (forWhat === "claim_free" && resource === undefined) {
+          return 'crosstalk: waiting for a resource needs "resource" (the path you want to edit)'
+        }
+
+        const stop = startHeartbeat(context, deps.options.heartbeatMs, () => ({
+          status: "waiting",
+          for: forWhat,
+          ...(sessionID ? { sessionID } : {}),
+          ...(resource ? { resource } : {}),
+        }))
+
+        let body: string
+        try {
+          if (forWhat === "peer_idle" && sessionID) {
+            const result = await deps.mesh.waitForPeerIdle(context.sessionID, sessionID, timeoutMs, context.signal)
+            body = formatWait({
+              forWhat,
+              reason: result.reason,
+              elapsedMs: result.elapsedMs,
+              ...(result.reason === "gone" ? { detail: `${sessionID} is not on this channel any more` } : {}),
+              ...(result.reason === "outside" ? { detail: `${sessionID} is outside the ${deps.options.scope} scope` } : {}),
+            })
+          } else if (resource) {
+            const result = await deps.mesh.waitForClaimFree(
+              context.sessionID,
+              resource,
+              timeoutMs,
+              deps.mesh.directoryOf(context.sessionID),
+              context.signal,
+            )
+            body = formatWait({
+              forWhat,
+              reason: result.reason,
+              elapsedMs: result.elapsedMs,
+              ...(result.holder ? { detail: `still held by ${result.holder}` } : {}),
+            })
+          } else {
+            body = "crosstalk: nothing to wait for"
+          }
+        } finally {
+          stop()
+        }
+        return body
+      })
+    },
+  }
+}

package/src/tui/avatar.ts

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview How a frozen portrait is shown: the emoticon that belongs to
+ * the Persona it was given, the title that emoticon is written into, and the
+ * status summary shown under the avatar.
+ *
+ * The selection itself lives in `src/core/avatar.ts`: the server freezes one
+ * portrait per session when a task is first declared, so this side only maps a
+ * portrait path back to its manifest entry and decorates it. Pure and
+ * host-free so it is unit-testable.
+ */
+
+import { hash, type AvatarEntry } from "../core/avatar.ts"
+import { ellipsis } from "../core/format.ts"
+
+export {
+  chooseAvatar,
+  hasTask,
+  hash,
+  poolHint,
+  portraitFor,
+  type AvatarEntry,
+  type AvatarPool,
+  type AvatarSession,
+} from "../core/avatar.ts"
+
+/** The manifest entry a frozen portrait (`pool/file`) refers to. */
+export function entryForPortrait(
+  entries: readonly AvatarEntry[],
+  portrait: string | undefined,
+): AvatarEntry | undefined {
+  if (portrait === undefined) return undefined
+  return entries.find((entry) => `${entry.pool}/${entry.file}` === portrait)
+}
+
+/**
+ * One emoticon per Persona role, curated from tools, objects, and people.
+ *
+ * Roles with several entries in the same pool carry alternates so two sessions
+ * wearing the same trade do not collapse into one glyph; which alternate an
+ * avatar gets is decided by its file name, so it never changes between renders.
+ * A role missing from this table falls back to `FALLBACK_EMOTICONS`, which keeps
+ * a regenerated manifest working before anyone curates the new roles.
+ */
+export const EMOTICONS: Record<string, readonly string[]> = {
+  analyst: ["📊", "📉"],
+  architect: ["🏛️", "📐"],
+  auditor: ["🧮", "🧾"],
+  builder: ["🧱", "🪚"],
+  coder: ["💻", "⌨️", "🖥️"],
+  compiler: ["🛠️", "🗜️"],
+  coordinator: ["📡", "🧭"],
+  debugger: ["🪛", "🔦"],
+  deployer: ["🚀", "📤"],
+  designer: ["🎨", "📐"],
+  editor: ["📓", "✂️"],
+  explorer: ["🧭", "🗺️"],
+  fixer: ["🔧", "🩹"],
+  formatter: ["📐", "📏"],
+  gardener: ["🪴", "🧤"],
+  guardian: ["🛡️", "🔒"],
+  hacker: ["🕶️", "💻"],
+  integrator: ["🔗", "🧲"],
+  librarian: ["📚", "🗃️"],
+  linter: ["🧹", "🚨"],
+  maintainer: ["🛢️", "🔧"],
+  manager: ["💼", "🗂️"],
+  mentor: ["🎓", "📖"],
+  migrator: ["🚚", "🧳"],
+  operator: ["🎛️", "🕹️"],
+  optimizer: ["⚙️", "🛢️"],
+  parser: ["🧩", "🔤"],
+  patcher: ["🩹", "🧵"],
+  pioneer: ["🏔️", "⛺"],
+  planner: ["📅", "🗒️"],
+  profiler: ["📈", "⏱️"],
+  refactorer: ["🔨", "🏗️"],
+  researcher: ["🔬", "📜"],
+  reviewer: ["🔍", "🧐"],
+  scout: ["🔭", "📡"],
+  sentinel: ["🚨", "📹"],
+  shipper: ["📦", "🛳️"],
+  shepherd: ["🧶", "🪢"],
+  simplifier: ["✂️", "🧹"],
+  strategist: ["🎯", "♟️"],
+  steward: ["🗂️", "🧾"],
+  tester: ["🧪", "🧫"],
+  tinkerer: ["🔩", "🪛"],
+  tracker: ["📍", "📌"],
+  wrangler: ["🎣", "🪝"],
+  writer: ["✒️", "📝"],
+}
+
+/** For manifest roles this table has not caught up with yet. */
+export const FALLBACK_EMOTICONS: readonly string[] = ["🧰", "🧩", "📦", "🧭"]
+
+const MANAGED_GLYPHS: readonly string[] = [
+  ...new Set([...Object.values(EMOTICONS).flat(), ...FALLBACK_EMOTICONS]),
+].sort((a, b) => b.length - a.length)
+
+/** The emoticon one avatar was given. Always defined: an unknown role degrades. */
+export function emoticonFor(entry: AvatarEntry | undefined): string {
+  const candidates = entry ? (EMOTICONS[entry.role.toLowerCase()] ?? FALLBACK_EMOTICONS) : FALLBACK_EMOTICONS
+  return candidates[hash(entry?.file ?? "crosstalk") % candidates.length] ?? FALLBACK_EMOTICONS[0]!
+}
+
+/**
+ * Drop a leading emoticon this plugin manages.
+ *
+ * Only glyphs from the curated table count, so a glyph the user typed into a
+ * title themselves is left alone.
+ */
+export function stripEmoticon(title: string): string {
+  const lead = title.replace(/^\s+/, "")
+  for (const glyph of MANAGED_GLYPHS) {
+    if (lead.startsWith(glyph)) return lead.slice(glyph.length).replace(/^[\s\u00a0]+/, "")
+  }
+  return title
+}
+
+/**
+ * Drop a leading `Name: ` prefix this plugin manages.
+ *
+ * Only a prefix matching the declared name counts, so a name the user typed
+ * into a title themselves is left alone.
+ */
+function stripNamePrefix(title: string, name: string): string {
+  const lead = title.replace(/^\s+/, "")
+  const prefix = `${name}:`
+  if (lead.startsWith(prefix)) return lead.slice(prefix.length).replace(/^[\s\u00a0]+/, "")
+  return title
+}
+
+/**
+ * The tab-header title for one session, or `undefined` when nothing should be
+ * written — either there is no title to decorate or it is already correct, so a
+ * caller can compare instead of guessing and the write stays idempotent.
+ *
+ * With a declared name the title becomes `Name: base`; without one it stays
+ * `base`, so sessions that never declared a name are unchanged.
+ */
+export function titleWithEmoticon(
+  title: string | undefined,
+  glyph: string | undefined,
+  name: string | undefined,
+): string | undefined {
+  if (title === undefined || glyph === undefined) return undefined
+  let base = title
+  if (name !== undefined && name.length > 0) base = stripNamePrefix(base, name)
+  base = stripEmoticon(base)
+  if (base.length === 0) return undefined
+  const wanted = name !== undefined && name.length > 0 ? `${name}: ${base}` : base
+  return wanted === title ? undefined : wanted
+}
+
+/** Widest status summary the sidebar shows; matches the tool's write limit. */
+export const SUMMARY_MAX = 200
+
+/**
+ * A summary older than this is dimmed in the sidebar. The session probably
+ * moved on and has not said so, and an undimmed stale line reads as a promise
+ * the session did not make. Mirrors the peer-line rule: an agent-facing age at
+ * five minutes, a human-facing dim at fifteen.
+ */
+export const STALE_SUMMARY_MS = 15 * 60_000
+
+/**
+ * Whether a summary is old enough to dim. A missing timestamp — a declaration
+ * from before the feature, or a snapshot that predates it — never dims: there
+ * is no evidence it is stale, only an absence of evidence.
+ */
+export function isSummaryStale(at: number | undefined, now: number): boolean {
+  return at !== undefined && now - at > STALE_SUMMARY_MS
+}
+
+/**
+ * The status summary under one avatar: what the session says it is doing right
+ * now, flattened onto a single line so the renderer wraps it itself. The
+ * declared summary wins; a session that never wrote one falls back to its goal,
+ * so a declaration made before the summary existed still says something.
+ * Undefined when neither is there — the avatar block then shows only the name
+ * and the role, and the caller renders nothing.
+ */
+export function summaryText(entry: { summary?: string; goal?: string } | undefined): string | undefined {
+  const raw = entry?.summary ?? entry?.goal
+  if (raw === undefined) return undefined
+  const flat = ellipsis(raw, SUMMARY_MAX)
+  return flat.length === 0 ? undefined : flat
+}