opencode-crosstalk 0.0.0-stage → 0.2.0

package/src/core/registry.ts

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview Presence registry: folds the OpenCode event stream into a live
+ * view of which sessions exist, where they run, and whether they are busy.
+ *
+ * The plugin context deliberately exposes no `session.list()` / `session.active`
+ * (its session domain is a narrow `Pick` of the client API), so discovery is
+ * built from `ctx.event.subscribe()`. Events arrive as `{ type, location, data }`.
+ * Most carry a top-level `location`, but no session event besides
+ * `session.created` and `session.moved` carries a project id — a peer that
+ * missed those two never learns its project from the stream alone.
+ *
+ * Liveness has two thresholds: past `staleAfterMs` a peer is still listed but
+ * flagged, because an agent can spend minutes inside one model call without
+ * emitting anything; past `evictAfterMs` it is dropped, because a server that
+ * died will never send another event.
+ */
+
+import type { Peer, PeerStatus, PeerView, Scope } from "../types.ts"
+
+/** Structural subset of an OpenCode server event that the registry reads. */
+export interface CrosstalkEvent {
+  readonly type: string
+  readonly created?: number
+  readonly location?: { readonly directory?: string; readonly workspaceID?: string }
+  readonly data?: Readonly<Record<string, unknown>>
+}
+
+export interface RegistryOptions {
+  now(): number
+  staleAfterMs: number
+  evictAfterMs: number
+}
+
+export interface ListFilter {
+  selfID?: string
+  scope?: Scope
+  /** Falls back to the plugin location when the peer record has no project. */
+  selfProjectID?: string
+  selfDirectory?: string
+  status?: "running" | "idle" | "all"
+  includeSelf?: boolean
+  limit?: number
+  /**
+   * Communication wall: exclude peers whose location cannot be proven within
+   * the scope. Plain listings keep over-reporting unknown peers; sends, waits,
+   * and injection retries pass `strict: true` so a session whose project is
+   * unknown can never be addressed.
+   */
+  strict?: boolean
+}
+
+const STATUS_RANK: Readonly<Record<PeerStatus, number>> = { running: 0, idle: 1, unknown: 2 }
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
+
+/** Best-effort extraction of a session directory from an event. */
+function directoryOf(event: CrosstalkEvent): string | undefined {
+  const data = event.data
+  const nested = data?.location
+  if (nested && typeof nested === "object") {
+    const value = (nested as { directory?: unknown }).directory
+    if (typeof value === "string" && value.length > 0) return value
+  }
+  return str(event.location?.directory)
+}
+
+function modelLabel(value: unknown): string | undefined {
+  if (typeof value === "string") return value
+  if (!value || typeof value !== "object") return undefined
+  const ref = value as { providerID?: unknown; id?: unknown; variant?: unknown }
+  const id = str(ref.id)
+  if (!id) return undefined
+  const provider = str(ref.providerID)
+  const variant = str(ref.variant)
+  const base = provider ? `${provider}/${id}` : id
+  return variant ? `${base}#${variant}` : base
+}
+
+export class Registry {
+  readonly #peers = new Map<string, Peer>()
+  readonly #now: () => number
+  readonly #staleAfterMs: number
+  readonly #evictAfterMs: number
+
+  constructor(options: RegistryOptions) {
+    this.#now = options.now
+    this.#staleAfterMs = options.staleAfterMs
+    this.#evictAfterMs = options.evictAfterMs
+  }
+
+  get size(): number {
+    return this.#peers.size
+  }
+
+  get(sessionID: string): Peer | undefined {
+    return this.#peers.get(sessionID)
+  }
+
+  /**
+   * Create a placeholder record for a session the registry has not seen an
+   * event for — a child session started before the plugin loaded, or the
+   * calling session itself.
+   */
+  ensure(sessionID: string, defaults: { projectID?: string; directory?: string; agent?: string } = {}): Peer {
+    const existing = this.#peers.get(sessionID)
+    if (existing) return existing
+    const now = this.#now()
+    const peer: Peer = {
+      sessionID,
+      status: "unknown",
+      created: now,
+      lastSeen: now,
+      projectID: defaults.projectID,
+      directory: defaults.directory,
+      agent: defaults.agent,
+    }
+    this.#peers.set(sessionID, peer)
+    return peer
+  }
+
+  /** Merge a patch into a peer, creating it when unknown. */
+  update(sessionID: string, patch: Partial<Peer>): Peer {
+    const peer = this.ensure(sessionID)
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === undefined) continue
+      if (key === "sessionID" || key === "lastSeen") continue
+      // `declared` is a nested record; callers pass the whole object.
+      ;(peer as unknown as Record<string, unknown>)[key] = value
+    }
+    return peer
+  }
+
+  delete(sessionID: string): boolean {
+    return this.#peers.delete(sessionID)
+  }
+
+  /**
+   * Fold one server event into the registry. Returns true when the event was
+   * recognized and changed or refreshed a record. Unknown event types are
+   * ignored so the reducer can be extended without breaking older hosts.
+   */
+  apply(event: CrosstalkEvent): boolean {
+    const data = event.data
+    if (!data) return false
+    const sessionID = str(data.sessionID)
+    if (!sessionID) return false
+
+    if (event.type === "session.deleted") return this.delete(sessionID)
+
+    const at = this.#timestamp(event)
+    const directory = directoryOf(event)
+    // `ensure` is what creates a record, so the event's own directory has to be
+    // passed in here — a second `ensure` call would find the record already
+    // present and ignore the defaults.
+    const target = this.ensure(sessionID, { directory })
+    target.lastSeen = at
+    // A record can be born on any event type: a session that started before the
+    // plugin loaded first shows up in `session.status`, not `session.created`.
+    // Real server events carry a top-level directory on most types and none of
+    // them carries a project, so every event that knows where the session runs
+    // refreshes it — and an event that does not must not clear what is known.
+    // `projectID` still only arrives with `session.created` / `session.moved`.
+    if (directory !== undefined) target.directory = directory
+
+    switch (event.type) {
+      case "session.created": {
+        target.projectID = str(data.projectID) ?? target.projectID
+        target.directory = directoryOf(event) ?? target.directory
+        target.title = str(data.title) ?? target.title
+        target.agent = str(data.agent) ?? target.agent
+        target.parentID = str(data.parentID) ?? target.parentID
+        target.model = modelLabel(data.model) ?? target.model
+        target.created = typeof data.created === "number" ? data.created : (target.created ?? at)
+        break
+      }
+      case "session.forked": {
+        target.parentID = str(data.parentID) ?? target.parentID
+        break
+      }
+      case "session.renamed": {
+        target.title = str(data.title) ?? target.title
+        break
+      }
+      case "session.moved": {
+        target.projectID = str(data.projectID) ?? target.projectID
+        const moved = data.location
+        if (moved && typeof moved === "object") {
+          const dir = (moved as { directory?: unknown }).directory
+          if (typeof dir === "string" && dir.length > 0) target.directory = dir
+        }
+        break
+      }
+      case "session.execution.started": {
+        target.status = "running"
+        break
+      }
+      case "session.status": {
+        const status = data.status
+        if (status && typeof status === "object") {
+          const kind = (status as { type?: unknown }).type
+          if (kind === "busy" || kind === "retry") target.status = "running"
+          else if (kind === "idle") target.status = "idle"
+        }
+        break
+      }
+      case "session.idle":
+      case "session.execution.succeeded":
+      case "session.execution.failed":
+      case "session.execution.interrupted": {
+        target.status = "idle"
+        break
+      }
+      case "session.tool.called":
+      case "session.step.started":
+      case "session.shell.started": {
+        target.status = "running"
+        break
+      }
+      default:
+        // Touched liveness above; no field to update.
+        return true
+    }
+    return true
+  }
+
+  /** True when no event arrived within the stale threshold. */
+  isStale(peer: Peer, now = this.#now()): boolean {
+    return now - peer.lastSeen > this.#staleAfterMs
+  }
+
+  /** Drop peers with no activity within the eviction threshold. */
+  prune(now = this.#now()): string[] {
+    const removed: string[] = []
+    for (const peer of this.#peers.values()) {
+      if (now - peer.lastSeen > this.#evictAfterMs) {
+        this.#peers.delete(peer.sessionID)
+        removed.push(peer.sessionID)
+      }
+    }
+    return removed
+  }
+
+  /** Peers visible under `filter`, running first, then most recently active. */
+  list(filter: ListFilter = {}): Peer[] {
+    const scope = filter.scope ?? "server"
+    const self = filter.selfID ? this.#peers.get(filter.selfID) : undefined
+    const selfProject = self?.projectID ?? filter.selfProjectID
+    const selfDirectory = self?.directory ?? filter.selfDirectory
+    const want = filter.status ?? "all"
+
+    const visible: Peer[] = []
+    for (const peer of this.#peers.values()) {
+      const isSelf = filter.selfID !== undefined && peer.sessionID === filter.selfID
+      if (isSelf && !filter.includeSelf) continue
+      if (scope === "project" && selfProject !== undefined) {
+        // Unknown-project peers stay visible in listings: better to over-report
+        // than to hide a session that is genuinely working the same repository.
+        // Under a strict filter (communication) they are excluded instead.
+        if (peer.projectID !== undefined && peer.projectID !== selfProject) continue
+        if (filter.strict && peer.projectID === undefined) continue
+      }
+      if (scope === "location" && selfDirectory !== undefined) {
+        if (peer.directory !== undefined && peer.directory !== selfDirectory) continue
+        if (filter.strict && peer.directory === undefined) continue
+      }
+      // Asking for yourself is asking for yourself: a status filter is about
+      // peers, so it should not silently drop the caller.
+      if (!isSelf && want !== "all" && peer.status !== want) continue
+      visible.push(peer)
+    }
+
+    visible.sort((a, b) => {
+      const rank = STATUS_RANK[a.status] - STATUS_RANK[b.status]
+      if (rank !== 0) return rank
+      if (a.lastSeen !== b.lastSeen) return b.lastSeen - a.lastSeen
+      return a.sessionID < b.sessionID ? -1 : a.sessionID > b.sessionID ? 1 : 0
+    })
+
+    if (filter.limit !== undefined && filter.limit >= 0 && visible.length > filter.limit) {
+      return visible.slice(0, filter.limit)
+    }
+    return visible
+  }
+
+  /** Peer plus mesh-derived fields, as tools hand them to agents. */
+  view(
+    peer: Peer,
+    extras: { isSelf: boolean; unread: number; claims: string[]; addressable: boolean },
+    now = this.#now(),
+  ): PeerView {
+    return {
+      ...peer,
+      isSelf: extras.isSelf,
+      stale: this.isStale(peer, now),
+      unread: extras.unread,
+      claims: extras.claims,
+      addressable: extras.addressable,
+    }
+  }
+
+  #timestamp(event: CrosstalkEvent): number {
+    return typeof event.created === "number" ? event.created : this.#now()
+  }
+}

package/src/deliverer.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Delivery of crosstalk messages into live sessions.
+ *
+ * A mailbox entry alone would not reach an agent that is mid-task, so each
+ * message is also injected into the recipient's session with
+ * `ctx.session.synthetic` — a durable, non-user message that does not masquerade
+ * as something the human typed. `steer` (the default) folds it into the
+ * recipient's current turn; `queue` waits for the turn to end.
+ *
+ * Delivery is best effort. A plugin instance belongs to one location, so
+ * synthesizing into a session owned by another location can fail; the mailbox
+ * copy is authoritative and the recipient sees the message on their next
+ * `crosstalk_inbox`.
+ */
+
+import type { CrosstalkMessage } from "./types.ts"
+import type { Deliverer } from "./core/mesh.ts"
+
+/** Structural subset of `ctx.session`. */
+export interface SessionLike {
+  synthetic(input: {
+    sessionID: string
+    text: string
+    description?: string
+    delivery?: "steer" | "queue"
+    metadata?: Record<string, unknown>
+  }): Promise<unknown>
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  if (typeof error === "string") return error
+  return "delivery failed"
+}
+
+/** The text injected into the recipient's session. */
+export function renderDelivery(message: CrosstalkMessage): string {
+  const lines: string[] = ["[crosstalk] another session on this project is talking to you."]
+  const actor = `${message.from}${message.fromName ? ` (${message.fromName})` : ""}`
+  if (message.fromRole) lines.push(`from ${actor} (${message.fromRole}) — ${message.kind}.`)
+  else lines.push(`from ${actor} — ${message.kind}.`)
+  if (message.topic) lines.push(`topic: ${message.topic}`)
+  lines.push("")
+  lines.push(message.text)
+  lines.push("")
+  // Only a `request` demands an answer. Steering every message manufactured
+  // ack loops between polite sessions; `meta.requested` carries the sender's
+  // role for context, it is not a reply demand.
+  if (message.kind === "request") {
+    lines.push(
+      `This is a request: answer with crosstalk_send addressed to ${message.fromName ?? message.from}, then continue your task.`,
+    )
+  } else {
+    lines.push("Read it with crosstalk_inbox when convenient; reply only if a reply is warranted.")
+  }
+  return lines.join("\n")
+}
+
+export function createSessionDeliverer(session: SessionLike): Deliverer {
+  return {
+    async deliver(message: CrosstalkMessage) {
+      try {
+        await session.synthetic({
+          sessionID: message.to,
+          text: renderDelivery(message),
+          description: `crosstalk ${message.kind} from ${message.from}`,
+          delivery: message.delivery,
+          metadata: {
+            crosstalk: {
+              id: message.id,
+              seq: message.seq,
+              from: message.from,
+              ...(message.fromName ? { fromName: message.fromName } : {}),
+              fromRole: message.fromRole,
+              kind: message.kind,
+              ...(message.topic ? { topic: message.topic } : {}),
+            },
+          },
+        })
+        return { delivered: true }
+      } catch (error) {
+        return { delivered: false, reason: errorMessage(error) }
+      }
+    },
+  }
+}

package/src/events.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Event stream plumbing.
+ *
+ * `ctx.event.subscribe()` is the only way a plugin learns what sessions exist
+ * (the plugin context has no `session.list`). The consumer must survive
+ * individual malformed events and must stop when the plugin unloads, so the
+ * pump takes a plain `AsyncIterable` and an `AbortSignal` rather than the
+ * context directly — which also makes it trivially testable.
+ */
+
+import type { CrosstalkEvent } from "./core/registry.ts"
+
+/** Structural subset of `ctx.event.subscribe()`. */
+export interface EventStream {
+  subscribe(options?: { signal?: AbortSignal }): AsyncIterable<unknown>
+}
+
+export interface PumpOptions {
+  onEvent(event: CrosstalkEvent): void
+  onError?(error: unknown, event: unknown): void
+}
+
+/** Narrow an unknown stream item to something the registry can read. */
+export function asCrosstalkEvent(value: unknown): CrosstalkEvent | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const candidate = value as { type?: unknown; data?: unknown; created?: unknown; location?: unknown }
+  if (typeof candidate.type !== "string") return undefined
+  const data =
+    candidate.data && typeof candidate.data === "object" && !Array.isArray(candidate.data)
+      ? (candidate.data as Record<string, unknown>)
+      : undefined
+  return {
+    type: candidate.type,
+    ...(typeof candidate.created === "number" ? { created: candidate.created } : {}),
+    ...(data ? { data } : {}),
+    ...(candidate.location && typeof candidate.location === "object"
+      ? { location: candidate.location as { directory?: string } }
+      : {}),
+  }
+}
+
+/**
+ * Consume the event stream until it ends or `signal` aborts. Never rejects: a
+ * thrown handler is reported through `onError` and the pump keeps going, so one
+ * bad event cannot silently kill presence tracking.
+ */
+export async function pumpEvents(
+  stream: EventStream,
+  signal: AbortSignal,
+  options: PumpOptions,
+): Promise<void> {
+  try {
+    for await (const raw of stream.subscribe({ signal })) {
+      if (signal.aborted) return
+      const event = asCrosstalkEvent(raw)
+      if (!event) continue
+      try {
+        options.onEvent(event)
+      } catch (error) {
+        options.onError?.(error, raw)
+      }
+    }
+  } catch (error) {
+    if (!signal.aborted) options.onError?.(error, undefined)
+  }
+}