@pinet/slack-bridge 0.1.0

package/dist/broker/socket-server.js

@@ -0,0 +1,1087 @@
+import * as net from "node:net";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { DEFAULT_SOCKET_PATH } from "./paths.js";
+import { MessageRouter } from "./router.js";
+import { dispatchDirectAgentMessage } from "./agent-messaging.js";
+import { sendBrokerMessage } from "./message-send.js";
+import { assertLoopbackTcpHost } from "./raw-tcp-loopback.js";
+import { RPC_PARSE_ERROR, RPC_INVALID_REQUEST, RPC_METHOD_NOT_FOUND, RPC_INVALID_PARAMS, RPC_INTERNAL_ERROR, RPC_AUTH_REQUIRED, RPC_AGENT_NAME_CONFLICT, RPC_AGENT_STABLE_ID_CONFLICT, } from "./types.js";
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15_000;
+export const DEFAULT_PRUNE_INTERVAL_MS = 5_000;
+export const DEFAULT_AUTH_TIMEOUT_MS = 2_000;
+function toClientAgentInfo(agent) {
+    const { stableId, ...clientAgent } = agent;
+    void stableId;
+    return clientAgent;
+}
+// ─── RPC helpers ─────────────────────────────────────────
+function rpcOk(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function rpcError(id, code, message, data) {
+    const error = { code, message };
+    if (data !== undefined)
+        error.data = data;
+    return { jsonrpc: "2.0", id, error };
+}
+function isJsonRpcRequestId(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value !== 0;
+    }
+    return typeof value === "string" && value.length > 0;
+}
+function isJsonRpcRequestPayload(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const request = value;
+    if (request.jsonrpc !== "2.0") {
+        return false;
+    }
+    if (typeof request.method !== "string" || request.method.length === 0) {
+        return false;
+    }
+    if (!isJsonRpcRequestId(request.id)) {
+        return false;
+    }
+    if (request.params !== undefined &&
+        (typeof request.params !== "object" || request.params === null || Array.isArray(request.params))) {
+        return false;
+    }
+    return true;
+}
+function extractJsonRpcRequestId(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const id = value.id;
+    return isJsonRpcRequestId(id) ? id : null;
+}
+// ─── Socket server ───────────────────────────────────────
+export class BrokerSocketServer {
+    server = null;
+    target;
+    db;
+    router;
+    connections = new Map();
+    heartbeatTimeoutMs;
+    pruneIntervalMs;
+    authTimeoutMs;
+    meshSecret;
+    pruneTimer = null;
+    assignedPort = null;
+    agentMessageCallback = null;
+    agentStatusChangeCallback = null;
+    outboundMessageAdapters = [];
+    agentRegistrationResolver = null;
+    constructor(db, target, options = {}) {
+        this.db = db;
+        this.router = new MessageRouter(db);
+        this.heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+        this.pruneIntervalMs = options.pruneIntervalMs ?? DEFAULT_PRUNE_INTERVAL_MS;
+        this.authTimeoutMs = options.authTimeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS;
+        const meshSecret = options.meshSecret?.trim();
+        this.meshSecret = meshSecret && meshSecret.length > 0 ? meshSecret : null;
+        if (typeof target === "string") {
+            this.target = { type: "unix", path: target };
+        }
+        else if (target) {
+            this.target = target;
+        }
+        else {
+            this.target = { type: "unix", path: DEFAULT_SOCKET_PATH };
+        }
+        if (this.target.type === "tcp") {
+            assertLoopbackTcpHost(this.target.host, "broker listen target");
+        }
+    }
+    async start() {
+        // Clean up stale socket file for Unix mode
+        if (this.target.type === "unix") {
+            if (fs.existsSync(this.target.path)) {
+                fs.unlinkSync(this.target.path);
+            }
+            fs.mkdirSync(path.dirname(this.target.path), { recursive: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.server = net.createServer((socket) => this.onConnection(socket));
+            this.server.on("error", (err) => {
+                reject(err);
+            });
+            if (this.target.type === "unix") {
+                this.server.listen(this.target.path, () => {
+                    this.startPruning();
+                    resolve();
+                });
+            }
+            else {
+                this.server.listen(this.target.port, this.target.host, () => {
+                    const addr = this.server.address();
+                    if (addr && typeof addr === "object") {
+                        this.assignedPort = addr.port;
+                    }
+                    this.startPruning();
+                    resolve();
+                });
+            }
+        });
+    }
+    async stop() {
+        this.stopPruning();
+        // Mark all connected agents as resumably disconnected. Clear agentId so the
+        // async close handler won't mark them a second time after db shutdown.
+        for (const [socket, state] of this.connections) {
+            if (state.agentId) {
+                this.db.disconnectAgent(state.agentId, this.heartbeatTimeoutMs);
+                state.agentId = null;
+            }
+            socket.destroy();
+        }
+        this.connections.clear();
+        return new Promise((resolve) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.server.close(() => {
+                // Clean up socket file for Unix mode
+                if (this.target.type === "unix") {
+                    try {
+                        if (fs.existsSync(this.target.path)) {
+                            fs.unlinkSync(this.target.path);
+                        }
+                    }
+                    catch {
+                        // best effort
+                    }
+                }
+                this.server = null;
+                this.assignedPort = null;
+                resolve();
+            });
+        });
+    }
+    /**
+     * Get connection info for clients. Returns the socket path (Unix)
+     * or { host, port } (TCP).
+     */
+    getConnectInfo() {
+        if (this.target.type === "unix") {
+            return { type: "unix", path: this.target.path };
+        }
+        return {
+            type: "tcp",
+            host: this.target.host,
+            port: this.assignedPort ?? this.target.port,
+        };
+    }
+    /**
+     * Register a callback invoked whenever a worker sends an agent-to-agent
+     * message via the socket server. The broker uses this to push messages
+     * targeting itself into its in-memory inbox.
+     */
+    onAgentMessage(cb) {
+        this.agentMessageCallback = cb;
+    }
+    /**
+     * Register a callback invoked whenever a connected agent explicitly updates
+     * its broker status. The broker uses idle transitions to kick maintenance so
+     * backlog can be reassigned immediately.
+     */
+    onAgentStatusChange(cb) {
+        this.agentStatusChangeCallback = cb;
+    }
+    setAgentRegistrationResolver(resolver) {
+        this.agentRegistrationResolver = resolver;
+    }
+    setOutboundMessageAdapters(adapters) {
+        this.outboundMessageAdapters = adapters;
+    }
+    startPruning() {
+        this.stopPruning();
+        this.pruneTimer = setInterval(() => {
+            try {
+                this.db.pruneStaleAgents(this.heartbeatTimeoutMs);
+            }
+            catch {
+                /* best effort */
+            }
+        }, this.pruneIntervalMs);
+        this.pruneTimer.unref?.();
+    }
+    stopPruning() {
+        if (!this.pruneTimer)
+            return;
+        clearInterval(this.pruneTimer);
+        this.pruneTimer = null;
+    }
+    clearAuthTimer(state) {
+        if (!state.authTimer)
+            return;
+        clearTimeout(state.authTimer);
+        state.authTimer = null;
+    }
+    startAuthTimer(socket, state) {
+        this.clearAuthTimer(state);
+        if (state.authenticated || !this.meshSecret) {
+            return;
+        }
+        state.authTimer = setTimeout(() => {
+            this.clearAuthTimer(state);
+            socket.destroy();
+        }, this.authTimeoutMs);
+        state.authTimer.unref?.();
+    }
+    disconnectDuplicateConnections(agentId, currentSocket) {
+        for (const [socket, state] of this.connections) {
+            if (socket === currentSocket || state.agentId !== agentId) {
+                continue;
+            }
+            state.agentId = null;
+            socket.destroy();
+        }
+    }
+    findLiveStableIdConflict(stableId, currentSocket) {
+        const existing = this.db.getAgentByStableId(stableId);
+        if (!existing) {
+            return null;
+        }
+        for (const [socket, state] of this.connections) {
+            if (socket === currentSocket || state.agentId !== existing.id) {
+                continue;
+            }
+            return { ownerAgentId: existing.id };
+        }
+        return null;
+    }
+    // ─── Connection handling ─────────────────────────────
+    onConnection(socket) {
+        const state = {
+            agentId: null,
+            buffer: "",
+            authenticated: this.meshSecret == null,
+            authTimer: null,
+        };
+        this.connections.set(socket, state);
+        this.startAuthTimer(socket, state);
+        socket.on("data", (chunk) => {
+            state.buffer += chunk.toString("utf-8");
+            void this.processBuffer(socket, state);
+        });
+        socket.on("close", () => {
+            this.clearAuthTimer(state);
+            if (state.agentId) {
+                this.db.disconnectAgent(state.agentId, this.heartbeatTimeoutMs);
+            }
+            this.connections.delete(socket);
+        });
+        socket.on("error", () => {
+            // close event will handle cleanup
+        });
+    }
+    processBuffer(socket, state) {
+        let newlineIdx;
+        while ((newlineIdx = state.buffer.indexOf("\n")) !== -1) {
+            const line = state.buffer.slice(0, newlineIdx).trim();
+            state.buffer = state.buffer.slice(newlineIdx + 1);
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                this.send(socket, rpcError(null, RPC_PARSE_ERROR, "Parse error"));
+                continue;
+            }
+            if (!isJsonRpcRequestPayload(parsed)) {
+                this.send(socket, rpcError(extractJsonRpcRequestId(parsed), RPC_INVALID_REQUEST, "Invalid request"));
+                continue;
+            }
+            void this.dispatchRequest(parsed, state, socket);
+        }
+    }
+    async dispatchRequest(req, state, socket) {
+        try {
+            const response = await this.handleRequest(req, state, socket);
+            this.send(socket, response);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.send(socket, rpcError(req.id, RPC_INTERNAL_ERROR, message));
+        }
+    }
+    send(socket, response) {
+        try {
+            socket.write(JSON.stringify(response) + "\n");
+        }
+        catch {
+            // connection may have closed
+        }
+    }
+    // ─── Request dispatch ────────────────────────────────
+    async handleRequest(req, state, socket) {
+        try {
+            if (!state.authenticated && req.method !== "auth") {
+                setImmediate(() => socket.destroy());
+                return rpcError(req.id, RPC_AUTH_REQUIRED, "Authentication required before calling broker methods.");
+            }
+            switch (req.method) {
+                case "auth":
+                    return this.handleAuth(req, state, socket);
+                case "register":
+                    return this.handleRegister(req, state, socket);
+                case "unregister":
+                    return this.handleUnregister(req, state);
+                case "heartbeat":
+                    return this.handleHeartbeat(req, state);
+                case "inbox.poll":
+                    return this.handleInboxPoll(req, state);
+                case "inbox.read":
+                    return this.handleInboxRead(req, state);
+                case "inbox.ack":
+                    return this.handleInboxAck(req, state);
+                case "send":
+                    return this.handleSend(req, state);
+                case "message.send":
+                    return await this.handleMessageSend(req, state);
+                case "threads.list":
+                    return this.handleThreadsList(req, state);
+                case "agents.list":
+                    return this.handleAgentsList(req);
+                case "thread.claim":
+                    return this.handleThreadClaim(req, state);
+                case "resolveThread":
+                    return this.handleResolveThread(req, state);
+                case "agent.message":
+                    return this.handleAgentMessage(req, state);
+                case "agent.broadcast":
+                    return this.handleAgentBroadcast(req, state);
+                case "lane.list":
+                    return this.handleLaneList(req, state);
+                case "lane.upsert":
+                    return this.handleLaneUpsert(req, state);
+                case "lane.participant":
+                    return this.handleLaneParticipant(req, state);
+                case "portLease.acquire":
+                    return this.handlePortLeaseAcquire(req, state);
+                case "portLease.renew":
+                    return this.handlePortLeaseRenew(req, state);
+                case "portLease.release":
+                    return this.handlePortLeaseRelease(req, state);
+                case "portLease.status":
+                    return this.handlePortLeaseStatus(req, state);
+                case "portLease.list":
+                    return this.handlePortLeaseList(req, state);
+                case "portLease.expire":
+                    return this.handlePortLeaseExpire(req, state);
+                case "schedule.create":
+                    return this.handleScheduleCreate(req, state);
+                case "status.update":
+                    return this.handleStatusUpdate(req, state);
+                case "adapter.capability":
+                    return await this.handleAdapterCapability(req, state);
+                case "slack.proxy":
+                    return await this.handleLegacySlackProxy(req, state);
+                default:
+                    return rpcError(req.id, RPC_METHOD_NOT_FOUND, `Unknown method: ${req.method}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INTERNAL_ERROR, message);
+        }
+    }
+    // ─── Method handlers ─────────────────────────────────
+    handleAuth(req, state, socket) {
+        if (!this.meshSecret) {
+            state.authenticated = true;
+            this.clearAuthTimer(state);
+            return rpcOk(req.id, { ok: true });
+        }
+        const params = req.params ?? {};
+        const providedSecret = typeof params.secret === "string" ? params.secret.trim() : "";
+        if (!providedSecret) {
+            setImmediate(() => socket.destroy());
+            return rpcError(req.id, RPC_AUTH_REQUIRED, "Mesh secret is required.");
+        }
+        if (providedSecret !== this.meshSecret) {
+            setImmediate(() => socket.destroy());
+            return rpcError(req.id, RPC_AUTH_REQUIRED, "Invalid mesh secret.");
+        }
+        state.authenticated = true;
+        this.clearAuthTimer(state);
+        return rpcOk(req.id, { ok: true });
+    }
+    handleRegister(req, state, socket) {
+        const params = req.params ?? {};
+        const requestedName = typeof params.name === "string" ? params.name.trim() : "";
+        const requestedEmoji = typeof params.emoji === "string" ? params.emoji : "";
+        const pid = typeof params.pid === "number" ? params.pid : 0;
+        const stableId = typeof params.stableId === "string" ? params.stableId : undefined;
+        const metadata = params.metadata && typeof params.metadata === "object"
+            ? params.metadata
+            : undefined;
+        if (stableId) {
+            const liveStableIdConflict = this.findLiveStableIdConflict(stableId, socket);
+            if (liveStableIdConflict) {
+                return rpcError(req.id, RPC_AGENT_STABLE_ID_CONFLICT, `Agent stableId "${stableId}" is already active on another live connection. Wait for that agent to disconnect before retrying.`, {
+                    code: "AGENT_STABLE_ID_CONFLICT",
+                    stableId,
+                    ownerAgentId: liveStableIdConflict.ownerAgentId,
+                    retryable: true,
+                });
+            }
+        }
+        const candidateId = state.agentId ?? crypto.randomUUID();
+        const resolved = this.agentRegistrationResolver?.({
+            agentId: candidateId,
+            name: requestedName,
+            emoji: requestedEmoji,
+            pid,
+            stableId,
+            metadata,
+        });
+        const explicitNameRequest = requestedName.length > 0;
+        const finalName = explicitNameRequest
+            ? requestedName
+            : (resolved?.name ?? requestedName) || "anonymous";
+        const finalEmoji = explicitNameRequest
+            ? requestedEmoji.trim() || resolved?.emoji?.trim() || ""
+            : (resolved?.emoji ?? requestedEmoji).trim();
+        const finalMetadata = resolved?.metadata ?? metadata;
+        if (explicitNameRequest) {
+            const conflict = this.db.findAgentNameConflict(finalName, candidateId, stableId);
+            if (conflict) {
+                // Do not expose raw ownerStableId on this client-visible payload (#495).
+                // The message + code + requestedName are enough to drive the retry path.
+                return rpcError(req.id, RPC_AGENT_NAME_CONFLICT, `Agent name "${finalName}" is already reserved. Retry with a different name or leave the name empty so the broker can assign one.`, {
+                    code: "AGENT_NAME_CONFLICT",
+                    requestedName: finalName,
+                    retryable: true,
+                });
+            }
+        }
+        const agent = this.db.registerAgent(candidateId, finalName, finalEmoji, pid, finalMetadata, stableId);
+        this.disconnectDuplicateConnections(agent.id, socket);
+        state.agentId = agent.id;
+        return rpcOk(req.id, {
+            agentId: agent.id,
+            name: agent.name,
+            emoji: agent.emoji,
+            metadata: agent.metadata,
+        });
+    }
+    handleUnregister(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        this.db.unregisterAgent(state.agentId);
+        state.agentId = null;
+        return rpcOk(req.id, { ok: true });
+    }
+    handleHeartbeat(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const metadata = params.metadata;
+        if (metadata !== undefined && (typeof metadata !== "object" || Array.isArray(metadata))) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "metadata must be an object or null");
+        }
+        this.db.heartbeatAgent(state.agentId);
+        if (metadata !== undefined) {
+            this.db.updateAgentMetadata(state.agentId, metadata);
+        }
+        return rpcOk(req.id, { ok: true });
+    }
+    handleInboxPoll(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        this.db.touchAgent(state.agentId);
+        const params = req.params ?? {};
+        const limit = typeof params.limit === "number" ? params.limit : 50;
+        const items = this.db.getInbox(state.agentId, limit);
+        return rpcOk(req.id, items.map((item) => ({
+            inboxId: item.entry.id,
+            message: item.message,
+        })));
+    }
+    handleInboxRead(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        this.db.touchAgent(state.agentId);
+        const params = req.params ?? {};
+        const threadId = typeof params.threadId === "string" ? params.threadId.trim() : undefined;
+        if (params.threadId !== undefined && !threadId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "threadId must be a non-empty string");
+        }
+        const limit = params.limit === undefined ? undefined : params.limit;
+        if (limit !== undefined && (typeof limit !== "number" || !Number.isFinite(limit))) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "limit must be a finite number");
+        }
+        const unreadOnly = params.unreadOnly === undefined ? undefined : params.unreadOnly;
+        if (unreadOnly !== undefined && typeof unreadOnly !== "boolean") {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "unreadOnly must be a boolean");
+        }
+        const markRead = params.markRead === undefined ? undefined : params.markRead;
+        if (markRead !== undefined && typeof markRead !== "boolean") {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "markRead must be a boolean");
+        }
+        return rpcOk(req.id, this.db.readInbox(state.agentId, {
+            ...(threadId ? { threadId } : {}),
+            ...(typeof limit === "number" ? { limit } : {}),
+            ...(typeof unreadOnly === "boolean" ? { unreadOnly } : {}),
+            ...(typeof markRead === "boolean" ? { markRead } : {}),
+        }));
+    }
+    handleInboxAck(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const ids = params.ids;
+        if (!Array.isArray(ids) || !ids.every((id) => typeof id === "number")) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "ids must be an array of numbers");
+        }
+        this.db.markDelivered(ids, state.agentId);
+        // Activity tracking: acknowledging messages proves the agent processed them
+        if (state.agentId) {
+            this.db.touchAgentActivity(state.agentId);
+        }
+        return rpcOk(req.id, { ok: true });
+    }
+    handleSend(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const threadId = typeof params.threadId === "string" ? params.threadId : null;
+        const body = typeof params.body === "string" ? params.body : null;
+        if (!threadId || !body) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "threadId and body are required");
+        }
+        const source = typeof params.source === "string" ? params.source : "agent";
+        const direction = params.direction === "inbound" || params.direction === "outbound"
+            ? params.direction
+            : "outbound";
+        const metadata = params.metadata && typeof params.metadata === "object"
+            ? params.metadata
+            : undefined;
+        // Ensure thread exists
+        let thread = this.db.getThread(threadId);
+        if (!thread) {
+            const channel = typeof params.channel === "string" ? params.channel : "";
+            thread = this.db.createThread(threadId, source, channel, state.agentId);
+        }
+        // Route to all OTHER connected agents
+        const allAgents = this.db.getAgents();
+        const targetIds = allAgents.filter((a) => a.id !== state.agentId).map((a) => a.id);
+        const msg = this.db.insertMessage(threadId, source, direction, state.agentId, body, targetIds, metadata);
+        // Activity tracking: sending a message proves the agent is working
+        this.db.touchAgentActivity(state.agentId);
+        return rpcOk(req.id, { messageId: msg.id });
+    }
+    async handleMessageSend(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const threadId = typeof params.threadId === "string" ? params.threadId : null;
+        const body = typeof params.body === "string" ? params.body : null;
+        const source = typeof params.source === "string" ? params.source : undefined;
+        const channel = typeof params.channel === "string" ? params.channel : undefined;
+        const agentName = typeof params.agentName === "string" ? params.agentName : undefined;
+        const agentEmoji = typeof params.agentEmoji === "string" ? params.agentEmoji : undefined;
+        const agentOwnerToken = typeof params.agentOwnerToken === "string" ? params.agentOwnerToken : undefined;
+        const blocks = Array.isArray(params.blocks)
+            ? params.blocks.filter((entry) => !!entry && typeof entry === "object")
+            : undefined;
+        let content;
+        if (params.content !== undefined) {
+            if (!params.content || typeof params.content !== "object" || Array.isArray(params.content)) {
+                return rpcError(req.id, RPC_INVALID_PARAMS, "content must be an object");
+            }
+            const raw = params.content;
+            const text = typeof raw.text === "string" ? raw.text.trim() : "";
+            if (!text) {
+                return rpcError(req.id, RPC_INVALID_PARAMS, "content.text is required when content is provided");
+            }
+            const markdown = typeof raw.markdown === "string" ? raw.markdown.trim() : undefined;
+            const slackBlocks = Array.isArray(raw.slackBlocks)
+                ? raw.slackBlocks.filter((entry) => !!entry && typeof entry === "object")
+                : undefined;
+            content = {
+                text,
+                ...(markdown ? { markdown } : {}),
+                ...(slackBlocks && slackBlocks.length > 0 ? { slackBlocks } : {}),
+            };
+        }
+        const metadata = params.metadata && typeof params.metadata === "object"
+            ? params.metadata
+            : undefined;
+        if (!threadId || !body) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "threadId and body are required");
+        }
+        const result = await sendBrokerMessage({
+            db: this.db,
+            adapters: this.outboundMessageAdapters,
+        }, {
+            threadId,
+            body,
+            senderAgentId: state.agentId,
+            ...(source ? { source } : {}),
+            ...(channel ? { channel } : {}),
+            ...(content ? { content } : {}),
+            ...(blocks && blocks.length > 0 ? { blocks } : {}),
+            ...(agentName ? { agentName } : {}),
+            ...(agentEmoji ? { agentEmoji } : {}),
+            ...(agentOwnerToken ? { agentOwnerToken } : {}),
+            ...(metadata ? { metadata } : {}),
+        });
+        this.db.touchAgentActivity(state.agentId);
+        return rpcOk(req.id, {
+            adapter: result.adapter,
+            messageId: result.message.id,
+            threadId: result.thread.threadId,
+            channel: result.thread.channel,
+            source: result.thread.source,
+        });
+    }
+    handleThreadsList(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const threads = this.db.getThreads(state.agentId);
+        return rpcOk(req.id, threads);
+    }
+    handleAgentsList(req) {
+        const params = req.params ?? {};
+        const includeDisconnected = params.includeDisconnected === true;
+        const agents = (includeDisconnected ? this.db.getAllAgents() : this.db.getAgents()).map((agent) => ({
+            ...toClientAgentInfo(agent),
+            pendingInboxCount: this.db.getPendingInboxCount(agent.id),
+        }));
+        return rpcOk(req.id, agents);
+    }
+    // ─── Thread claim handler ─────────────────────────────
+    handleThreadClaim(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const threadId = typeof params.threadId === "string" ? params.threadId : null;
+        if (!threadId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "threadId is required");
+        }
+        const channel = typeof params.channel === "string" ? params.channel : undefined;
+        let source = typeof params.source === "string" && params.source.trim().length > 0
+            ? params.source.trim()
+            : undefined;
+        // Backward compatibility: legacy Slack callers used channel-only thread.claim
+        // requests. Keep those claims Slack-sendable while allowing truly source-less
+        // claims to fall through to broker-core's neutral default.
+        const legacyChannelOnlyClaim = !source && !!channel;
+        if (legacyChannelOnlyClaim) {
+            source = "slack";
+        }
+        const claimed = this.router.claimThread(threadId, state.agentId, channel, source);
+        if (claimed && legacyChannelOnlyClaim) {
+            this.db.updateThread(threadId, { source, channel });
+        }
+        return rpcOk(req.id, { claimed });
+    }
+    handleResolveThread(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const threadTs = typeof params.threadTs === "string" ? params.threadTs : null;
+        if (!threadTs) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "threadTs is required");
+        }
+        const channelId = this.db.getThread(threadTs)?.channel || null;
+        return rpcOk(req.id, { channelId });
+    }
+    // ─── Agent-to-agent messaging ─────────────────────────
+    handleAgentMessage(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const targetAgent = typeof params.targetAgent === "string" ? params.targetAgent : null;
+        const body = typeof params.body === "string" ? params.body : null;
+        if (!targetAgent || !body) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "targetAgent and body are required");
+        }
+        const metadata = params.metadata && typeof params.metadata === "object"
+            ? params.metadata
+            : undefined;
+        const sender = this.db.getAgents().find((agent) => agent.id === state.agentId);
+        const senderName = sender?.name ?? state.agentId;
+        try {
+            const result = dispatchDirectAgentMessage(this.db, {
+                senderAgentId: state.agentId,
+                senderAgentName: senderName,
+                target: targetAgent,
+                body,
+                metadata,
+            }, (target, msg, enrichedMeta) => {
+                this.agentMessageCallback?.(target.id, msg, enrichedMeta);
+            });
+            // Activity tracking: sending agent-to-agent messages proves the agent is working
+            this.db.touchAgentActivity(state.agentId);
+            return rpcOk(req.id, { ok: true, messageId: result.messageId });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handleAgentBroadcast(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const channel = typeof params.channel === "string" ? params.channel : null;
+        const body = typeof params.body === "string" ? params.body : null;
+        if (!channel || !body) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "channel and body are required");
+        }
+        return rpcError(req.id, RPC_INVALID_PARAMS, "Broadcast channels are broker-only and cannot be sent by connected clients.");
+    }
+    handleLaneList(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const options = {
+            ...(typeof params.state === "string" ? { state: params.state } : {}),
+            ...(typeof params.ownerAgentId === "string" ? { ownerAgentId: params.ownerAgentId } : {}),
+            ...(typeof params.includeDone === "boolean" ? { includeDone: params.includeDone } : {}),
+        };
+        try {
+            return rpcOk(req.id, this.db.listPinetLanes(options));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handleLaneUpsert(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        if (typeof params.laneId !== "string" || params.laneId.trim().length === 0) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "laneId is required");
+        }
+        const input = {
+            laneId: params.laneId,
+            ...(typeof params.name === "string" || params.name === null
+                ? { name: params.name }
+                : {}),
+            ...(typeof params.task === "string" || params.task === null
+                ? { task: params.task }
+                : {}),
+            ...(typeof params.issueNumber === "number" || params.issueNumber === null
+                ? { issueNumber: params.issueNumber }
+                : {}),
+            ...(typeof params.prNumber === "number" || params.prNumber === null
+                ? { prNumber: params.prNumber }
+                : {}),
+            ...(typeof params.threadId === "string" || params.threadId === null
+                ? { threadId: params.threadId }
+                : {}),
+            ...(typeof params.ownerAgentId === "string" || params.ownerAgentId === null
+                ? { ownerAgentId: params.ownerAgentId }
+                : {}),
+            ...(typeof params.implementationLeadAgentId === "string" ||
+                params.implementationLeadAgentId === null
+                ? { implementationLeadAgentId: params.implementationLeadAgentId }
+                : {}),
+            ...(typeof params.pmMode === "boolean" ? { pmMode: params.pmMode } : {}),
+            ...(typeof params.state === "string" ? { state: params.state } : {}),
+            ...(typeof params.summary === "string" || params.summary === null
+                ? { summary: params.summary }
+                : {}),
+            ...(params.metadata && typeof params.metadata === "object" && !Array.isArray(params.metadata)
+                ? { metadata: params.metadata }
+                : params.metadata === null
+                    ? { metadata: null }
+                    : {}),
+        };
+        try {
+            const lane = this.db.upsertPinetLane(input);
+            this.db.touchAgentActivity(state.agentId);
+            return rpcOk(req.id, lane);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handleLaneParticipant(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        if (typeof params.laneId !== "string" || params.laneId.trim().length === 0) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "laneId is required");
+        }
+        const agentId = typeof params.agentId === "string" && params.agentId.trim().length > 0
+            ? params.agentId
+            : state.agentId;
+        const input = {
+            laneId: params.laneId,
+            agentId,
+            role: (typeof params.role === "string" ? params.role : "observer"),
+            ...(typeof params.status === "string" || params.status === null
+                ? { status: params.status }
+                : {}),
+            ...(typeof params.summary === "string" || params.summary === null
+                ? { summary: params.summary }
+                : {}),
+            ...(params.metadata && typeof params.metadata === "object" && !Array.isArray(params.metadata)
+                ? { metadata: params.metadata }
+                : params.metadata === null
+                    ? { metadata: null }
+                    : {}),
+        };
+        try {
+            const participant = this.db.setPinetLaneParticipant(input);
+            this.db.touchAgentActivity(state.agentId);
+            return rpcOk(req.id, participant);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handlePortLeaseAcquire(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const input = {
+            purpose: typeof params.purpose === "string" ? params.purpose : "",
+            ttlMs: typeof params.ttlMs === "number" ? params.ttlMs : Number(params.ttlMs),
+            ownerAgentId: state.agentId,
+            ...(typeof params.host === "string" ? { host: params.host } : {}),
+            ...(typeof params.port === "number" ? { port: params.port } : {}),
+            ...(typeof params.minPort === "number" ? { minPort: params.minPort } : {}),
+            ...(typeof params.maxPort === "number" ? { maxPort: params.maxPort } : {}),
+            ...(typeof params.pid === "number" || params.pid === null
+                ? { pid: params.pid }
+                : {}),
+            ...(params.metadata && typeof params.metadata === "object" && !Array.isArray(params.metadata)
+                ? { metadata: params.metadata }
+                : params.metadata === null
+                    ? { metadata: null }
+                    : {}),
+        };
+        try {
+            const lease = this.db.acquirePortLease(input);
+            this.db.touchAgentActivity(state.agentId);
+            return rpcOk(req.id, lease);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handlePortLeaseRenew(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const input = {
+            leaseId: typeof params.leaseId === "string" ? params.leaseId : "",
+            ttlMs: typeof params.ttlMs === "number" ? params.ttlMs : Number(params.ttlMs),
+            ownerAgentId: state.agentId,
+        };
+        try {
+            const lease = this.db.renewPortLease(input);
+            this.db.touchAgentActivity(state.agentId);
+            return rpcOk(req.id, lease);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handlePortLeaseRelease(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const input = {
+            leaseId: typeof params.leaseId === "string" ? params.leaseId : "",
+            ownerAgentId: state.agentId,
+        };
+        try {
+            const lease = this.db.releasePortLease(input);
+            this.db.touchAgentActivity(state.agentId);
+            return rpcOk(req.id, lease);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handlePortLeaseStatus(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const leaseId = typeof params.leaseId === "string" ? params.leaseId : "";
+        try {
+            const lease = this.db.getPortLease(leaseId);
+            return rpcOk(req.id, lease?.ownerAgentId === state.agentId ? lease : null);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handlePortLeaseList(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const options = {
+            ...(typeof params.includeInactive === "boolean"
+                ? { includeInactive: params.includeInactive }
+                : {}),
+            ...(typeof params.expiredOnly === "boolean" ? { expiredOnly: params.expiredOnly } : {}),
+            ownerAgentId: state.agentId,
+            ...(typeof params.purpose === "string" ? { purpose: params.purpose } : {}),
+            ...(typeof params.host === "string" ? { host: params.host } : {}),
+        };
+        try {
+            return rpcOk(req.id, this.db.listPortLeases(options));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handlePortLeaseExpire(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        try {
+            const leases = this.db
+                .expirePortLeases()
+                .filter((lease) => lease.ownerAgentId === state.agentId);
+            if (leases.length > 0) {
+                this.db.touchAgentActivity(state.agentId);
+            }
+            return rpcOk(req.id, leases);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(req.id, RPC_INVALID_PARAMS, message);
+        }
+    }
+    handleScheduleCreate(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const fireAt = typeof params.fireAt === "string" ? params.fireAt : null;
+        const body = typeof params.body === "string" ? params.body.trim() : null;
+        if (!fireAt || !body) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "fireAt and body are required");
+        }
+        if (Number.isNaN(Date.parse(fireAt))) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "fireAt must be a valid ISO timestamp");
+        }
+        const wakeup = this.db.scheduleWakeup(state.agentId, body, fireAt);
+        return rpcOk(req.id, {
+            id: wakeup.id,
+            threadId: wakeup.threadId,
+            fireAt: wakeup.fireAt,
+        });
+    }
+    // ─── Status update handler ─────────────────────────────
+    handleStatusUpdate(req, state) {
+        if (!state.agentId) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "Not registered");
+        }
+        const params = req.params ?? {};
+        const status = params.status === "working" ? "working" : "idle";
+        this.db.updateAgentStatus(state.agentId, status);
+        try {
+            this.agentStatusChangeCallback?.(state.agentId, status);
+        }
+        catch {
+            /* best effort */
+        }
+        return rpcOk(req.id, { ok: true });
+    }
+    // ─── Adapter capability handler ───────────────────────
+    async handleAdapterCapability(req, state) {
+        const params = req.params ?? {};
+        const adapterName = typeof params.adapter === "string"
+            ? params.adapter.trim()
+            : typeof params.source === "string"
+                ? params.source.trim()
+                : "";
+        const capability = typeof params.capability === "string" ? params.capability.trim() : "";
+        if (!adapterName) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "adapter is required for adapter.capability");
+        }
+        if (!capability) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "capability is required for adapter.capability");
+        }
+        const capabilityParams = params.params && typeof params.params === "object" && !Array.isArray(params.params)
+            ? params.params
+            : {};
+        return await this.dispatchAdapterCapability(req.id, adapterName, capability, capabilityParams, state);
+    }
+    async handleLegacySlackProxy(req, state) {
+        const params = req.params ?? {};
+        const method = typeof params.method === "string" ? params.method.trim() : "";
+        if (!method) {
+            return rpcError(req.id, RPC_INVALID_PARAMS, "method is required for slack.proxy");
+        }
+        const apiParams = params.params && typeof params.params === "object" && !Array.isArray(params.params)
+            ? params.params
+            : {};
+        return await this.dispatchAdapterCapability(req.id, "slack", "api.call", { method, params: apiParams }, state, "slack.proxy");
+    }
+    async dispatchAdapterCapability(id, adapterName, capability, capabilityParams, state, errorPrefix = `${adapterName}.${capability}`) {
+        const adapter = this.outboundMessageAdapters.find((candidate) => candidate.name === adapterName);
+        if (!adapter?.invokeCapability) {
+            return rpcError(id, RPC_METHOD_NOT_FOUND, `Adapter ${adapterName} does not implement capability ${capability}`);
+        }
+        try {
+            const response = await adapter.invokeCapability({ capability, params: capabilityParams });
+            this.applyAdapterCapabilityEffects(adapterName, response, state);
+            return rpcOk(id, response.result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return rpcError(id, RPC_INTERNAL_ERROR, `${errorPrefix}: ${message}`);
+        }
+    }
+    applyAdapterCapabilityEffects(adapterName, response, state) {
+        if (!state.agentId)
+            return;
+        const claimThread = response.effects?.claimThread;
+        const claims = Array.isArray(claimThread) ? claimThread : claimThread ? [claimThread] : [];
+        for (const claim of claims) {
+            if (!claim.threadId)
+                continue;
+            const claimed = this.router.claimThread(claim.threadId, state.agentId, claim.channel, adapterName);
+            if (claimed && claim.channel) {
+                this.db.updateThread(claim.threadId, { source: adapterName, channel: claim.channel });
+            }
+        }
+    }
+}