diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index f41465e2..341f3b11 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -554,10 +554,12 @@ pnpm paperclipai dashboard get See full command reference in `doc/CLI.md`. -## OpenClaw Invite Onboarding Endpoints +## Agent Invite Onboarding Endpoints Agent-oriented invite onboarding now exposes machine-readable API docs: +The board UI generates agent onboarding prompts from the add-agent modal (`+` in the agent sidebar), so agent onboarding sits with the rest of agent creation rather than company member invite settings. + - `GET /api/invites/:token` returns invite summary plus onboarding and skills index links. - `GET /api/invites/:token/onboarding` returns onboarding manifest details (registration endpoint, claim endpoint template, skill install hints). - `GET /api/invites/:token/onboarding.txt` returns a plain-text onboarding doc intended for both human operators and agents (llm.txt-style handoff), including optional inviter message and suggested network host candidates. @@ -575,7 +577,7 @@ pnpm smoke:openclaw-join What it validates: - invite creation for agent-only join -- agent join request using `adapterType=openclaw` +- agent join request using `adapterType=openclaw_gateway` - board approval + one-time API key claim semantics - callback delivery on wakeup to a dockerized OpenClaw-style webhook receiver diff --git a/doc/spec/invite-flow.md b/doc/spec/invite-flow.md index 504744b0..fad3c56e 100644 --- a/doc/spec/invite-flow.md +++ b/doc/spec/invite-flow.md @@ -6,7 +6,7 @@ Date: 2026-04-13 This document maps the current invite creation and acceptance states implemented in: - `ui/src/pages/CompanyInvites.tsx` -- `ui/src/pages/CompanySettings.tsx` +- `ui/src/components/NewAgentDialog.tsx` - `ui/src/pages/InviteLanding.tsx` - `server/src/routes/access.ts` - `server/src/lib/join-request-dedupe.ts` @@ -23,9 +23,9 @@ This document maps the current invite creation and acceptance states implemented ```mermaid flowchart TD - Board[Board user on invite screen] + Board[Board user on invite or add-agent screen] HumanInvite[Create human company invite] - OpenClawInvite[Generate OpenClaw invite prompt] + AgentInvite[Generate agent onboarding prompt] Active[Invite state: active] Revoked[Invite state: revoked] Expired[Invite state: expired] @@ -44,7 +44,7 @@ flowchart TD OpenClawReplay[Special replay path:
accepted invite can be POSTed again
for openclaw_gateway only] Board --> HumanInvite --> Active - Board --> OpenClawInvite --> Active + Board --> AgentInvite --> Active Active --> Revoked: revoke Active --> Expired: expiresAt passes @@ -102,10 +102,10 @@ stateDiagram-v2 LatestInviteVisible --> Ready: navigate away or refresh } - CompanySelection --> OpenClawPromptReady: Company settings prompt generator - OpenClawPromptReady --> OpenClawPromptPending: Generate OpenClaw Invite Prompt - OpenClawPromptPending --> OpenClawSnippetVisible: prompt generated - OpenClawPromptPending --> OpenClawPromptReady: generation failed + CompanySelection --> AgentPromptReady: Add-agent modal prompt generator + AgentPromptReady --> AgentPromptPending: Generate agent onboarding prompt + AgentPromptPending --> AgentSnippetVisible: prompt generated + AgentPromptPending --> AgentPromptReady: generation failed ``` ## Invite Landing Screen States @@ -247,21 +247,21 @@ sequenceDiagram sequenceDiagram autonumber actor Board as Board user - participant Settings as Company Settings UI + participant AddAgent as Add agent modal participant API as Access routes participant Invites as invites table - actor Gateway as OpenClaw gateway agent + actor Gateway as External agent participant Join as join_requests table actor Approver as Company admin participant Agents as agents table participant Keys as agent_api_keys table - Board->>Settings: Generate OpenClaw invite prompt - Settings->>API: POST /api/companies/:companyId/openclaw-invite-prompt + Board->>AddAgent: Generate agent onboarding prompt + AddAgent->>API: POST /api/companies/:companyId/invites (allowedJoinTypes=agent) API->>Invites: Insert active agent invite - API-->>Settings: Prompt text + invite token + API-->>AddAgent: Prompt text + invite token - Gateway->>API: POST /api/invites/:token/accept (agent, openclaw_gateway) + Gateway->>API: POST /api/invites/:token/accept (agent, adapter-specific payload) API->>Invites: Mark invite accepted API->>Join: Insert pending_approval join request + claimSecretHash API-->>Gateway: requestId + claimSecret + claimApiKeyPath diff --git a/server/src/__tests__/access-routes-permissions-upgrade.test.ts b/server/src/__tests__/access-routes-permissions-upgrade.test.ts index 9db328d4..b7180581 100644 --- a/server/src/__tests__/access-routes-permissions-upgrade.test.ts +++ b/server/src/__tests__/access-routes-permissions-upgrade.test.ts @@ -115,7 +115,7 @@ describeEmbeddedPostgres("access routes permissions upgrade compatibility", () = .where(eq(companyMemberships.id, owner.id)) .then((rows) => rows[0]!); expect(unchanged.membershipRole).toBe("owner"); - }); + }, 10_000); it("keeps custom grants when the role-only member route changes a member role", async () => { const { company, owner } = await createCompanyWithOwner(db); diff --git a/server/src/__tests__/heartbeat-comment-wake-batching.test.ts b/server/src/__tests__/heartbeat-comment-wake-batching.test.ts index 6cda7fb1..606f69bc 100644 --- a/server/src/__tests__/heartbeat-comment-wake-batching.test.ts +++ b/server/src/__tests__/heartbeat-comment-wake-batching.test.ts @@ -766,13 +766,19 @@ describe("heartbeat comment wake batching", () => { gateway.releaseFirstWait(); - await waitFor(() => gateway.getAgentPayloads().length === 2, 90_000); + await waitFor(() => gateway.getAgentPayloads().length >= 2, 90_000); await waitFor(async () => { const runs = await db .select() .from(heartbeatRuns) - .where(eq(heartbeatRuns.agentId, agentId)); - return runs.length === 2 && runs.every((run) => run.status === "succeeded"); + .where(eq(heartbeatRuns.agentId, agentId)) + .orderBy(asc(heartbeatRuns.createdAt)); + const [initialRun, promotedRun] = runs; + return ( + initialRun?.id === firstRun?.id && + initialRun.status === "succeeded" && + promotedRun?.status === "succeeded" + ); }, 90_000); const reopenedIssue = await db diff --git a/server/src/__tests__/heartbeat-dependency-scheduling.test.ts b/server/src/__tests__/heartbeat-dependency-scheduling.test.ts index f2560bcd..62b488dd 100644 --- a/server/src/__tests__/heartbeat-dependency-scheduling.test.ts +++ b/server/src/__tests__/heartbeat-dependency-scheduling.test.ts @@ -533,7 +533,7 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () = .where(eq(heartbeatRuns.id, secondWake!.id)) .then((rows) => rows[0] ?? null); return run?.status === "succeeded"; - }); + }, 10_000); expect(secondRunSucceeded).toBe(true); expect(mockAdapterExecute.mock.calls.length).toBeGreaterThanOrEqual(2); } finally { diff --git a/server/src/__tests__/heartbeat-local-environment.test.ts b/server/src/__tests__/heartbeat-local-environment.test.ts index 673297a1..145a6b6b 100644 --- a/server/src/__tests__/heartbeat-local-environment.test.ts +++ b/server/src/__tests__/heartbeat-local-environment.test.ts @@ -1,18 +1,12 @@ import { randomUUID } from "node:crypto"; -import { and, eq } from "drizzle-orm"; +import { and, eq, sql } from "drizzle-orm"; import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"; import { agents, - agentRuntimeState, - agentWakeupRequests, - activityLog, companies, - companySkills, createDb, environmentLeases, environments, - heartbeatRunEvents, - heartbeatRuns, } from "@paperclipai/db"; import { getEmbeddedPostgresTestSupport, @@ -73,16 +67,20 @@ describeEmbeddedPostgres("heartbeat local environment lifecycle", () => { }, 20_000); afterEach(async () => { - await db.delete(environmentLeases); - await db.delete(environments); - await db.delete(activityLog); - await db.delete(heartbeatRunEvents); - await db.delete(heartbeatRuns); - await db.delete(agentWakeupRequests); - await db.delete(agentRuntimeState); - await db.delete(companySkills); - await db.delete(agents); - await db.delete(companies); + await db.execute(sql.raw(` + TRUNCATE TABLE + "environment_leases", + "environments", + "activity_log", + "heartbeat_run_events", + "heartbeat_runs", + "agent_wakeup_requests", + "agent_runtime_state", + "company_skills", + "agents", + "companies" + RESTART IDENTITY CASCADE + `)); }); afterAll(async () => { diff --git a/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts b/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts index f55ffb9e..eecf0bf2 100644 --- a/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts +++ b/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts @@ -2,21 +2,15 @@ import { randomUUID } from "node:crypto"; import { eq, sql } from "drizzle-orm"; import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest"; import { - activityLog, agents, - agentRuntimeState, agentWakeupRequests, companies, - companySkills, createDb, documentRevisions, documents, - heartbeatRunEvents, heartbeatRuns, issueComments, issueDocuments, - issueRelations, - issueTreeHolds, issues, } from "@paperclipai/db"; import { ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY } from "@paperclipai/shared"; @@ -89,35 +83,39 @@ async function waitForCondition(fn: () => Promise, timeoutMs = 3_000) { } async function cleanupHeartbeatInvalidationFixture(db: ReturnType) { - for (let attempt = 0; attempt < 5; attempt += 1) { + for (let attempt = 0; attempt < 10; attempt += 1) { try { - await db.delete(companySkills); - await db.delete(issueComments); - await db.delete(issueDocuments); - await db.delete(documentRevisions); - await db.delete(documents); - await db.delete(issueRelations); - await db.delete(issueTreeHolds); - await db.delete(issues); - await db.delete(heartbeatRunEvents); - await db.delete(activityLog); - await db.delete(heartbeatRuns); - await db.delete(agentWakeupRequests); - await db.delete(agentRuntimeState); - await db.delete(agents); - await db.delete(companies); + await db.execute(sql.raw(` + TRUNCATE TABLE + "company_skills", + "issue_comments", + "issue_documents", + "document_revisions", + "documents", + "issue_relations", + "issue_tree_holds", + "issues", + "heartbeat_run_events", + "activity_log", + "heartbeat_runs", + "agent_wakeup_requests", + "agent_runtime_state", + "agents", + "companies" + RESTART IDENTITY CASCADE + `)); return; } catch (error) { const isLateCommentRace = error instanceof Error && error.message.includes("issue_comments_issue_id_issues_id_fk"); - if (!isLateCommentRace || attempt === 4) { + if (!isLateCommentRace || attempt === 9) { throw error; } // Heartbeat completion can write issue-thread comments shortly after the // run leaves queued/running. Retry the dependent deletes once those land. - await new Promise((resolve) => setTimeout(resolve, 50)); + await new Promise((resolve) => setTimeout(resolve, 100)); } } } diff --git a/server/src/__tests__/invite-onboarding-text.test.ts b/server/src/__tests__/invite-onboarding-text.test.ts index d2d57500..7d8407b6 100644 --- a/server/src/__tests__/invite-onboarding-text.test.ts +++ b/server/src/__tests__/invite-onboarding-text.test.ts @@ -39,7 +39,7 @@ describe("buildInviteOnboardingTextDocument", () => { allowedHostnames: [], }); - expect(text).toContain("Paperclip OpenClaw Gateway Onboarding"); + expect(text).toContain("Paperclip Agent Onboarding"); expect(text).toContain("/api/invites/token-123/accept"); expect(text).toContain("/api/join-requests/{requestId}/claim-api-key"); expect(text).toContain("/api/invites/token-123/onboarding.txt"); @@ -48,14 +48,13 @@ describe("buildInviteOnboardingTextDocument", () => { expect(text).toContain("http://localhost:3100"); expect(text).toContain("host.docker.internal"); expect(text).toContain("paperclipApiUrl"); - expect(text).toContain("adapterType \"openclaw_gateway\""); + expect(text).toContain('"adapterType": "openclaw_gateway"'); expect(text).toContain("headers.x-openclaw-token"); expect(text).toContain("Do NOT use /v1/responses or /hooks/*"); expect(text).toContain("set the first reachable candidate as agentDefaultsPayload.paperclipApiUrl"); - expect(text).toContain("~/.openclaw/workspace/paperclip-claimed-api-key.json"); expect(text).toContain("PAPERCLIP_API_KEY"); - expect(text).toContain("saved token field"); - expect(text).toContain("Gateway token unexpectedly short"); + expect(text).toContain("Use your runtime's normal skill or instruction installation path."); + expect(text).toContain("Decide which Paperclip adapter type matches your runtime."); }); it("includes loopback diagnostics for authenticated/private onboarding", () => { diff --git a/server/src/routes/access.ts b/server/src/routes/access.ts index ac7423f3..e9c07f87 100644 --- a/server/src/routes/access.ts +++ b/server/src/routes/access.ts @@ -1554,16 +1554,17 @@ function buildInviteOnboardingManifest( ), onboarding: { instructions: - "Join as an OpenClaw Gateway agent, save your one-time claim secret, wait for board approval, then claim your API key. Save the claim response token to ~/.openclaw/workspace/paperclip-claimed-api-key.json and load PAPERCLIP_API_KEY from that file before starting heartbeat loops. You MUST submit adapterType='openclaw_gateway', set agentDefaultsPayload.url to your ws:// or wss:// OpenClaw gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token (or legacy x-openclaw-auth).", + "Join as an external Paperclip agent, save your one-time claim secret, wait for board approval, then claim your API key. Use requestType='agent', include your agentName and capabilities, and set adapterType plus agentDefaultsPayload for your runtime when applicable. OpenClaw Gateway agents must use adapterType='openclaw_gateway', set agentDefaultsPayload.url to a ws:// or wss:// gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token.", inviteMessage: extractInviteMessage(invite), - recommendedAdapterType: "openclaw_gateway", + recommendedAdapterType: null, requiredFields: { requestType: "agent", agentName: "Display name for this agent", - adapterType: "Use 'openclaw_gateway' for OpenClaw Gateway agents", + adapterType: + "Adapter type for this runtime. Use 'openclaw_gateway' only for OpenClaw Gateway agents.", capabilities: "Optional capability summary", agentDefaultsPayload: - "Adapter config for OpenClaw gateway. MUST include url (ws:// or wss://) and headers.x-openclaw-token (or legacy x-openclaw-auth). Optional fields: paperclipApiUrl, waitTimeoutMs, sessionKeyStrategy, sessionKey, role, scopes, disableDeviceAuth, devicePrivateKeyPem." + "Runtime-specific adapter config. OpenClaw Gateway agents must include url (ws:// or wss://) and headers.x-openclaw-token. Other runtimes should include the config their adapter expects." }, registrationEndpoint: { method: "POST", @@ -1600,7 +1601,7 @@ function buildInviteOnboardingManifest( name: "paperclip", path: skillPath, url: skillUrl, - installPath: "~/.openclaw/skills/paperclip/SKILL.md" + installPath: "runtime-specific Paperclip skill location" } } }; @@ -1651,7 +1652,7 @@ export function buildInviteOnboardingTextDocument( }; appendBlock(` - # Paperclip OpenClaw Gateway Onboarding + # Paperclip Agent Onboarding This document is meant to be readable by both humans and agents. @@ -1675,62 +1676,30 @@ export function buildInviteOnboardingTextDocument( appendBlock(` ## Step 0 - Get the OpenClaw gateway auth token (THIS MUST BE SENT) - Token lives in: + Decide which Paperclip adapter type matches your runtime. - ~/.openclaw/openclaw.json -> gateway.auth.token - Extract: - - TOKEN="$(node -p 'require(process.env.HOME+\"/.openclaw/openclaw.json\").gateway.auth.token')" - test -n "$TOKEN" || (echo "Missing TOKEN" && exit 1) - test "\${#TOKEN}" -ge 16 || (echo "Gateway token unexpectedly short (\${#TOKEN})" && exit 1) - - 3) IMPORTANT: Don't accidentally drop the token when generating JSON - If you build JSON with Node, pass the token explicitly (argv), don't rely on an un-exported env var. - - Safe payload build looks sort of like this (substitute where necessary): - - BODY="$(node -e ' - const token = process.argv[1]; - if (!token) process.exit(2); - const body = { - requestType: "agent", - agentName: "OpenClaw", - adapterType: "openclaw_gateway", - capabilities: "OpenClaw agent adapter", - agentDefaultsPayload: { - url: "ws://127.0.0.1:18789", - paperclipApiUrl: "http://host.docker.internal:3100", - headers: { "x-openclaw-token": token }, - waitTimeoutMs: 120000, - sessionKeyStrategy: "issue", - role: "operator", - scopes: ["operator.admin"] - } - }; - process.stdout.write(JSON.stringify(body)); - ' "$TOKEN")" + Use adapterType only when there is a matching Paperclip adapter. Put runtime-specific settings in agentDefaultsPayload. ## Step 1: Submit agent join request ${onboarding.registrationEndpoint.method} ${ onboarding.registrationEndpoint.url } - IMPORTANT: You MUST include agentDefaultsPayload.headers.x-openclaw-token with your gateway token. - Legacy x-openclaw-auth is also accepted, but x-openclaw-token is preferred. - Use adapterType "openclaw_gateway" and a ws:// or wss:// gateway URL. - Pairing mode requirement: - - Keep device auth enabled (recommended). If devicePrivateKeyPem is omitted, Paperclip generates and persists one during join so pairing approvals are stable. - - You may set disableDeviceAuth=true only for special environments that cannot support pairing. - - First run may return "pairing required" once; approve the pending pairing request in OpenClaw, then retry. - Do NOT use /v1/responses or /hooks/* in this gateway join flow. - Body (JSON): + { + "requestType": "agent", + "agentName": "My Agent", + "adapterType": "adapter_type_for_this_runtime", + "capabilities": "Short summary of what this agent can do", + "agentDefaultsPayload": {} + } + + OpenClaw Gateway payload example: { "requestType": "agent", "agentName": "My OpenClaw Agent", "adapterType": "openclaw_gateway", - "capabilities": "Optional summary", + "capabilities": "OpenClaw gateway agent", "agentDefaultsPayload": { "url": "wss://your-openclaw-gateway.example", "paperclipApiUrl": "https://paperclip-hostname-your-agent-can-reach:3100", @@ -1742,6 +1711,8 @@ export function buildInviteOnboardingTextDocument( } } + For OpenClaw Gateway, include agentDefaultsPayload.headers.x-openclaw-token with your gateway token. Legacy x-openclaw-auth is also accepted, but x-openclaw-token is preferred. Do NOT use /v1/responses or /hooks/* in this gateway join flow. + Expected response includes: - request id - one-time claimSecret @@ -1760,35 +1731,18 @@ export function buildInviteOnboardingTextDocument( "claimSecret": "" } - On successful claim, save the full JSON response to: - - - ~/.openclaw/workspace/paperclip-claimed-api-key.json - chmod 600 ~/.openclaw/workspace/paperclip-claimed-api-key.json - - And set the PAPERCLIP_API_KEY and PAPERCLIP_API_URL in your environment variables as specified here: - https://docs.openclaw.ai/help/environment - - e.g. - - { - env: { - PAPERCLIP_API_KEY: "...", - PAPERCLIP_API_URL: "...", - }, - } - - Then set PAPERCLIP_API_KEY and PAPERCLIP_API_URL from the saved token field for every heartbeat run. + On successful claim, save the full JSON response somewhere private for your runtime and set PAPERCLIP_API_KEY and PAPERCLIP_API_URL for future Paperclip API calls. Important: - claim secrets expire - claim secrets are single-use - claim fails before board approval - ## Step 4: Install Paperclip skill in OpenClaw + ## Step 4: Install Paperclip skill GET ${onboarding.skill.url} Install path: ${onboarding.skill.installPath} - Be sure to prepend your PAPERCLIP_API_URL to the top of your skill and note the path to your PAPERCLIP_API_URL + Use your runtime's normal skill or instruction installation path. ## Text onboarding URL ${onboarding.textInstructions.url} diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.ts index ddd5dacb..e710d07b 100644 --- a/ui/src/adapters/adapter-display-registry.ts +++ b/ui/src/adapters/adapter-display-registry.ts @@ -110,10 +110,11 @@ const adapterDisplayMap: Record = { }, openclaw_gateway: { label: "OpenClaw Gateway", - description: "Invoke OpenClaw via gateway protocol", + description: "External gateway adapter", icon: Bot, comingSoon: true, - disabledLabel: "Configure OpenClaw within the App", + disabledLabel: "Invite external agents from the add-agent modal", + hideFromVisualSelection: true, }, process: { label: "Process", diff --git a/ui/src/components/NewAgentDialog.test.tsx b/ui/src/components/NewAgentDialog.test.tsx new file mode 100644 index 00000000..b1c63b9e --- /dev/null +++ b/ui/src/components/NewAgentDialog.test.tsx @@ -0,0 +1,210 @@ +// @vitest-environment jsdom + +import { act } from "react"; +import type { ReactNode } from "react"; +import { createRoot } from "react-dom/client"; +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { NewAgentDialog } from "./NewAgentDialog"; + +const createCompanyInviteMock = vi.hoisted(() => vi.fn()); +const getInviteOnboardingMock = vi.hoisted(() => vi.fn()); +const listAgentsMock = vi.hoisted(() => vi.fn()); +const listAdaptersMock = vi.hoisted(() => vi.fn()); +const navigateMock = vi.hoisted(() => vi.fn()); +const closeNewAgentMock = vi.hoisted(() => vi.fn()); +const openNewIssueMock = vi.hoisted(() => vi.fn()); +const pushToastMock = vi.hoisted(() => vi.fn()); +const clipboardWriteTextMock = vi.hoisted(() => vi.fn()); + +vi.mock("@/lib/router", () => ({ + useNavigate: () => navigateMock, +})); + +vi.mock("../context/DialogContext", () => ({ + useDialog: () => ({ + newAgentOpen: true, + closeNewAgent: closeNewAgentMock, + openNewIssue: openNewIssueMock, + }), +})); + +vi.mock("../context/CompanyContext", () => ({ + useCompany: () => ({ + selectedCompanyId: "company-1", + }), +})); + +vi.mock("../context/ToastContext", () => ({ + useToast: () => ({ pushToast: pushToastMock }), +})); + +vi.mock("../api/access", () => ({ + accessApi: { + createCompanyInvite: (companyId: string, input: unknown) => + createCompanyInviteMock(companyId, input), + getInviteOnboarding: (token: string) => getInviteOnboardingMock(token), + }, +})); + +vi.mock("../api/agents", () => ({ + agentsApi: { + list: (companyId: string) => listAgentsMock(companyId), + }, +})); + +vi.mock("../api/adapters", () => ({ + adaptersApi: { + list: () => listAdaptersMock(), + }, +})); + +vi.mock("../adapters", () => ({ + listUIAdapters: () => [{ type: "claude_local" }, { type: "openclaw_gateway" }], +})); + +vi.mock("../adapters/metadata", () => ({ + isVisualAdapterChoice: (type: string) => type !== "openclaw_gateway", +})); + +vi.mock("../adapters/use-disabled-adapters", () => ({ + useDisabledAdaptersSync: () => new Set(), +})); + +vi.mock("@/components/ui/dialog", () => ({ + Dialog: ({ open, children }: { open: boolean; children: ReactNode }) => + open ?
{children}
: null, + DialogContent: ({ children, className }: { children: ReactNode; className?: string }) => ( +
{children}
+ ), +})); + +// eslint-disable-next-line @typescript-eslint/no-explicit-any +(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true; + +async function flushReact() { + await act(async () => { + await Promise.resolve(); + await new Promise((resolve) => window.setTimeout(resolve, 0)); + }); +} + +describe("NewAgentDialog", () => { + let container: HTMLDivElement; + + beforeEach(() => { + container = document.createElement("div"); + document.body.appendChild(container); + + listAgentsMock.mockResolvedValue([ + { id: "agent-ceo", role: "ceo" }, + ]); + listAdaptersMock.mockResolvedValue([]); + createCompanyInviteMock.mockResolvedValue({ + id: "invite-1", + token: "agent-token", + inviteUrl: "https://paperclip.local/invite/agent-token", + expiresAt: "2026-04-20T00:00:00.000Z", + allowedJoinTypes: "agent", + humanRole: null, + onboardingTextUrl: "https://paperclip.local/api/invites/agent-token/onboarding.txt", + onboardingTextPath: "/api/invites/agent-token/onboarding.txt", + }); + getInviteOnboardingMock.mockResolvedValue({ + onboarding: { + connectivity: { + connectionCandidates: ["https://paperclip.local"], + testResolutionEndpoint: { + url: "https://paperclip.local/api/invites/agent-token/test-resolution", + }, + }, + }, + }); + + Object.defineProperty(globalThis.navigator, "clipboard", { + configurable: true, + value: { writeText: clipboardWriteTextMock }, + }); + }); + + afterEach(() => { + container.remove(); + document.body.innerHTML = ""; + vi.clearAllMocks(); + }); + + it("generates an external agent onboarding prompt inside the add-agent modal", async () => { + const root = createRoot(container); + const queryClient = new QueryClient({ + defaultOptions: { queries: { retry: false } }, + }); + + await act(async () => { + root.render( + + + , + ); + }); + await flushReact(); + + expect(container.textContent).toContain("Add a new agent"); + expect(container.textContent).toContain("Invite an external agent"); + + const inviteButton = Array.from(container.querySelectorAll("button")).find( + (button) => button.textContent?.startsWith("Invite an external agent"), + ); + + await act(async () => { + inviteButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + }); + + expect(container.textContent).toContain("Generate a one-time onboarding prompt"); + expect(container.textContent).not.toContain("Company Invites"); + + const generateButton = Array.from(container.querySelectorAll("button")).find( + (button) => button.textContent === "Generate onboarding prompt", + ); + + await act(async () => { + generateButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + }); + await flushReact(); + await flushReact(); + + expect(createCompanyInviteMock).toHaveBeenCalledWith("company-1", { + allowedJoinTypes: "agent", + humanRole: null, + agentMessage: null, + }); + expect(getInviteOnboardingMock).toHaveBeenCalledWith("agent-token"); + expect(clipboardWriteTextMock).toHaveBeenCalledWith( + expect.stringContaining("You're invited to join a Paperclip company as an agent."), + ); + expect(container.textContent).toContain("Agent onboarding prompt"); + expect(container.textContent).toContain("Send this prompt to the external agent"); + expect(container.textContent).not.toContain("Optional message for the agent"); + expect(container.textContent).not.toContain("Generate onboarding prompt"); + expect(pushToastMock).toHaveBeenCalledWith({ + title: "Agent invite created", + body: "Agent onboarding prompt ready below and copied to clipboard.", + tone: "success", + }); + + const backButton = Array.from(container.querySelectorAll("button")).find( + (button) => button.textContent === "Back", + ); + + await act(async () => { + backButton?.dispatchEvent(new MouseEvent("click", { bubbles: true })); + }); + await flushReact(); + + expect(container.textContent).toContain("Optional message for the agent"); + expect(container.textContent).toContain("Generate onboarding prompt"); + + await act(async () => { + root.unmount(); + }); + }); +}); diff --git a/ui/src/components/NewAgentDialog.tsx b/ui/src/components/NewAgentDialog.tsx index 6400038d..6062d443 100644 --- a/ui/src/components/NewAgentDialog.tsx +++ b/ui/src/components/NewAgentDialog.tsx @@ -1,8 +1,9 @@ -import { useState, useMemo } from "react"; -import { useQuery } from "@tanstack/react-query"; +import { useEffect, useMemo, useState } from "react"; +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; import { useNavigate } from "@/lib/router"; import { useDialog } from "../context/DialogContext"; import { useCompany } from "../context/CompanyContext"; +import { accessApi } from "../api/access"; import { agentsApi } from "../api/agents"; import { adaptersApi } from "../api/adapters"; import { queryKeys } from "@/lib/queryKeys"; @@ -11,15 +12,21 @@ import { DialogContent, } from "@/components/ui/dialog"; import { Button } from "@/components/ui/button"; +import { Textarea } from "@/components/ui/textarea"; import { ArrowLeft, Bot, + Check, + MailPlus, + Settings2, } from "lucide-react"; import { cn } from "@/lib/utils"; +import { buildAgentOnboardingPrompt } from "@/lib/agent-onboarding-prompt"; import { listUIAdapters } from "../adapters"; import { isVisualAdapterChoice } from "../adapters/metadata"; import { getAdapterDisplay } from "../adapters/adapter-display-registry"; import { useDisabledAdaptersSync } from "../adapters/use-disabled-adapters"; +import { useToast } from "../context/ToastContext"; /** * Adapter types that are suitable for agent creation (excludes internal @@ -27,6 +34,8 @@ import { useDisabledAdaptersSync } from "../adapters/use-disabled-adapters"; */ const SYSTEM_ADAPTER_TYPES = new Set(["process", "http"]); +type NewAgentDialogMode = "choices" | "runtime" | "invite" | "prompt"; + function isAgentAdapterType(type: string): boolean { return !SYSTEM_ADAPTER_TYPES.has(type); } @@ -34,10 +43,30 @@ function isAgentAdapterType(type: string): boolean { export function NewAgentDialog() { const { newAgentOpen, closeNewAgent, openNewIssue } = useDialog(); const { selectedCompanyId } = useCompany(); + const { pushToast } = useToast(); const navigate = useNavigate(); - const [showAdvancedCards, setShowAdvancedCards] = useState(false); + const queryClient = useQueryClient(); + const [mode, setMode] = useState("choices"); + const [agentMessage, setAgentMessage] = useState(""); + const [latestAgentPrompt, setLatestAgentPrompt] = useState(null); + const [latestAgentPromptCopied, setLatestAgentPromptCopied] = useState(false); const disabledTypes = useDisabledAdaptersSync(); + function resetDialogState() { + setMode("choices"); + setAgentMessage(""); + setLatestAgentPrompt(null); + setLatestAgentPromptCopied(false); + } + + useEffect(() => { + if (!latestAgentPromptCopied) return; + const timeout = window.setTimeout(() => { + setLatestAgentPromptCopied(false); + }, 1600); + return () => window.clearTimeout(timeout); + }, [latestAgentPromptCopied]); + // Fetch registered adapters from server (syncs disabled store + provides data) const { data: serverAdapters } = useQuery({ queryKey: queryKeys.adapters.all, @@ -53,6 +82,7 @@ export function NewAgentDialog() { }); const ceoAgent = (agents ?? []).find((a) => a.role === "ceo"); + const inviteHistoryQueryKey = queryKeys.access.invites(selectedCompanyId ?? "", "all", 5); // Build the adapter grid from the UI registry merged with display metadata. // This automatically includes external/plugin adapters. @@ -95,28 +125,110 @@ export function NewAgentDialog() { } function handleAdvancedConfig() { - setShowAdvancedCards(true); + setMode("runtime"); + } + + function handleInviteExternalAgent() { + setMode("invite"); } function handleAdvancedAdapterPick(adapterType: string) { closeNewAgent(); - setShowAdvancedCards(false); + resetDialogState(); navigate(`/agents/new?adapterType=${encodeURIComponent(adapterType)}`); } + async function copyText(text: string, unavailableBody: string) { + try { + if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) { + await navigator.clipboard.writeText(text); + return true; + } + } catch { + // Fall through to the unavailable message below. + } + + pushToast({ + title: "Clipboard unavailable", + body: unavailableBody, + tone: "warn", + }); + return false; + } + + const createAgentInviteMutation = useMutation({ + mutationFn: () => + accessApi.createCompanyInvite(selectedCompanyId!, { + allowedJoinTypes: "agent", + humanRole: null, + agentMessage: agentMessage.trim() || null, + }), + onSuccess: async (invite) => { + const base = window.location.origin.replace(/\/+$/, ""); + const onboardingTextLink = + invite.onboardingTextUrl ?? + invite.onboardingTextPath ?? + `/api/invites/${invite.token}/onboarding.txt`; + const onboardingTextUrl = onboardingTextLink.startsWith("http") + ? onboardingTextLink + : `${base}${onboardingTextLink}`; + + let prompt: string; + try { + const manifest = await accessApi.getInviteOnboarding(invite.token); + prompt = buildAgentOnboardingPrompt({ + onboardingTextUrl, + connectionCandidates: + manifest.onboarding.connectivity?.connectionCandidates ?? null, + testResolutionUrl: + manifest.onboarding.connectivity?.testResolutionEndpoint?.url ?? + null, + }); + } catch { + prompt = buildAgentOnboardingPrompt({ + onboardingTextUrl, + connectionCandidates: null, + testResolutionUrl: null, + }); + } + + setLatestAgentPrompt(prompt); + setLatestAgentPromptCopied(false); + setMode("prompt"); + const copied = await copyText(prompt, "Copy the agent onboarding prompt manually from the field below."); + + await queryClient.invalidateQueries({ queryKey: inviteHistoryQueryKey }); + pushToast({ + title: "Agent invite created", + body: copied ? "Agent onboarding prompt ready below and copied to clipboard." : "Agent onboarding prompt ready below.", + tone: "success", + }); + }, + onError: (error) => { + pushToast({ + title: "Failed to create agent invite", + body: error instanceof Error ? error.message : "Unknown error", + tone: "error", + }); + }, + }); + return ( { if (!open) { - setShowAdvancedCards(false); + resetDialogState(); closeNewAgent(); } }} > {/* Header */}
@@ -126,7 +238,7 @@ export function NewAgentDialog() { size="icon-xs" className="text-muted-foreground" onClick={() => { - setShowAdvancedCards(false); + resetDialogState(); closeNewAgent(); }} > @@ -134,8 +246,8 @@ export function NewAgentDialog() {
-
- {!showAdvancedCards ? ( +
+ {mode === "choices" ? ( <> {/* Recommendation */}
@@ -143,9 +255,8 @@ export function NewAgentDialog() {

- We recommend letting your CEO handle agent setup — they know the - org structure and can configure reporting, permissions, and - adapters. + Ask a leader to propose the hire, configure a runtime yourself, + or send an onboarding prompt to an external agent.

@@ -154,28 +265,34 @@ export function NewAgentDialog() { Ask the CEO to create a new agent - {/* Advanced link */} -
- +
+ +
+ +

+ (OpenClaw, Hermes, or any agent that can call the invite API.) +

+
- ) : ( + ) : mode === "runtime" ? ( <>

- Choose your adapter type for advanced setup. + Choose the runtime Paperclip should start or resume directly.

@@ -207,6 +324,92 @@ export function NewAgentDialog() { ))}
+ ) : mode === "invite" ? ( +
+
+ +
+

Invite an external agent

+

+ Generate a one-time onboarding prompt that any compatible agent can use to request access, wait for approval, and claim its Paperclip API key. +

+
+
+ +