Files
openshell_controller/scripts/inter-sandbox-chat-mcp.mjs
T

246 lines
12 KiB
JavaScript
Executable File

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import { z } from "zod"
import {
MAX_MESSAGE_LENGTH,
ackChatMessage,
claimOperatorMessages,
cleanRoom,
cleanText,
listRooms,
messageNeedsAck,
postChatMessage,
readStore,
roomData,
} from "./inter-sandbox-chat-core.mjs"
function asText(payload) {
return {
content: [
{
type: "text",
text: typeof payload === "string" ? payload : JSON.stringify(payload, null, 2),
},
],
}
}
const server = new McpServer({
name: "inter-sandbox-chat",
version: "0.3.0",
})
server.registerTool(
"post_message",
{
title: "Post Message",
description: "Post a message into an inter-sandbox chat room. Sandbox-to-sandbox messages are normal chat and do not need acknowledgements. Operator-injected messages should set origin='operator'; only those messages are marked for agent acknowledgement.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
sender: z.string().default("anonymous-sandbox").describe("Sender name, usually the sandbox or agent name."),
message: z.string().min(1).max(MAX_MESSAGE_LENGTH).describe("Message text to share with other sandboxes."),
origin: z.enum(["sandbox", "operator"]).default("sandbox").describe("Message origin. Use 'operator' only for human/operator-injected chats that agents should acknowledge."),
ackToken: z.string().optional().describe("Optional stable token supplied by the operator UI. Stored only for operator messages; omitted sandbox messages do not need receipts."),
targetSandboxIds: z.array(z.string()).default([]).describe("Optional sandbox ids to notify. Use this for direct sandbox-to-sandbox chat without broadcasting a room."),
targetSandboxNames: z.array(z.string()).default([]).describe("Optional sandbox names to notify. A room named for a sandbox also counts as targeted."),
targetAgentIds: z.array(z.string()).default([]).describe("Optional sidecar/agent ids to notify."),
},
},
async ({ room, sender, message, origin, ackToken, targetSandboxIds, targetSandboxNames, targetAgentIds }) => {
return asText(await postChatMessage({
room,
sender,
message,
origin,
ackToken,
targetSandboxIds,
targetSandboxNames,
targetAgentIds,
}))
},
)
server.registerTool(
"post_operator_message",
{
title: "Post Operator Message",
description: "Post a human/operator-injected chat into a room. Messages created by this tool always have origin='operator' and requiresAck=true so agents know to acknowledge receipt with ack_message. Use post_message for normal sandbox-to-sandbox chat.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
sender: z.string().default("operator").describe("Operator or UI sender label."),
message: z.string().min(1).max(MAX_MESSAGE_LENGTH).describe("Operator message text to share with agents."),
ackToken: z.string().optional().describe("Optional stable token supplied by the operator UI for correlating receipts."),
targetSandboxIds: z.array(z.string()).default([]).describe("Optional sandbox ids that should be woken by the controller sidecar."),
targetSandboxNames: z.array(z.string()).default([]).describe("Optional sandbox names that should be woken by the controller sidecar."),
targetAgentIds: z.array(z.string()).default([]).describe("Optional agent ids that should be woken by the controller sidecar."),
},
},
async ({ room, sender, message, ackToken, targetSandboxIds, targetSandboxNames, targetAgentIds }) => {
return asText(await postChatMessage({
room,
sender,
message,
origin: "operator",
ackToken,
targetSandboxIds,
targetSandboxNames,
targetAgentIds,
}))
},
)
server.registerTool(
"read_messages",
{
title: "Read Messages",
description: "Read recent messages from an inter-sandbox chat room. Important model behavior: acknowledge only operator-originated messages. If a returned message has origin='operator' and requiresAck=true, call ack_message immediately with status='received'. Do not acknowledge sandbox-originated messages.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
afterId: z.string().optional().describe("Only return messages after this message id."),
limit: z.number().int().min(1).max(100).default(50).describe("Maximum number of messages to return."),
},
},
async ({ room, afterId, limit }) => {
const store = await readStore()
const roomId = cleanRoom(room)
const messages = roomData(store, roomId).messages
const start = afterId ? messages.findIndex((message) => message.id === afterId) + 1 : 0
const selected = messages.slice(Math.max(0, start)).slice(-limit)
return asText({ ok: true, room: roomId, count: selected.length, messages: selected })
},
)
server.registerTool(
"ack_message",
{
title: "Acknowledge Operator Message",
description: "Acknowledge receipt or handling of an operator-originated chat message. Use this only for messages where origin='operator' and requiresAck=true. Never call this for sandbox-to-sandbox chat messages.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
messageId: z.string().min(1).describe("Operator message id being acknowledged."),
ackToken: z.string().optional().describe("Optional operator ack token. If the message has a token, a provided token must match it."),
agentId: z.string().default("anonymous-agent").describe("Stable acknowledging agent id."),
sandboxId: z.string().optional().describe("Stable sandbox id or sandbox name for UI grouping."),
status: z.enum(["received", "processed", "failed"]).default("received").describe("Use received immediately after seeing the operator message, then processed or failed after acting on it."),
note: z.string().max(1000).optional().describe("Optional short machine-readable or human-readable note."),
},
},
async ({ room, messageId, ackToken, agentId, sandboxId, status, note }) => {
return asText(await ackChatMessage({ room, messageId, ackToken, agentId, sandboxId, status, note }))
},
)
server.registerTool(
"claim_operator_messages",
{
title: "Claim Operator Messages",
description: "Return only new targeted operator messages for an agent/sandbox and optionally mark them received. Use this instead of polling read_messages from an LLM loop. Broadcast lobby messages are ignored unless includeBroadcast=true; messages in a room named for the sandbox are considered targeted.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
agentId: z.string().default("anonymous-agent").describe("Stable claiming agent id."),
sandboxId: z.string().optional().describe("Stable sandbox id for cursoring and receipt grouping."),
sandboxName: z.string().optional().describe("Sandbox name for target matching."),
limit: z.number().int().min(1).max(50).default(5).describe("Maximum number of new operator messages to claim."),
includeBroadcast: z.boolean().default(false).describe("When true, untargeted operator messages in the room are also claimable."),
autoAck: z.boolean().default(true).describe("When true, writes a received receipt before returning messages."),
},
},
async ({ room, agentId, sandboxId, sandboxName, limit, includeBroadcast, autoAck }) => {
return asText(await claimOperatorMessages({ room, agentId, sandboxId, sandboxName, limit, includeBroadcast, autoAck }))
},
)
server.registerTool(
"get_message_receipts",
{
title: "Get Operator Message Receipts",
description: "Return parseable acknowledgement state for an operator message. This is intended for operator UIs and orchestration; sandbox-to-sandbox messages normally have no receipts.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
messageId: z.string().min(1).describe("Message id to inspect."),
expectedAgents: z.array(z.string()).default([]).describe("Optional agent or sandbox ids expected to acknowledge the operator message."),
},
},
async ({ room, messageId, expectedAgents }) => {
const store = await readStore()
const roomId = cleanRoom(room)
const currentRoom = roomData(store, roomId)
const message = currentRoom.messages.find((entry) => entry.id === messageId) || null
const receipts = currentRoom.receipts[messageId] && typeof currentRoom.receipts[messageId] === "object"
? currentRoom.receipts[messageId]
: {}
const expected = Array.from(new Set((expectedAgents || []).map((entry) => cleanText(entry)).filter(Boolean)))
const pendingAgents = expected.filter((agent) => !receipts[agent])
return asText({
ok: true,
room: roomId,
messageId,
requiresAck: messageNeedsAck(message),
ackToken: message?.ackToken || null,
receiptCount: Object.keys(receipts).length,
receipts,
expectedAgents: expected,
pendingAgents,
acknowledged: expected.length > 0 ? pendingAgents.length === 0 : Object.keys(receipts).length > 0,
})
},
)
server.registerTool(
"list_operator_ack_status",
{
title: "List Operator Ack Status",
description: "List recent operator messages with acknowledgement status for dashboards. Sandbox-originated messages are intentionally excluded because they do not require acknowledgements.",
inputSchema: {
room: z.string().default("lobby").describe("Chat room name. Defaults to lobby."),
limit: z.number().int().min(1).max(100).default(50).describe("Maximum number of recent operator messages to inspect."),
expectedAgents: z.array(z.string()).default([]).describe("Optional agent or sandbox ids expected to acknowledge each operator message."),
},
},
async ({ room, limit, expectedAgents }) => {
const store = await readStore()
const roomId = cleanRoom(room)
const currentRoom = roomData(store, roomId)
const expected = Array.from(new Set((expectedAgents || []).map((entry) => cleanText(entry)).filter(Boolean)))
const operatorMessages = currentRoom.messages
.filter(messageNeedsAck)
.slice(-limit)
.map((message) => {
const receipts = currentRoom.receipts[message.id] && typeof currentRoom.receipts[message.id] === "object"
? currentRoom.receipts[message.id]
: {}
const pendingAgents = expected.filter((agent) => !receipts[agent])
return {
messageId: message.id,
ackToken: message.ackToken || null,
at: message.at,
sender: message.sender,
message: message.message,
receiptCount: Object.keys(receipts).length,
receipts,
pendingAgents,
acknowledged: expected.length > 0 ? pendingAgents.length === 0 : Object.keys(receipts).length > 0,
}
})
return asText({ ok: true, room: roomId, count: operatorMessages.length, expectedAgents: expected, operatorMessages })
},
)
server.registerTool(
"list_rooms",
{
title: "List Rooms",
description: "List inter-sandbox chat rooms that currently have messages.",
inputSchema: {
includeEmpty: z.boolean().default(false).describe("Reserved for compatibility; rooms are created when messages are posted."),
},
},
async () => {
return asText({ ok: true, rooms: await listRooms() })
},
)
const transport = new StdioServerTransport()
await server.connect(transport)