@haywoodmarx/agent-pager 0.1.0

package/dist/src/messaging/mcp.js

@@ -0,0 +1,501 @@
+import { createServer } from "node:http";
+import { isAbsolute } from "node:path";
+import { LOOPBACK_HOST } from "../configuration-defaults.js";
+import { closeServer, listenServer, urlHost, writeJson } from "../shared/http.js";
+import { isPlainObject } from "../shared/guards.js";
+import { assertProtocolVersion, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_MAX, normalizeMessageSubject, normalizeMessageType, ATTACH_HEADER, ProtocolError, validateImplementationId, validateSessionKey, } from "../broker/protocol.js";
+import { MCP_TOOLS } from "./tools.js";
+import { PAGER_VERSION } from "../version.js";
+/**
+ * Names the MCP revision echoed to a client that requested none.
+ *
+ * The value is the specification revision, not a package version; it changes only when this server
+ * is verified against a newer one.
+ */
+const DEFAULT_MCP_PROTOCOL_VERSION = "2025-03-26";
+/** JSON-RPC error code for a failure this server reports. */
+const JSON_RPC_SERVER_ERROR = -32000;
+/** JSON-RPC error code for a method this server does not implement. */
+const JSON_RPC_METHOD_NOT_FOUND = -32601;
+/** Reports a failure the handler did not anticipate, as opposed to a declared protocol rejection. */
+const INTERNAL_ERROR_CODE = "internal_error";
+/**
+ * Message exposed to a caller for an unanticipated failure.
+ *
+ * Never the caught error's own message: that may carry detail about broker internals a remote caller
+ * has no standing to see, unlike a `ProtocolError`'s message, which is written to be safe to expose.
+ */
+const INTERNAL_ERROR_MESSAGE = "Internal error";
+/** Names the request header an attached session presents its host delivery address in. */
+export const DELIVERY_ADDRESS_HEADER = "x-pager-delivery-address";
+/**
+ * Start a JSON Streamable-HTTP-compatible MCP foundation server on the host it is given, loopback by default.
+ * The server authenticates no caller, so the caller owns the choice of a non-loopback host.
+ * @param options - Broker, network binding, and optional launch-internal observers.
+ * @returns - Handle carrying the bound endpoint URL and the operation that stops the server.
+ */
+export async function startMcpServer(options) {
+    const { broker, port = 0, notifications, host = LOOPBACK_HOST, healthIdentity, diagnostics } = options;
+    const context = {
+        broker,
+        notifications,
+        endpoint: "",
+        ...(healthIdentity ? { healthIdentity } : {}),
+        ...(diagnostics ? { diagnostics } : {}),
+    };
+    const server = createServer((request, response) => {
+        void handleRequest(context, request, response);
+    });
+    await listenServer(server, port, host);
+    const address = server.address();
+    context.endpoint = `http://${urlHost(address.address)}:${String(address.port)}/mcp`;
+    return {
+        url: context.endpoint,
+        close: () => closeServer(server),
+    };
+}
+async function handleRequest(context, request, response) {
+    const { broker } = context;
+    try {
+        if (request.method === "GET" && request.url === "/health") {
+            writeJson(response, 200, { ok: true, status: "ready", ...context.healthIdentity });
+            return;
+        }
+        if (request.method === "DELETE") {
+            // Connectors end their attachments with the `detach` tool; no client may end a session this way.
+            writeJson(response, 405, {
+                ok: false,
+                error: { code: "validation_failed", message: "Session termination over DELETE is not supported" },
+            }, { allow: "POST" });
+            return;
+        }
+        if (request.method !== "POST")
+            throw new ProtocolError("validation_failed", "POST required");
+        const body = parseRequestBody(await readBody(request));
+        if (isMcpRequest(body)) {
+            try {
+                handleMcpRequest(context, request, response, body);
+            }
+            catch (error) {
+                if (error instanceof ProtocolError) {
+                    writeMcpError(response, body.id, JSON_RPC_SERVER_ERROR, error.message, 200, {}, { code: error.code });
+                }
+                else {
+                    writeMcpError(response, body.id, JSON_RPC_SERVER_ERROR, INTERNAL_ERROR_MESSAGE, 500);
+                }
+            }
+            return;
+        }
+        assertProtocolVersion(body.version);
+        const call = readToolCall(body);
+        // The pre-attach tools carry no session and no identity.
+        const attached = call.tool === "attach" || call.tool === "register_agent" ? undefined : authenticate(broker, request);
+        // A detaching connector is leaving, so its push address is not taken up again.
+        if (attached && call.tool !== "detach")
+            registerDeliveryAddress(context, request, attached.agentId);
+        const result = attached
+            ? callTool(context, attached, call.tool, call.args, "connector")
+            : call.tool === "attach"
+                ? broker.attach(String(request.headers[ATTACH_HEADER] ?? ""), attachSessionKey(request))
+                : registerAgent(context, call.args);
+        const headers = call.tool === "attach" && typeof result === "object" && result && "sessionId" in result && "epoch" in result
+            ? {
+                "mcp-session-id": String(result.sessionId),
+                "x-pager-epoch": String(result.epoch),
+                // The attach reservation is single-use, so this token is the client's only way back after a
+                // restart fences the session it just opened.
+                ...("fencingToken" in result ? { "x-pager-resume-token": String(result.fencingToken) } : {}),
+                ...("agentId" in result ? { "x-pager-agent-id": String(result.agentId) } : {}),
+            }
+            : refreshedSessionHeaders(attached);
+        writeJson(response, 200, { ok: true, result }, headers);
+    }
+    catch (error) {
+        if (error instanceof ProtocolError) {
+            writeJson(response, error.code === "validation_failed" ? 400 : 409, {
+                ok: false,
+                error: { code: error.code, message: error.message },
+            });
+        }
+        else {
+            writeJson(response, 500, { ok: false, error: { code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE } });
+        }
+    }
+}
+/**
+ * Parse a request body as JSON, refusing malformed input as a client protocol error.
+ *
+ * Kept distinct from the broker-internal failures this module answers with 500: invalid JSON, and a
+ * parse result that is not a plain object (`null`, an array, a primitive), are always the caller's
+ * fault, whatever runs after this point.
+ * @param raw - Untrusted request body text.
+ * @returns - Decoded body, shaped by the caller's own checks.
+ */
+function parseRequestBody(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ProtocolError("validation_failed", "Request body is not valid JSON");
+    }
+    if (!isPlainObject(parsed))
+        throw new ProtocolError("validation_failed", "Request body must be a JSON object");
+    return parsed;
+}
+/**
+ * Narrow a decoded request body to the tool call it claims to be.
+ * @param body - Decoded request body, fields untrusted.
+ * @returns - Tool name and arguments record.
+ */
+function readToolCall(body) {
+    const { tool, arguments: args } = body;
+    if (typeof tool !== "string" || tool.length === 0) {
+        throw new ProtocolError("validation_failed", "Request tool is required");
+    }
+    if (args !== undefined && !isPlainObject(args)) {
+        throw new ProtocolError("validation_failed", "Request arguments must be a JSON object");
+    }
+    return { tool, args: args ?? {} };
+}
+/**
+ * Announce a session generation the caller does not yet hold.
+ * @param attached - Authenticated session, carrying `refreshed` when this request resumed it in place,
+ * or nothing for a pre-attach call that holds no session to rotate.
+ * @returns - Rotated session headers, or an empty set when the caller's generation is still current.
+ */
+function refreshedSessionHeaders(attached) {
+    if (!attached?.refreshed)
+        return {};
+    return {
+        "mcp-session-id": attached.sessionId,
+        "x-pager-epoch": attached.epoch,
+        "x-pager-resume-token": attached.refreshed.fencingToken,
+    };
+}
+function authenticate(broker, request) {
+    const sessionId = String(request.headers["mcp-session-id"] ?? "");
+    const epoch = String(request.headers["x-pager-epoch"] ?? "");
+    const resumeToken = String(request.headers["x-pager-resume-token"] ?? "");
+    if (sessionId === "") {
+        throw new ProtocolError("validation_failed", "Request carries no mcp-session-id header; attach with a reservation first");
+    }
+    try {
+        return { agentId: broker.resolveSession(sessionId, epoch || undefined), sessionId, epoch };
+    }
+    catch (error) {
+        // A restarted service fences every session it did not issue. The caller already holds the proof
+        // needed to re-establish one, and its attach reservation was single-use, so refusing here would
+        // strand an attached agent for the rest of its run with no way back.
+        if (!(error instanceof ProtocolError) || error.code !== "expired" || !resumeToken)
+            throw error;
+        const resumed = broker.resumeSession({ sessionId: sessionId, fencingToken: resumeToken, epoch: epoch || undefined });
+        return {
+            agentId: resumed.agentId,
+            sessionId: resumed.sessionId,
+            epoch: resumed.epoch,
+            refreshed: { fencingToken: resumed.fencingToken },
+        };
+    }
+}
+function callTool(context, attached, tool, args, surface) {
+    if (!context.diagnostics)
+        return runTool(context, attached, tool, args, surface);
+    try {
+        const output = runTool(context, attached, tool, args, surface);
+        context.diagnostics.onToolCall({ agentId: attached.agentId, tool: tool ?? "", args, outcome: { ok: true, output } });
+        return output;
+    }
+    catch (error) {
+        const failure = error instanceof ProtocolError
+            ? { code: error.code, message: error.message }
+            : { code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE };
+        context.diagnostics.onToolCall({
+            agentId: attached.agentId,
+            tool: tool ?? "",
+            args,
+            outcome: { ok: false, error: failure },
+        });
+        throw error;
+    }
+}
+function runTool(context, attached, tool, args, surface) {
+    const { broker, notifications } = context;
+    // The model-facing path reaches only the advertised tools; the connector-only ones below can end or
+    // move the caller's own identity, which a model must not be able to do to its harness.
+    if (surface === "model" && !MCP_TOOLS.some((listed) => listed.name === tool)) {
+        throw new ProtocolError("validation_failed", "Unknown tool");
+    }
+    switch (tool) {
+        case "whoami":
+            return broker.agentIdentity(attached.agentId);
+        case "update_agent_alias":
+            if (typeof args.alias !== "string")
+                throw new ProtocolError("validation_failed", "Agent alias is required");
+            return broker.updateAgentAlias(attached.agentId, args.alias);
+        case "adopt_session_key": {
+            return broker.adoptSessionKey(attached.agentId, validateSessionKey(args.sessionKey));
+        }
+        case "list_team_members":
+            return { members: broker.listTeamMembers(attached.agentId) };
+        case "list_agents":
+            return { agents: broker.listAgents() };
+        case "send_agent_message": {
+            const sent = broker.send({
+                from: attached.agentId,
+                to: String(args.to),
+                subject: normalizeMessageSubject(args.subject),
+                body: args.body,
+                type: normalizeMessageType(args.type),
+                ...(typeof args.idempotencyKey === "string" ? { idempotencyKey: args.idempotencyKey } : {}),
+            });
+            notifications?.notifyMessage(sent.messageId, sent.to);
+            return sent;
+        }
+        case "broadcast_agent_message": {
+            const broadcast = broker.broadcast({
+                from: attached.agentId,
+                ...(args.workspace === undefined ? {} : { workspace: broadcastWorkspace(args.workspace) }),
+                subject: normalizeMessageSubject(args.subject),
+                body: args.body,
+                type: normalizeMessageType(args.type),
+                ...(typeof args.idempotencyKey === "string" ? { idempotencyKey: args.idempotencyKey } : {}),
+            });
+            for (const sent of broadcast.sent)
+                notifications?.notifyMessage(sent.messageId, sent.to);
+            return broadcast;
+        }
+        case "fetch_agent_messages":
+            return { messages: broker.fetch({ agentId: attached.agentId, limit: fetchLimit(args.limit) }) };
+        case "ack_agent_messages":
+            return broker.ack(attached.agentId, ackClaimTokens(args.claimTokens));
+        case "get_message_status":
+            return broker.status(String(args.messageId), attached.agentId);
+        case "detach":
+            broker.releaseAttachments(attached.agentId);
+            notifications?.forgetDeliveryAddress?.(attached.agentId);
+            return { detached: true };
+        case undefined:
+            throw new ProtocolError("validation_failed", "Unknown tool");
+        default:
+            throw new ProtocolError("validation_failed", "Unknown tool");
+    }
+}
+/**
+ * Report whether a decoded body claims to be a JSON-RPC request.
+ *
+ * Recognises `jsonrpc` and `method` only.
+ * @param value - Decoded request body.
+ * @returns - Whether the body claims to be a JSON-RPC request.
+ */
+function isMcpRequest(value) {
+    return isPlainObject(value) && value.jsonrpc === "2.0" && typeof value.method === "string";
+}
+/**
+ * Read one named member of a request's parameters.
+ * @param params - Parameters as supplied, of any JSON-RPC shape.
+ * @param name - Member to read.
+ * @returns - The member's value, or nothing when the parameters are positional or absent.
+ */
+function namedParameter(params, name) {
+    return isPlainObject(params) ? params[name] : undefined;
+}
+function handleMcpRequest(context, request, response, rpc) {
+    const { broker } = context;
+    if (rpc.method === "initialize") {
+        const declared = namedParameter(rpc.params, "protocolVersion");
+        const existingSessionId = String(request.headers["mcp-session-id"] ?? "");
+        const attached = existingSessionId
+            ? broker.resumeSession({
+                sessionId: existingSessionId,
+                fencingToken: String(request.headers["x-pager-resume-token"] ?? "") || undefined,
+                epoch: String(request.headers["x-pager-epoch"] ?? "") || undefined,
+            })
+            : broker.attach(String(request.headers[ATTACH_HEADER] ?? ""), attachSessionKey(request));
+        const headers = {
+            "mcp-session-id": attached.sessionId,
+            "x-pager-epoch": attached.epoch,
+            "x-pager-resume-token": attached.fencingToken,
+            "x-pager-agent-id": attached.agentId,
+            "x-pager-lease-ttl-ms": String(broker.sessionLeaseTtlMs()),
+        };
+        // The session above is already established by the time this can throw, so an internal failure here
+        // must still carry its headers — otherwise a client that just attached or transparently resumed is
+        // left presenting credentials the server has already superseded.
+        try {
+            registerDeliveryAddress(context, request, attached.agentId);
+        }
+        catch (error) {
+            if (error instanceof ProtocolError) {
+                writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, error.message, 200, headers, { code: error.code });
+            }
+            else {
+                writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, INTERNAL_ERROR_MESSAGE, 500, headers);
+            }
+            return;
+        }
+        writeMcpResult(response, rpc.id, {
+            protocolVersion: typeof declared === "string" ? declared : DEFAULT_MCP_PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: "pager", version: PAGER_VERSION },
+        }, headers);
+        return;
+    }
+    if (rpc.method === "notifications/initialized") {
+        // Authenticating this notification can itself transparently resume the session, so the 202 has to
+        // carry the new generation. Dropping it leaves the client acknowledging initialization with
+        // credentials the server superseded on this very request.
+        response.writeHead(202, refreshedSessionHeaders(authenticate(broker, request)));
+        response.end();
+        return;
+    }
+    const attached = authenticate(broker, request);
+    // A transparent resume issues a new generation the client is still unaware of; every later response
+    // must carry it. Computed before registerDeliveryAddress for the same reason as initialize's headers
+    // above: a throw there must still answer with it.
+    const refreshed = refreshedSessionHeaders(attached);
+    try {
+        registerDeliveryAddress(context, request, attached.agentId);
+    }
+    catch (error) {
+        if (error instanceof ProtocolError) {
+            writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, error.message, 200, refreshed, { code: error.code });
+        }
+        else {
+            writeMcpError(response, rpc.id, JSON_RPC_SERVER_ERROR, INTERNAL_ERROR_MESSAGE, 500, refreshed);
+        }
+        return;
+    }
+    if (rpc.method === "tools/list") {
+        writeMcpResult(response, rpc.id, { tools: mcpTools() }, refreshed);
+        return;
+    }
+    if (rpc.method === "tools/call") {
+        const named = namedParameter(rpc.params, "name");
+        const name = typeof named === "string" ? named : undefined;
+        const supplied = namedParameter(rpc.params, "arguments");
+        const args = isPlainObject(supplied) ? supplied : {};
+        try {
+            const result = callTool(context, attached, name, args, "model");
+            writeMcpResult(response, rpc.id, { content: [{ type: "text", text: JSON.stringify(result) }] }, refreshed);
+        }
+        catch (error) {
+            const failure = error instanceof ProtocolError
+                ? { code: error.code, message: error.message }
+                : { code: INTERNAL_ERROR_CODE, message: INTERNAL_ERROR_MESSAGE };
+            writeMcpResult(response, rpc.id, { content: [{ type: "text", text: JSON.stringify(failure) }], isError: true }, refreshed);
+        }
+        return;
+    }
+    writeMcpError(response, rpc.id, JSON_RPC_METHOD_NOT_FOUND, "Method not found");
+}
+function mcpTools() {
+    return MCP_TOOLS.map((tool) => ({ ...tool }));
+}
+/**
+ * Hand a presented delivery address to the notification port, on every authenticated request.
+ *
+ * Presented on every request rather than once, so a service that restarted and transparently resumed
+ * the session learns the address again without the session having to notice.
+ * @param context - Server context carrying the optional notification port.
+ * @param request - Authenticated request that may carry the address header.
+ * @param agentId - Recipient the request authenticated as.
+ */
+function registerDeliveryAddress(context, request, agentId) {
+    const raw = request.headers[DELIVERY_ADDRESS_HEADER];
+    if (typeof raw !== "string" || raw.length === 0)
+        return;
+    context.notifications?.registerDeliveryAddress?.(agentId, raw);
+}
+function attachSessionKey(request) {
+    const sessionKey = String(request.headers["x-pager-session-key"] ?? "");
+    return sessionKey ? { sessionKey } : {};
+}
+function registerAgent(context, args) {
+    const { broker, notifications } = context;
+    const workspacePath = args.workspacePath;
+    const implementationId = args.implementationId;
+    const sessionName = args.sessionName;
+    const sessionKey = args.sessionKey;
+    const continuesSessionKey = args.continuesSessionKey;
+    if (typeof workspacePath !== "string" || !isAbsolute(workspacePath)) {
+        throw new ProtocolError("validation_failed", "registration workspacePath must be absolute");
+    }
+    const implementation = validateImplementationId(implementationId);
+    // The broker owns the session-name contract; this boundary checks only the type.
+    if (sessionName !== undefined && typeof sessionName !== "string") {
+        throw new ProtocolError("validation_failed", "registration sessionName is invalid");
+    }
+    if (sessionKey !== undefined)
+        validateSessionKey(sessionKey);
+    if (continuesSessionKey !== undefined)
+        validateSessionKey(continuesSessionKey);
+    const registered = broker.registerAgentWithoutReservation({
+        workspacePath,
+        implementation: { id: implementation },
+        ...(typeof sessionName === "string" ? { sessionName } : {}),
+        ...(typeof sessionKey === "string" ? { sessionKey } : {}),
+        ...(typeof continuesSessionKey === "string" ? { continuesSessionKey } : {}),
+    });
+    if (registered.resumed)
+        notifications?.forgetDeliveryAddress?.(registered.agentId);
+    return {
+        ...registered,
+        deliveryReservation: broker.reserveAttachment(registered.agentId, "delivery"),
+    };
+}
+/**
+ * Validate the claim batch size a caller asked for.
+ *
+ * A value outside the supported range is rejected, never replaced by the default.
+ * @param value - Caller-supplied limit, absent for the default.
+ * @returns - Positive integer batch size within the supported range.
+ */
+function fetchLimit(value) {
+    if (value === undefined)
+        return FETCH_LIMIT_DEFAULT;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > FETCH_LIMIT_MAX) {
+        throw new ProtocolError("validation_failed", `fetch limit must be an integer between 1 and ${String(FETCH_LIMIT_MAX)}`);
+    }
+    return value;
+}
+function broadcastWorkspace(value) {
+    if (typeof value !== "string")
+        throw new ProtocolError("validation_failed", "Broadcast workspace must be a string");
+    return value;
+}
+/**
+ * Validate the acknowledgement batch a caller supplied.
+ * @param value - Caller-supplied claim tokens.
+ * @returns - Claim tokens, each authorising one acknowledgement.
+ */
+function ackClaimTokens(value) {
+    if (!Array.isArray(value))
+        throw new ProtocolError("validation_failed", "ack claimTokens must be an array");
+    return value.map((entry) => {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new ProtocolError("validation_failed", "each ack entry must be a claim token");
+        }
+        return entry;
+    });
+}
+function writeMcpResult(response, id, result, headers = {}) {
+    writeJson(response, 200, { jsonrpc: "2.0", id: correlationId(id), result }, headers);
+}
+function writeMcpError(response, id, code, message, status = 200, headers = {}, data) {
+    writeJson(response, status, { jsonrpc: "2.0", id: correlationId(id), error: { code, message, ...(data ? { data } : {}) } }, headers);
+}
+/**
+ * Narrow a request's correlation id where it is written back.
+ * @param id - The `id` member as the caller sent it.
+ * @returns - The id to echo, or null when the caller's own cannot be one.
+ */
+function correlationId(id) {
+    return typeof id === "string" || typeof id === "number" ? id : null;
+}
+async function readBody(request) {
+    const chunks = [];
+    for await (const chunk of request)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString("utf8");
+}