opencode-collaboration 0.2.3

package/dist/tui.d.ts

@@ -0,0 +1,3 @@
+import type { TuiPluginModule } from "@opencode-ai/plugin/tui";
+declare const mod: TuiPluginModule;
+export default mod;

package/dist/tui.js

@@ -0,0 +1,228 @@
+/**
+ * TUI entrypoint (loaded via package.json exports["./tui"]).
+ *
+ * Server-defined slash commands never execute on the first Enter in the
+ * opencode TUI — selecting one in the autocomplete only inserts "/name " and
+ * waits for a second Enter. To get single-Enter execution WITHOUT a duplicate
+ * autocomplete row, this module does two things:
+ *
+ *  1. Registers the five commands as palette commands (no `slashName`, so
+ *     they do NOT add rows to the autocomplete — the menu keeps only the
+ *     server-defined row).
+ *  2. Registers a high-priority "return" binding whose handler checks the
+ *     focused prompt's text. When it is exactly one of our slash commands
+ *     (no arguments), the handler executes it via `client.session.command`
+ *     — the same `command.execute.before` interception as a normal submit —
+ *     and reports the key handled. On the home route (no session yet) it
+ *     first creates a session and navigates to it, replicating the stock
+ *     home-submit flow. For any other text it returns `false`, and the
+ *     keymap falls through to the normal bindings (autocomplete select /
+ *     input submit), so every other keypress behaves exactly as stock.
+ *
+ * Commands typed WITH arguments (e.g. `/peers-name foo`) never match the
+ * exact-text check, so they submit normally with the argument intact.
+ *
+ * CONSTRAINT: this file must compile to a zero-runtime-import dist/tui.js.
+ * `@opencode-ai/plugin/tui` re-exports @opentui/keymap at runtime, which is
+ * not resolvable inside the TUI process — `import type` only. That is also
+ * why the command names are duplicated here instead of imported from
+ * ./index.js (which would drag the whole server dependency chain along).
+ */
+const COMMANDS = [
+    { cmd: "peers", title: "List peers", desc: "List same-machine opencode peers" },
+    { cmd: "list-agents", title: "List agents", desc: "Alias of /peers" },
+    { cmd: "peers-name", title: "Show/set peer name", desc: "Show or set this instance's peer name" },
+    { cmd: "peers-inbox", title: "Peer inbox", desc: "Review held peer messages" },
+    { cmd: "peers-outbox", title: "Peer outbox", desc: "Review peer delivery acknowledgements" },
+];
+const EXACT = new Set(COMMANDS.map(({ cmd }) => `/${cmd}`));
+/** Must outrank the autocomplete's select binding (the TUI uses 0..1). */
+const LAYER_PRIORITY = 10;
+/**
+ * Slash-typeable names that are NOT ours (server-defined commands + TUI slash
+ * entries). Used to decide whether a partially typed name uniquely highlights
+ * one of our rows in the autocomplete. Refreshed opportunistically; while it
+ * is unknown we stay conservative and only intercept exact matches.
+ */
+let otherNames = null;
+let otherNamesAt = 0;
+async function refreshOtherNames(api) {
+    try {
+        const names = new Set();
+        const res = await api.client.command.list();
+        for (const c of res.data ?? []) {
+            if (c?.name)
+                names.add(c.name);
+        }
+        const km = api.keymap;
+        for (const e of km.getCommandEntries?.({ visibility: "reachable", namespace: "palette" }) ?? []) {
+            const slash = e.command?.slashName;
+            if (typeof slash === "string" && slash)
+                names.add(slash);
+            const aliases = e.command?.slashAliases;
+            if (Array.isArray(aliases))
+                for (const a of aliases)
+                    if (typeof a === "string" && a)
+                        names.add(a);
+        }
+        for (const { cmd } of COMMANDS)
+            names.delete(cmd);
+        otherNames = names;
+        otherNamesAt = Date.now();
+    }
+    catch {
+        // Keep the previous (possibly empty) cache; a retry happens on the next Enter.
+    }
+}
+/**
+ * Resolve the prompt text to one of our command names, or return null.
+ * Exact matches always resolve. A partial name resolves only when it is a
+ * prefix of exactly one of our commands and of no other slash-typeable name —
+ * i.e. when our row is the unambiguous highlighted autocomplete entry (the
+ * TUI's scorer doubles prefix matches, so that entry is strictly on top).
+ */
+function resolveTyped(text) {
+    if (EXACT.has(text))
+        return text.slice(1);
+    if (!text.startsWith("/"))
+        return null;
+    const name = text.slice(1);
+    if (!name || /\s/.test(name))
+        return null;
+    const ours = COMMANDS.filter(({ cmd }) => cmd.startsWith(name));
+    if (ours.length !== 1)
+        return null;
+    if (!otherNames)
+        return null;
+    for (const n of otherNames) {
+        if (n.startsWith(name))
+            return null;
+    }
+    return ours[0].cmd;
+}
+async function runCommand(api, command, commandArguments = "") {
+    const route = api.route.current;
+    let sessionID = route.name === "session"
+        ? route.params?.sessionID
+        : undefined;
+    try {
+        if (!sessionID) {
+            // Home route: replicate the stock submit flow — create a session,
+            // switch to it, then run the command there. Server defaults apply
+            // for agent/model; our commands are consumed before any model call.
+            const res = await api.client.session.create();
+            sessionID = res.data?.id;
+            if (!sessionID)
+                throw new Error("session.create returned no session id");
+            api.route.navigate("session", { sessionID });
+        }
+        await api.client.session.command({ sessionID, command, arguments: commandArguments });
+    }
+    catch (err) {
+        api.ui.toast({
+            variant: "error",
+            title: `/${command} failed`,
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function runControl(api, command) {
+    const dialogs = api.ui;
+    if (command === "peers-name") {
+        const name = (await dialogs.DialogPrompt({ title: "Rename this peer", placeholder: "1-32 safe characters" }))?.trim();
+        if (!name)
+            return;
+        if (!(await dialogs.DialogConfirm({ title: "Confirm peer rename", message: `Rename this peer to "${name}"?` })))
+            return;
+        return runCommand(api, command, name);
+    }
+    if (command === "peers-inbox") {
+        const action = await dialogs.DialogSelect({
+            title: "Peer inbox action",
+            options: [
+                { title: "List held messages", value: "list" },
+                { title: "Accept held message", value: "accept" },
+                { title: "Drop held message", value: "drop" },
+            ],
+        });
+        if (!action)
+            return;
+        if (action === "list")
+            return runCommand(api, command);
+        const target = (await dialogs.DialogPrompt({ title: `${action === "accept" ? "Accept" : "Drop"} which message?`, placeholder: "number or all" }))?.trim();
+        if (!target || (!/^\d+$/.test(target) && target !== "all"))
+            return;
+        if (action === "drop" && !(await dialogs.DialogConfirm({ title: "Confirm message drop", message: `Permanently drop held message ${target}?` })))
+            return;
+        return runCommand(api, command, `${action} ${target}`);
+    }
+    const selected = await dialogs.DialogSelect({
+        title: command === "peers-outbox" ? "Peer outbox" : "Peer sessions",
+        options: [{ title: command === "peers-outbox" ? "View delivery status" : "List peer sessions", value: "list" }],
+    });
+    if (selected !== "list")
+        return;
+    return runCommand(api, command);
+}
+/**
+ * Sync Enter handler: returns true (handled) only when the focused prompt
+ * holds exactly one of our commands; anything else returns false so the
+ * keymap falls through to the stock bindings. Must stay synchronous — a
+ * Promise result is always treated as handled by the keymap.
+ */
+function onEnter(api, ctx) {
+    // Never hijack Enter inside dialogs (rename prompts, palette search, …).
+    if (api.ui.dialog.open)
+        return false;
+    const route = api.route.current;
+    // Only the session prompt and the home prompt are command-entry points;
+    // plugin routes and anything else keep stock behavior.
+    if (route.name !== "session" && route.name !== "home")
+        return false;
+    const focused = ctx.focused;
+    if (typeof focused?.plainText !== "string")
+        return false;
+    if (Date.now() - otherNamesAt > 60_000)
+        void refreshOtherNames(api);
+    const command = resolveTyped(focused.plainText.trim());
+    if (!command)
+        return false;
+    try {
+        focused.setText?.("");
+    }
+    catch {
+        // Cosmetic only — prompt.clear below is the fallback.
+    }
+    // Drop the typed text from the prompt store as well, like a normal submit.
+    try {
+        api.keymap.dispatchCommand("prompt.clear");
+    }
+    catch {
+        // Command name may change in a future opencode version.
+    }
+    void runCommand(api, command);
+    return true;
+}
+const mod = {
+    id: "opencode-collaboration",
+    tui: async (api) => {
+        const unregister = api.keymap.registerLayer({
+            priority: LAYER_PRIORITY,
+            commands: COMMANDS.map(({ cmd, title, desc }) => ({
+                namespace: "palette",
+                name: `opencode-collaboration.${cmd}`,
+                title,
+                desc,
+                // No slashName on purpose: slash entries would add a second,
+                // duplicate row to the autocomplete menu. Instant execution comes
+                // from the Enter binding below; these stay reachable via the
+                // command palette.
+                run: () => runControl(api, cmd),
+            })),
+            bindings: [{ key: "return", cmd: (ctx) => onEnter(api, ctx) }],
+        });
+        api.lifecycle.onDispose(() => unregister());
+        void refreshOtherNames(api);
+    },
+};
+export default mod;

package/dist/types.d.ts

@@ -0,0 +1,162 @@
+export type InboundPolicy = "accept" | "auto" | "hold" | "refuse";
+export type PeerPermissionMode = "allow" | "ask" | "deny";
+export interface PeerFrom {
+    instanceId: string;
+    name: string;
+    directory: string;
+}
+export interface PeerEntry {
+    version: 1;
+    instanceId: string;
+    name: string;
+    pid: number;
+    hostname: string;
+    directory: string;
+    serverUrl: string;
+    inboxUrl: string;
+    inboxToken: string;
+    activeSessionId: string | null;
+    activeSessionTitle: string | null;
+    /** True while a turn is running in the active session. Optional (v0.1.4+). */
+    busy?: boolean;
+    /** Messages queued locally awaiting delivery. Optional (v0.1.4+). */
+    queuedCount?: number;
+    inboundPolicy: InboundPolicy;
+    startedAt: number;
+    heartbeatAt: number;
+    pluginVersion: string;
+}
+export type SessionEndpointStatus = "idle" | "busy" | "retry";
+export interface PeerRegistryV2 {
+    version: 2;
+    endpointId: string;
+    processId: string;
+    pid: number;
+    sessionId: string;
+    parentSessionId?: string;
+    title: string;
+    name: string;
+    hostname: string;
+    directory: string;
+    status: SessionEndpointStatus;
+    transport: LocalTransportAddress;
+    serverUrl: string;
+    inboxUrl: string;
+    inboxToken: string;
+    capabilities: string[];
+    timestamps: {
+        startedAt: number;
+        updatedAt: number;
+        heartbeatAt: number;
+    };
+    policy: {
+        inboundPolicy: InboundPolicy;
+        peerPermissions: PeerPermissionMode;
+    };
+    pluginVersion: string;
+    /** Compatibility aliases retained for existing formatters and commands. */
+    activeSessionId: string;
+    activeSessionTitle: string;
+    busy: boolean;
+    queuedCount: number;
+    inboundPolicy: InboundPolicy;
+    startedAt: number;
+    heartbeatAt: number;
+}
+export type PeerRegistryEntry = PeerEntry | PeerRegistryV2;
+/** Protocol-v1 input accepted from existing peers. */
+export interface InboundMessageV1 {
+    id: string;
+    from: PeerFrom;
+    text: string;
+    via: string[];
+    sentAt: number;
+}
+/** Backward-compatible name for protocol-v1 inbound input. */
+export type InboundMessage = InboundMessageV1;
+/** Protocol-v2 message shape used by endpoint-addressed transports. */
+export interface PeerMessageV2 {
+    version: 2;
+    messageId: string;
+    fromEndpointId: string;
+    toEndpointId: string;
+    from: PeerFrom;
+    text: string;
+    via: string[];
+    sentAt: number;
+}
+export type AcknowledgementStatus = "delivered" | "refused" | "expired" | "dropped" | "duplicate";
+/** Durable final outcome for a protocol-v2 message. */
+export interface PeerAcknowledgementV2 {
+    version: 2;
+    messageId: string;
+    fromEndpointId: string;
+    toEndpointId: string;
+    status: AcknowledgementStatus;
+    acknowledgedAt: number;
+}
+export interface OutboxRecord {
+    version: 1;
+    messageId: string;
+    fromEndpointId: string;
+    toEndpointId: string;
+    toName: string;
+    text: string;
+    createdAt: number;
+    updatedAt: number;
+    receiptStatus?: ReceiveStatus;
+    finalStatus?: AcknowledgementStatus;
+    acknowledgedAt?: number;
+    error?: string;
+}
+export type LocalTransportAddress = {
+    type: "unix";
+    path: string;
+} | {
+    type: "tcp";
+    host: "127.0.0.1";
+    port: number;
+};
+export interface HeldMessage extends InboundMessage {
+    heldAt: number;
+    expiresAt: number;
+}
+export type ReceiveStatus = "delivered" | "queued" | "held" | "refused" | "expired" | "dropped" | "full" | "duplicate";
+export interface PluginConfig {
+    /** Override the storage dir (defaults to $XDG_DATA_HOME/opencode-collaboration). */
+    storageDir?: string;
+    /** Display name for this instance (default: basename of directory). */
+    name?: string;
+    /** What to do with inbound messages. Default "accept". */
+    inboundPolicy?: InboundPolicy;
+    /**
+     * How to resolve permission requests raised while acting on a peer
+     * message (a turn started by an injected peer message). Default "allow":
+     * auto-approve so cross-session tasks run unattended. "ask" restores the
+     * default behavior (local user confirms); "deny" blocks tool use in
+     * peer-triggered turns.
+     */
+    peerPermissions?: PeerPermissionMode;
+    /** Heartbeat interval ms. Default 10_000. */
+    heartbeatMs?: number;
+    /** A peer is stale if its heartbeat is older than this. Default 30_000. */
+    staleMs?: number;
+    /** Max queued messages awaiting an immediate-delivery retry. Default 50. */
+    maxQueue?: number;
+    /** Max held messages. Default 100. */
+    maxHeld?: number;
+    /** Max bytes for a single message body. Default 8192. */
+    maxMessageBytes?: number;
+    /** Expiry for messages awaiting local approval. Default 300000 ms. */
+    heldExpiryMs?: number;
+    /** Maximum sender timestamp age/skew accepted by the receiver. Default 300000 ms. */
+    maxMessageAgeMs?: number;
+    /** Outbound rate limit per peer per minute. Default 10. */
+    sendRatePerMin?: number;
+    /** Inbound rate limit per sender per minute. Default 20. */
+    recvRatePerMin?: number;
+    /** Fallback sweep interval ms. Default 15_000. */
+    sweepMs?: number;
+}
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type Logger = (level: LogLevel, message: string, extra?: Record<string, unknown>) => Promise<void>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "opencode-collaboration",
+  "version": "0.2.3",
+  "description": "Cross-session messaging for opencode — let independent sessions discover and text each other, modeled after Claude Code's cross-session messaging",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    },
+    "./commands/peers.md": "./commands/peers.md",
+    "./commands/list-agents.md": "./commands/list-agents.md",
+    "./commands/peers-name.md": "./commands/peers-name.md",
+    "./commands/peers-inbox.md": "./commands/peers-inbox.md",
+    "./commands/peers-outbox.md": "./commands/peers-outbox.md",
+    "./commands/*": "./commands/*"
+  },
+  "files": [
+    "dist",
+    "commands",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "claude-code",
+    "cross-session",
+    "messaging",
+    "multi-agent",
+    "ai-coding-agent"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "opencode-collaboration authors"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/cqy0/opencode-collaboration.git"
+  },
+  "bugs": {
+    "url": "https://gitee.com/cqy0/opencode-collaboration/issues"
+  },
+  "homepage": "https://gitee.com/cqy0/opencode-collaboration#readme",
+  "engines": {
+    "node": ">=18",
+    "opencode": ">=1.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "dry-run": "npm publish --dry-run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.18.0"
+  },
+  "dependencies": {
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.0",
+    "@opentui/core": "^0.4.5",
+    "@opentui/keymap": "^0.4.5",
+    "@opentui/solid": "^0.4.5",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  },
+  "opencode": {
+    "plugin": true,
+    "commands": [
+      "commands/peers.md",
+      "commands/list-agents.md",
+      "commands/peers-name.md",
+      "commands/peers-inbox.md",
+      "commands/peers-outbox.md"
+    ]
+  }
+}