opencode-crosstalk 0.0.0-stage → 0.2.0

package/src/tools/claim.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview `crosstalk_claim` — exclusive, expiring leases on files.
+ *
+ * This is the tool that makes two agents safe on one repository: a claim is a
+ * hard lease, not a note in the conversation, and the default atomic behaviour
+ * means a batch request that touches one busy file takes nothing at all.
+ */
+
+import { formatClaims } from "../core/format.ts"
+import { readBoolean, readEnum, readNumber, readString, readStringArray } from "./args.ts"
+import { jsonSchema, run, type CrosstalkToolInfo, type ToolDeps } from "./types.ts"
+
+export function claimTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "claim",
+    description: [
+      "Take an exclusive, expiring lease on files or named resources so another session does not",
+      "edit them at the same time. Claim before you edit, release when you are done, renew if you",
+      "work longer than the lease. If a file is already leased the request is refused and tells you",
+      "who holds it — signal them with crosstalk_send, wait with crosstalk_wait, or pass force: true.",
+      "Paths are normalized, and relative paths resolve against this session's directory.",
+      "Claim keys are exact: there is no glob expansion, and leasing a directory",
+      "does not cover the files inside it — claim each file you edit.",
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["claim", "renew", "release", "list"],
+          description: "Operation. 'list' reports the leases you hold and needs no resources.",
+        },
+        resources: {
+          type: "array",
+          items: { type: "string" },
+          description: "Exact normalized file paths (src/a.ts, src/auth/login.ts) or named resources (db:migrate). No globs: '**' is an ordinary path segment, not a pattern",
+        },
+        ttlSeconds: { type: "number", description: "Lease duration in seconds (default 300, max 86400)" },
+        note: { type: "string", description: "Why you hold it — shown to the peer you block" },
+        force: { type: "boolean", description: "Steal a lease held by another session" },
+        atomic: {
+          type: "boolean",
+          description: "On conflict take nothing (default true). false claims whatever is free",
+        },
+        includeExpired: { type: "boolean", description: "Include lapsed leases in list output" },
+      },
+      required: ["action"],
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(() => {
+        const action = readEnum(input, "action", ["claim", "renew", "release", "list"] as const, undefined)
+        if (action === undefined) {
+          return 'crosstalk: "action" is required (claim, renew, release, or list)'
+        }
+        const resources = readStringArray(input, "resources", { max: 64, maxLength: 400 })
+        const ttlSeconds = readNumber(input, "ttlSeconds", { min: 1, max: 86_400 })
+        const note = readString(input, "note", { max: 200 })
+        const force = readBoolean(input, "force", false)
+        const atomic = readBoolean(input, "atomic", true)
+        const includeExpired = readBoolean(input, "includeExpired", false)
+
+        if (action !== "list" && (resources === undefined || resources.length === 0)) {
+          return `crosstalk: action "${action}" needs "resources" (use action "list" to see what you hold)`
+        }
+
+        const result = deps.mesh.claim(context.sessionID, {
+          action,
+          ...(resources ? { resources } : {}),
+          ...(ttlSeconds !== undefined ? { ttlMs: ttlSeconds * 1000 } : {}),
+          ...(note ? { note } : {}),
+          force,
+          atomic,
+          includeExpired,
+        })
+
+        return formatClaims({
+          self: deps.mesh.view(context.sessionID),
+          outcome: result.outcome,
+          ttlMs: result.ttlMs,
+          now: deps.mesh.now(),
+          held: result.held,
+        })
+      })
+    },
+  }
+}

package/src/tools/heartbeat.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview `crosstalk_heartbeat` — send a message to a peer on an interval.
+ *
+ * Useful for "check in every 30 s" coordination without the caller having to
+ * poll. Each started heartbeat is tracked per sender session and can be stopped
+ * or listed. Timers are unref'd so they never keep the process alive.
+ */
+
+import { readBoolean, readEnum, readNumber, readString } from "./args.ts"
+import { jsonSchema, run, type CrosstalkToolInfo, type ToolDeps } from "./types.ts"
+
+interface Heartbeat {
+  id: string
+  sessionID: string
+  to?: string
+  role?: string
+  all?: boolean
+  text: string
+  topic?: string
+  kind?: "message" | "status" | "request" | "answer" | "system"
+  intervalMs: number
+  count: number  // 0 = forever
+  sent: number
+  timer: ReturnType<typeof setInterval>
+}
+
+const heartbeats = new Map<string, Heartbeat>()
+let seq = 0
+
+export function heartbeatTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "heartbeat",
+    description: [
+      "Send a message to another session on a repeating interval. Use this for periodic",
+      "check-ins (e.g. \"report status every 30 s\") without polling. Actions: 'start' begins a",
+      "heartbeat, 'stop' cancels one by id, 'list' shows this session's active heartbeats.",
+      "Timers are unref'd and stop automatically when the session ends.",
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["start", "stop", "list"],
+          description: "What to do. Defaults to 'start'.",
+        },
+        id: { type: "string", description: "Heartbeat id (for 'stop')." },
+        to: { type: "string", description: "Recipient session id or declared name." },
+        role: { type: "string", description: "Send to every peer with this role." },
+        all: { type: "boolean", description: "Send to every peer." },
+        text: { type: "string", description: "Message body." },
+        topic: { type: "string", description: "Optional thread label." },
+        kind: {
+          type: "string",
+          enum: ["message", "status", "request", "answer", "system"],
+          description: "Intent.",
+        },
+        intervalSeconds: {
+          type: "number",
+          description: "Seconds between sends. Min 5, max 3600. Defaults to 30.",
+        },
+        count: {
+          type: "number",
+          description: "How many times to send. 0 = forever (until stopped). Defaults to 0.",
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(async () => {
+        const action = readEnum(input, "action", ["start", "stop", "list"] as const, "start")
+        const sessionID = context.sessionID
+
+        if (action === "list") {
+          const mine = [...heartbeats.values()].filter((h) => h.sessionID === sessionID)
+          if (mine.length === 0) return "crosstalk: no active heartbeats"
+          return "crosstalk: active heartbeats:\n" + mine
+            .map((h) => `  ${h.id}  every ${h.intervalMs / 1000}s  sent ${h.sent}/${h.count || "∞"}  to=${h.to ?? h.role ?? (h.all ? "all" : "?")}`)
+            .join("\n")
+        }
+
+        if (action === "stop") {
+          const id = readString(input, "id", { required: true, max: 64 })
+          const h = heartbeats.get(id)
+          if (!h || h.sessionID !== sessionID)
+            return `crosstalk: no heartbeat '${id}' owned by this session`
+          clearInterval(h.timer)
+          heartbeats.delete(id)
+          return `crosstalk: stopped heartbeat ${id} (sent ${h.sent})`
+        }
+
+        // start
+        const text = readString(input, "text", { required: true, max: 8_000 })
+        const to = readString(input, "to", { max: 200 })
+        const role = readString(input, "role", { max: 64 })
+        const all = readBoolean(input, "all", false)
+        const topic = readString(input, "topic", { max: 80 })
+        const kind = readEnum(input, "kind", ["message", "status", "request", "answer", "system"] as const, "message")
+        if (!to && !role && !all)
+          return 'crosstalk: give one of "to", "role", or "all": true'
+        const intervalSeconds = Math.max(5, Math.min(3600, readNumber(input, "intervalSeconds", { fallback: 30 }) ?? 30))
+        const count = Math.max(0, Math.floor(readNumber(input, "count", { fallback: 0 }) ?? 0))
+        const intervalMs = intervalSeconds * 1000
+
+        const id = `hb-${++seq}`
+        let sent = 0
+
+        const sendOne = async () => {
+          sent++
+          const h = heartbeats.get(id)
+          if (!h) return
+          try {
+            await deps.mesh.send(sessionID, {
+              text,
+              ...(to ? { to } : {}),
+              ...(role ? { role } : {}),
+              ...(all ? { all: true } : {}),
+              ...(topic ? { topic } : {}),
+              ...(kind ? { kind } : {}),
+            }, new AbortController().signal)
+          } catch {
+            // ignore delivery failures; the next tick retries
+          }
+          h.sent = sent
+          if (count > 0 && sent >= count) {
+            clearInterval(h.timer)
+            heartbeats.delete(id)
+          }
+        }
+
+        const timer = setInterval(() => { void sendOne() }, intervalMs)
+        timer.unref?.()
+
+        const h: Heartbeat = {
+          id, sessionID, text, intervalMs, count, sent: 0, timer,
+          ...(to ? { to } : {}),
+          ...(role ? { role } : {}),
+          ...(all ? { all: true } : {}),
+          ...(topic ? { topic } : {}),
+          ...(kind ? { kind } : {}),
+        }
+        heartbeats.set(id, h)
+
+        // Send the first one immediately.
+        void sendOne()
+
+        return `crosstalk: started heartbeat ${id} (every ${intervalSeconds}s, ${count || "∞"} sends) to ${to || role || "all"}`
+      })
+    },
+  }
+}

package/src/tools/inbox.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview `crosstalk_inbox` — read and acknowledge mail from peers.
+ */
+
+import { formatInbox } from "../core/format.ts"
+import { readBoolean, readNumber, readString } from "./args.ts"
+import { clampWait, jsonSchema, run, startHeartbeat, type CrosstalkToolInfo, type ToolDeps } from "./types.ts"
+
+export function inboxTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "inbox",
+    description: [
+      "Read messages other sessions sent you. Set wait to block until something arrives (or the",
+      "timeout expires) instead of returning an empty inbox — useful when you are waiting on a peer",
+      "to finish. Messages are marked read unless you pass markRead: false.",
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        wait: {
+          type: "number",
+          description: "Seconds to block for a new message. 0 returns immediately. Capped by plugin config.",
+        },
+        limit: { type: "number", description: "Maximum messages to return (most recent, default 20)" },
+        topic: { type: "string", description: "Only messages with this topic" },
+        unreadOnly: { type: "boolean", description: "Skip messages you already read" },
+        since: { type: "string", description: "Return only messages after this message ID" },
+        markRead: { type: "boolean", description: "Mark the returned messages read (default true)" },
+      },
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(async () => {
+        const waitSeconds = readNumber(input, "wait", { min: 0, max: 600, fallback: 0 })
+        const limit = readNumber(input, "limit", { min: 1, max: 200, fallback: 20 })
+        const topic = readString(input, "topic", { max: 80 })
+        const unreadOnly = readBoolean(input, "unreadOnly", false)
+        const since = readString(input, "since", { max: 80 })
+        const markRead = readBoolean(input, "markRead", true)
+        const waitMs = clampWait((waitSeconds ?? 0) * 1000, deps.options)
+
+        const stop = startHeartbeat(context, deps.options.heartbeatMs, () => ({
+          status: "waiting",
+          waitSeconds: Math.round(waitMs / 1000),
+        }))
+        let outcome
+        try {
+          outcome = await deps.mesh.inbox(
+            context.sessionID,
+            {
+              waitMs,
+              markRead,
+              limit,
+              ...(unreadOnly ? { unreadOnly: true } : {}),
+              ...(topic ? { topic } : {}),
+              ...(since ? { since } : {}),
+            },
+            context.signal,
+          )
+        } finally {
+          stop()
+        }
+
+        return formatInbox({
+          self: deps.mesh.view(context.sessionID),
+          messages: outcome.messages,
+          marked: outcome.marked,
+          unread: outcome.unreadBefore,
+          now: deps.mesh.now(),
+          reason: outcome.reason,
+          ...(limit !== undefined ? { limit } : {}),
+        })
+      })
+    },
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Tool registration.
+ *
+ * All seven tools share one namespace and one permission action, so a project can
+ * allow or deny coordination with a single rule.
+ */
+
+import type { ToolEditor } from "@opencode/plugin/promise/tool"
+import { claimTool } from "./claim.ts"
+import { heartbeatTool } from "./heartbeat.ts"
+import { inboxTool } from "./inbox.ts"
+import { peersTool } from "./peers.ts"
+import { sendTool } from "./send.ts"
+import { statusTool } from "./status.ts"
+import { waitTool } from "./wait.ts"
+import type { CrosstalkToolInfo, ToolDeps } from "./types.ts"
+
+export const NAMESPACE_DESCRIPTION =
+  "Coordinate with the other OpenCode sessions on this project: discover peers, exchange messages, " +
+  "and lease files so two agents never edit the same path at once. Start with status, then peers."
+
+/** Tool factories in registration order. */
+export const toolFactories: Array<(deps: ToolDeps) => CrosstalkToolInfo> = [
+  statusTool,
+  peersTool,
+  sendTool,
+  inboxTool,
+  claimTool,
+  heartbeatTool,
+  waitTool,
+]
+
+/**
+ * Register the namespace and every tool. Must run inside
+ * `ctx.tool.transform`, whose callback has to stay synchronous and cheap.
+ *
+ * Every executor is wrapped to retry queued injections first, so a message
+ * whose delivery failed — most likely because the recipient's session belongs
+ * to another location — still reaches its turn the moment that session next
+ * calls any crosstalk tool.
+ */
+export function registerTools(editor: ToolEditor, deps: ToolDeps): void {
+  editor.namespace({ name: deps.options.namespace, description: NAMESPACE_DESCRIPTION })
+  for (const factory of toolFactories) {
+    const tool = factory(deps)
+    const execute = tool.execute
+    editor.add({
+      ...tool,
+      execute: async (input, context) => {
+        await deps.mesh.flushPendingInjection(context.sessionID, context.signal)
+        return execute(input, context)
+      },
+      options: {
+        namespace: deps.options.namespace,
+        permission: deps.options.permission,
+        codemode: deps.options.codemode,
+      },
+    })
+  }
+}
+
+export { claimTool, heartbeatTool, inboxTool, peersTool, sendTool, statusTool, waitTool }

package/src/tools/peers.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview `crosstalk_peers` — who else is running right now.
+ */
+
+import { formatPeers } from "../core/format.ts"
+import { normalizeResource } from "../core/claims.ts"
+import type { PeerView } from "../types.ts"
+import { readBoolean, readEnum, readNumber, readStringArray } from "./args.ts"
+import { jsonSchema, run, type CrosstalkToolInfo, type ToolDeps } from "./types.ts"
+
+/**
+ * Which peers touch any of `paths`: a session holding a lease on the exact key,
+ * or one that listed it in `workingOn`. Both sides are normalized to absolute
+ * keys — the caller's paths against the caller's directory, a peer's
+ * `workingOn` against the peer's own — so `src/auth.ts` typed by a session in
+ * another worktree does not match this one until it provably is the same file.
+ *
+ * Keys are exact, like every claim key: asking about a directory never matches
+ * the files inside it, and `**` is an ordinary path segment. An empty `paths`
+ * list matches every peer, which is "no filter" expressed as data.
+ */
+export function overlappingPeers(
+  peers: readonly PeerView[],
+  paths: readonly string[],
+  baseDir?: string,
+): PeerView[] {
+  const wanted = paths.map((path) => normalizeResource(path, baseDir)).filter((key) => key !== "")
+  if (wanted.length === 0) return [...peers]
+  const claimed = new Set(wanted)
+  return peers.filter(
+    (peer) =>
+      peer.claims.some((claim) => claimed.has(claim)) ||
+      (peer.declared?.workingOn ?? []).some((entry) => claimed.has(normalizeResource(entry, peer.directory))),
+  )
+}
+
+export function peersTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "peers",
+    description: [
+      "List the other OpenCode sessions on this channel with their liveness, what they declared",
+      "they are working on, unread mail counts, and the files they have leased.",
+      "Use this before editing shared code, and to find out which session to signal.",
+      'Pass "overlap" with exact paths to see only the peers whose leases or workingOn cover them.',
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["all", "running", "idle"],
+          description: "Filter by liveness. 'all' (default) lists everyone the mesh knows.",
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "location", "server"],
+          description: "Widen or narrow visibility for this call. Defaults to the configured scope.",
+        },
+        overlap: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Only peers whose leases or workingOn cover one of these exact paths — no globs, relative paths resolve against your directory",
+        },
+        includeSelf: { type: "boolean", description: "Include this session in the list" },
+        limit: { type: "number", description: "Maximum peers to return (default 50)" },
+      },
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(() => {
+        const status = readEnum(input, "status", ["all", "running", "idle"] as const, "all")
+        const scope =
+          readEnum(input, "scope", ["project", "location", "server"] as const, deps.options.scope) ??
+          deps.options.scope
+        const overlap = readStringArray(input, "overlap", { max: 32, maxLength: 200 })
+        const includeSelf = readBoolean(input, "includeSelf", false)
+        const limit = readNumber(input, "limit", { min: 1, max: 500, fallback: 50 })
+
+        const known = deps.mesh.peers(context.sessionID, {
+          status,
+          scope,
+          includeSelf,
+          ...(limit !== undefined ? { limit } : {}),
+        })
+        // An empty list is "no filter", not "match nothing".
+        const asked = overlap && overlap.length > 0 ? overlap : undefined
+        const peers = asked
+          ? overlappingPeers(known, asked, deps.mesh.directoryOf(context.sessionID))
+          : known
+        return formatPeers({
+          self: deps.mesh.view(context.sessionID),
+          peers,
+          scope,
+          now: deps.mesh.now(),
+          ...(asked ? { overlap: { paths: asked, considered: known.length } } : {}),
+        })
+      })
+    },
+  }
+}

package/src/tools/send.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview `crosstalk_send` — talk to another session.
+ */
+
+import { formatSend } from "../core/format.ts"
+import { readBoolean, readEnum, readString } from "./args.ts"
+import { jsonSchema, run, type CrosstalkToolInfo, type ToolDeps } from "./types.ts"
+
+export function sendTool(deps: ToolDeps): CrosstalkToolInfo {
+  return {
+    name: "send",
+    description: [
+      "Send a message to another OpenCode session on this channel. The message is stored in the",
+      "recipient's mailbox and, when possible, injected into their running session so they see it",
+      "without waiting. Address it with a session id or a peer's declared human name (crosstalk_peers",
+      "shows both), to everyone with a declared role, or to all peers. Only sessions in this project",
+      "are reachable — peers marked \"not addressable\" are refused.",
+      "Give one reason per message and say what you need back; the recipient replies with crosstalk_send.",
+    ].join(" "),
+    input: jsonSchema({
+      type: "object",
+      properties: {
+        to: { type: "string", description: "Session ID or declared human name of the recipient (see crosstalk_peers)" },
+        role: { type: "string", description: "Send to every peer that declared this role" },
+        all: { type: "boolean", description: "Send to every peer on this channel" },
+        text: { type: "string", description: "The message body. Be specific about what you need." },
+        topic: { type: "string", description: "Optional thread label, e.g. auth-refactor" },
+        kind: {
+          type: "string",
+          enum: ["message", "status", "request", "answer", "system"],
+          description: "Intent. 'request' expects a reply; 'answer' is a response to one.",
+        },
+        delivery: {
+          type: "string",
+          enum: ["steer", "queue"],
+          description: "'steer' (default) folds into the recipient's current turn; 'queue' waits for it to end",
+        },
+        replyTo: { type: "string", description: "Message ID this answers" },
+      },
+      required: ["text"],
+      additionalProperties: false,
+    }),
+    async execute(input, context) {
+      return run(async () => {
+        const text = readString(input, "text", { required: true, max: 8_000 })
+        const to = readString(input, "to", { max: 200 })
+        const role = readString(input, "role", { max: 64 })
+        const all = readBoolean(input, "all", false)
+        const topic = readString(input, "topic", { max: 80 })
+        const kind = readEnum(input, "kind", ["message", "status", "request", "answer", "system"] as const, "message")
+        const delivery = readEnum(input, "delivery", ["steer", "queue"] as const, "steer")
+        const replyTo = readString(input, "replyTo", { max: 80 })
+
+        // `all` defaults to false rather than undefined, so test the values.
+        if (!to && !role && !all) {
+          return 'crosstalk: give one of "to" (session id or name), "role", or "all": true'
+        }
+
+        const outcome = await deps.mesh.send(
+          context.sessionID,
+          {
+            text,
+            ...(to ? { to } : {}),
+            ...(role ? { role } : {}),
+            ...(all ? { all: true } : {}),
+            ...(topic ? { topic } : {}),
+            ...(kind ? { kind } : {}),
+            ...(delivery ? { delivery } : {}),
+            ...(replyTo ? { replyTo } : {}),
+          },
+          context.signal,
+        )
+
+        return formatSend({
+          self: deps.mesh.view(context.sessionID),
+          recipients: outcome.recipients,
+          skipped: outcome.skipped,
+          text,
+          now: deps.mesh.now(),
+        })
+      })
+    },
+  }
+}