feat(dot): expand governed Runner capabilities and finish pairing setup

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ui/src/components/DotRunnerConnection.test.tsx

@@ -4,9 +4,11 @@ import { createRoot, type Root } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import { DotRunnerConnection } from "./DotRunnerConnection";
+import { copyTextToClipboard } from "@/lib/clipboard";
 
 const api = vi.hoisted(() => ({ get: vi.fn(), post: vi.fn(), delete: vi.fn() }));
 vi.mock("../api/client", () => ({ api }));
+vi.mock("@/lib/clipboard", () => ({ copyTextToClipboard: vi.fn() }));
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 const binding = { id: "binding", status: "connected", connected: true, subscriptionVerified: true, hasPendingChallenge: false };
 let root: Root;
@@ -90,3 +92,62 @@ it("shows event testing when a connected Dot subscribes without a manual refresh
     expect(container.textContent).toContain("Event subscription: verified");
   } finally { vi.useRealTimers(); }
 });
+
+
+it("copies the complete Dot setup with its server URL, one-use code and event instructions", async () => {
+  const expiresAt = new Date(Date.now() + 15 * 60_000).toISOString();
+  api.post.mockImplementation(async () => {
+    api.get.mockResolvedValue({ enabled: true, resourceUrl: "https://paperclip.example/mcp/runner", binding: { ...binding, status: "pairing", connected: false, subscriptionVerified: false } });
+    return { bindingId: binding.id, pairingCode: "fresh-one-use-pairing-code", expiresAt };
+  });
+  vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+  await render();
+  expect(container.querySelector('[aria-label="Set up with Dot"]')).toBeNull();
+  await act(async () => Array.from(container.querySelectorAll("button")).find(button => button.textContent === "Pair Dot")!.click());
+  await flush();
+  await act(async () => container.querySelector<HTMLButtonElement>('[aria-label="Set up with Dot"]')!.click());
+  expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
+  const prompt = vi.mocked(copyTextToClipboard).mock.calls[0][0];
+  expect(prompt).toContain("Add and enable a private MCP plugin");
+  expect(prompt).toContain("https://paperclip.example/mcp/runner");
+  expect(prompt).toContain('"Connect Dot with pairing code"');
+  expect(prompt).toContain("Paperclip company: company. Agent: agent.");
+  expect(prompt).toContain("One-use pairing code:\nfresh-one-use-pairing-code");
+  expect(prompt).toContain(expiresAt);
+  expect(prompt).toContain("paperclip.dot.mailbox_updated");
+  expect(prompt).toContain("paperclip_dot_inbox");
+  expect(prompt).toContain("paperclip_dot_confirm_event");
+  expect(prompt).toContain('"Test event delivery"');
+  expect(document.querySelector('[aria-label="Setup prompt"]')?.textContent).toBe(prompt);
+  expect(document.querySelector(".agent-setup-copy")?.textContent).toBe("Copied to clipboard");
+  expect(api.post).toHaveBeenCalledTimes(1);
+  // Returning to setup cannot recover the one-use code from cached config.
+  await act(async () => root.render(null));
+  await render();
+  expect(container.querySelector('[aria-label="Set up with Dot"]')).toBeNull();
+  expect(document.querySelector('[aria-label="Setup prompt"]')).toBeNull();
+  expect(container.textContent).toContain("generate a fresh setup prompt");
+  expect(container.textContent).not.toContain("fresh-one-use-pairing-code");
+});
+
+it("removes the copy action and open preview when the pairing code expires", async () => {
+  vi.useFakeTimers();
+  try {
+    api.post.mockImplementation(async () => {
+      api.get.mockResolvedValue({ enabled: true, resourceUrl: "https://paperclip.example/mcp/runner", binding: { ...binding, status: "pairing", connected: false, subscriptionVerified: false } });
+      return { bindingId: binding.id, pairingCode: "soon-expiring-pairing-code", expiresAt: new Date(Date.now() + 1000).toISOString() };
+    });
+    vi.mocked(copyTextToClipboard).mockResolvedValue(undefined);
+    await act(async () => root.render(<QueryClientProvider client={client}><Form /></QueryClientProvider>));
+    await act(async () => { await vi.advanceTimersByTimeAsync(20); });
+    await act(async () => Array.from(container.querySelectorAll("button")).find(button => button.textContent === "Pair Dot")!.click());
+    await act(async () => { await vi.advanceTimersByTimeAsync(20); });
+    await act(async () => container.querySelector<HTMLButtonElement>('[aria-label="Set up with Dot"]')!.click());
+    expect(document.querySelector('[aria-label="Setup prompt"]')?.textContent).toContain("soon-expiring-pairing-code");
+    await act(async () => { await vi.advanceTimersByTimeAsync(1000); });
+    expect(container.querySelector('[aria-label="Set up with Dot"]')).toBeNull();
+    expect(document.querySelector('[aria-label="Setup prompt"]')).toBeNull();
+    expect(container.textContent).toContain("generate a fresh setup prompt");
+    expect(copyTextToClipboard).toHaveBeenCalledTimes(1);
+  } finally { vi.useRealTimers(); }
+});

ui/src/components/DotRunnerConnection.tsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { api } from "../api/client";
 import { Button } from "./ui/button";
+import { AgentSetupPrompt } from "./AgentSetupPrompt";
 
 interface Connection {
   enabled: boolean;
@@ -34,6 +35,11 @@ export function DotRunnerConnection({ companyId, agentId, bindingId, onBinding }
       setPairing(null); onBinding("");
       await client.invalidateQueries({ queryKey: key });
     } });
+  useEffect(() => {
+    if (!pairing) return;
+    const timer = window.setTimeout(() => setPairing(null), Math.max(0, Date.parse(pairing.expiresAt) - Date.now()));
+    return () => window.clearTimeout(timer);
+  }, [pairing]);
   const existingBindingId = state.data?.binding?.id;
   useEffect(() => {
     if (existingBindingId && existingBindingId !== bindingId && !revoke.isPending) onBinding(existingBindingId);
@@ -41,19 +47,45 @@ export function DotRunnerConnection({ companyId, agentId, bindingId, onBinding }
   if (!agentId) return <p className="text-sm text-muted-foreground">Save the agent, then return here to pair your Dot.</p>;
   const error = state.error ?? pair.error ?? test.error ?? revoke.error;
   const b = state.data?.binding;
+  const setupPrompt = pairing && state.data?.resourceUrl ? `Add and enable a private MCP plugin named "Paperclip Dot" using this server URL:
+${state.data.resourceUrl}
+
+Use OAuth authentication with CIMD. Reuse a plugin for this exact URL if one is already installed. If the name is already used for another URL, choose an available name such as "Paperclip Dot Test Drive" and keep the other plugin unchanged. Complete its connection in your browser: enter the one-use pairing code below in Paperclip’s "Pairing code" field. Entering the code automatically shows a scope preview without consuming the code or granting access. Verify the displayed company and agent match the IDs below, then click "Connect Dot with pairing code" to grant access and consume the code. This authorizes only the agent selected in Paperclip; operator sign-in is unnecessary. Paperclip company: ${companyId}. Agent: ${agentId}.
+
+When you setup the plugin, I already understand that MCP servers have risk, so you check “I understand and want to continue,” and click “Create as a plugin.” I want you to create the plugin for me completely and I don't want to have to do anything.
+
+One-use pairing code:
+${pairing.pairingCode}
+
+Entering this code on the OAuth connection page completes agent pairing. Then use the connected plugin to call paperclip_dot_inbox with {"after":0} to verify access and obtain the binding ID. Do not call paperclip_dot_pair again: the code has already been consumed.
+
+This one-use code expires at ${pairing.expiresAt}. If it has expired, ask me for a fresh setup prompt.
+
+Subscribe through MCP Events to paperclip.dot.mailbox_updated using Paperclip company ${companyId} and the binding ID returned by the inbox. Complete callback verification and follow the returned eventInstructions.
+
+Whenever an event arrives, drain paperclip_dot_inbox after your last cursor. Confirm readiness_challenge items with paperclip_dot_confirm_event. Read and accept assignments, then work through their provided tool catalog and follow the returned completion instructions.
+
+When I ask you to do work while idle, first call paperclip_dot_capabilities. Use paperclip_dot_request_turn with my request and a stable UUID; you do not need an already assigned task. Read and accept the resulting assignment, then use its provided catalog. Use get_identity and list_people to discover people, and create_task with assigneeUserId to assign a task to a person. Read assigned skills and use assigned app tools when provided. Renew accepted assignments with paperclip_dot_renew before expiry. When follow_up items arrive, read get_task_history and incorporate the new comments at the next safe boundary. After a tool returns pending, check its receipt with the same request ID; never duplicate mutations.
+
+Once the event subscription is verified, tell me to click "Test event delivery" in Paperclip. Confirm that challenge when it arrives so the connection becomes ready.` : "";
   return <div className="space-y-3">
-    <p className="text-sm text-muted-foreground">Dot manages its model and external tools. Paperclip supplies task tools through a dedicated agent connection. Provider usage and cost are unavailable; stopping a Paperclip run revokes access without confirming an external stop.</p>
+    <p className="text-sm text-muted-foreground">Dot manages its model and external tools. Paperclip supplies task coordination, people, assigned skills, and connected app tools. Dot can start a task directly from its conversation. Enable workspace files and commands below for file work. Provider usage and cost are unavailable; stopping a Paperclip run revokes access without confirming an external stop.</p>
     {state.data && !state.data.enabled && <p className="text-sm text-muted-foreground">Enable OpenAI Dot, Paperclip Runner, and Assistant connections (MCP) in experimental settings.</p>}
     {state.data?.resourceUrl && <p className="text-sm break-all">Private plugin MCP URL: <code>{state.data.resourceUrl}</code></p>}
     {b && <p className="text-sm">Connection: {b.status}. Event subscription: {b.subscriptionVerified ? "verified" : "required"}.</p>}
     {b?.assignment && <p className="text-sm">Assignment: {b.assignment.status === "offered" ? "waiting for Dot to accept" : "accepted by Dot"}.</p>}
     {b?.assignment?.attentionRequired && <p className="text-sm text-destructive" role="alert">Dot has not reported useful activity for 15 minutes. Inspect the Dot before assigning replacement work; Paperclip cannot confirm its external stop.</p>}
-    {pairing && b?.status === "pairing" && <div className="space-y-2 rounded-md border border-border p-3">
-      <p className="text-sm">Connect the private plugin in your Dot and approve agent access. Ask it to call <code>paperclip_dot_pair</code> with this code, then subscribe to <code>paperclip.dot.mailbox_updated</code> for the returned binding.</p>
-      <code className="text-sm break-all">{pairing.pairingCode}</code>
-      <p className="text-xs text-muted-foreground">Expires {new Date(pairing.expiresAt).toLocaleTimeString()}.</p>
+    {pairing && setupPrompt && b?.status === "pairing" && <div className="space-y-2">
+      <AgentSetupPrompt
+        prompt={setupPrompt}
+        label="Set up with Dot"
+        title="Connect your Dot"
+        description="Paste into your Dot to connect this agent."
+        side="bottom"
+      />
+      <p className="text-xs text-muted-foreground">Setup prompt expires {new Date(pairing.expiresAt).toLocaleTimeString()}.</p>
     </div>}
-    {!pairing && b?.status === "pairing" && <p className="text-sm text-muted-foreground">This page no longer has the one-use code. Revoke the pending connection and pair again to generate a fresh code.</p>}
+    {!pairing && b?.status === "pairing" && <p className="text-sm text-muted-foreground">Revoke the pending connection and pair again to generate a fresh setup prompt.</p>}
     <div className="flex flex-wrap items-center gap-2">
       {!b && <Button type="button" variant="outline" disabled={!state.data?.enabled || !state.data?.resourceUrl || pair.isPending} onClick={() => pair.mutate()}>Pair Dot</Button>}
       {b?.subscriptionVerified && <Button type="button" variant="outline" disabled={test.isPending || b.hasPendingChallenge} onClick={() => test.mutate()}>Test event delivery</Button>}