From 4811d8dd333dbf6af5f2da5cdd97586d2f205907 Mon Sep 17 00:00:00 2001 From: Aron Prins Date: Fri, 22 May 2026 22:27:54 +0200 Subject: [PATCH 1/5] Fix wrapped company issue prefix conflicts (#6423) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Company creation is the first control-plane object operators create, and the generated issue prefix becomes part of task identity. > - The company service already retries when a generated issue prefix collides with the `companies_issue_prefix_idx` unique constraint. > - Drizzle 0.45.x wraps PostgreSQL errors in `DrizzleQueryError`, leaving the real `23505` constraint error on the `.cause` chain. > - The existing retry detector only inspected the top-level error, so wrapped prefix collisions surfaced as 500s instead of retrying. > - This pull request walks the error cause chain for the exact prefix constraint and verifies the retry path against embedded Postgres. > - The benefit is company creation no longer fails when generated prefixes collide under Drizzle 0.45.x wrappers. ## What Changed - Walk the error `.cause` chain when detecting `companies_issue_prefix_idx` unique violations, with a cycle guard and support for `constraint` / `constraint_name` fields. - Added an embedded Postgres regression test that seeds `ARO`, creates `Aron & Sharon`, and verifies the retry produces `AROA`. - Stabilized existing async tests touched by full verification: instance sidebar plugin rendering now waits for React Query results, and Tailscale-unavailable CLI tests explicitly hide host `tailscale` detection. ## Verification - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/companies-service.test.ts` - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/heartbeat-stale-queue-invalidation.test.ts` - `pnpm --filter @paperclipai/ui exec vitest run src/components/InstanceSidebar.test.tsx` - `pnpm --filter paperclipai exec vitest run src/__tests__/network-bind.test.ts src/__tests__/onboard.test.ts` - `pnpm test:run` - `pnpm -r typecheck` - `pnpm build` ## Risks - Low runtime risk: the retry behavior only expands detection for the existing exact company issue-prefix unique constraint. - The cause-chain walk is bounded by visited objects to avoid cycles. - The sidebar and CLI changes are test-only stabilization and do not change production behavior. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent in Codex desktop, with local shell/tool execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (N/A: no UI behavior change) - [x] I have updated relevant documentation to reflect my changes (N/A: bug fix with no user-facing docs change) - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge Closes #6350 --- cli/src/__tests__/network-bind.test.ts | 19 ++++--- cli/src/__tests__/onboard.test.ts | 8 ++- .../src/__tests__/companies-service.test.ts | 50 +++++++++++++++++++ server/src/services/companies.ts | 22 ++++---- ui/src/components/InstanceSidebar.test.tsx | 14 ++++-- 5 files changed, 93 insertions(+), 20 deletions(-) create mode 100644 server/src/__tests__/companies-service.test.ts diff --git a/cli/src/__tests__/network-bind.test.ts b/cli/src/__tests__/network-bind.test.ts index d75452abafd..513e3853a10 100644 --- a/cli/src/__tests__/network-bind.test.ts +++ b/cli/src/__tests__/network-bind.test.ts @@ -2,6 +2,8 @@ import { describe, expect, it } from "vitest"; import { resolveRuntimeBind, validateConfiguredBindMode } from "@paperclipai/shared"; import { buildPresetServerConfig } from "../config/server-bind.js"; +const ORIGINAL_PATH = process.env.PATH; + describe("network bind helpers", () => { it("rejects non-loopback bind modes in local_trusted", () => { expect( @@ -50,13 +52,18 @@ describe("network bind helpers", () => { it("falls back to loopback when no tailscale address is available for tailnet presets", () => { delete process.env.PAPERCLIP_TAILNET_BIND_HOST; + process.env.PATH = ""; - const preset = buildPresetServerConfig("tailnet", { - port: 3100, - allowedHostnames: [], - serveUi: true, - }); + try { + const preset = buildPresetServerConfig("tailnet", { + port: 3100, + allowedHostnames: [], + serveUi: true, + }); - expect(preset.server.host).toBe("127.0.0.1"); + expect(preset.server.host).toBe("127.0.0.1"); + } finally { + process.env.PATH = ORIGINAL_PATH; + } }); }); diff --git a/cli/src/__tests__/onboard.test.ts b/cli/src/__tests__/onboard.test.ts index 0c694f4be83..b7c01eb5cd7 100644 --- a/cli/src/__tests__/onboard.test.ts +++ b/cli/src/__tests__/onboard.test.ts @@ -7,6 +7,7 @@ import type { PaperclipConfig } from "../config/schema.js"; const ORIGINAL_ENV = { ...process.env }; const ORIGINAL_CWD = process.cwd(); +const ORIGINAL_PATH = process.env.PATH; function createExistingConfigFixture() { const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-")); @@ -171,8 +172,13 @@ describe("onboard", () => { it("keeps tailnet quickstart on loopback until tailscale is available", async () => { const configPath = createFreshConfigPath(); delete process.env.PAPERCLIP_TAILNET_BIND_HOST; + process.env.PATH = ""; - await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" }); + try { + await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" }); + } finally { + process.env.PATH = ORIGINAL_PATH; + } const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig; expect(raw.server.deploymentMode).toBe("authenticated"); diff --git a/server/src/__tests__/companies-service.test.ts b/server/src/__tests__/companies-service.test.ts new file mode 100644 index 00000000000..8977b041865 --- /dev/null +++ b/server/src/__tests__/companies-service.test.ts @@ -0,0 +1,50 @@ +import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest"; +import { companies, createDb } from "@paperclipai/db"; +import { + getEmbeddedPostgresTestSupport, + startEmbeddedPostgresTestDatabase, +} from "./helpers/embedded-postgres.js"; +import { companyService } from "../services/companies.js"; + +const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport(); +const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip; + +if (!embeddedPostgresSupport.supported) { + console.warn( + `Skipping embedded Postgres company service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`, + ); +} + +describeEmbeddedPostgres("companyService", () => { + let db!: ReturnType; + let tempDb: Awaited> | null = null; + + beforeAll(async () => { + tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-service-"); + db = createDb(tempDb.connectionString); + }, 20_000); + + afterEach(async () => { + await db.delete(companies); + }); + + afterAll(async () => { + await tempDb?.cleanup(); + }); + + it("retries generated issue prefixes when Drizzle wraps the unique constraint error", async () => { + await db.insert(companies).values({ + name: "Aron Existing", + issuePrefix: "ARO", + }); + + const created = await companyService(db).create({ + name: "Aron & Sharon", + }); + + expect(created.issuePrefix).toBe("AROA"); + + const rows = await db.select({ issuePrefix: companies.issuePrefix }).from(companies); + expect(rows.map((row) => row.issuePrefix).sort()).toEqual(["ARO", "AROA"]); + }); +}); diff --git a/server/src/services/companies.ts b/server/src/services/companies.ts index 8704b986cd2..e69abb9e222 100644 --- a/server/src/services/companies.ts +++ b/server/src/services/companies.ts @@ -125,16 +125,18 @@ export function companyService(db: Db) { } function isIssuePrefixConflict(error: unknown) { - const constraint = typeof error === "object" && error !== null && "constraint" in error - ? (error as { constraint?: string }).constraint - : typeof error === "object" && error !== null && "constraint_name" in error - ? (error as { constraint_name?: string }).constraint_name - : undefined; - return typeof error === "object" - && error !== null - && "code" in error - && (error as { code?: string }).code === "23505" - && constraint === "companies_issue_prefix_idx"; + const seen = new Set(); + let current = error; + while (typeof current === "object" && current !== null && !seen.has(current)) { + seen.add(current); + const maybe = current as { code?: string; constraint?: string; constraint_name?: string; cause?: unknown }; + const constraint = maybe.constraint ?? maybe.constraint_name; + if (maybe.code === "23505" && constraint === "companies_issue_prefix_idx") { + return true; + } + current = maybe.cause; + } + return false; } async function createCompanyWithUniquePrefix(data: typeof companies.$inferInsert) { diff --git a/ui/src/components/InstanceSidebar.test.tsx b/ui/src/components/InstanceSidebar.test.tsx index 2463116b618..e49d940b0ca 100644 --- a/ui/src/components/InstanceSidebar.test.tsx +++ b/ui/src/components/InstanceSidebar.test.tsx @@ -223,9 +223,14 @@ describe("InstanceSidebar", () => { await flushReact(); await findPluginLinks(container, 1); - const topLevelLinks = Array.from( - container.querySelectorAll('a[href^="/instance/settings/"]'), - ); + await vi.waitFor(() => { + const links = Array.from( + container.querySelectorAll('a[href^="/instance/settings/"]'), + ); + expect(links.some((a) => a.getAttribute("href") === "/instance/settings/plugins/linear")).toBe(true); + }); + + const topLevelLinks = Array.from(container.querySelectorAll('a[href^="/instance/settings/"]')); const hrefs = topLevelLinks.map((a) => a.getAttribute("href")); const pluginsIndex = hrefs.indexOf("/instance/settings/plugins"); @@ -266,6 +271,9 @@ describe("InstanceSidebar", () => { queryClient = rendered.queryClient; await flushReact(); + await vi.waitFor(() => { + expect(mockPluginsApi.list).toHaveBeenCalled(); + }); const pluginLinks = Array.from(container.querySelectorAll('a[href^="/instance/settings/plugins/"]')); expect(pluginLinks).toHaveLength(0); }); From e85ff094ec182f046794897f745b236dabefebb7 Mon Sep 17 00:00:00 2001 From: Aron Prins Date: Fri, 22 May 2026 22:28:49 +0200 Subject: [PATCH 2/5] fix(ui): invite page goes blank from companies query-key collision (#6433) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies; humans operate the board through the React UI. > - The board gates company access via `CompanyProvider` (CompanyContext) and onboards new humans through the invite landing page at `/invite/:token`. > - Reported symptom: opening an invite link and signing in works, but the page then renders completely blank (black in dark mode). > - End-to-end browser testing reproduced a client-side crash: `companiesQuery.data?.some is not a function` and `Cannot read properties of undefined (reading 'filter')`. > - Root cause: `CompanyProvider` and `InviteLandingPage` both use the React Query key `["companies"]` but return **different shapes** — `{ companies, unauthorized }` vs a bare `Company[]` — so they silently corrupt the shared cache entry; whichever component reads the other's shape calls `.some()`/`.filter()` on the wrong type and throws, unmounting the tree. > - Owners never hit it (they never mount the invite page); only invitees landing on `/invite/:token` crash. > - This PR unifies the `["companies"]` query into a single shared definition so the cache entry always has one shape and the two consumers can't drift apart again. > - The benefit is a working invite/onboarding flow and removal of a whole class of cache-shape bugs on this key. ## What Changed - Add `ui/src/api/companies-query.ts` exporting a single shared `companiesListQueryOptions` (and `CompanyListResult`) — one `queryKey` + one `queryFn` that always returns the wrapped `{ companies, unauthorized }` shape, documented with the shared-cache contract. - `ui/src/context/CompanyContext.tsx` now uses `useQuery(companiesListQueryOptions)` instead of an inline copy of that query. - `ui/src/pages/InviteLanding.tsx` uses the same `companiesListQueryOptions` (with its own `enabled` gate), reads `companiesQuery.data?.companies` for the membership checks, and uses `queryClient.fetchQuery(companiesListQueryOptions)` in the post-auth path — so it reads and writes the identical shape. ## Verification - `pnpm --filter @paperclipai/ui typecheck` — clean. - `vitest run src/pages/InviteLanding.test.tsx src/context/CompanyContext.test.tsx` — 17/17 pass, unchanged. - Manual end-to-end via a real browser against a LAN-exposed authenticated instance: - Owner creates an Owner-role invite. - New user opens the link and registers — **the "awaiting approval" screen renders** (previously blank), `POST /api/invites/:token/accept` returns `202`, no console errors. - Owner approves at Company Settings → Access (`200`); invitee becomes an active member. - Invitee signs in — full board loads; smoke test of dashboard / issues / inbox / routines / goals / company settings — all render, zero `pageerror`s. - Before: invite page `#root` empty after sign-in (blank/black). After: awaiting-approval panel renders. (Screenshots available on request.) ## Risks - Low. `CompanyProvider`'s query behavior is unchanged (same `queryFn` logic, just extracted into a shared module). `InviteLandingPage` now reads the same shape it writes. No API, schema, or migration changes. Existing tests pass unchanged. ## Model Used - Claude (Anthropic), model ID `claude-opus-4-7` (Opus 4.7), 1M-context, extended thinking + tool use; driving Claude Code with browser automation for end-to-end reproduction and verification. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [ ] I have added or updated tests where applicable (existing InviteLanding/CompanyContext tests cover the touched code and pass; a cross-provider regression test that mounts both consumers is a sensible follow-up) - [ ] If this change affects the UI, I have included before/after screenshots (described textually above; this is a crash/blank-page fix, screenshots available on request) - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Claude Opus 4.7 (1M context) --- ui/src/api/companies-query.ts | 25 +++++++++++++++++++++++++ ui/src/context/CompanyContext.tsx | 19 +++---------------- ui/src/pages/InviteLanding.tsx | 27 +++++++++------------------ 3 files changed, 37 insertions(+), 34 deletions(-) create mode 100644 ui/src/api/companies-query.ts diff --git a/ui/src/api/companies-query.ts b/ui/src/api/companies-query.ts new file mode 100644 index 00000000000..c01c481a936 --- /dev/null +++ b/ui/src/api/companies-query.ts @@ -0,0 +1,25 @@ +import type { Company } from "@paperclipai/shared"; +import { companiesApi } from "./companies"; +import { ApiError } from "./client"; +import { queryKeys } from "../lib/queryKeys"; + +export type CompanyListResult = { companies: Company[]; unauthorized: boolean }; + +// Single source of truth for the `["companies"]` query. Both CompanyProvider and +// the invite landing page read this cache entry, so they must agree on the shape — +// returning a bare `Company[]` from one and this wrapped object from the other +// silently corrupts the shared cache and crashes whichever reads the other's shape. +export const companiesListQueryOptions = { + queryKey: queryKeys.companies.all, + queryFn: async (): Promise => { + try { + return { companies: await companiesApi.list(), unauthorized: false }; + } catch (err) { + if (err instanceof ApiError && err.status === 401) { + return { companies: [], unauthorized: true }; + } + throw err; + } + }, + retry: false, +} as const; diff --git a/ui/src/context/CompanyContext.tsx b/ui/src/context/CompanyContext.tsx index 18a043f0c35..140d2c83562 100644 --- a/ui/src/context/CompanyContext.tsx +++ b/ui/src/context/CompanyContext.tsx @@ -10,11 +10,10 @@ import { import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"; import type { Company } from "@paperclipai/shared"; import { companiesApi } from "../api/companies"; -import { ApiError } from "../api/client"; +import { companiesListQueryOptions, type CompanyListResult } from "../api/companies-query"; import { queryKeys } from "../lib/queryKeys"; import type { CompanySelectionSource } from "../lib/company-selection"; type CompanySelectionOptions = { source?: CompanySelectionSource }; -type CompanyListResult = { companies: Company[]; unauthorized: boolean }; interface CompanyContextValue { companies: Company[]; @@ -69,20 +68,8 @@ export function CompanyProvider({ children }: { children: ReactNode }) { const [selectionSource, setSelectionSource] = useState("bootstrap"); const [selectedCompanyId, setSelectedCompanyIdState] = useState(null); - const { data: companiesResult = { companies: [], unauthorized: false }, isLoading, error } = useQuery({ - queryKey: queryKeys.companies.all, - queryFn: async () => { - try { - return { companies: await companiesApi.list(), unauthorized: false }; - } catch (err) { - if (err instanceof ApiError && err.status === 401) { - return { companies: [], unauthorized: true }; - } - throw err; - } - }, - retry: false, - }); + const { data: companiesResult = { companies: [], unauthorized: false }, isLoading, error } = + useQuery(companiesListQueryOptions); const companies = companiesResult.companies; const companyListUnauthorized = companiesResult.unauthorized; const sidebarCompanies = useMemo( diff --git a/ui/src/pages/InviteLanding.tsx b/ui/src/pages/InviteLanding.tsx index cb394505900..15642ecc001 100644 --- a/ui/src/pages/InviteLanding.tsx +++ b/ui/src/pages/InviteLanding.tsx @@ -8,7 +8,7 @@ import { useCompany } from "@/context/CompanyContext"; import { Link, useNavigate, useParams } from "@/lib/router"; import { accessApi } from "../api/access"; import { authApi } from "../api/auth"; -import { companiesApi } from "../api/companies"; +import { companiesListQueryOptions } from "../api/companies-query"; import { healthApi } from "../api/health"; import { getAdapterLabel } from "../adapters/adapter-display-registry"; import { clearPendingInviteToken, rememberPendingInviteToken } from "../lib/invite-memory"; @@ -248,11 +248,10 @@ export function InviteLandingPage() { }); const companiesQuery = useQuery({ - queryKey: queryKeys.companies.all, - queryFn: () => companiesApi.list(), + ...companiesListQueryOptions, enabled: !!sessionQuery.data && !!inviteQuery.data?.companyId, - retry: false, }); + const companyList = companiesQuery.data?.companies ?? []; useEffect(() => { if (token) rememberPendingInviteToken(token); @@ -263,11 +262,9 @@ export function InviteLandingPage() { }, [token]); useEffect(() => { - if (!companiesQuery.data || !inviteQuery.data?.companyId) return; - const isMember = companiesQuery.data.some( - (c) => c.id === inviteQuery.data!.companyId - ); - if (isMember) { + const list = companiesQuery.data?.companies; + if (!list || !inviteQuery.data?.companyId) return; + if (list.some((c) => c.id === inviteQuery.data!.companyId)) { clearPendingInviteToken(token); navigate("/", { replace: true }); } @@ -280,9 +277,7 @@ export function InviteLandingPage() { companiesQuery.isLoading; const isCurrentMember = Boolean(invite?.companyId) && - Boolean( - companiesQuery.data?.some((company) => company.id === invite?.companyId), - ); + companyList.some((company) => company.id === invite?.companyId); const companyName = invite?.companyName?.trim() || null; const companyDisplayName = companyName || "this Paperclip company"; const companyLogoUrl = invite?.companyLogoUrl?.trim() || null; @@ -375,13 +370,9 @@ export function InviteLandingPage() { setAuthFeedback(null); rememberPendingInviteToken(token); await queryClient.invalidateQueries({ queryKey: queryKeys.auth.session }); - const companies = await queryClient.fetchQuery({ - queryKey: queryKeys.companies.all, - queryFn: () => companiesApi.list(), - retry: false, - }); + const { companies: freshCompanies } = await queryClient.fetchQuery(companiesListQueryOptions); - if (invite?.companyId && companies.some((company) => company.id === invite.companyId)) { + if (invite?.companyId && freshCompanies.some((company) => company.id === invite.companyId)) { clearPendingInviteToken(token); setSelectedCompanyId(invite.companyId, { source: "manual" }); navigate("/", { replace: true }); From e3c875c1c76cdccd64b7ffa1f3cb5fca263608b6 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Fri, 22 May 2026 13:34:11 -0700 Subject: [PATCH 3/5] fix(sandbox): prevent E2B workspace upload + lease idle failures (PAPA-382) (#6560) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Heartbeats run inside managed sandboxes (E2B, Cloudflare Sandbox), and each run begins by uploading the agent's workspace as a tar archive > - PAPA-381's E2B runs were failing at 5 and 11 minutes — two distinct failure modes were entangled: workspace tar extraction errors on Linux, and sandbox idle/lease timeouts during normal heartbeat gaps > - Workspace tar extraction failed because macOS bsdtar embeds `LIBARCHIVE.xattr.*` PAX headers that GNU tar on Linux rejects with "This does not look like a tar archive"; the existing `COPYFILE_DISABLE=1` only suppresses AppleDouble `._*` sidecars, not inline PAX xattr entries > - E2B sandboxes also expired between heartbeats because `timeoutMs` defaulted to a short window and was never refreshed per execute, and Cloudflare sandboxes idled out because `sleepAfter` defaulted to 10 minutes > - This pull request adds `--no-xattrs` to the workspace tar invocation, refreshes the E2B sandbox lifetime on each execute and bumps the default `timeoutMs` to 1h, and raises the Cloudflare `sleepAfter` default to 1h > - The benefit is that long-running heartbeat-driven runs (Claude, Codex, etc.) survive across both their initial workspace upload and the natural idle gaps between executes on both E2B and Cloudflare ## What Changed - `packages/adapter-utils/src/sandbox-managed-runtime.ts`: added `--no-xattrs` to `createTarballFromDirectory` so macOS bsdtar produces a clean POSIX tar that GNU tar on Linux can extract, with an inline comment explaining why `COPYFILE_DISABLE=1` alone is insufficient. - `packages/plugins/sandbox-providers/e2b/src/plugin.ts`: refresh the sandbox lifetime on every execute (so long runs don't expire mid-job) and raised the default `timeoutMs` to 1h. - `packages/plugins/sandbox-providers/e2b/src/manifest.ts` and `plugin.test.ts`: updated manifest defaults and added regression coverage for the new behavior. - `packages/plugins/sandbox-providers/cloudflare/src/config.ts`, `manifest.ts`, `plugin.test.ts`: raised default `sleepAfter` from 10m to 1h, mirroring the E2B 1h default, and added a regression test asserting the acquire-lease request body sends `sleepAfter: "1h"` when not overridden. ## Verification - `pnpm --filter @paperclipai/plugin-e2b test` - `pnpm --filter @paperclipai/plugin-cloudflare-sandbox test` - Locally cherry-picked the `--no-xattrs` fix onto master and confirmed end-to-end via a real PAPA-381-style heartbeat-driven E2B run that the workspace upload now extracts cleanly on Linux. The user (board operator) tested this on master and reported "Ok, that worked." - Manual reviewer steps: trigger an E2B heartbeat from a macOS host (this is where the bsdtar xattr headers come from), confirm the workspace tar extracts on the Linux sandbox side; run a long (>15 min) Cloudflare sandbox flow and confirm no lost-lease/idle errors between executes. ## Risks - Low risk overall. - `--no-xattrs` is widely supported by both macOS bsdtar and GNU tar (Linux). Worst case it silently no-ops on a future host that doesn't support it; in that case the existing failure mode reappears, it doesn't introduce a new one. - Raising default `timeoutMs` (E2B) and `sleepAfter` (Cloudflare) from short values to 1h means sandboxes stay alive longer between executes by default. This is the intended behavior — operators that want a tighter idle window can still override via plugin config. - E2B per-execute sandbox lifetime refresh adds a small API call per execute; it is bounded by the same client that already handles execute traffic, so no new dependencies or retry semantics. ## Model Used - Claude (Anthropic), `claude-opus-4-7`, extended thinking enabled, tool use enabled (file/grep/git tools and Paperclip control-plane API). Used to diagnose the dual failure mode (workspace tar PAX xattr headers + sandbox lifetime), write the fixes and tests, and drive the verification loop with the board operator. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots (N/A — no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip --- .../src/sandbox-managed-runtime.ts | 7 +++ .../cloudflare/src/config.ts | 2 +- .../cloudflare/src/manifest.ts | 5 +- .../cloudflare/src/plugin.test.ts | 25 ++++++++- .../sandbox-providers/e2b/src/manifest.ts | 5 +- .../sandbox-providers/e2b/src/plugin.test.ts | 53 +++++++++++++++++++ .../sandbox-providers/e2b/src/plugin.ts | 16 +++++- 7 files changed, 105 insertions(+), 8 deletions(-) diff --git a/packages/adapter-utils/src/sandbox-managed-runtime.ts b/packages/adapter-utils/src/sandbox-managed-runtime.ts index 62375d7da21..13e9e9120da 100644 --- a/packages/adapter-utils/src/sandbox-managed-runtime.ts +++ b/packages/adapter-utils/src/sandbox-managed-runtime.ts @@ -138,6 +138,13 @@ async function createTarballFromDirectory(input: { const excludeArgs = ["._*", ...(input.exclude ?? [])].flatMap((entry) => ["--exclude", entry]); await execTar([ "-c", + // Prevent macOS bsdtar from embedding LIBARCHIVE.xattr.* PAX extended + // headers for extended attributes (e.g. com.apple.provenance). GNU tar on + // Linux does not recognise these proprietary headers and fails extraction + // with "This does not look like a tar archive". COPYFILE_DISABLE=1 (set in + // execTar) already suppresses AppleDouble ._* sidecar files; --no-xattrs + // additionally suppresses the inline PAX xattr entries. + "--no-xattrs", ...(input.followSymlinks ? ["-h"] : []), "-f", input.archivePath, diff --git a/packages/plugins/sandbox-providers/cloudflare/src/config.ts b/packages/plugins/sandbox-providers/cloudflare/src/config.ts index 1ed62a266f9..8bd6bab5bdc 100644 --- a/packages/plugins/sandbox-providers/cloudflare/src/config.ts +++ b/packages/plugins/sandbox-providers/cloudflare/src/config.ts @@ -1,7 +1,7 @@ import type { CloudflareDriverConfig } from "./types.js"; const DEFAULT_REQUESTED_CWD = "/workspace/paperclip"; -const DEFAULT_SLEEP_AFTER = "10m"; +const DEFAULT_SLEEP_AFTER = "1h"; const DEFAULT_TIMEOUT_MS = 300_000; const DEFAULT_BRIDGE_REQUEST_TIMEOUT_MS = 300_000; const LOCALHOST_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]); diff --git a/packages/plugins/sandbox-providers/cloudflare/src/manifest.ts b/packages/plugins/sandbox-providers/cloudflare/src/manifest.ts index 21f3ddda74f..52b18660d5e 100644 --- a/packages/plugins/sandbox-providers/cloudflare/src/manifest.ts +++ b/packages/plugins/sandbox-providers/cloudflare/src/manifest.ts @@ -49,8 +49,9 @@ const manifest: PaperclipPluginManifestV1 = { }, sleepAfter: { type: "string", - default: "10m", - description: "Idle timeout passed to getSandbox(). Ignored when keepAlive is true.", + default: "1h", + description: + "Idle timeout passed to getSandbox() on lease creation. Defaults to 1 hour so a fresh sandbox survives normal Claude/Codex heartbeats. Ignored when keepAlive is true.", }, normalizeId: { type: "boolean", diff --git a/packages/plugins/sandbox-providers/cloudflare/src/plugin.test.ts b/packages/plugins/sandbox-providers/cloudflare/src/plugin.test.ts index 84a6077b2f1..5e3908bd5c4 100644 --- a/packages/plugins/sandbox-providers/cloudflare/src/plugin.test.ts +++ b/packages/plugins/sandbox-providers/cloudflare/src/plugin.test.ts @@ -62,7 +62,7 @@ describe("Cloudflare sandbox provider plugin", () => { bridgeAuthToken: "secret-ref://bridge-token", reuseLease: true, keepAlive: true, - sleepAfter: "10m", + sleepAfter: "1h", normalizeId: false, requestedCwd: "/workspace/custom", sessionStrategy: "default", @@ -145,6 +145,29 @@ describe("Cloudflare sandbox provider plugin", () => { }); }); + it("defaults the sleepAfter passed to the bridge to 1h so long runs don't idle out", async () => { + fetchMock.mockResolvedValueOnce( + jsonResponse({ + providerLeaseId: "pc-run-1-abcd1234", + metadata: { provider: "cloudflare", remoteCwd: "/workspace/paperclip", resumedLease: false }, + }), + ); + + await plugin.definition.onEnvironmentAcquireLease?.({ + driverKey: "cloudflare", + companyId: "company-1", + environmentId: "env-1", + runId: "run-1", + requestedCwd: "/workspace/paperclip", + config: { + bridgeBaseUrl: "https://bridge.example.workers.dev", + bridgeAuthToken: "resolved-token", + }, + }); + + expect(requestBodyAt()).toMatchObject({ sleepAfter: "1h" }); + }); + it("returns expired lease semantics when resume reports lost state", async () => { fetchMock.mockResolvedValueOnce( jsonResponse( diff --git a/packages/plugins/sandbox-providers/e2b/src/manifest.ts b/packages/plugins/sandbox-providers/e2b/src/manifest.ts index 11b235909bc..a245e80c739 100644 --- a/packages/plugins/sandbox-providers/e2b/src/manifest.ts +++ b/packages/plugins/sandbox-providers/e2b/src/manifest.ts @@ -39,8 +39,9 @@ const manifest: PaperclipPluginManifestV1 = { }, timeoutMs: { type: "number", - description: "Sandbox timeout in milliseconds.", - default: 300000, + description: + "Sandbox lifetime in milliseconds, refreshed on each command. Defaults to 1 hour. Raise this if your runs commonly idle longer than the default between commands.", + default: 3600000, }, reuseLease: { type: "boolean", diff --git a/packages/plugins/sandbox-providers/e2b/src/plugin.test.ts b/packages/plugins/sandbox-providers/e2b/src/plugin.test.ts index 99b881c87c7..3f982284f27 100644 --- a/packages/plugins/sandbox-providers/e2b/src/plugin.test.ts +++ b/packages/plugins/sandbox-providers/e2b/src/plugin.test.ts @@ -379,6 +379,59 @@ describe("E2B sandbox provider plugin", () => { }); }); + it("refreshes the sandbox lifetime on every execute so long runs don't die mid-command", async () => { + const sandbox = createMockSandbox(); + mockConnect.mockResolvedValue(sandbox); + + await plugin.definition.onEnvironmentExecute?.({ + driverKey: "e2b", + companyId: "company-1", + environmentId: "env-1", + config: { + template: "base", + apiKey: "resolved-key", + timeoutMs: 1_800_000, + reuseLease: false, + }, + lease: { providerLeaseId: "sandbox-123", metadata: {} }, + command: "printf", + args: ["hello"], + cwd: "/workspace", + env: {}, + timeoutMs: 1000, + }); + + expect(sandbox.setTimeout).toHaveBeenCalledWith(1_800_000); + }); + + it("still runs the command when the setTimeout refresh fails transiently", async () => { + const sandbox = createMockSandbox(); + sandbox.setTimeout.mockRejectedValueOnce(new Error("transient e2b api error")); + mockConnect.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentExecute?.({ + driverKey: "e2b", + companyId: "company-1", + environmentId: "env-1", + config: { + template: "base", + apiKey: "resolved-key", + timeoutMs: 1_800_000, + reuseLease: false, + }, + lease: { providerLeaseId: "sandbox-123", metadata: {} }, + command: "printf", + args: ["hello"], + cwd: "/workspace", + env: {}, + timeoutMs: 1000, + }); + + expect(sandbox.setTimeout).toHaveBeenCalledWith(1_800_000); + expect(sandbox.commands.run).toHaveBeenCalled(); + expect(result?.exitCode).toBe(0); + }); + it("cleans up staged stdin even when writing it fails", async () => { const sandbox = createMockSandbox(); const failure = new Error("write failed"); diff --git a/packages/plugins/sandbox-providers/e2b/src/plugin.ts b/packages/plugins/sandbox-providers/e2b/src/plugin.ts index daf1548645e..e20dfd68c42 100644 --- a/packages/plugins/sandbox-providers/e2b/src/plugin.ts +++ b/packages/plugins/sandbox-providers/e2b/src/plugin.ts @@ -34,11 +34,11 @@ function parseDriverConfig(raw: Record): E2bDriverConfig { const template = typeof raw.template === "string" && raw.template.trim().length > 0 ? raw.template.trim() : "base"; - const timeoutMs = Number(raw.timeoutMs ?? 300_000); + const timeoutMs = Number(raw.timeoutMs ?? 3_600_000); return { template, apiKey: typeof raw.apiKey === "string" && raw.apiKey.trim().length > 0 ? raw.apiKey.trim() : null, - timeoutMs: Number.isFinite(timeoutMs) ? Math.trunc(timeoutMs) : 300_000, + timeoutMs: Number.isFinite(timeoutMs) ? Math.trunc(timeoutMs) : 3_600_000, reuseLease: raw.reuseLease === true, }; } @@ -391,6 +391,18 @@ const plugin = definePlugin({ const config = parseDriverConfig(params.config); const sandbox = await connectSandbox(config, params.lease.providerLeaseId); + // Refresh the sandbox death clock on every command. E2B's `timeoutMs` is + // the absolute sandbox lifetime from create/connect; without this, a run + // longer than `config.timeoutMs` will have its sandbox killed mid-command + // and the next call throws "Sandbox is probably not running anymore". + // The refresh is best-effort: the sandbox is already healthy at this + // point, so a transient API error on setTimeout should not block the + // command from running. Worst case the existing lifetime stands. + try { + await sandbox.setTimeout(config.timeoutMs); + } catch { + // ignore — keep going with the existing sandbox lifetime + } const baseCommand = buildLoginShellScript({ command: params.command, args: params.args ?? [], From 897cc322c75e46695be8b3b8b198797f05f0bb4c Mon Sep 17 00:00:00 2001 From: Aron Prins Date: Sat, 23 May 2026 16:09:40 +0200 Subject: [PATCH 4/5] Improve external agent invite flow (#6183) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Agent creation can happen through local runtimes, managed runtimes, and external agents that onboard through invites. > - The old OpenClaw-oriented invite UX lived under company settings/invites and made a gateway-specific path look like a company access setting. > - That hid the broader bring-your-own-agent flow and forced operators to leave the add-agent modal when adding an external agent. > - This pull request moves external agent invite generation into the add-agent modal and makes the copy agent-oriented instead of OpenClaw-only. > - The benefit is a clearer agent-first onboarding path while company invites stay focused on human access. ## What Changed - Added an external-agent invite branch to the add-agent modal, including a dedicated prompt result view with Back navigation. - Added a shared agent onboarding prompt builder and focused modal coverage for prompt replacement/back navigation. - Removed the agent invite prompt UI from Company Settings and Company Invites, leaving Company Invites focused on human access links and invite history. - Updated the hidden OpenClaw Gateway runtime hint to direct operators to the add-agent invite flow instead of presenting it as a blocked runtime card. - Updated invite/onboarding docs, storybook coverage, and server-side onboarding copy toward generic agent language while preserving existing gateway compatibility. ## Verification - `pnpm -r typecheck` - `pnpm build` - `FAKE_BIN="$(mktemp -d)/bin"; mkdir -p "$FAKE_BIN"; printf '#!/bin/sh\nexit 1\n' > "$FAKE_BIN/tailscale"; chmod +x "$FAKE_BIN/tailscale"; PATH="$FAKE_BIN:$PATH" pnpm test:run` - `pnpm test:run` without the fake `tailscale` shim was also attempted; it failed only in two pre-existing CLI tailnet fallback tests because this host has a real Tailscale address (`100.125.202.3`) where those tests expect no Tailscale. - Focused confirmation for that host-env issue: `FAKE_BIN=... PATH="$FAKE_BIN:$PATH" pnpm exec vitest run --project paperclipai cli/src/__tests__/network-bind.test.ts cli/src/__tests__/onboard.test.ts` - Manual UI verification: served UI locally in light mode, opened add-agent modal, generated external agent prompt, verified the generated prompt replaces the form and Back returns to the form. ### Screenshots ![Add agent modal](https://raw.githubusercontent.com/aronprins/paperclip/pr-assets/6183-agent-invites/.github/pr-screenshots/6183/add-agent-modal-light.png) ![External agent invite form](https://raw.githubusercontent.com/aronprins/paperclip/pr-assets/6183-agent-invites/.github/pr-screenshots/6183/external-agent-invite-form-light.png) ![Generated onboarding prompt replacement view](https://raw.githubusercontent.com/aronprins/paperclip/pr-assets/6183-agent-invites/.github/pr-screenshots/6183/onboarding-prompt-result-light.png) ## Risks - Existing OpenClaw gateway compatibility remains, but operators now discover external agent onboarding from the add-agent modal instead of company settings. - Agent invites still appear in the invite history table, so that page may show agent-scoped invite rows even though it no longer creates agent onboarding prompts. - Low migration risk: no schema changes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent in Codex desktop; tool-enabled repository, shell, browser, and GitHub workflow. Context window size was not exposed by the runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --- doc/DEVELOPING.md | 6 +- doc/spec/invite-flow.md | 28 +- .../access-routes-permissions-upgrade.test.ts | 2 +- .../heartbeat-comment-wake-batching.test.ts | 12 +- .../heartbeat-dependency-scheduling.test.ts | 2 +- .../heartbeat-local-environment.test.ts | 32 +-- ...heartbeat-stale-queue-invalidation.test.ts | 46 ++- .../__tests__/invite-onboarding-text.test.ts | 9 +- server/src/routes/access.ts | 94 ++---- ui/src/adapters/adapter-display-registry.ts | 5 +- ui/src/components/NewAgentDialog.test.tsx | 210 ++++++++++++++ ui/src/components/NewAgentDialog.tsx | 251 ++++++++++++++-- ui/src/lib/agent-onboarding-prompt.ts | 111 ++++++++ ui/src/pages/CompanyInvites.test.tsx | 19 +- ui/src/pages/CompanyInvites.tsx | 26 +- ui/src/pages/CompanySettings.tsx | 267 +----------------- .../stories/dialogs-modals.stories.tsx | 24 +- 17 files changed, 693 insertions(+), 451 deletions(-) create mode 100644 ui/src/components/NewAgentDialog.test.tsx create mode 100644 ui/src/lib/agent-onboarding-prompt.ts diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index f41465e2928..341f3b1117e 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 504744b038d..fad3c56e10d 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 9db328d4519..b7180581a5d 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 6cda7fb1743..606f69bca95 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 f2560bcdd5e..62b488dd280 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 673297a1c81..145a6b6b860 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 f55ffb9e754..eecf0bf21a2 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 d2d575009c7..7d8407b608f 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 ac7423f32cc..e9c07f87e7f 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 ddd5dacbdae..e710d07b9c6 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 00000000000..b1c63b9e1c2 --- /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 6400038de00..6062d4438de 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. +

+
+
+ +