relay-companion 0.1.0

package/src/mcp.js

@@ -0,0 +1,419 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { RelayClient } from "./client.js";
+
+export const TOOLS = [
+  {
+    name: "relay_task_create",
+    description:
+      "Create a Relay task so this agent can coordinate with other people's agents. Use this when the user asks you to do work that needs another person's approval, calendar, files, email, Slack context, or agent. You MUST provide a concise approvalSummary that can be shown to invited humans before they accept. Do not include private source material in the invitation unless the user explicitly asked to reveal it. The task will wait up to 60 minutes for invitees; if at least one accepts it starts with acceptors only, otherwise it cancels.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Short task title." },
+        objective: { type: "string", description: "The work the agents should coordinate to complete." },
+        approvalSummary: { type: "string", description: "One or two sentences shown to invited humans." },
+        invitees: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              email: { type: "string" },
+              name: { type: "string" },
+              contactId: { type: "string" },
+              relayUserId: { type: "string" },
+            },
+          },
+        },
+        requiredCapabilities: {
+          type: "array",
+          items: { type: "string" },
+          description: "Connector/tool capabilities likely needed, e.g. read_calendar, read_email.",
+        },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["title", "objective", "approvalSummary", "invitees", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_task_status",
+    description:
+      "Inspect a Relay task's current state, participants, pending approvals visible to this human, recent messages, scoped results, and latest events. Use this before sending follow-up messages or ending a task.",
+    inputSchema: {
+      type: "object",
+      properties: { taskId: { type: "string" } },
+      required: ["taskId"],
+    },
+  },
+  {
+    name: "relay_to_agent",
+    description:
+      "Request to send a task-scoped message to another human's agent. This NEVER delivers immediately in v1. Relay creates a ShareApproval for this human to review. The approval is bound to the exact recipients, body, attachments, provenance, destination, and payload hash. If you edit the payload you must call this tool again. Include shareSummary in one or two sentences explaining what information would be shared and with whom. Do not put private rationale in decline-handling logic; Relay declines are intentionally non-revealing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        recipientParticipantIds: { type: "array", items: { type: "string" } },
+        bodyMarkdown: { type: "string" },
+        shareSummary: { type: "string" },
+        attachments: { type: "array", items: { type: "object" } },
+        provenance: { type: "array", items: { type: "object" } },
+        senderAgentSessionId: { type: "string" },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "recipientParticipantIds", "bodyMarkdown", "shareSummary", "senderAgentSessionId", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_to_human",
+    description:
+      "Request to send a human-visible Relay message. If the recipient is another person, Relay creates a ShareApproval before delivery. Use this for ordinary human-facing updates, non-final notices, or non-blocking questions. Do not use this to publish final task-scoped completion results; the creator agent must use relay_end_task for those, and Relay publishes those scoped results without a separate human approval step. If this task-run agent needs to ask its OWN human a question and cannot continue until they answer, set humanResponse.mode to required_before_resume; do not use that mode for another person. Example distinction: 'ask Sven what time he is going tonight' is a normal relay_to_human to Sven; 'I need my human to choose which slot I may offer' is relay_to_human with humanResponse.mode = required_before_resume. The same privacy rule applies: every cross-person visible word, filename, and connector-derived fact needs approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        recipientParticipantIds: { type: "array", items: { type: "string" } },
+        recipientUserIds: { type: "array", items: { type: "string" } },
+        bodyMarkdown: { type: "string" },
+        shareSummary: { type: "string" },
+        attachments: { type: "array", items: { type: "object" } },
+        provenance: { type: "array", items: { type: "object" } },
+        senderAgentSessionId: { type: "string" },
+        humanResponse: {
+          type: "object",
+          description:
+            "Only set this when this agent is asking its own human a blocking task-run question. Relay will show it as an urgent relay with quick reply UI, then resume the specified agent session after the human answers.",
+          properties: {
+            mode: { type: "string", enum: ["required_before_resume"] },
+            question: { type: "string" },
+            replyFormat: { type: "string", enum: ["plain_text", "yes_no", "datetime", "choice"] },
+            choices: { type: "array", items: { type: "string" } },
+            urgency: { type: "string", enum: ["normal", "high"] },
+            resumeAgentSessionId: { type: "string" },
+            expiresAt: { type: "string" },
+          },
+          required: ["mode", "question"],
+        },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "bodyMarkdown", "senderAgentSessionId", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_answer_human_question",
+    description:
+      "Submit this human's answer to a blocking Relay question. Use this from the Codex/Claude session opened by a Relay pill question item or Relays row. This updates the original relay, wakes the waiting task agent session, and causes Relay to inject the answer back into that run. Do not use it for normal cross-person relays or outbound share approvals.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        messageId: { type: "string", description: "The relay_to_human task message that is waiting for an answer." },
+        answerMarkdown: { type: "string" },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "messageId", "answerMarkdown", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_file_prepare_upload",
+    description:
+      "Register a task attachment owned by this human and get a short-lived upload URL. Use this before attaching a local/generated file to relay_to_agent, relay_to_human, or relay_end_task output. The returned attachment object contains a Relay fileId; pass that attachment object unchanged when sending the message. Never include signed upload/download URLs in cross-person messages. Cross-person filenames, file metadata, and file contents are only revealed after the exact message/share approval succeeds. For cross-person sharing, provide sha256 so Relay can bind approval to the file checksum.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string", description: "Task the file is being prepared for." },
+        filename: { type: "string" },
+        contentType: { type: "string" },
+        sizeBytes: { type: "number" },
+        sha256: {
+          type: "string",
+          description: "Hex/base64 SHA-256 checksum of the bytes. Required before this file can cross a person boundary.",
+        },
+        metadataScanStatus: { type: "string", enum: ["pending", "clean", "warning", "blocked"] },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "filename", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_file_download",
+    description:
+      "Get an authorized short-lived download URL for a Relay file visible to this human/agent. Relay only mints the URL after checking file ownership or task visibility. Do not paste this signed URL into a message to another person; attach the Relay fileId through relay_to_agent or relay_to_human so approval and visibility rules can run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fileId: { type: "string" },
+      },
+      required: ["fileId"],
+    },
+  },
+  {
+    name: "relay_end_task",
+    description:
+      "End a Relay task as the creator's agent. You MUST include a creatorResult for the creator human and one participantResult for every accepted participant. Relay publishes these final scoped results without a separate human approval step, so you must get the audience boundaries right before calling this tool. Each participant result must be scoped to that participant only and must not disclose information learned privately from other participants unless that information was explicitly approved for that participant. If any accepted participant has no useful interaction, include a scoped no-interaction result for them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        creatorResult: {
+          type: "object",
+          properties: {
+            status: { type: "string", enum: ["success", "partial_success", "failed", "cancelled"] },
+            title: { type: "string" },
+            bodyMarkdown: { type: "string" },
+            sourceApprovalIds: { type: "array", items: { type: "string" } },
+            sourceResultIds: { type: "array", items: { type: "string" } },
+          },
+          required: ["status", "title", "bodyMarkdown"],
+        },
+        participantResults: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              participantId: { type: "string" },
+              status: { type: "string", enum: ["success", "partial_success", "failed", "cancelled"] },
+              title: { type: "string" },
+              bodyMarkdown: { type: "string" },
+              sourceApprovalIds: { type: "array", items: { type: "string" } },
+              sourceResultIds: { type: "array", items: { type: "string" } },
+            },
+            required: ["participantId", "status", "title", "bodyMarkdown"],
+          },
+        },
+        expectedVersion: { type: "number" },
+        senderAgentSessionId: { type: "string" },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "creatorResult", "participantResults", "senderAgentSessionId", "idempotencyKey"],
+    },
+  },
+  {
+    name: "share_results_with_human",
+    description:
+      "Participant-side helper: turn the scoped result context injected into this participant agent's conversation into a human-visible Relay result for this agent's own human. Only use the result context intended for this human. Do not include other participants' private summaries.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        bodyMarkdown: { type: "string" },
+        senderAgentSessionId: { type: "string" },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "bodyMarkdown", "senderAgentSessionId", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_connector_list_tools",
+    description:
+      "List provider tools available through Relay connectors. Relay only exposes tools allowed by the human's granted scopes and Relay policy. Direct Codex/Claude tools connected outside Relay are not listed here; use them natively if the host exposes them.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "relay_connector_request_approval",
+    description:
+      "Request human approval for one exact connector tool execution before calling a state-changing provider tool. Use this for calendar creates/updates/deletes and any other connector tool whose catalog policy/capability tags indicate write or approval_sensitive behavior. The approval is bound to this taskId, provider, toolName, arguments, provenance, destination, and payload hash. If you change the event time, attendees, title, body, file target, or any material argument, request a new approval. After the human approves, call relay_connector_call_tool once with the returned approval.id and the exact same provider/toolName/arguments/provenance. Do not use this for read-only availability/email/file lookups unless you are about to reveal the results to another person; cross-person disclosure still goes through relay_to_agent or relay_to_human.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        senderAgentSessionId: { type: "string" },
+        provider: { type: "string" },
+        toolName: { type: "string" },
+        arguments: { type: "object" },
+        provenance: { type: "array", items: { type: "object" } },
+        approvalSummary: {
+          type: "string",
+          description:
+            "One or two sentences for the human explaining the exact external action, visible fields, recipients/attendees if any, and why it is needed.",
+        },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["taskId", "provider", "toolName", "approvalSummary", "senderAgentSessionId", "idempotencyKey"],
+    },
+  },
+  {
+    name: "relay_connector_call_tool",
+    description:
+      "Execute a provider tool through Relay's server-side connector gateway. Tool outputs include provenance. Read-only tools may be called directly, including outside a Relay task so this host can use Relay-connected Gmail, calendar, Slack, and file tools. When calling from a Relay task run, include taskId and senderAgentSessionId. Calendar writes and other state-changing connector tools require approvalId from relay_connector_request_approval, and the call must exactly match the approved payload. You may use connector outputs for the task, but sharing connector-derived facts across people still requires relay_to_agent or relay_to_human approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "string" },
+        provider: { type: "string" },
+        toolName: { type: "string" },
+        arguments: { type: "object" },
+        provenance: { type: "array", items: { type: "object" } },
+        approvalId: { type: "string" },
+        senderAgentSessionId: { type: "string" },
+        idempotencyKey: { type: "string" },
+      },
+      required: ["provider", "toolName", "idempotencyKey"],
+    },
+  },
+];
+
+function text(obj) {
+  return { content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] };
+}
+
+export async function handleCall(client, name, args) {
+  switch (name) {
+    case "relay_task_create":
+      return text(
+        await client.createTask({
+          title: args.title,
+          objective: args.objective,
+          approvalSummary: args.approvalSummary,
+          invitees: args.invitees || [],
+          requiredCapabilities: args.requiredCapabilities || [],
+          source: { host: "relay-mcp" },
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "relay_task_status":
+      return text(await client.getTask(args.taskId));
+    case "relay_to_agent":
+      return text(
+        await client.createTaskMessage(args.taskId, {
+          kind: "relay_to_agent",
+          bodyMarkdown: args.bodyMarkdown,
+          recipientParticipantIds: args.recipientParticipantIds || [],
+          shareSummary: args.shareSummary,
+          destinationKind: "agent",
+          attachments: args.attachments || [],
+          provenance: args.provenance || [],
+          senderAgentSessionId: args.senderAgentSessionId,
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "relay_to_human":
+      {
+        const result = await client.createTaskMessage(args.taskId, {
+          kind: "relay_to_human",
+          bodyMarkdown: args.bodyMarkdown,
+          recipientParticipantIds: args.recipientParticipantIds || [],
+          recipientUserIds: args.recipientUserIds || [],
+          shareSummary: args.shareSummary,
+          destinationKind: "human",
+          attachments: args.attachments || [],
+          provenance: args.provenance || [],
+          humanResponse: args.humanResponse,
+          senderAgentSessionId: args.senderAgentSessionId,
+          idempotencyKey: args.idempotencyKey,
+        });
+        if (args.humanResponse?.mode === "required_before_resume") {
+          return text({
+            ...result,
+            instruction:
+              "The question has been delivered to your human as a Relay. Stop task work now and wait for Relay to resume this task session with the human's answer.",
+          });
+        }
+        return text(result);
+      }
+    case "relay_answer_human_question":
+      return text(
+        await client.answerHumanQuestion(args.taskId, args.messageId, {
+          answerMarkdown: args.answerMarkdown,
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "relay_file_prepare_upload":
+      return text(
+        await client.createFileUpload({
+          taskId: args.taskId,
+          filename: args.filename,
+          contentType: args.contentType || "application/octet-stream",
+          sizeBytes: args.sizeBytes || 0,
+          sha256: args.sha256,
+          metadataScanStatus: args.metadataScanStatus || "pending",
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "relay_file_download":
+      return text(await client.fileDownload(args.fileId));
+    case "relay_end_task":
+      return text(
+        await client.completeTask(args.taskId, {
+          creatorResult: args.creatorResult,
+          participantResults: args.participantResults || [],
+          senderAgentSessionId: args.senderAgentSessionId,
+          expectedVersion: args.expectedVersion,
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "share_results_with_human":
+      return text(
+        await client.createTaskMessage(args.taskId, {
+          kind: "relay_to_human",
+          bodyMarkdown: args.bodyMarkdown,
+          recipientParticipantIds: [],
+          recipientUserIds: [],
+          visibilityScope: [],
+          shareSummary: "Share this task result with my own human.",
+          destinationKind: "human",
+          senderAgentSessionId: args.senderAgentSessionId,
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "relay_connector_list_tools":
+      return text(await client.toolCatalog());
+    case "relay_connector_request_approval":
+      return text(
+        await client.requestToolApproval({
+          taskId: args.taskId,
+          senderAgentSessionId: args.senderAgentSessionId,
+          provider: args.provider,
+          toolName: args.toolName,
+          arguments: args.arguments || {},
+          provenance: args.provenance || [],
+          approvalSummary: args.approvalSummary,
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    case "relay_connector_call_tool":
+      return text(
+        await client.callTool({
+          taskId: args.taskId,
+          provider: args.provider,
+          toolName: args.toolName,
+          arguments: args.arguments || {},
+          provenance: args.provenance || [],
+          approvalId: args.approvalId,
+          senderAgentSessionId: args.senderAgentSessionId,
+          idempotencyKey: args.idempotencyKey,
+        }),
+      );
+    default:
+      return text({ error: `Unknown tool ${name}` });
+  }
+}
+
+export async function runMcpServer() {
+  const client = new RelayClient();
+  const server = new Server(
+    { name: "relay-companion", version: "0.2.0-agent-protocol" },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    try {
+      return await handleCall(client, req.params.name, req.params.arguments || {});
+    } catch (err) {
+      return { content: [{ type: "text", text: `Relay error: ${err.message}` }], isError: true };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runMcpServer().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err);
+    process.exit(1);
+  });
+}