opencode-collaboration 0.2.3

package/dist/registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Instance registry: each opencode instance writes one file into peers.d/.
+ * One file per instance eliminates multi-writer races; no locking needed.
+ */
+import type { InboundPolicy, LocalTransportAddress, Logger, PeerPermissionMode, PeerRegistryEntry, SessionEndpointStatus } from "./types.js";
+export interface RegistryEndpoint {
+    endpointId: string;
+    sessionId: string;
+    parentSessionId?: string;
+    title: string;
+    name: string;
+    directory: string;
+    status: SessionEndpointStatus;
+    startedAt: number;
+    updatedAt: number;
+    queuedCount: number;
+}
+export interface RegistryDynamic {
+    name: string;
+    inboundPolicy: InboundPolicy;
+    activeSessionId: string | null;
+    activeSessionTitle: string | null;
+    /** True while a turn is running in the active session. */
+    busy: boolean;
+    /** Messages queued locally awaiting delivery. */
+    queuedCount: number;
+}
+export interface RegistryOptions {
+    peersDir: string;
+    instanceId: string;
+    pid: number;
+    directory: string;
+    serverUrl: string;
+    inboxUrl: string;
+    inboxToken: string;
+    pluginVersion: string;
+    heartbeatMs: number;
+    staleMs: number;
+    getDynamic: () => RegistryDynamic;
+    /** Enables protocol-v2 publication while retaining one v1 compatibility file. */
+    getEndpoints?: () => RegistryEndpoint[];
+    /** Exact endpoint used by protocol-v1 routing and publication. */
+    getCompatibilityEndpointId?: () => string | null;
+    transport?: LocalTransportAddress;
+    peerPermissions?: PeerPermissionMode;
+    logger: Logger;
+}
+export interface ListedPeer {
+    entry: PeerRegistryEntry;
+    alive: boolean;
+    staleReason: string | null;
+}
+export declare function newInstanceId(): string;
+export declare function newInboxToken(): string;
+export declare function pidAlive(pid: number): boolean;
+export interface RegistryInstance {
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    heartbeat: () => Promise<void>;
+    list: () => Promise<ListedPeer[]>;
+    isAlive: (entry: PeerRegistryEntry) => boolean;
+    cleanupStale: () => Promise<number>;
+    selfFile: string;
+}
+export declare function Registry(opts: RegistryOptions): RegistryInstance;
+/** Pick a unique name among alive peers, appending -2, -3, ... on conflict. */
+export declare function uniqueName(desired: string, peers: ListedPeer[]): {
+    name: string;
+    changed: boolean;
+};

package/dist/registry.js

@@ -0,0 +1,308 @@
+/**
+ * Instance registry: each opencode instance writes one file into peers.d/.
+ * One file per instance eliminates multi-writer races; no locking needed.
+ */
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { hostname } from "node:os";
+import { join } from "node:path";
+export function newInstanceId() {
+    return randomBytes(4).toString("hex");
+}
+export function newInboxToken() {
+    return randomBytes(24).toString("hex");
+}
+export function pidAlive(pid) {
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "EPERM";
+    }
+}
+export function Registry(opts) {
+    const selfFile = join(opts.peersDir, `${opts.instanceId}.json`);
+    const selfV2Files = new Set();
+    let timer = null;
+    let writeTail = Promise.resolve();
+    let stopPromise = null;
+    let lifecycle = "new";
+    const startedAt = Date.now();
+    function compatibilityDynamic() {
+        const dyn = opts.getDynamic();
+        const endpoints = opts.getEndpoints?.() ?? [];
+        const compatibilityId = opts.getCompatibilityEndpointId?.();
+        const latest = endpoints.find((endpoint) => endpoint.endpointId === compatibilityId)
+            ?? endpoints.slice().sort((a, b) => b.updatedAt - a.updatedAt)[0];
+        if (!latest)
+            return dyn;
+        return {
+            name: latest.name,
+            inboundPolicy: dyn.inboundPolicy,
+            activeSessionId: latest.sessionId,
+            activeSessionTitle: latest.title,
+            busy: latest.status !== "idle",
+            queuedCount: latest.queuedCount,
+        };
+    }
+    function buildEntry() {
+        const dyn = compatibilityDynamic();
+        return {
+            version: 1,
+            instanceId: opts.instanceId,
+            name: dyn.name,
+            pid: opts.pid,
+            hostname: hostname(),
+            directory: opts.directory,
+            serverUrl: opts.serverUrl,
+            inboxUrl: opts.inboxUrl,
+            inboxToken: opts.inboxToken,
+            activeSessionId: dyn.activeSessionId,
+            activeSessionTitle: dyn.activeSessionTitle,
+            busy: dyn.busy,
+            queuedCount: dyn.queuedCount,
+            inboundPolicy: dyn.inboundPolicy,
+            startedAt,
+            heartbeatAt: Date.now(),
+            pluginVersion: opts.pluginVersion,
+        };
+    }
+    function buildV2Entry(endpoint, heartbeatAt) {
+        const inboundPolicy = opts.getDynamic().inboundPolicy;
+        return {
+            version: 2,
+            endpointId: endpoint.endpointId,
+            processId: opts.instanceId,
+            pid: opts.pid,
+            sessionId: endpoint.sessionId,
+            ...(endpoint.parentSessionId ? { parentSessionId: endpoint.parentSessionId } : {}),
+            title: endpoint.title,
+            name: endpoint.name,
+            hostname: hostname(),
+            directory: endpoint.directory,
+            status: endpoint.status,
+            transport: opts.transport,
+            serverUrl: opts.serverUrl,
+            inboxUrl: opts.inboxUrl,
+            inboxToken: opts.inboxToken,
+            capabilities: ["local", "protocol-v2", "prompt-async", "ack"],
+            timestamps: {
+                startedAt: endpoint.startedAt,
+                updatedAt: endpoint.updatedAt,
+                heartbeatAt,
+            },
+            policy: {
+                inboundPolicy,
+                peerPermissions: opts.peerPermissions ?? "allow",
+            },
+            pluginVersion: opts.pluginVersion,
+            activeSessionId: endpoint.sessionId,
+            activeSessionTitle: endpoint.title,
+            busy: endpoint.status !== "idle",
+            queuedCount: endpoint.queuedCount,
+            inboundPolicy,
+            startedAt: endpoint.startedAt,
+            heartbeatAt,
+        };
+    }
+    async function writeEntry(path, entry) {
+        const tmp = `${path}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify(entry, null, 2), { mode: 0o600 });
+        await chmod(tmp, 0o600).catch(() => { });
+        await rename(tmp, path);
+    }
+    async function writeSelf() {
+        await writeEntry(selfFile, buildEntry());
+        if (!opts.getEndpoints || !opts.transport)
+            return;
+        const heartbeatAt = Date.now();
+        const nextFiles = new Set();
+        for (const endpoint of opts.getEndpoints()) {
+            const safeId = endpoint.endpointId.replace(/[^a-zA-Z0-9_-]/g, "_");
+            const path = join(opts.peersDir, `${opts.instanceId}.${safeId}.v2.json`);
+            await writeEntry(path, buildV2Entry(endpoint, heartbeatAt));
+            nextFiles.add(path);
+        }
+        for (const path of selfV2Files) {
+            if (!nextFiles.has(path))
+                await rm(path, { force: true });
+        }
+        selfV2Files.clear();
+        for (const path of nextFiles)
+            selfV2Files.add(path);
+    }
+    function scheduleWrite() {
+        if (lifecycle !== "running")
+            return Promise.resolve();
+        const writeIfRunning = () => lifecycle === "running" ? writeSelf() : Promise.resolve();
+        const pending = writeTail.then(writeIfRunning, writeIfRunning);
+        writeTail = pending.catch(() => { });
+        return pending;
+    }
+    async function readEntry(file) {
+        try {
+            const raw = await readFile(join(opts.peersDir, file), "utf8");
+            const entry = JSON.parse(raw);
+            if (entry.version === 1 && entry.instanceId && entry.inboxUrl)
+                return entry;
+            if (entry.version === 2 && entry.endpointId && entry.processId && entry.transport && entry.sessionId)
+                return entry;
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    function staleReason(entry, now) {
+        const ageMs = now - entry.heartbeatAt;
+        if (ageMs > opts.staleMs)
+            return `last heartbeat ${Math.round(ageMs / 1000)}s ago`;
+        if (!pidAlive(entry.pid))
+            return `pid ${entry.pid} is not running`;
+        return null;
+    }
+    const inst = {
+        selfFile,
+        async start() {
+            if (lifecycle !== "new")
+                throw new Error(`registry cannot start while ${lifecycle}`);
+            await mkdir(opts.peersDir, { recursive: true, mode: 0o700 });
+            await chmod(opts.peersDir, 0o700).catch(() => { });
+            lifecycle = "running";
+            try {
+                await scheduleWrite();
+            }
+            catch (err) {
+                lifecycle = "stopped";
+                throw err;
+            }
+            timer = setInterval(() => {
+                inst.heartbeat().catch((err) => {
+                    opts.logger("warn", "heartbeat failed", { error: String(err) });
+                });
+            }, opts.heartbeatMs);
+            timer.unref?.();
+        },
+        async stop() {
+            if (stopPromise)
+                return stopPromise;
+            if (lifecycle === "stopped")
+                return;
+            lifecycle = "stopping";
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            stopPromise = (async () => {
+                await writeTail;
+                await rm(selfFile, { force: true });
+                await Promise.all([...selfV2Files].map((path) => rm(path, { force: true })));
+                selfV2Files.clear();
+                lifecycle = "stopped";
+            })();
+            return stopPromise;
+        },
+        async heartbeat() {
+            if (lifecycle !== "running")
+                return;
+            await scheduleWrite();
+            if (lifecycle !== "running")
+                return;
+            await inst.cleanupStale();
+        },
+        async list() {
+            let files = [];
+            try {
+                files = await readdir(opts.peersDir);
+            }
+            catch {
+                return [];
+            }
+            const now = Date.now();
+            const entries = [];
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const entry = await readEntry(file);
+                if (!entry)
+                    continue;
+                if (entry.version === 1 && entry.instanceId === opts.instanceId)
+                    continue;
+                entries.push(entry);
+            }
+            const v2Processes = new Set(entries.flatMap((entry) => entry.version === 2 ? [entry.processId] : []));
+            const out = [];
+            const v2ByEndpoint = new Map();
+            for (const entry of entries) {
+                if (entry.version === 1 && v2Processes.has(entry.instanceId))
+                    continue;
+                const reason = staleReason(entry, now);
+                const listed = { entry, alive: reason === null, staleReason: reason };
+                if (entry.version !== 2) {
+                    out.push(listed);
+                    continue;
+                }
+                const current = v2ByEndpoint.get(entry.endpointId);
+                const currentHeartbeat = current?.entry.heartbeatAt ?? -Infinity;
+                if (!current || (listed.alive && !current.alive) ||
+                    (listed.alive === current.alive && entry.heartbeatAt > currentHeartbeat)) {
+                    v2ByEndpoint.set(entry.endpointId, listed);
+                }
+            }
+            return [...out, ...v2ByEndpoint.values()];
+        },
+        isAlive(entry) {
+            return staleReason(entry, Date.now()) === null;
+        },
+        async cleanupStale() {
+            if (lifecycle !== "running")
+                return 0;
+            let files = [];
+            try {
+                files = await readdir(opts.peersDir);
+            }
+            catch {
+                return 0;
+            }
+            const now = Date.now();
+            let removed = 0;
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                const path = join(opts.peersDir, file);
+                if (path === selfFile || selfV2Files.has(path))
+                    continue;
+                try {
+                    const st = await stat(path);
+                    if (now - st.mtimeMs < 5 * 60_000)
+                        continue;
+                    const entry = await readEntry(file);
+                    if (entry && pidAlive(entry.pid))
+                        continue;
+                    await rm(path, { force: true });
+                    removed++;
+                }
+                catch {
+                    // best effort
+                }
+            }
+            return removed;
+        },
+    };
+    return inst;
+}
+/** Pick a unique name among alive peers, appending -2, -3, ... on conflict. */
+export function uniqueName(desired, peers) {
+    const taken = new Set(peers.filter((p) => p.alive).map((p) => p.entry.name));
+    if (!taken.has(desired))
+        return { name: desired, changed: false };
+    for (let i = 2; i < 100; i++) {
+        const candidate = `${desired}-${i}`;
+        if (!taken.has(candidate))
+            return { name: candidate, changed: true };
+    }
+    return { name: `${desired}-${randomBytes(2).toString("hex")}`, changed: true };
+}

package/dist/sender.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Outbound delivery over the local v1/v2 transport boundary.
+ */
+import type { InboundMessage, PeerFrom, PeerMessageV2, PeerRegistryEntry, ReceiveStatus } from "./types.js";
+import { type Transport } from "./transport.js";
+import type { OutboxInstance } from "./outbox.js";
+export type SendOutcome = {
+    ok: true;
+    status: ReceiveStatus;
+    messageId?: string;
+} | {
+    ok: false;
+    error: string;
+    messageId?: string;
+};
+export interface SenderOptions {
+    self: PeerFrom;
+    timeoutMs?: number;
+    transport?: Transport;
+    outbox?: OutboxInstance;
+}
+export declare function buildMessage(self: PeerFrom, text: string, via?: string[]): InboundMessage;
+export declare function buildMessageV2(self: PeerFrom, toEndpointId: string, text: string, via?: string[]): PeerMessageV2;
+export declare function Sender(opts: SenderOptions): {
+    buildMessage: (text: string) => import("./types.js").InboundMessageV1;
+    send(entry: PeerRegistryEntry, text: string, sender?: PeerFrom): Promise<SendOutcome>;
+};

package/dist/sender.js

@@ -0,0 +1,139 @@
+/**
+ * Outbound delivery over the local v1/v2 transport boundary.
+ */
+import { randomBytes } from "node:crypto";
+import { LocalTransport } from "./transport.js";
+export function buildMessage(self, text, via = []) {
+    return {
+        id: randomBytes(8).toString("hex"),
+        from: self,
+        text,
+        via: [...via, self.instanceId],
+        sentAt: Date.now(),
+    };
+}
+export function buildMessageV2(self, toEndpointId, text, via = []) {
+    return {
+        version: 2,
+        messageId: randomBytes(8).toString("hex"),
+        fromEndpointId: self.instanceId,
+        toEndpointId,
+        from: self,
+        text,
+        via: [...via, self.instanceId],
+        sentAt: Date.now(),
+    };
+}
+async function postMessage(entry, msg, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${entry.inboxUrl}/message`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${entry.inboxToken}`,
+            },
+            body: JSON.stringify(msg),
+            signal: controller.signal,
+        });
+        let status;
+        try {
+            const body = (await res.json());
+            status = body.status;
+        }
+        catch {
+            // non-JSON body; fall through with just the HTTP code
+        }
+        return { http: res.status, status };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function healthCheck(entry, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${entry.inboxUrl}/health`, {
+            headers: { authorization: `Bearer ${entry.inboxToken}` },
+            signal: controller.signal,
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function Sender(opts) {
+    const timeoutMs = opts.timeoutMs ?? 3_000;
+    const transport = opts.transport ?? LocalTransport({ timeoutMs });
+    return {
+        buildMessage: (text) => buildMessage(opts.self, text),
+        async send(entry, text, sender = opts.self) {
+            if (entry.version === 2) {
+                const msg = buildMessageV2(sender, entry.endpointId, text);
+                await opts.outbox?.recordPending(msg, entry.name);
+                try {
+                    const { http, status } = await transport.send(entry, msg);
+                    if (status)
+                        await opts.outbox?.recordReceipt(msg.messageId, msg.fromEndpointId, status);
+                    if (http === 202 && status) {
+                        return { ok: true, status, messageId: msg.messageId };
+                    }
+                    if (http === 403)
+                        return { ok: false, error: `"${entry.name}" refuses inbound messages.`, messageId: msg.messageId };
+                    if (http === 429)
+                        return { ok: false, error: `"${entry.name}" is rate limiting or its queue is full; try again later.`, messageId: msg.messageId };
+                    if (http === 401)
+                        return { ok: false, error: `Authentication failed for "${entry.name}" (stale registry entry?).`, messageId: msg.messageId };
+                    if (http === 404)
+                        return { ok: false, error: `Endpoint "${entry.endpointId}" is no longer registered.`, messageId: msg.messageId };
+                    const error = `Unexpected response ${http} from "${entry.name}".`;
+                    await opts.outbox?.recordFailure(msg.messageId, msg.fromEndpointId, error);
+                    return { ok: false, error, messageId: msg.messageId };
+                }
+                catch (err) {
+                    const error = `Failed to send to "${entry.name}": ${String(err)}`;
+                    await opts.outbox?.recordFailure(msg.messageId, msg.fromEndpointId, error);
+                    return { ok: false, error, messageId: msg.messageId };
+                }
+            }
+            const msg = buildMessage(sender, text);
+            let lastErr = null;
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    const { http, status } = await postMessage(entry, msg, timeoutMs);
+                    if (http === 202 && status)
+                        return { ok: true, status };
+                    if (http === 403)
+                        return { ok: false, error: `"${entry.name}" refuses inbound messages.` };
+                    if (http === 429) {
+                        return { ok: false, error: `"${entry.name}" is rate limiting or its queue is full; try again later.` };
+                    }
+                    if (http === 401) {
+                        return { ok: false, error: `Authentication failed for "${entry.name}" (stale registry entry?).` };
+                    }
+                    return { ok: false, error: `Unexpected response ${http} from "${entry.name}".` };
+                }
+                catch (err) {
+                    lastErr = err;
+                    // Retry once to cover a stale registry entry racing a peer restart.
+                    if (attempt === 0)
+                        await new Promise((r) => setTimeout(r, 300));
+                }
+            }
+            const alive = await healthCheck(entry, timeoutMs);
+            const hint = alive
+                ? "inbox reachable but POST failed"
+                : "peer appears offline (inbox unreachable)";
+            return {
+                ok: false,
+                error: `Failed to send to "${entry.name}": ${hint}. ${String(lastErr)}`,
+            };
+        },
+    };
+}

package/dist/session-runtime.d.ts

@@ -0,0 +1,40 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { ResolvedConfig } from "./config.js";
+import { type DeliveryInstance } from "./delivery.js";
+import { type QueueInstance } from "./queue.js";
+import type { RegistryEndpoint } from "./registry.js";
+import type { InboundMessage, InboundPolicy, Logger, PeerAcknowledgementV2, ReceiveStatus } from "./types.js";
+type Client = PluginInput["client"];
+export interface SessionRuntimeOptions {
+    client: Client;
+    config: ResolvedConfig;
+    directory: string;
+    name: () => string;
+    logger: Logger;
+}
+export interface SessionRuntimeInstance {
+    initialize: () => Promise<void>;
+    /** Resolves once the first initialize() attempt has settled (never rejects). */
+    whenReady: () => Promise<void>;
+    stop: () => Promise<void>;
+    registryEndpoints: () => RegistryEndpoint[];
+    publishableEndpoints: () => RegistryEndpoint[];
+    compatibilityEndpointId: () => string | null;
+    hasEndpoint: (endpointId: string) => boolean;
+    endpointIdForSession: (sessionId: string) => string | null;
+    receive: (message: InboundMessage, endpointId: string, policy: InboundPolicy) => Promise<ReceiveStatus>;
+    handleEvent: (event: {
+        type?: string;
+        properties?: Record<string, unknown>;
+    }) => Promise<boolean>;
+    noteActivity: (sessionId: string) => Promise<void>;
+    queueForSession: (sessionId: string) => QueueInstance | null;
+    deliveryForSession: (sessionId: string) => DeliveryInstance | null;
+    sweep: () => Promise<void>;
+    pendingAcknowledgements: () => Array<{
+        queue: QueueInstance;
+        acknowledgement: PeerAcknowledgementV2;
+    }>;
+}
+export declare function SessionRuntime(opts: SessionRuntimeOptions): SessionRuntimeInstance;
+export {};