Reusable env-var editor (agents, projects, environments, routines). One shared grid, an
diff --git a/ui/src/pages/InstanceExperimentalSettings.test.tsx b/ui/src/pages/InstanceExperimentalSettings.test.tsx
index 45f4da85c13..300f2e2454c 100644
--- a/ui/src/pages/InstanceExperimentalSettings.test.tsx
+++ b/ui/src/pages/InstanceExperimentalSettings.test.tsx
@@ -55,6 +55,7 @@ const SERVER_INFO_TOGGLE_SELECTOR =
'button[aria-label="Toggle server info debug view experimental setting"]';
const BUILT_IN_AGENTS_TOGGLE_SELECTOR =
'button[aria-label="Toggle built-in agents experimental setting"]';
+const APPS_TOGGLE_SELECTOR = 'button[aria-label="Toggle apps experimental setting"]';
const AUTO_RECOVERY_TOGGLE_SELECTOR =
'button[aria-label="Toggle task graph liveness auto-recovery"]';
@@ -187,6 +188,19 @@ describe("InstanceExperimentalSettings — Conference Room Chat card (PAP-11233)
expect(warning?.textContent).toContain("no compatibility guarantees");
});
+ it("enables the Apps UI from experimental settings", async () => {
+ await renderPage();
+
+ const toggle = container.querySelector(APPS_TOGGLE_SELECTOR);
+ expect(toggle?.getAttribute("aria-checked")).toBe("false");
+
+ await act(() => toggle?.click());
+ await flushReact();
+
+ expect(mockInstanceSettingsApi.updateExperimental).toHaveBeenCalledWith({ enableApps: true });
+ expect(container.querySelector(APPS_TOGGLE_SELECTOR)?.getAttribute("aria-checked")).toBe("true");
+ });
+
it("does not render the Conference Room Chat experimental setting for now", async () => {
await renderPage();
diff --git a/ui/src/pages/InstanceExperimentalSettings.tsx b/ui/src/pages/InstanceExperimentalSettings.tsx
index b77f205a3dd..80bcfac88fd 100644
--- a/ui/src/pages/InstanceExperimentalSettings.tsx
+++ b/ui/src/pages/InstanceExperimentalSettings.tsx
@@ -284,6 +284,7 @@ export function InstanceExperimentalSettings() {
);
const enableEnvironments = experimentalQuery.data?.enableEnvironments === true;
const enableIsolatedWorkspaces = experimentalQuery.data?.enableIsolatedWorkspaces === true;
+ const enableApps = experimentalQuery.data?.enableApps === true;
// Streamlined left navigation is now the standard sidebar (PAP-12472); the
// experimental opt-out was retired, so it no longer surfaces a toggle here.
const enableConferenceRoomChat = experimentalQuery.data?.enableConferenceRoomChat === true;
@@ -299,6 +300,7 @@ export function InstanceExperimentalSettings() {
const enableGoalsSidebarLink = experimentalQuery.data?.enableGoalsSidebarLink === true;
const enableCases = experimentalQuery.data?.enableCases === true;
const enableServerInfoDebugView = experimentalQuery.data?.enableServerInfoDebugView === true;
+ const enableSmokeLab = experimentalQuery.data?.enableSmokeLab === true;
const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;
const enableIssueGraphLivenessAutoRecovery =
experimentalQuery.data?.enableIssueGraphLivenessAutoRecovery === true;
@@ -426,6 +428,26 @@ export function InstanceExperimentalSettings() {
) : null}
+
+
+
+
+
Apps
+ Experimental
+
+
+ Show the Apps navigation and allow access to app connections, gateways, and advanced app tooling.
+
+
+
toggleMutation.mutate({ enableApps: !enableApps })}
+ disabled={toggleMutation.isPending}
+ aria-label="Toggle apps experimental setting"
+ />
+
+
@@ -686,6 +708,25 @@ export function InstanceExperimentalSettings() {
+
+
+
+
Smoke Lab
+
+ Add a "Smoke Lab" tab under Apps → Developer and an "Integration smoke" card on the
+ dashboard for exercising every integration path against deterministic local fixtures
+ (fake OAuth provider + loopback MCP servers). Private (non-public) deployments only.
+
+
+
toggleMutation.mutate({ enableSmokeLab: !enableSmokeLab })}
+ disabled={toggleMutation.isPending}
+ aria-label="Toggle smoke lab experimental setting"
+ />
+
+
diff --git a/ui/src/pages/apps/AppDetail.test.tsx b/ui/src/pages/apps/AppDetail.test.tsx
new file mode 100644
index 00000000000..240822b5249
--- /dev/null
+++ b/ui/src/pages/apps/AppDetail.test.tsx
@@ -0,0 +1,684 @@
+// @vitest-environment jsdom
+
+import { flushSync } from "react-dom";
+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 { AppDetail } from "./AppDetail";
+
+const getConnectionMock = vi.hoisted(() => vi.fn());
+const getConnectionInstallsMock = vi.hoisted(() => vi.fn());
+const listGalleryMock = vi.hoisted(() => vi.fn());
+const listCatalogMock = vi.hoisted(() => vi.fn());
+const listProfilesMock = vi.hoisted(() => vi.fn());
+const listPoliciesMock = vi.hoisted(() => vi.fn());
+const listConnectionActivityMock = vi.hoisted(() => vi.fn());
+const listActionRequestsMock = vi.hoisted(() => vi.fn());
+const updateConnectionMock = vi.hoisted(() => vi.fn());
+const finishAppMock = vi.hoisted(() => vi.fn());
+const putConnectionInstallsMock = vi.hoisted(() => vi.fn());
+const refreshCatalogMock = vi.hoisted(() => vi.fn());
+const startOAuthMock = vi.hoisted(() => vi.fn());
+const mockNavigate = vi.hoisted(() => vi.fn());
+const mockParams = vi.hoisted(() => ({ connectionId: "conn-1", tab: "setup" as string | undefined }));
+const navigateComponentMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@/api/tools", () => ({
+ toolsApi: {
+ getConnection: (connectionId: string) => getConnectionMock(connectionId),
+ getConnectionInstalls: (connectionId: string) => getConnectionInstallsMock(connectionId),
+ listGallery: (companyId: string) => listGalleryMock(companyId),
+ listCatalog: (connectionId: string) => listCatalogMock(connectionId),
+ listProfiles: (companyId: string) => listProfilesMock(companyId),
+ listPolicies: (companyId: string) => listPoliciesMock(companyId),
+ listConnectionActivity: (connectionId: string, limit: number) =>
+ listConnectionActivityMock(connectionId, limit),
+ listActionRequests: (companyId: string, status: string) =>
+ listActionRequestsMock(companyId, status),
+ updateConnection: (connectionId: string, input: unknown) =>
+ updateConnectionMock(connectionId, input),
+ finishApp: (companyId: string, connectionId: string, input: unknown) =>
+ finishAppMock(companyId, connectionId, input),
+ putConnectionInstalls: (connectionId: string, installs: unknown) =>
+ putConnectionInstallsMock(connectionId, installs),
+ archiveConnection: vi.fn(),
+ refreshCatalog: (connectionId: string) => refreshCatalogMock(connectionId),
+ startOAuth: (connectionId: string) => startOAuthMock(connectionId),
+ reconnectConnection: vi.fn(),
+ },
+}));
+
+vi.mock("@/api/agents", () => ({
+ agentsApi: {
+ list: vi.fn().mockResolvedValue([
+ { id: "agent-1", name: "Coder", title: "Engineer", status: "active" },
+ ]),
+ },
+}));
+
+vi.mock("@/lib/router", () => ({
+ useParams: () => mockParams,
+ useNavigate: () => mockNavigate,
+ useSearchParams: () => [new URLSearchParams(), vi.fn()],
+ Navigate: ({ to, replace }: { to: string; replace?: boolean }) => {
+ navigateComponentMock({ to, replace });
+ return
;
+ },
+ Link: ({ to, children, ...props }: { to: string; children: ReactNode }) => (
+
+ {children}
+
+ ),
+}));
+
+vi.mock("@/context/CompanyContext", () => ({
+ useCompany: () => ({
+ selectedCompanyId: "company-1",
+ selectedCompany: { id: "company-1", name: "Paperclip" },
+ }),
+}));
+
+vi.mock("@/context/BreadcrumbContext", () => ({
+ useBreadcrumbs: () => ({ setBreadcrumbs: vi.fn() }),
+}));
+
+vi.mock("@/context/ToastContext", () => ({
+ useToast: () => ({ pushToast: vi.fn() }),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+async function act(callback: () => void | Promise
) {
+ let result: void | Promise = undefined;
+ flushSync(() => {
+ result = callback();
+ });
+ await result;
+}
+
+async function flushReact() {
+ for (let i = 0; i < 3; i += 1) {
+ await act(async () => {
+ await Promise.resolve();
+ await new Promise((resolve) => window.setTimeout(resolve, 0));
+ });
+ }
+}
+
+function connection(overrides: Record = {}) {
+ return {
+ id: "conn-1",
+ companyId: "company-1",
+ applicationId: "app-1",
+ name: "GitHub",
+ connectionKind: "managed",
+ transport: "remote_http",
+ status: "active",
+ transportConfig: { url: "https://github.example/mcp" },
+ config: { url: "https://github.example/mcp" },
+ credentialSecretRefs: [],
+ credentialRefs: [],
+ healthStatus: "healthy",
+ healthCheckedAt: null,
+ lastError: null,
+ enabled: true,
+ lastUsedAt: null,
+ createdByAgentId: null,
+ createdByUserId: null,
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ updatedAt: new Date("2026-01-01T00:00:00Z"),
+ ...overrides,
+ };
+}
+
+function catalogEntry(overrides: Record = {}) {
+ return {
+ id: "catalog-read",
+ companyId: "company-1",
+ connectionId: "conn-1",
+ toolName: "read_repo",
+ title: "Read repo",
+ description: "Read repository metadata",
+ status: "active",
+ isReadOnly: true,
+ riskLevel: "read",
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ updatedAt: new Date("2026-01-01T00:00:00Z"),
+ ...overrides,
+ };
+}
+
+function setInputValue(input: HTMLInputElement, value: string) {
+ const setter = Object.getOwnPropertyDescriptor(
+ window.HTMLInputElement.prototype,
+ "value",
+ )?.set;
+ setter?.call(input, value);
+ input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+describe("AppDetail", () => {
+ let container: HTMLDivElement;
+ let root: ReturnType;
+
+ beforeEach(() => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ mockParams.connectionId = "conn-1";
+ mockParams.tab = "setup";
+ getConnectionMock.mockResolvedValue(connection());
+ getConnectionInstallsMock.mockResolvedValue({ connectionId: "conn-1", installs: [] });
+ listGalleryMock.mockResolvedValue({
+ apps: [
+ {
+ key: "github",
+ name: "GitHub",
+ logoUrl: "https://example.com/github.png",
+ tagline: "GitHub tagline",
+ description: "Give agents a governed way to inspect repositories and pull requests.",
+ authKind: "api_key",
+ transportTemplate: { transport: "remote_http", url: "https://github.example/mcp" },
+ credentialFields: [],
+ recommendedDefaults: {},
+ urlPatterns: [],
+ },
+ ],
+ });
+ listCatalogMock.mockResolvedValue({
+ catalog: [
+ catalogEntry(),
+ catalogEntry({
+ id: "catalog-write",
+ toolName: "write_issue",
+ title: "Write issue",
+ description: "Create or update an issue",
+ isReadOnly: false,
+ }),
+ catalogEntry({
+ id: "catalog-quarantined",
+ toolName: "delete_repo",
+ title: "Delete repo",
+ status: "quarantined",
+ isReadOnly: false,
+ }),
+ ],
+ });
+ listProfilesMock.mockResolvedValue({
+ profiles: [
+ {
+ profileKey: "app:conn-1",
+ entries: [
+ { effect: "include", catalogEntryId: "catalog-read" },
+ { effect: "include", catalogEntryId: "catalog-write" },
+ ],
+ bindings: [{ targetType: "company" }],
+ },
+ ],
+ });
+ listPoliciesMock.mockResolvedValue({
+ policies: [
+ {
+ policyType: "require_approval",
+ enabled: true,
+ config: {
+ source: "app_gallery_finish",
+ connectionId: "conn-1",
+ catalogEntryId: "catalog-write",
+ },
+ },
+ ],
+ });
+ listConnectionActivityMock.mockResolvedValue({ events: [], issues: {}, actionRequests: {} });
+ listActionRequestsMock.mockResolvedValue({ actionRequests: [] });
+ updateConnectionMock.mockResolvedValue(connection({ enabled: false }));
+ finishAppMock.mockResolvedValue({});
+ putConnectionInstallsMock.mockResolvedValue({ connectionId: "conn-1", installs: [] });
+ refreshCatalogMock.mockResolvedValue({ discoveredCount: 0, quarantinedCount: 0, catalog: [] });
+ startOAuthMock.mockResolvedValue({
+ connectionId: "conn-1",
+ provider: "smoke_lab",
+ authorizationUrl: "http://example.test/oauth",
+ expiresAt: "2026-07-10T00:00:00.000Z",
+ });
+ });
+
+ afterEach(() => {
+ flushSync(() => root?.unmount());
+ container.remove();
+ vi.clearAllMocks();
+ });
+
+ async function renderAppDetail() {
+ const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+ root = createRoot(container);
+ await act(async () => {
+ root.render(
+
+ ,
+ );
+ });
+ await flushReact();
+ }
+
+ it("pauses the app by flipping the connection enabled flag", async () => {
+ await renderAppDetail();
+
+ const toggle = container.querySelector(
+ 'button[role="switch"][aria-label="Pause this app"]',
+ );
+ expect(toggle).toBeTruthy();
+
+ await act(async () => {
+ toggle!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(updateConnectionMock).toHaveBeenCalledWith("conn-1", { enabled: false });
+ });
+
+ it("redirects a missing tab to setup", async () => {
+ mockParams.tab = undefined;
+
+ await renderAppDetail();
+
+ expect(navigateComponentMock).toHaveBeenCalledWith({ to: "/apps/conn-1/setup", replace: true });
+ });
+
+ it.each([
+ ["setup", "Agents can use this app"],
+ ["review", "1 new action to review"],
+ ["permissions", "Action permissions"],
+ ["activity", "No activity yet."],
+ ["advanced", "Technical details"],
+ ])("renders the %s tab panel", async (tab, expectedText) => {
+ mockParams.tab = tab;
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("GitHub");
+ expect(container.textContent).toContain("2 actions available");
+ expect(container.textContent).toContain(expectedText);
+ });
+
+ it("hides secret URL parameters in advanced technical details", async () => {
+ mockParams.tab = "advanced";
+ getConnectionMock.mockResolvedValue(
+ connection({
+ config: {
+ url: "https://mcp.zapier.com/api/v1/connect?token=zapier-secret®ion=us",
+ },
+ }),
+ );
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain(
+ "https://mcp.zapier.com/api/v1/connect?token=REDACTED®ion=us",
+ );
+ expect(container.textContent).not.toContain("zapier-secret");
+ });
+
+ it("shows new quarantined actions on the review tab instead of an empty state", async () => {
+ mockParams.tab = "review";
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("1 new action to review");
+ await act(async () => {
+ Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent?.trim() === "Review")
+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+ expect(container.textContent).toContain("Delete repo");
+ expect(container.textContent).not.toContain("Nothing is waiting for your OK right now.");
+ });
+
+ it("keeps setup focused on description and lifecycle", async () => {
+ mockParams.tab = "setup";
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Give agents a governed way to inspect repositories and pull requests.");
+ expect(container.textContent).toContain("Agents can use this app");
+ expect(container.textContent).not.toContain("Read repo");
+ expect(container.textContent).not.toContain("Action permissions");
+ });
+
+ it("shows the Smoke OAuth connection action for the installed HTTP fixture", async () => {
+ getConnectionMock.mockResolvedValue(connection({
+ name: "Smoke Lab HTTP MCP fixture",
+ config: {
+ smokeLabFixture: "oauth-http",
+ oauth: {
+ provider: "smoke_lab",
+ smokeLabFixture: true,
+ scopes: ["smoke:openid"],
+ },
+ },
+ }));
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Connect with Smoke OAuth");
+ expect(
+ Array.from(container.querySelectorAll("button")).some(
+ (button) => button.textContent?.trim() === "Connect with Smoke OAuth",
+ ),
+ ).toBe(true);
+ });
+
+ it("lets Google Sheets connections add spreadsheet links from setup", async () => {
+ mockParams.tab = "setup";
+ getConnectionMock.mockResolvedValue(connection({
+ name: "Google Sheets",
+ transport: "local_stdio",
+ config: {
+ templateId: "paperclip.google-sheets",
+ sourceTemplateKey: "google-sheets",
+ allowedSpreadsheetIds: ["sheet_existing"],
+ env: { GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS: "sheet_existing" },
+ },
+ }));
+ listGalleryMock.mockResolvedValue({
+ apps: [
+ {
+ key: "google-sheets",
+ name: "Google Sheets",
+ logoUrl: "https://example.com/sheets.png",
+ tagline: "Read and update selected spreadsheets.",
+ description: "Share each sheet with the robot email, then paste the sheet links here.",
+ authKind: "none",
+ transportTemplate: { transport: "local_stdio", templateKey: "paperclip.google-sheets" },
+ credentialFields: [],
+ recommendedDefaults: {},
+ urlPatterns: ["https://docs.google.com/spreadsheets/*"],
+ availability: { available: true, robotEmail: "robot@paperclip.iam.gserviceaccount.com" },
+ },
+ ],
+ });
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Sheets agents can use");
+ expect(container.textContent).toContain("https://docs.google.com/spreadsheets/d/sheet_existing/edit");
+ expect(container.textContent).toContain("sheet_existing");
+ const input = container.querySelector(
+ 'input[placeholder="https://docs.google.com/spreadsheets/d/..."]',
+ );
+ expect(input).toBeTruthy();
+ await act(async () => setInputValue(input!, "https://docs.google.com/spreadsheets/d/sheet_new/edit"));
+ await flushReact();
+ await act(async () => {
+ Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent?.trim() === "Add sheet")
+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(updateConnectionMock).toHaveBeenCalledWith("conn-1", {
+ config: expect.objectContaining({
+ allowedSpreadsheetIds: ["sheet_existing", "sheet_new"],
+ env: expect.objectContaining({ GOOGLE_SHEETS_ALLOWED_SPREADSHEET_IDS: "sheet_existing,sheet_new" }),
+ }),
+ transportConfig: { url: "https://github.example/mcp" },
+ });
+ });
+
+ it("renders unified action permission dropdowns in the permissions tab", async () => {
+ mockParams.tab = "permissions";
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Read only");
+ expect(container.textContent).toContain("Can make changes");
+ expect(container.textContent).toContain("Read repo");
+ expect(container.textContent).toContain("Write issue");
+ expect(container.textContent).toContain("1 new action to review");
+ const readSelect = container.querySelector('select[aria-label="Read repo permission"]');
+ const writeSelect = container.querySelector('select[aria-label="Write issue permission"]');
+ expect(readSelect?.value).toBe("allowed");
+ expect(writeSelect?.value).toBe("ask");
+ });
+
+ it("persists ask-first for read-only actions from the unified dropdown", async () => {
+ mockParams.tab = "permissions";
+
+ await renderAppDetail();
+
+ const readSelect = container.querySelector('select[aria-label="Read repo permission"]');
+ expect(readSelect).toBeTruthy();
+ await act(async () => {
+ readSelect!.value = "ask";
+ readSelect!.dispatchEvent(new Event("change", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(finishAppMock).toHaveBeenCalledWith("company-1", "conn-1", {
+ enabledCatalogEntryIds: expect.arrayContaining(["catalog-read", "catalog-write"]),
+ askFirstCatalogEntryIds: expect.arrayContaining(["catalog-read", "catalog-write"]),
+ access: "all_agents",
+ });
+ });
+
+ it("persists off by removing an action from enabled and ask-first sets", async () => {
+ mockParams.tab = "permissions";
+
+ await renderAppDetail();
+
+ const writeSelect = container.querySelector('select[aria-label="Write issue permission"]');
+ expect(writeSelect).toBeTruthy();
+ await act(async () => {
+ writeSelect!.value = "off";
+ writeSelect!.dispatchEvent(new Event("change", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(finishAppMock).toHaveBeenCalledWith("company-1", "conn-1", {
+ enabledCatalogEntryIds: ["catalog-read"],
+ askFirstCatalogEntryIds: [],
+ access: "all_agents",
+ });
+ });
+
+ it("persists installed agents from the permissions tab", async () => {
+ mockParams.tab = "permissions";
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Installed on agents");
+ await act(async () => {
+ Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent?.includes("Choose agents to install on"))
+ ?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ const coderCheckbox = document.body.querySelector('[aria-label="Allow Coder"]');
+ expect(coderCheckbox).toBeTruthy();
+ await act(async () => {
+ coderCheckbox!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(putConnectionInstallsMock).toHaveBeenCalledWith("conn-1", [
+ { targetType: "agent", targetId: "agent-1" },
+ ]);
+ });
+
+ it("renders activity attribution with issue context and human resolver names", async () => {
+ mockParams.tab = "activity";
+ listConnectionActivityMock.mockResolvedValue({
+ events: [
+ {
+ id: "evt-1",
+ eventType: "call_completed",
+ agentId: "agent-1",
+ issueId: "issue-1",
+ actionRequestId: null,
+ toolName: "Get value",
+ outcome: "success",
+ createdAt: new Date("2026-06-12T10:00:00Z"),
+ },
+ {
+ id: "evt-2",
+ eventType: "approval_resolved",
+ agentId: "agent-1",
+ issueId: "issue-1",
+ actionRequestId: "request-1",
+ toolName: "Mark done",
+ outcome: "success",
+ createdAt: new Date("2026-06-12T10:01:00Z"),
+ },
+ ],
+ issues: {
+ "issue-1": { identifier: "PAP-10912", title: "Fix app connection copy" },
+ },
+ actionRequests: {
+ "request-1": {
+ status: "approved",
+ resolverDisplayName: "Dotta",
+ resolvedByAgentId: null,
+ resolvedByUserId: "board-user",
+ },
+ },
+ });
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Coder used Get value");
+ expect(container.textContent).toContain("while working on PAP-10912");
+ expect(container.textContent).toContain("Dotta approved Mark done");
+ expect(container.querySelector('a[href="/issues/PAP-10912"]')).toBeTruthy();
+ expect(container.textContent).not.toContain("You reviewed");
+ });
+
+ it("humanizes the raw gateway-prefixed tool name in activity", async () => {
+ mockParams.tab = "activity";
+ listConnectionActivityMock.mockResolvedValue({
+ events: [
+ {
+ id: "evt-1",
+ eventType: "call_completed",
+ agentId: "agent-1",
+ issueId: null,
+ actionRequestId: null,
+ toolName: "mcp.app-gallery-link-ccad39e8-6798a369:kv-set",
+ outcome: "success",
+ createdAt: new Date("2026-06-12T10:00:00Z"),
+ },
+ ],
+ issues: {},
+ actionRequests: {},
+ });
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Coder used Kv Set");
+ expect(container.textContent).not.toContain("mcp.app-gallery-link");
+ });
+
+ it("renders connection lifecycle events humanized on the timeline", async () => {
+ mockParams.tab = "activity";
+ listConnectionActivityMock.mockResolvedValue({
+ events: [
+ {
+ id: "evt-1",
+ eventType: "call_completed",
+ agentId: "agent-1",
+ issueId: null,
+ actionRequestId: null,
+ toolName: "Get value",
+ outcome: "success",
+ createdAt: new Date("2026-06-12T10:30:00Z"),
+ },
+ ],
+ lifecycleEvents: [
+ {
+ id: "life-connected",
+ connectionId: "conn-1",
+ type: "app_connected",
+ actorType: "user",
+ actorId: "board-user",
+ agentId: null,
+ actorDisplayName: "Dotta",
+ details: null,
+ createdAt: new Date("2026-06-12T09:00:00Z"),
+ },
+ {
+ id: "life-paused",
+ connectionId: "conn-1",
+ type: "app_paused",
+ actorType: "user",
+ actorId: "board-user",
+ agentId: null,
+ actorDisplayName: "Dotta",
+ details: { enabled: false },
+ createdAt: new Date("2026-06-12T11:00:00Z"),
+ },
+ {
+ id: "life-allowlist",
+ connectionId: "conn-1",
+ type: "allowlist_changed",
+ actorType: "user",
+ actorId: "board-user",
+ agentId: null,
+ actorDisplayName: "Dotta",
+ details: { added: 1, removed: 0, total: 2 },
+ createdAt: new Date("2026-06-12T10:45:00Z"),
+ },
+ {
+ id: "life-quarantine",
+ connectionId: "conn-1",
+ type: "actions_quarantined",
+ actorType: "system",
+ actorId: null,
+ agentId: null,
+ actorDisplayName: null,
+ details: { count: 2 },
+ createdAt: new Date("2026-06-12T10:50:00Z"),
+ },
+ ],
+ issues: {},
+ actionRequests: {},
+ });
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("Dotta connected GitHub");
+ expect(container.textContent).toContain("Dotta paused this app");
+ expect(container.textContent).toContain("Dotta added 1 sheet to the allowlist");
+ expect(container.textContent).toContain("2 new actions need review");
+ // Lifecycle rows deep-link to the Setup tab; quarantine uses the review label.
+ expect(container.querySelector('a[href="/apps/conn-1/setup"]')).toBeTruthy();
+ expect(container.textContent).toContain("Review in Setup");
+
+ // Merged timeline: the newest event (the pause at 11:00) renders before the
+ // tool call at 10:30, which renders before the connect at 09:00.
+ const pausedAt = container.textContent?.indexOf("Dotta paused this app") ?? -1;
+ const usedAt = container.textContent?.indexOf("Coder used Get value") ?? -1;
+ const connectedAt = container.textContent?.indexOf("Dotta connected GitHub") ?? -1;
+ expect(pausedAt).toBeGreaterThanOrEqual(0);
+ expect(pausedAt).toBeLessThan(usedAt);
+ expect(usedAt).toBeLessThan(connectedAt);
+ });
+
+ it("keeps the header and reconnect banner across tabs", async () => {
+ mockParams.tab = "permissions";
+ getConnectionMock.mockResolvedValue(connection({
+ healthStatus: "degraded",
+ healthMessage: "Token expired.",
+ }));
+
+ await renderAppDetail();
+
+ expect(container.textContent).toContain("GitHub");
+ expect(container.textContent).toContain("Needs attention");
+ expect(container.textContent).toContain("This app needs reconnecting");
+ expect(container.textContent).toContain("Token expired.");
+ expect(container.textContent).toContain("Who can use it");
+ });
+});
diff --git a/ui/src/pages/apps/AppDetail.tsx b/ui/src/pages/apps/AppDetail.tsx
new file mode 100644
index 00000000000..1f568cc450a
--- /dev/null
+++ b/ui/src/pages/apps/AppDetail.tsx
@@ -0,0 +1,639 @@
+import { useEffect, useMemo, useState } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Check, Loader2, Pencil } from "lucide-react";
+import type {
+ AppGalleryEntry,
+ ToolConnection,
+ ToolPolicy,
+ ToolProfileWithDetails,
+} from "@paperclipai/shared";
+import {
+ connectionDisplaySecondaryHint,
+ humanizeConnectionDisplayName,
+ isToolConnectionAttentionHealth as isAttentionHealthStatus,
+} from "@paperclipai/shared";
+import { Navigate, useParams, useNavigate } from "@/lib/router";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { useToast } from "@/context/ToastContext";
+import { queryKeys } from "@/lib/queryKeys";
+import { toolsApi } from "@/api/tools";
+import { agentsApi } from "@/api/agents";
+import { accessApi } from "@/api/access";
+import { authApi } from "@/api/auth";
+import { buildCompanyUserLabelMap } from "@/lib/company-members";
+import { installPayload, installStateFrom, type InstallState } from "@/lib/tool-installs";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Skeleton } from "@/components/ui/skeleton";
+import { cn } from "@/lib/utils";
+import { AppLogo } from "./AppLogo";
+import { appTabHref, appTabLabel, isAppTabKey, type AppTabKey } from "./app-tabs";
+import { SetupPanel } from "./app-detail/SetupPanel";
+import { PermissionsPanel } from "./app-detail/PermissionsPanel";
+import { TestPanel } from "./app-detail/TestPanel";
+import { ReviewPanel } from "./app-detail/ReviewPanel";
+import { ActivityPanel } from "./app-detail/ActivityPanel";
+import {
+ AdvancedPanel,
+ ReconnectCard,
+ DangerZone,
+ connectionAddress,
+ connectionTransportLabel,
+} from "./app-detail/AdvancedPanel";
+import type { AccessDraft } from "./app-detail/types";
+
+export { DangerZone, connectionAddress, connectionTransportLabel };
+
+export function AppDetail() {
+ const { connectionId = "", tab } = useParams<{ connectionId: string; tab?: string }>();
+ const navigate = useNavigate();
+ const queryClient = useQueryClient();
+ const { pushToast } = useToast();
+ const { selectedCompany, selectedCompanyId } = useCompany();
+ const { setBreadcrumbs } = useBreadcrumbs();
+
+ const activeTab: AppTabKey | null = isAppTabKey(tab) ? tab : null;
+
+ const connectionQuery = useQuery({
+ queryKey: queryKeys.tools.connection(connectionId),
+ queryFn: () => toolsApi.getConnection(connectionId),
+ enabled: !!connectionId && !!activeTab,
+ });
+ const installsQuery = useQuery({
+ queryKey: queryKeys.tools.connectionInstalls(connectionId),
+ queryFn: () => toolsApi.getConnectionInstalls(connectionId),
+ enabled: !!connectionId && activeTab === "permissions",
+ });
+ const galleryQuery = useQuery({
+ queryKey: queryKeys.apps.gallery(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listGallery(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+ const catalogQuery = useQuery({
+ queryKey: queryKeys.tools.catalog(connectionId),
+ queryFn: () => toolsApi.listCatalog(connectionId),
+ enabled: !!connectionId && !!activeTab,
+ });
+ const profilesQuery = useQuery({
+ queryKey: queryKeys.tools.profiles(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listProfiles(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+ const policiesQuery = useQuery({
+ queryKey: queryKeys.tools.policies(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listPolicies(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+ const agentsQuery = useQuery({
+ queryKey: queryKeys.agents.list(selectedCompanyId ?? "__none__"),
+ queryFn: () => agentsApi.list(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+ const activityQuery = useQuery({
+ queryKey: queryKeys.tools.connectionActivity(connectionId),
+ queryFn: () => toolsApi.listConnectionActivity(connectionId, 20),
+ enabled: !!connectionId && activeTab === "activity",
+ });
+ // Resolve who ran Test-tab calls (" tested as ") in the Activity feed (PAP-11415).
+ const userDirectoryQuery = useQuery({
+ queryKey: queryKeys.access.companyUserDirectory(selectedCompanyId ?? "__none__"),
+ queryFn: () => accessApi.listUserDirectory(selectedCompanyId!),
+ enabled: !!selectedCompanyId && activeTab === "activity",
+ });
+ const sessionQuery = useQuery({
+ queryKey: queryKeys.auth.session,
+ queryFn: () => authApi.getSession(),
+ enabled: activeTab === "activity",
+ });
+
+ const connection = connectionQuery.data;
+ const appName = connection ? humanizeConnectionDisplayName(connection) : "App";
+
+ useEffect(() => {
+ if (!activeTab) return;
+ setBreadcrumbs([
+ { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+ { label: "Apps", href: "/apps" },
+ { label: appName, href: appTabHref(connectionId, "setup") },
+ { label: appTabLabel(activeTab) },
+ ]);
+ return () => setBreadcrumbs([]);
+ }, [setBreadcrumbs, selectedCompany?.name, appName, connectionId, activeTab]);
+
+ const catalog = catalogQuery.data?.catalog ?? [];
+ const profile = useMemo(
+ () => (profilesQuery.data?.profiles ?? []).find((p) => p.profileKey === `app:${connectionId}`),
+ [profilesQuery.data, connectionId],
+ );
+ const enabledIds = useMemo(() => enabledCatalogIds(profile), [profile]);
+ const askFirstIds = useMemo(
+ () => askFirstCatalogIds(policiesQuery.data?.policies ?? [], connectionId),
+ [policiesQuery.data, connectionId],
+ );
+ const access = useMemo(() => accessFrom(profile), [profile]);
+ const install = useMemo(
+ () => installStateFrom(installsQuery.data?.installs ?? connection?.installs),
+ [connection?.installs, installsQuery.data?.installs],
+ );
+ const agents = agentsQuery.data ?? [];
+ const userLabelById = useMemo(() => {
+ const labels = buildCompanyUserLabelMap(userDirectoryQuery.data?.users);
+ const session = sessionQuery.data;
+ // Prefer the viewer's own profile name for their own test runs ("Dotta", not a fallback).
+ if (session?.user?.id && session.user.name?.trim()) {
+ labels.set(session.user.id, session.user.name.trim());
+ }
+ return labels;
+ }, [userDirectoryQuery.data, sessionQuery.data]);
+ const logoEntry = useMemo(
+ () => galleryEntryFor(galleryQuery.data?.apps ?? [], connection),
+ [galleryQuery.data, connection],
+ );
+
+ const [pending, setPending] = useState(false);
+ const persist = useMutation({
+ mutationFn: (next: { enabled: Set; askFirst: Set; access: AccessDraft }) =>
+ toolsApi.finishApp(selectedCompanyId!, connectionId, {
+ enabledCatalogEntryIds: [...next.enabled],
+ askFirstCatalogEntryIds: [...next.askFirst].filter((id) => next.enabled.has(id)),
+ access: next.access.mode === "all" ? "all_agents" : { agentIds: [...next.access.agentIds] },
+ }),
+ onMutate: () => setPending(true),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.catalog(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.profiles(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.policies(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't save that",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ onSettled: () => setPending(false),
+ });
+
+ const persistInstall = useMutation({
+ mutationFn: (next: InstallState) =>
+ toolsApi.putConnectionInstalls(connectionId, installPayload(selectedCompanyId!, next)),
+ onSuccess: (snapshot) => {
+ queryClient.setQueryData(queryKeys.tools.connectionInstalls(connectionId), snapshot);
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.profiles(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't save installs",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const [renaming, setRenaming] = useState(false);
+ const [nameDraft, setNameDraft] = useState("");
+ const rename = useMutation({
+ mutationFn: (name: string) => toolsApi.updateConnection(connectionId, { name }),
+ onSuccess: () => {
+ setRenaming(false);
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't rename the app",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const updateConfig = useMutation({
+ mutationFn: (config: Record) => toolsApi.updateConnection(connectionId, {
+ config,
+ transportConfig: connection?.transportConfig ?? {},
+ }),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't save that",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const startOAuth = useMutation({
+ mutationFn: () => toolsApi.startOAuth(connectionId),
+ onSuccess: ({ authorizationUrl }) => {
+ window.location.assign(authorizationUrl);
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't start sign-in",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const removeApp = useMutation({
+ mutationFn: () => toolsApi.archiveConnection(connectionId),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.applications(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ pushToast({
+ title: "App removed",
+ body: `${appName} no longer has access. You can connect it again any time.`,
+ tone: "success",
+ });
+ navigate("/apps");
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't remove the app",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const toggleEnabled = useMutation({
+ mutationFn: () => toolsApi.updateConnection(connectionId, { enabled: !connection?.enabled }),
+ onSuccess: (updated) => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.applications(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ pushToast({
+ title: updated.enabled ? "App resumed" : "App paused",
+ body: updated.enabled
+ ? `${humanizeConnectionDisplayName(updated)} is available to agents again.`
+ : `${humanizeConnectionDisplayName(updated)} is paused for agents.`,
+ tone: "success",
+ });
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't update the app",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const refreshTools = useMutation({
+ mutationFn: () => toolsApi.refreshCatalog(connectionId),
+ onSuccess: (result) => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.catalog(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId!) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId!) });
+ pushToast({
+ title: `Found ${result.discoveredCount} ${result.discoveredCount === 1 ? "action" : "actions"}`,
+ body: result.quarantinedCount > 0
+ ? `${result.quarantinedCount} new ${result.quarantinedCount === 1 ? "action needs" : "actions need"} your OK.`
+ : undefined,
+ tone: "success",
+ });
+ },
+ onError: (error) =>
+ pushToast({
+ title: "Couldn't refresh actions",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ }),
+ });
+
+ const apply = (mutate: { enabled?: Set; askFirst?: Set; access?: AccessDraft }) =>
+ persist.mutate({
+ enabled: mutate.enabled ?? new Set(enabledIds),
+ askFirst: mutate.askFirst ?? new Set(askFirstIds),
+ access: mutate.access ?? access,
+ });
+
+ if (!connectionId || !activeTab) {
+ return Select a company to manage apps.
;
+ }
+ if (connectionQuery.isLoading || catalogQuery.isLoading) {
+ return (
+
+
+ );
+ }
+ if (!connection) {
+ return (
+
+
We couldn't find that app.
+
navigate("/apps")}>
+ Back to apps
+
+
+
{
+ setNameDraft(appName);
+ setRenaming(true);
+ }}
+ onRenameCancel={() => setRenaming(false)}
+ onRenameSubmit={(next) => {
+ if (next && next !== appName) rename.mutate(next);
+ else setRenaming(false);
+ }}
+ />
+
+ {needsReconnect && (
+ {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId) });
+ }}
+ />
+ )}
+
+ {activeTab === "setup" && (
+ toggleEnabled.mutate()}
+ configUpdateDisabled={updateConfig.isPending}
+ onUpdateConfig={(config) => updateConfig.mutate(config)}
+ oauthStartDisabled={startOAuth.isPending}
+ onStartOAuth={() => startOAuth.mutate()}
+ />
+ )}
+ {activeTab === "review" && (
+ apply({ enabled: addAll(new Set(enabledIds), ids) })}
+ />
+ )}
+ {activeTab === "permissions" && (
+ apply({ access: next })}
+ onSaveInstall={(next) => persistInstall.mutate(next)}
+ onRefreshActions={() => refreshTools.mutate()}
+ onSetActionPermission={(id, next) => apply(actionPermissionMutation(id, next, enabledIds, askFirstIds))}
+ onTurnOnQuarantined={(ids) => apply({ enabled: addAll(new Set(enabledIds), ids) })}
+ />
+ )}
+ {activeTab === "test" && (
+ removeApp.mutate()}
+ onReplaced={() => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connection(connectionId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.connections(selectedCompanyId) });
+ queryClient.invalidateQueries({ queryKey: queryKeys.apps.attention(selectedCompanyId) });
+ }}
+ />
+ )}
+
+
+
+
+ {renaming ? (
+
+ ) : (
+
+ )}
+ {connectionDisplaySecondaryHint(connection) && (
+
{connectionDisplaySecondaryHint(connection)}
+ )}
+
+
+ {actionCount} {actionCount === 1 ? "action" : "actions"} available
+
+
+
+
+ );
+}
+
+type StatusInfo = { label: string; tone: "connected" | "attention" | "paused" };
+
+function statusFor(connection: ToolConnection): StatusInfo {
+ if (connection.enabled === false || connection.status === "disabled") {
+ return { label: "Paused", tone: "paused" };
+ }
+ if (isAttentionHealthStatus(connection.healthStatus)) {
+ return { label: "Needs attention", tone: "attention" };
+ }
+ return { label: "Connected", tone: "connected" };
+}
+
+function StatusBadge({ status }: { status: StatusInfo }) {
+ const klass: Record = {
+ connected: "border-emerald-500/40 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300",
+ attention: "border-amber-500/40 bg-amber-500/10 text-amber-700 dark:text-amber-300",
+ paused: "border-border bg-muted text-muted-foreground",
+ };
+ return (
+
+ {status.tone === "connected" &&
+ );
+}
+
+function enabledCatalogIds(profile: ToolProfileWithDetails | undefined): Set {
+ const ids = new Set();
+ for (const entry of profile?.entries ?? []) {
+ if (entry.effect === "include" && entry.catalogEntryId) ids.add(entry.catalogEntryId);
+ }
+ return ids;
+}
+
+function askFirstCatalogIds(policies: ToolPolicy[], connectionId: string): Set {
+ const ids = new Set();
+ for (const policy of policies) {
+ if (policy.policyType !== "require_approval" || policy.enabled === false) continue;
+ const config = (policy.config ?? {}) as { source?: unknown; connectionId?: unknown; catalogEntryId?: unknown };
+ if (config.source === "app_gallery_finish" && config.connectionId === connectionId && typeof config.catalogEntryId === "string") {
+ ids.add(config.catalogEntryId);
+ }
+ }
+ return ids;
+}
+
+function accessFrom(profile: ToolProfileWithDetails | undefined): AccessDraft {
+ const bindings = profile?.bindings ?? [];
+ if (bindings.some((b) => b.targetType === "company")) {
+ return { mode: "all", agentIds: new Set() };
+ }
+ const agentIds = new Set(bindings.filter((b) => b.targetType === "agent").map((b) => b.targetId));
+ if (agentIds.size === 0) return { mode: "all", agentIds: new Set() };
+ return { mode: "specific", agentIds };
+}
+
+function galleryEntryFor(apps: AppGalleryEntry[], connection: ToolConnection | undefined): AppGalleryEntry | null {
+ if (!connection) return null;
+ const name = connection.name.toLowerCase();
+ return apps.find((a) => a.name.toLowerCase() === name) ?? apps.find((a) => a.key === name) ?? null;
+}
+
+function addAll(set: Set, ids: string[]): Set {
+ const next = new Set(set);
+ for (const id of ids) next.add(id);
+ return next;
+}
+
+function actionPermissionMutation(
+ id: string,
+ next: "off" | "allowed" | "ask",
+ enabledIds: Set,
+ askFirstIds: Set,
+) {
+ const enabled = new Set(enabledIds);
+ const askFirst = new Set(askFirstIds);
+ if (next === "off") {
+ enabled.delete(id);
+ askFirst.delete(id);
+ } else {
+ enabled.add(id);
+ if (next === "ask") askFirst.add(id);
+ else askFirst.delete(id);
+ }
+ return { enabled, askFirst };
+}
diff --git a/ui/src/pages/apps/AppLogo.tsx b/ui/src/pages/apps/AppLogo.tsx
new file mode 100644
index 00000000000..3a570175736
--- /dev/null
+++ b/ui/src/pages/apps/AppLogo.tsx
@@ -0,0 +1,69 @@
+import { useState } from "react";
+import { cn } from "@/lib/utils";
+
+const TILE_COLORS = [
+ "bg-(--app-logo-tile-1)",
+ "bg-(--app-logo-tile-2)",
+ "bg-(--app-logo-tile-3)",
+ "bg-(--app-logo-tile-4)",
+ "bg-(--app-logo-tile-5)",
+ "bg-(--app-logo-tile-6)",
+ "bg-(--app-logo-tile-7)",
+ "bg-(--app-logo-tile-8)",
+];
+
+function colorFor(seed: string): string {
+ let hash = 0;
+ for (let i = 0; i < seed.length; i++) hash = (hash * 31 + seed.charCodeAt(i)) >>> 0;
+ return TILE_COLORS[hash % TILE_COLORS.length]!;
+}
+
+interface AppLogoProps {
+ name: string;
+ logoUrl?: string | null;
+ size?: number;
+ className?: string;
+}
+
+/**
+ * App icon for the gallery and connected-apps surfaces. Renders the manifest
+ * favicon when available, falling back to a coloured letter tile (deterministic
+ * colour per app name) when the image is missing or fails to load.
+ */
+export function AppLogo({ name, logoUrl, size = 36, className }: AppLogoProps) {
+ const [failed, setFailed] = useState(false);
+ const letter = (name.trim()[0] ?? "?").toUpperCase();
+ const dimension = { width: size, height: size };
+
+ if (logoUrl && !failed) {
+ return (
+
+
+ );
+ }
+
+ return (
+
+ {letter}
+
+ );
+}
diff --git a/ui/src/pages/apps/AppNotConnected.test.tsx b/ui/src/pages/apps/AppNotConnected.test.tsx
new file mode 100644
index 00000000000..e2037ad12c9
--- /dev/null
+++ b/ui/src/pages/apps/AppNotConnected.test.tsx
@@ -0,0 +1,223 @@
+// @vitest-environment jsdom
+
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AppNotConnected } from "./AppNotConnected";
+
+const listApplicationsMock = vi.hoisted(() => vi.fn());
+const listConnectionsMock = vi.hoisted(() => vi.fn());
+const listGalleryMock = vi.hoisted(() => vi.fn());
+const listConnectionActivityMock = vi.hoisted(() => vi.fn());
+const listActionRequestsMock = vi.hoisted(() => vi.fn());
+const updateApplicationMock = vi.hoisted(() => vi.fn());
+const mockAgentsList = vi.hoisted(() => vi.fn());
+const mockNavigate = vi.hoisted(() => vi.fn());
+const navigateComponentMock = vi.hoisted(() => vi.fn());
+const mockParams = vi.hoisted(() => ({ applicationId: "app-1", tab: "setup" as string | undefined }));
+
+vi.mock("@/api/tools", () => ({
+ toolsApi: {
+ listApplications: (companyId: string) => listApplicationsMock(companyId),
+ listConnections: (companyId: string) => listConnectionsMock(companyId),
+ listGallery: (companyId: string) => listGalleryMock(companyId),
+ listConnectionActivity: (connectionId: string, limit: number) =>
+ listConnectionActivityMock(connectionId, limit),
+ listActionRequests: (companyId: string, status: string) =>
+ listActionRequestsMock(companyId, status),
+ updateApplication: (applicationId: string, input: unknown) =>
+ updateApplicationMock(applicationId, input),
+ approveActionRequest: vi.fn(),
+ declineActionRequest: vi.fn(),
+ createTrustRuleFromActionRequest: vi.fn(),
+ },
+}));
+
+vi.mock("@/api/agents", () => ({
+ agentsApi: {
+ list: (companyId: string) => mockAgentsList(companyId),
+ },
+}));
+
+vi.mock("@/lib/router", () => ({
+ useParams: () => mockParams,
+ useNavigate: () => mockNavigate,
+ Navigate: ({ to, replace }: { to: string; replace?: boolean }) => {
+ navigateComponentMock({ to, replace });
+ return
;
+ },
+ Link: ({ to, children, ...props }: { to: string; children: React.ReactNode }) => (
+ {children}
+ ),
+}));
+
+vi.mock("@/context/CompanyContext", () => ({
+ useCompany: () => ({
+ selectedCompanyId: "company-1",
+ selectedCompany: { id: "company-1", name: "Paperclip" },
+ }),
+}));
+
+vi.mock("@/context/BreadcrumbContext", () => ({
+ useBreadcrumbs: () => ({ setBreadcrumbs: vi.fn() }),
+}));
+
+vi.mock("@/context/ToastContext", () => ({
+ useToast: () => ({ pushToast: vi.fn() }),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+async function act(callback: () => void | Promise) {
+ let result: void | Promise = undefined;
+ flushSync(() => {
+ result = callback();
+ });
+ await result;
+}
+
+async function flushReact() {
+ for (let i = 0; i < 3; i += 1) {
+ await act(async () => {
+ await Promise.resolve();
+ await new Promise((resolve) => window.setTimeout(resolve, 0));
+ });
+ }
+}
+
+function application(overrides: Record = {}) {
+ return {
+ id: "app-1",
+ companyId: "company-1",
+ applicationKey: "github",
+ name: "GitHub",
+ description: "Repository app",
+ type: "mcp_http",
+ status: "active",
+ pluginId: null,
+ ownerAgentId: null,
+ ownerUserId: null,
+ metadata: null,
+ archivedAt: null,
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ updatedAt: new Date("2026-01-01T00:00:00Z"),
+ ...overrides,
+ };
+}
+
+function connection(overrides: Record = {}) {
+ return {
+ id: "conn-old",
+ companyId: "company-1",
+ applicationId: "app-1",
+ name: "GitHub",
+ connectionKind: "managed",
+ transport: "remote_http",
+ status: "archived",
+ transportConfig: { url: "https://github.example/mcp" },
+ config: { url: "https://github.example/mcp" },
+ credentialSecretRefs: [],
+ credentialRefs: [],
+ healthStatus: "error",
+ healthMessage: "Token expired.",
+ healthCheckedAt: null,
+ lastError: null,
+ enabled: true,
+ lastUsedAt: new Date("2026-06-10T00:00:00Z"),
+ createdByAgentId: null,
+ createdByUserId: null,
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ updatedAt: new Date("2026-06-11T00:00:00Z"),
+ ...overrides,
+ };
+}
+
+describe("AppNotConnected", () => {
+ let container: HTMLDivElement;
+ let root: ReturnType;
+
+ beforeEach(() => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ mockParams.applicationId = "app-1";
+ mockParams.tab = "setup";
+ listApplicationsMock.mockResolvedValue({ applications: [application()] });
+ listConnectionsMock.mockResolvedValue({ connections: [connection()] });
+ listGalleryMock.mockResolvedValue({
+ apps: [{ key: "github", name: "GitHub", logoUrl: "https://example.test/github.png" }],
+ });
+ listConnectionActivityMock.mockResolvedValue({ events: [], issues: {}, actionRequests: {} });
+ listActionRequestsMock.mockResolvedValue({ actionRequests: [] });
+ mockAgentsList.mockResolvedValue([]);
+ updateApplicationMock.mockResolvedValue(application({ status: "archived" }));
+ });
+
+ afterEach(() => {
+ flushSync(() => root?.unmount());
+ container.remove();
+ document.body.innerHTML = "";
+ vi.clearAllMocks();
+ });
+
+ async function renderPage() {
+ const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+ root = createRoot(container);
+ await act(async () => {
+ root.render(
+
+ ,
+ );
+ });
+ await flushReact();
+ }
+
+ it("redirects the application root route to setup", async () => {
+ mockParams.tab = undefined;
+
+ await renderPage();
+
+ expect(navigateComponentMock).toHaveBeenCalledWith({ to: "/apps/app/app-1/setup", replace: true });
+ expect(listApplicationsMock).not.toHaveBeenCalled();
+ });
+
+ it("redirects to the connected app tab when a live connection exists", async () => {
+ mockParams.tab = "permissions";
+ listConnectionsMock.mockResolvedValue({
+ connections: [connection({ id: "conn-live", status: "active" })],
+ });
+
+ await renderPage();
+
+ expect(navigateComponentMock).toHaveBeenCalledWith({ to: "/apps/conn-live/permissions", replace: true });
+ });
+
+ it.each([
+ ["setup", "Reconnect this app"],
+ ["review", "Nothing is waiting for your OK right now."],
+ ["permissions", "Permissions paused"],
+ ["test", "Reconnect to test this app."],
+ ["activity", "No activity yet."],
+ ["advanced", "Danger zone"],
+ ])("renders the %s tab with persistent app identity", async (tab, expectedText) => {
+ mockParams.tab = tab;
+
+ await renderPage();
+
+ expect(container.textContent).toContain("GitHub");
+ expect(container.textContent).toContain("Not connected");
+ expect(container.textContent).toContain(expectedText);
+ });
+
+ it("keeps previous setup context on reconnect tabs", async () => {
+ mockParams.tab = "setup";
+
+ await renderPage();
+
+ expect(container.textContent).toContain("Previous setup");
+ expect(container.textContent).toContain("Last error: Token expired.");
+ expect(container.textContent).toContain("https://github.example/mcp");
+ });
+});
diff --git a/ui/src/pages/apps/AppNotConnected.tsx b/ui/src/pages/apps/AppNotConnected.tsx
new file mode 100644
index 00000000000..b3ed0820229
--- /dev/null
+++ b/ui/src/pages/apps/AppNotConnected.tsx
@@ -0,0 +1,371 @@
+import { useEffect, useMemo } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { ToolConnection } from "@paperclipai/shared";
+import { Navigate, useNavigate, useParams } from "@/lib/router";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { useToast } from "@/context/ToastContext";
+import { queryKeys } from "@/lib/queryKeys";
+import { timeAgo } from "@/lib/timeAgo";
+import { toolsApi } from "@/api/tools";
+import { agentsApi } from "@/api/agents";
+import { Button } from "@/components/ui/button";
+import { Skeleton } from "@/components/ui/skeleton";
+import { AppLogo } from "./AppLogo";
+import { connectionAddress, connectionTransportLabel, DangerZone } from "./AppDetail";
+import { ActivityPanel } from "./app-detail/ActivityPanel";
+import { ReviewPanel } from "./app-detail/ReviewPanel";
+import { appApplicationTabHref, appTabHref, appTabLabel, isAppTabKey, type AppTabKey } from "./app-tabs";
+
+export function AppNotConnected() {
+ const { applicationId = "", tab } = useParams<{ applicationId: string; tab?: string }>();
+ const navigate = useNavigate();
+ const queryClient = useQueryClient();
+ const { pushToast } = useToast();
+ const { selectedCompany, selectedCompanyId } = useCompany();
+ const { setBreadcrumbs } = useBreadcrumbs();
+ const activeTab: AppTabKey | null = isAppTabKey(tab) ? tab : null;
+
+ const applicationsQuery = useQuery({
+ queryKey: queryKeys.tools.applications(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listApplications(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+ const connectionsQuery = useQuery({
+ queryKey: queryKeys.tools.connections(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listConnections(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+ const galleryQuery = useQuery({
+ queryKey: queryKeys.apps.gallery(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listGallery(selectedCompanyId!),
+ enabled: !!selectedCompanyId && !!activeTab,
+ });
+
+ const application = useMemo(
+ () => (applicationsQuery.data?.applications ?? []).find((app) => app.id === applicationId),
+ [applicationsQuery.data, applicationId],
+ );
+ const appConnections = useMemo(
+ () => (connectionsQuery.data?.connections ?? []).filter((c) => c.applicationId === applicationId),
+ [connectionsQuery.data, applicationId],
+ );
+ const activeConnection = appConnections.find((c) => c.status !== "archived") ?? null;
+ const previousConnection = useMemo(() => latestArchivedConnection(appConnections), [appConnections]);
+ const activityQuery = useQuery({
+ queryKey: queryKeys.tools.connectionActivity(previousConnection?.id ?? "__none__"),
+ queryFn: () => toolsApi.listConnectionActivity(previousConnection!.id, 20),
+ enabled: !!previousConnection && activeTab === "activity",
+ });
+ const agentsQuery = useQuery({
+ queryKey: queryKeys.agents.list(selectedCompanyId ?? "__none__"),
+ queryFn: () => agentsApi.list(selectedCompanyId!),
+ enabled: !!selectedCompanyId && activeTab === "activity",
+ });
+
+ const appName = application?.name ?? "App";
+ useEffect(() => {
+ if (!activeTab) return;
+ setBreadcrumbs([
+ { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+ { label: "Apps", href: "/apps" },
+ { label: appName, href: appApplicationTabHref(applicationId, "setup") },
+ { label: appTabLabel(activeTab) },
+ ]);
+ return () => setBreadcrumbs([]);
+ }, [setBreadcrumbs, selectedCompany?.name, appName, applicationId, activeTab]);
+
+ const remove = useMutation({
+ mutationFn: () => toolsApi.updateApplication(applicationId, { status: "archived" }),
+ onSuccess: () => {
+ queryClient.invalidateQueries({ queryKey: queryKeys.tools.applications(selectedCompanyId ?? "__none__") });
+ pushToast({
+ title: "App removed",
+ body: `${appName} no longer shows in your apps. You can connect it again any time.`,
+ tone: "success",
+ });
+ navigate("/apps");
+ },
+ onError: (error) => {
+ pushToast({
+ title: "Couldn’t remove the app",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ });
+ },
+ });
+
+ if (!selectedCompanyId) {
+ return Select a company to manage apps.
;
+ }
+ if (!applicationId || !activeTab) {
+ return
+
+ );
+ }
+ if (!application) {
+ return (
+
+
This app doesn’t exist anymore.
+
navigate("/apps")}>Back to apps
+
+
+
+ {activeTab === "setup" && (
+
navigate(connectHref)}
+ />
+ )}
+ {activeTab === "review" && (
+ previousConnection ? (
+ remove.mutate()}
+ />
+ )}
+
+
+
+
+
+ {previousConnection ? "Reconnect this app" : "Connect this app"}
+
+
+ {previousConnection
+ ? "We kept the previous setup. Add a working key to bring it back online."
+ : "Agents can't use it until it's connected."}
+
+
+
+ {previousConnection ? "Reconnect" : "Connect"}
+
+
+
+ {previousConnection && (
+
+ )}
+
+ Previous setup
+ {connection.healthMessage && (
+
+ Last error: {connection.healthMessage}
+
+ )}
+
+ Address
+ {previousAddress}
+ Connection type
+ {connectionTransportLabel(connection.transport)}
+ Last used
+
+ {connection.lastUsedAt ? timeAgo(connection.lastUsedAt) : "Never"}
+
+
+
+ );
+}
+
+function PermissionsTab({ previousConnection }: { previousConnection: ToolConnection | null }) {
+ return (
+
+ Permissions paused
+
+ Reconnect this app to edit who can use it and which actions need a human first.
+
+ {previousConnection && (
+
+ Previous setup is retained for reconnect, but access controls stay read-only until the app is online.
+
+ )}
+
+ );
+}
+
+function AdvancedTab({
+ appName,
+ previousConnection,
+ previousAddress,
+ removing,
+ onRemove,
+}: {
+ appName: string;
+ previousConnection: ToolConnection | null;
+ previousAddress: string | null;
+ removing: boolean;
+ onRemove: () => void;
+}) {
+ return (
+
+ {previousConnection ? (
+
+ ) : (
+
+ )}
+
+
) {
+ let result: void | Promise = undefined;
+ flushSync(() => {
+ result = callback();
+ });
+ await result;
+}
+
+async function flushReact() {
+ await act(async () => {
+ await Promise.resolve();
+ await new Promise((resolve) => window.setTimeout(resolve, 0));
+ });
+}
+
+function setInputValue(input: HTMLInputElement, value: string) {
+ const setter = Object.getOwnPropertyDescriptor(
+ window.HTMLInputElement.prototype,
+ "value",
+ )?.set;
+ setter?.call(input, value);
+ input.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+function setTextareaValue(textarea: HTMLTextAreaElement, value: string) {
+ const setter = Object.getOwnPropertyDescriptor(
+ window.HTMLTextAreaElement.prototype,
+ "value",
+ )?.set;
+ setter?.call(textarea, value);
+ textarea.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+function buttonByText(text: string): HTMLButtonElement | undefined {
+ return Array.from(document.body.querySelectorAll("button")).find(
+ (b) => b.textContent?.trim() === text,
+ ) as HTMLButtonElement | undefined;
+}
+
+function buttonContaining(text: string): HTMLButtonElement | undefined {
+ return Array.from(document.body.querySelectorAll("button")).find(
+ (b) => b.textContent?.includes(text),
+ ) as HTMLButtonElement | undefined;
+}
+
+async function gotoLinkFrame(container: HTMLDivElement, url: string) {
+ const linkInput = Array.from(
+ container.querySelectorAll("input"),
+ ).find((i) => i.getAttribute("placeholder")?.startsWith("https://"));
+ expect(linkInput).toBeTruthy();
+ await act(async () => setInputValue(linkInput!, url));
+ await flushReact();
+ await act(async () => {
+ buttonByText("Continue")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+}
+
+describe("AppsConnect — Connect with a link (M4 frame)", () => {
+ let container: HTMLDivElement;
+
+ beforeEach(() => {
+ mockSearch.value = "";
+ mockParams.appKey = undefined;
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ listGalleryMock.mockResolvedValue({
+ apps: [
+ {
+ key: "zapier",
+ name: "Zapier",
+ tagline: "Automate things",
+ authKind: "api_key",
+ urlPatterns: ["https://zapier.com/*", "https://*.zapier.com/*"],
+ logoUrl: null,
+ credentialFields: [{ configPath: "credentials.authorization", label: "API key", required: true }],
+ },
+ ],
+ });
+ finishAppMock.mockResolvedValue({});
+ putConnectionInstallsMock.mockResolvedValue({ connectionId: "conn-1", installs: [] });
+ connectAppMock.mockResolvedValue({
+ connectionId: "conn-1",
+ application: { id: "app-1", name: "example.com" },
+ actions: { readOnly: [], canMakeChanges: [] },
+ catalog: [],
+ suggestedDefaults: {},
+ });
+ listAgentsMock.mockResolvedValue([
+ { id: "agent-1", name: "Ada", title: "CTO", status: "active", icon: "Bot" },
+ { id: "agent-2", name: "Grace", title: "Engineer", status: "active", icon: "Code" },
+ ]);
+ });
+
+ afterEach(() => {
+ document.body.removeChild(container);
+ document.body.innerHTML = "";
+ vi.clearAllMocks();
+ });
+
+ async function render() {
+ const root = createRoot(container);
+ const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+ await act(async () => {
+ root.render(
+
+ ,
+ );
+ });
+ await flushReact();
+ await flushReact();
+ return root;
+ }
+
+ it("an unrecognized URL routes to a frame with the URL, defaulted Name, and a Yes/No toggle", async () => {
+ await render();
+ await gotoLinkFrame(container, "https://www.example.com/actions");
+
+ expect(container.textContent).toContain("Connect with a link");
+ expect(container.textContent).toContain("https://www.example.com/actions");
+ expect(container.textContent).toContain("Does it need a key?");
+ expect(buttonByText("No")).toBeTruthy();
+ expect(buttonByText("Yes")).toBeTruthy();
+
+ // Name is auto-filled from the host with www. stripped.
+ const nameInput = Array.from(container.querySelectorAll("input")).find(
+ (i) => i.getAttribute("placeholder") === "My app",
+ );
+ expect(nameInput?.value).toBe("example.com");
+ });
+
+ it("opens the selected app directly on its setup route", async () => {
+ mockParams.appKey = "zapier";
+ await render();
+
+ expect(container.textContent).toContain("Connect Zapier");
+ expect(container.textContent).not.toContain("Pick the app you want your agents to use.");
+ });
+
+ it("choosing No and clicking Check link connects with no credentials", async () => {
+ await render();
+ await gotoLinkFrame(container, "https://www.example.com/actions");
+
+ await act(async () => {
+ buttonByText("Check link")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input).toMatchObject({ link: "https://www.example.com/actions", name: "example.com" });
+ expect(input.credentialValues).toBeUndefined();
+ });
+
+ it("choosing Yes reveals one masked key field plus the lock reassurance", async () => {
+ await render();
+ await gotoLinkFrame(container, "https://www.example.com/actions");
+
+ // No key field while No is selected.
+ expect(
+ Array.from(container.querySelectorAll("input")).some(
+ (i) => i.type === "password",
+ ),
+ ).toBe(false);
+
+ await act(async () => {
+ buttonByText("Yes")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ const passwordInputs = Array.from(
+ container.querySelectorAll("input"),
+ ).filter((i) => i.type === "password");
+ expect(passwordInputs).toHaveLength(1);
+ expect(container.textContent).toContain("Your key is stored securely.");
+
+ await act(async () => setInputValue(passwordInputs[0], "secret-key"));
+ await flushReact();
+
+ await act(async () => {
+ buttonByText("Check link")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input.credentialValues).toEqual({ "credentials.authorization": "secret-key" });
+ });
+
+ it("a Zapier MCP URL stays in the URL flow and includes its token in the submitted link", async () => {
+ await render();
+
+ const linkInput = Array.from(
+ container.querySelectorAll("input"),
+ ).find((i) => i.getAttribute("placeholder")?.startsWith("https://"));
+ const zapierUrl = "https://mcp.zapier.com/api/v1/connect?token=secret-token";
+ await act(async () => setInputValue(linkInput!, zapierUrl));
+ await flushReact();
+
+ expect(container.textContent).toContain("This looks like Zapier.");
+
+ await act(async () => {
+ buttonByText("Continue")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("Connect with a link");
+ expect(container.textContent).toContain(zapierUrl);
+ expect(nameInputFrom(container)?.value).toBe("Zapier");
+ expect(container.querySelector('input[type="password"]')).toBeNull();
+
+ await act(async () => {
+ buttonByText("Check link")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ expect(connectAppMock.mock.calls[0]?.[1]).toMatchObject({ link: zapierUrl, name: "Zapier" });
+ expect(connectAppMock.mock.calls[0]?.[1].credentialValues).toBeUndefined();
+ });
+
+ it("keeps Zapier visible and uses the compact agent multi-selector throughout its wizard", async () => {
+ mockSearch.value = "byo=1&source=zapier";
+ listGalleryMock.mockResolvedValueOnce({
+ apps: [
+ {
+ key: "zapier",
+ name: "Zapier",
+ tagline: "Automate things",
+ authKind: "api_key",
+ urlPatterns: ["https://zapier.com/*", "https://*.zapier.com/*"],
+ logoUrl: "https://example.com/zapier.png",
+ credentialFields: [],
+ },
+ ],
+ });
+ connectAppMock.mockResolvedValueOnce({
+ connectionId: "conn-1",
+ application: { id: "app-1", name: "Zapier" },
+ actions: {
+ readOnly: [
+ {
+ catalogEntryId: "action-1",
+ toolName: "find_record",
+ title: "Find record",
+ description: "Find a record.",
+ riskLevel: "read",
+ },
+ ],
+ canMakeChanges: [],
+ },
+ catalog: [],
+ suggestedDefaults: {},
+ });
+ await render();
+
+ expect(container.textContent).toContain("Step 1 of 4");
+ expect(container.textContent).toContain("Connect Zapier");
+ expect(container.textContent).toContain("Add MCP URL");
+ expect(container.querySelector('img[src="https://example.com/zapier.png"]')).toBeTruthy();
+ expect(container.textContent).not.toContain("Pick the app you want your agents to use.");
+ expect(container.textContent).not.toContain("More ways to connect");
+
+ const linkInput = container.querySelector(
+ 'input[placeholder^="https://mcp.zapier.com"]',
+ );
+ const zapierUrl = "https://mcp.zapier.com/api/v1/connect?token=secret-token";
+ await act(async () => setInputValue(linkInput!, zapierUrl));
+ await flushReact();
+
+ await act(async () => {
+ buttonByText("Check link")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ expect(connectAppMock.mock.calls[0]?.[1]).toMatchObject({ link: zapierUrl, name: "Zapier" });
+ expect(container.textContent).toContain("Step 2 of 4");
+ expect(container.querySelector('img[src="https://example.com/zapier.png"]')).toBeTruthy();
+
+ await act(async () => {
+ buttonByText("Continue with 1 action on")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("Step 3 of 4");
+ expect(container.querySelector('img[src="https://example.com/zapier.png"]')).toBeTruthy();
+
+ await act(async () => {
+ buttonContaining("Only specific agents")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("Select agents");
+ expect(container.textContent).not.toContain("Ada");
+ expect(container.textContent).not.toContain("Grace");
+
+ await act(async () => {
+ buttonByText("Select agents")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(document.body.textContent).toContain("Ada");
+ expect(document.body.textContent).toContain("Grace");
+
+ const adaCheckbox = document.body.querySelector('[aria-label="Allow Ada"]');
+ await act(async () => {
+ adaCheckbox?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+ await act(async () => {
+ buttonByText("Done")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("1 agent selected");
+ expect(container.textContent).not.toContain("Grace");
+
+ await act(async () => {
+ buttonByText("Continue to install")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("Step 4 of 4");
+ expect(container.textContent).toContain("Install Zapier tools?");
+ expect(container.textContent).toContain("Not yet");
+
+ await act(async () => {
+ buttonContaining("Specific agents")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("1 agent selected");
+ await act(async () => {
+ buttonByText("Finish setup")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(finishAppMock).toHaveBeenCalledWith("company-1", "conn-1", {
+ enabledCatalogEntryIds: ["action-1"],
+ askFirstCatalogEntryIds: [],
+ access: { agentIds: ["agent-1"] },
+ });
+ expect(putConnectionInstallsMock).toHaveBeenCalledWith("conn-1", [
+ { targetType: "agent", targetId: "agent-1" },
+ ]);
+ });
+
+ // PAP-10922: "Run your own" / "Paste a config" moved from the sidebar to rows
+ // under "Connect with a link" on the gallery step.
+ it("offers 'Run your own' and 'Paste a config' rows that route into the Advanced door", async () => {
+ await render();
+
+ expect(container.textContent).toContain("More ways to connect");
+
+ const buttonContaining = (text: string) =>
+ Array.from(container.querySelectorAll("button")).find((b) =>
+ b.textContent?.includes(text),
+ );
+
+ await act(async () => {
+ buttonContaining("Run your own")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ expect(mockNavigate).toHaveBeenCalledWith("/apps/advanced");
+
+ await act(async () => {
+ buttonContaining("Paste a config")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ expect(mockNavigate).toHaveBeenCalledWith("/apps/advanced/paste-config");
+ });
+
+ // PAP-11091: discoverability copy for remote MCP URLs — the link field
+ // advertises that any remote tool URL (incl. a local MCP server) works. Per
+ // the UX re-review, the localhost example lives in the body copy (legible at
+ // every viewport) rather than the placeholder, which truncated on mobile.
+ it("advertises that remote/local MCP URLs work under 'Connect with a link'", async () => {
+ await render();
+
+ expect(container.textContent).toContain(
+ "Any remote tool URL works here — including a local MCP server like",
+ );
+ expect(container.textContent).toContain("http://127.0.0.1:8848/mcp");
+ const linkInput = Array.from(container.querySelectorAll("input")).find((i) =>
+ i.getAttribute("placeholder")?.startsWith("https://example.com/actions"),
+ );
+ // Placeholder stays a single, short example so it never truncates.
+ expect(linkInput?.getAttribute("placeholder")).toBe("https://example.com/actions");
+ });
+
+ // Reconnect from the app page: ?link/?name/?applicationId prefill skips the
+ // gallery and re-attaches the connection to the existing application.
+ it("prefills the link frame from search params and passes applicationId to connect", async () => {
+ mockSearch.value =
+ "link=https%3A%2F%2Fwww.example.com%2Factions&name=Bla&applicationId=app-77";
+ await render();
+
+ expect(container.textContent).toContain("Connect with a link");
+ expect(container.textContent).toContain("https://www.example.com/actions");
+ const nameInput = Array.from(container.querySelectorAll("input")).find(
+ (i) => i.getAttribute("placeholder") === "My app",
+ );
+ expect(nameInput?.value).toBe("Bla");
+
+ await act(async () => {
+ buttonByText("Check link")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input).toMatchObject({
+ link: "https://www.example.com/actions",
+ name: "Bla",
+ applicationId: "app-77",
+ });
+ });
+
+ it("shows the Google Sheets robot email and keeps empty sheet links from continuing", async () => {
+ listGalleryMock.mockResolvedValueOnce({
+ apps: [
+ {
+ key: "google-sheets",
+ name: "Google Sheets",
+ tagline: "Read and update selected spreadsheets.",
+ authKind: "none",
+ urlPatterns: ["https://docs.google.com/spreadsheets/*"],
+ logoUrl: "https://example.com/sheets.png",
+ credentialFields: [],
+ availability: { available: true, robotEmail: "robot@paperclip.iam.gserviceaccount.com" },
+ },
+ ],
+ });
+ await render();
+
+ await act(async () => {
+ buttonContaining("Google Sheets")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("Share each sheet with this email");
+ expect(container.textContent).toContain("robot@paperclip.iam.gserviceaccount.com");
+ expect(container.textContent).toContain(
+ "In Google Sheets, click Share and add this email as an Editor. Then paste the sheet links below.",
+ );
+ expect(buttonByText("Connect")?.disabled).toBe(true);
+ });
+
+ it("shows inline validation for invalid Google Sheets links", async () => {
+ listGalleryMock.mockResolvedValueOnce({
+ apps: [
+ {
+ key: "google-sheets",
+ name: "Google Sheets",
+ tagline: "Read and update selected spreadsheets.",
+ authKind: "none",
+ urlPatterns: ["https://docs.google.com/spreadsheets/*"],
+ logoUrl: "https://example.com/sheets.png",
+ credentialFields: [],
+ availability: { available: true, robotEmail: "robot@paperclip.iam.gserviceaccount.com" },
+ },
+ ],
+ });
+ await render();
+
+ await act(async () => {
+ buttonContaining("Google Sheets")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+ const textarea = container.querySelector("textarea");
+ await act(async () => setTextareaValue(textarea!, "https://example.com/not-a-sheet"));
+ await flushReact();
+ await act(async () => {
+ buttonByText("Connect")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("That doesn't look like a Google Sheets link.");
+ expect(connectAppMock).not.toHaveBeenCalled();
+ });
+
+ // PAP-11283: the gallery step exposes a Name field (default = app name) so a
+ // connection can be named at create time, matching the link flow.
+ function nameInputFrom(root: HTMLDivElement): HTMLInputElement | undefined {
+ return Array.from(root.querySelectorAll("input")).find(
+ (i) => i.getAttribute("placeholder") === "My app",
+ );
+ }
+
+ it("gallery key step defaults the Name field to the app name", async () => {
+ await render();
+
+ await act(async () => {
+ buttonContaining("Zapier")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(container.textContent).toContain("Connect Zapier");
+ expect(nameInputFrom(container)?.value).toBe("Zapier");
+ expect(mockNavigate).toHaveBeenCalledWith("/apps/connect?byo=1&appKey=zapier&stage=setup");
+ });
+
+ it("returns from an app key step to the BYO gallery", async () => {
+ mockSearch.value = "byo=1";
+ mockParams.appKey = "zapier";
+ await render();
+
+ await act(async () => {
+ buttonByText("Back")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+
+ expect(mockNavigate).toHaveBeenCalledWith("/apps/connect?byo=1");
+ });
+
+ it("leaving the default name connects with the app name", async () => {
+ await render();
+
+ await act(async () => {
+ buttonContaining("Zapier")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ const keyField = container.querySelector("input[type=password]");
+ await act(async () => setInputValue(keyField!, "secret-key"));
+ await flushReact();
+ await act(async () => {
+ buttonByText("Connect")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ expect(mockNavigate).toHaveBeenCalledWith("/apps/connect?byo=1&appKey=zapier&stage=actions");
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input).toMatchObject({ galleryKey: "zapier", name: "Zapier" });
+ });
+
+ it("a custom name in the gallery step is sent to the connect mutation", async () => {
+ await render();
+
+ await act(async () => {
+ buttonContaining("Zapier")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ await act(async () => setInputValue(nameInputFrom(container)!, "Zapier (stdio smoke)"));
+ const keyField = container.querySelector("input[type=password]");
+ await act(async () => setInputValue(keyField!, "secret-key"));
+ await flushReact();
+ await act(async () => {
+ buttonByText("Connect")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input).toMatchObject({ galleryKey: "zapier", name: "Zapier (stdio smoke)" });
+ });
+
+ it("a custom name on the Google Sheets step is sent to the connect mutation", async () => {
+ listGalleryMock.mockResolvedValueOnce({
+ apps: [
+ {
+ key: "google-sheets",
+ name: "Google Sheets",
+ tagline: "Read and update selected spreadsheets.",
+ authKind: "none",
+ urlPatterns: ["https://docs.google.com/spreadsheets/*"],
+ logoUrl: "https://example.com/sheets.png",
+ credentialFields: [],
+ availability: { available: true, robotEmail: "robot@paperclip.iam.gserviceaccount.com" },
+ },
+ ],
+ });
+ await render();
+
+ await act(async () => {
+ buttonContaining("Google Sheets")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ // Default is the app name.
+ expect(nameInputFrom(container)?.value).toBe("Google Sheets");
+ await act(async () => setInputValue(nameInputFrom(container)!, "Google Sheets (stdio smoke)"));
+ const textarea = container.querySelector("textarea");
+ await act(async () =>
+ setTextareaValue(textarea!, "https://docs.google.com/spreadsheets/d/sheet_123/edit"),
+ );
+ await flushReact();
+ await act(async () => {
+ buttonByText("Connect")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input).toMatchObject({
+ galleryKey: "google-sheets",
+ name: "Google Sheets (stdio smoke)",
+ configValues: { allowedSpreadsheetIds: ["sheet_123"] },
+ });
+ });
+
+ it("passes parsed Google Sheets IDs as connection config values", async () => {
+ listGalleryMock.mockResolvedValueOnce({
+ apps: [
+ {
+ key: "google-sheets",
+ name: "Google Sheets",
+ tagline: "Read and update selected spreadsheets.",
+ authKind: "none",
+ urlPatterns: ["https://docs.google.com/spreadsheets/*"],
+ logoUrl: "https://example.com/sheets.png",
+ credentialFields: [],
+ availability: { available: true, robotEmail: "robot@paperclip.iam.gserviceaccount.com" },
+ },
+ ],
+ });
+ await render();
+
+ await act(async () => {
+ buttonContaining("Google Sheets")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+ const textarea = container.querySelector("textarea");
+ await act(async () =>
+ setTextareaValue(
+ textarea!,
+ "https://docs.google.com/spreadsheets/d/sheet_123/edit\nhttps://docs.google.com/spreadsheets/d/sheet_456",
+ )
+ );
+ await flushReact();
+ await act(async () => {
+ buttonByText("Connect")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ });
+ await flushReact();
+
+ expect(connectAppMock).toHaveBeenCalledTimes(1);
+ const [, input] = connectAppMock.mock.calls[0];
+ expect(input).toMatchObject({
+ galleryKey: "google-sheets",
+ configValues: { allowedSpreadsheetIds: ["sheet_123", "sheet_456"] },
+ });
+ });
+});
diff --git a/ui/src/pages/apps/AppsConnect.tsx b/ui/src/pages/apps/AppsConnect.tsx
new file mode 100644
index 00000000000..227f68ff227
--- /dev/null
+++ b/ui/src/pages/apps/AppsConnect.tsx
@@ -0,0 +1,1645 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+ ArrowUpRight,
+ Check,
+ ChevronRight,
+ Copy,
+ ClipboardPaste,
+ Link2,
+ Loader2,
+ Lock,
+ Search,
+ TerminalSquare,
+} from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+import type {
+ Agent,
+ AppGalleryEntry,
+ ConnectToolAppResult,
+ ToolAppConnectionActionSummary,
+} from "@paperclipai/shared";
+import { getToolAppGalleryEntryForUrl } from "@paperclipai/shared";
+import { useNavigate, useParams, useSearchParams } from "@/lib/router";
+import { useCompany } from "@/context/CompanyContext";
+import { useBreadcrumbs } from "@/context/BreadcrumbContext";
+import { useToast } from "@/context/ToastContext";
+import { queryKeys } from "@/lib/queryKeys";
+import { ApiError } from "@/api/client";
+import { toolsApi } from "@/api/tools";
+import { agentsApi } from "@/api/agents";
+import { appCopyFor, credentialFieldLabel } from "@/lib/app-gallery-copy";
+import { advancedTabHref } from "@/pages/tools/tool-tabs";
+import { AgentIcon } from "@/components/AgentIconPicker";
+import { AgentMultiSelect } from "@/components/AgentMultiSelect";
+import { InlineBanner } from "@/components/InlineBanner";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { ToggleSwitch } from "@/components/ui/toggle-switch";
+import { Skeleton } from "@/components/ui/skeleton";
+import { cn } from "@/lib/utils";
+import { AppLogo } from "./AppLogo";
+import { parseGoogleSheetIds } from "./google-sheets";
+import { autoExtendNotice, INSTALL_ALL_WARNING, installInfoNotice, installPayload } from "@/lib/tool-installs";
+
+type Step = "gallery" | "key" | "actions" | "who" | "install" | "success";
+
+const ROUTE_STAGE_BY_STEP: Partial> = {
+ key: "setup",
+ actions: "actions",
+ who: "access",
+ install: "install",
+ success: "complete",
+};
+
+function appConnectHref(appKey: string, step: Step): string {
+ const stage = ROUTE_STAGE_BY_STEP[step] ?? "setup";
+ const params = new URLSearchParams({ byo: "1", appKey, stage });
+ return `/apps/connect?${params.toString()}`;
+}
+type AppAccessSelection = "all_agents" | { agentIds: string[] };
+type InstallMode = "none" | "specific" | "all";
+const LINK_CREDENTIAL_CONFIG_PATH = "credentials.authorization";
+
+const STEP_LABELS = ["Pick app", "Add your key", "Choose actions", "Choose access", "Install tools"];
+const STEP_INDEX: Record, number> = {
+ gallery: 0,
+ key: 1,
+ actions: 2,
+ who: 3,
+ install: 4,
+};
+const ZAPIER_STEP_INDEX: Record, number> = {
+ key: 0,
+ actions: 1,
+ who: 2,
+ install: 3,
+};
+const ZAPIER_STEP_LABELS = ["Add MCP URL", "Choose actions", "Choose access", "Install tools"];
+
+function askFirstLevelsFrom(result: ConnectToolAppResult): string[] {
+ const raw = (result.suggestedDefaults as { askFirstRiskLevels?: unknown })?.askFirstRiskLevels;
+ return Array.isArray(raw) ? raw.filter((x): x is string => typeof x === "string") : ["write", "destructive"];
+}
+
+function isGoogleSheetsEntry(entry: AppGalleryEntry | null): boolean {
+ return entry?.key === "google-sheets";
+}
+
+export function AppsConnect() {
+ const navigate = useNavigate();
+ const routeParams = useParams<{ appKey?: string }>();
+ const { selectedCompany, selectedCompanyId } = useCompany();
+ const { setBreadcrumbs } = useBreadcrumbs();
+ const { pushToast } = useToast();
+ const [searchParams] = useSearchParams();
+ const appKey = routeParams.appKey ?? searchParams.get("appKey") ?? undefined;
+ const zapierSource = searchParams.get("source") === "zapier";
+
+ // Prefill arrives from the app page for reconnects; read once so later
+ // wizard navigation doesn't fight the URL.
+ const [prefill] = useState(() => {
+ const rawLink = searchParams.get("link")?.trim() ?? "";
+ return {
+ link: /^https?:\/\//i.test(rawLink) ? rawLink : "",
+ name: searchParams.get("name")?.trim() ?? "",
+ applicationId: searchParams.get("applicationId")?.trim() || undefined,
+ };
+ });
+
+ const [step, setStep] = useState(appKey || prefill.link || zapierSource ? "key" : "gallery");
+ const [entry, setEntry] = useState(null);
+ const [galleryName, setGalleryName] = useState("");
+ const [linkUrl, setLinkUrl] = useState(prefill.link);
+ const [linkName, setLinkName] = useState(prefill.name || (zapierSource ? "Zapier" : ""));
+ const [linkNeedsKey, setLinkNeedsKey] = useState(false);
+ const [linkKey, setLinkKey] = useState("");
+ const [credentials, setCredentials] = useState>({});
+ const [googleSheetsLinks, setGoogleSheetsLinks] = useState("");
+ const [googleSheetsError, setGoogleSheetsError] = useState(null);
+ const [connectResult, setConnectResult] = useState(null);
+ const [enabled, setEnabled] = useState>({});
+ const [access, setAccess] = useState<"all" | "specific">("all");
+ const [agentIds, setAgentIds] = useState>(new Set());
+ const [installMode, setInstallMode] = useState("none");
+ const [installAgentIds, setInstallAgentIds] = useState>(new Set());
+
+ const openGallery = () => {
+ setEntry(null);
+ setGalleryName("");
+ setLinkUrl("");
+ setLinkName("");
+ setLinkNeedsKey(false);
+ setLinkKey("");
+ setCredentials({});
+ setGoogleSheetsLinks("");
+ setGoogleSheetsError(null);
+ setConnectResult(null);
+ setInstallMode("none");
+ setInstallAgentIds(new Set());
+ setStep("gallery");
+ navigate("/apps/connect?byo=1");
+ };
+
+ useEffect(() => {
+ setBreadcrumbs([
+ { label: selectedCompany?.name ?? "Company", href: "/dashboard" },
+ { label: "Apps", href: "/apps" },
+ { label: "Connect an app" },
+ ]);
+ return () => setBreadcrumbs([]);
+ }, [setBreadcrumbs, selectedCompany?.name]);
+
+ const galleryQuery = useQuery({
+ queryKey: queryKeys.apps.gallery(selectedCompanyId ?? "__none__"),
+ queryFn: () => toolsApi.listGallery(selectedCompanyId!),
+ enabled: !!selectedCompanyId,
+ });
+
+ useEffect(() => {
+ if (!appKey || galleryQuery.isLoading || !galleryQuery.data) return;
+
+ const requestedEntry = galleryQuery.data.apps.find((candidate) => candidate.key === appKey);
+ if (!requestedEntry || requestedEntry.authKind === "oauth" || requestedEntry.availability?.available === false) {
+ setEntry(null);
+ setStep("gallery");
+ navigate("/apps/connect", { replace: true });
+ return;
+ }
+
+ if (entry?.key !== requestedEntry.key) {
+ setEntry(requestedEntry);
+ setGalleryName(requestedEntry.name);
+ setLinkUrl("");
+ setLinkName("");
+ setLinkNeedsKey(false);
+ setLinkKey("");
+ setCredentials({});
+ setGoogleSheetsLinks("");
+ setGoogleSheetsError(null);
+ setConnectResult(null);
+ }
+ setInstallMode("none");
+ setInstallAgentIds(new Set());
+ setStep("key");
+ }, [appKey, entry?.key, galleryQuery.data, galleryQuery.isLoading, navigate]);
+
+ const setAppStep = (nextStep: Step) => {
+ setStep(nextStep);
+ if (entry) navigate(appConnectHref(entry.key, nextStep));
+ };
+
+ const connectMutation = useMutation({
+ mutationFn: () => {
+ if (entry) {
+ const sheetIds = isGoogleSheetsEntry(entry) ? parseGoogleSheetIds(googleSheetsLinks).ids : [];
+ const trimmedGalleryName = galleryName.trim();
+ return toolsApi.connectApp(selectedCompanyId!, {
+ galleryKey: entry.key,
+ name: trimmedGalleryName || undefined,
+ credentialValues: credentials,
+ configValues: isGoogleSheetsEntry(entry) ? { allowedSpreadsheetIds: sheetIds } : undefined,
+ applicationId: prefill.applicationId,
+ });
+ }
+ const trimmedKey = linkNeedsKey ? linkKey.trim() : "";
+ const trimmedName = linkName.trim();
+ return toolsApi.connectApp(selectedCompanyId!, {
+ link: linkUrl,
+ name: trimmedName || undefined,
+ credentialValues: trimmedKey ? { [LINK_CREDENTIAL_CONFIG_PATH]: trimmedKey } : undefined,
+ applicationId: prefill.applicationId,
+ });
+ },
+ onSuccess: (result) => {
+ setConnectResult(result);
+ const defaults: Record = {};
+ for (const a of result.actions.readOnly) defaults[a.catalogEntryId] = true;
+ for (const a of result.actions.canMakeChanges) defaults[a.catalogEntryId] = false;
+ setEnabled(defaults);
+ setInstallMode("none");
+ setInstallAgentIds(new Set());
+ setAppStep("actions");
+ },
+ onError: (error) => {
+ const details = error instanceof ApiError && error.body && typeof error.body === "object"
+ ? (error.body as { details?: { code?: unknown } }).details
+ : null;
+ const oauthRequired = details?.code === "oauth_challenge";
+ pushToast({
+ title: oauthRequired ? "Sign-in required" : "Couldn’t connect",
+ body: oauthRequired
+ ? "This app needs you to sign in - coming soon."
+ : error instanceof Error
+ ? error.message
+ : "Please check your key and try again.",
+ tone: "error",
+ });
+ },
+ });
+
+ const finishMutation = useMutation({
+ mutationFn: async () => {
+ const askFirstLevels = connectResult ? askFirstLevelsFrom(connectResult) : [];
+ const changeActions = connectResult?.actions.canMakeChanges ?? [];
+ const enabledIds = Object.entries(enabled)
+ .filter(([, on]) => on)
+ .map(([id]) => id);
+ const askFirstIds = changeActions
+ .filter((a) => enabled[a.catalogEntryId] && askFirstLevels.includes(a.riskLevel))
+ .map((a) => a.catalogEntryId);
+ const selection: AppAccessSelection =
+ access === "all" ? "all_agents" : { agentIds: Array.from(agentIds) };
+ const result = await toolsApi.finishApp(selectedCompanyId!, connectResult!.connectionId, {
+ enabledCatalogEntryIds: enabledIds,
+ askFirstCatalogEntryIds: askFirstIds,
+ access: selection,
+ });
+ const installState = installMode === "all"
+ ? { onAll: true, agentIds: new Set() }
+ : { onAll: false, agentIds: installMode === "specific" ? installAgentIds : new Set() };
+ await toolsApi.putConnectionInstalls(
+ connectResult!.connectionId,
+ installPayload(selectedCompanyId!, installState),
+ );
+ return result;
+ },
+ onSuccess: () => setAppStep("success"),
+ onError: (error) => {
+ pushToast({
+ title: "Couldn’t finish setup",
+ body: error instanceof Error ? error.message : "Please try again.",
+ tone: "error",
+ });
+ },
+ });
+
+ if (!selectedCompanyId) {
+ return Select a company to connect apps.
;
+ }
+
+ const appName =
+ connectResult?.application.name ??
+ entry?.name ??
+ (linkName.trim() || defaultLinkName(linkUrl) || "this app");
+ const zapierEntry = zapierSource
+ ? galleryQuery.data?.apps.find((app) => app.key === "zapier") ?? null
+ : null;
+ const stepLabels = zapierSource
+ ? ZAPIER_STEP_LABELS
+ : isGoogleSheetsEntry(entry)
+ ? ["Pick app", "Share sheet", "Choose actions", "Choose access", "Install tools"]
+ : STEP_LABELS;
+ const stepIndex = zapierSource && step !== "gallery" && step !== "success"
+ ? ZAPIER_STEP_INDEX[step]
+ : step === "success"
+ ? stepLabels.length
+ : STEP_INDEX[step];
+
+ return (
+
+ {step !== "success" && (
+
navigate(zapierSource ? "/apps/browse" : "/apps")}
+ />
+ )}
+
+ {step === "gallery" && (
+ {
+ setEntry(picked);
+ setGalleryName(picked.name);
+ setLinkUrl("");
+ setLinkName("");
+ setLinkNeedsKey(false);
+ setLinkKey("");
+ setCredentials({});
+ setGoogleSheetsLinks("");
+ setGoogleSheetsError(null);
+ setConnectResult(null);
+ setInstallMode("none");
+ setInstallAgentIds(new Set());
+ setStep("key");
+ navigate(appConnectHref(picked.key, "key"));
+ }}
+ onUseLink={(url) => {
+ const matchedEntry = getToolAppGalleryEntryForUrl(url, galleryQuery.data?.apps ?? []);
+ setEntry(null);
+ setGalleryName("");
+ setLinkUrl(url);
+ setLinkName(matchedEntry?.name ?? defaultLinkName(url) ?? "");
+ setLinkNeedsKey(false);
+ setLinkKey("");
+ setCredentials({});
+ setGoogleSheetsLinks("");
+ setGoogleSheetsError(null);
+ setInstallMode("none");
+ setInstallAgentIds(new Set());
+ setStep("key");
+ }}
+ onRunYourOwn={() => navigate(advancedTabHref("run-your-own"))}
+ onPasteConfig={() => navigate(advancedTabHref("paste-config"))}
+ />
+ )}
+
+ {step === "key" && entry && (
+ {
+ setGoogleSheetsLinks(next);
+ setGoogleSheetsError(null);
+ }}
+ submitting={connectMutation.isPending}
+ onBack={openGallery}
+ onConnect={() => {
+ if (isGoogleSheetsEntry(entry)) {
+ const parsed = parseGoogleSheetIds(googleSheetsLinks);
+ if (parsed.invalidCount > 0) {
+ setGoogleSheetsError("That doesn't look like a Google Sheets link.");
+ return;
+ }
+ if (parsed.ids.length === 0) {
+ setGoogleSheetsError("Paste at least one Google Sheets link.");
+ return;
+ }
+ }
+ connectMutation.mutate();
+ }}
+ />
+ )}
+
+ {step === "key" && !entry && linkUrl && !zapierSource && (
+ {
+ setLinkNeedsKey(next);
+ if (!next) setLinkKey("");
+ }}
+ keyValue={linkKey}
+ onKeyChange={setLinkKey}
+ submitting={connectMutation.isPending}
+ onBack={() => setStep("gallery")}
+ onConnect={() => connectMutation.mutate()}
+ />
+ )}
+
+ {step === "key" && !entry && zapierSource && (
+ navigate("/apps/browse")}
+ onConnect={() => connectMutation.mutate()}
+ />
+ )}
+
+ {step === "actions" && connectResult && (
+ setEnabled((prev) => ({ ...prev, [id]: on }))}
+ onBulk={(ids, on) =>
+ setEnabled((prev) => {
+ const next = { ...prev };
+ for (const id of ids) next[id] = on;
+ return next;
+ })
+ }
+ onBack={() => setAppStep("key")}
+ onContinue={() => setAppStep("who")}
+ />
+ )}
+
+ {step === "who" && connectResult && (
+ setAppStep("actions")}
+ onContinue={() => setAppStep("install")}
+ />
+ )}
+
+ {step === "install" && connectResult && (
+ setAppStep("who")}
+ onFinish={() => finishMutation.mutate()}
+ />
+ )}
+
+ {step === "success" && (
+ navigate("/apps")}
+ />
+ )}
+
+
+
+ {appIdentity ? (
+
+ ) : null}
+
+
+ {appIdentity ? `Connect ${appIdentity.name}` : "Connect an app"}
+
+
{subtitle}
+
+
+
+ Cancel
+
+
+ {step !== "gallery" && (
+
+
+ {labels.map((label, i) => (
+
+ ))}
+
+
{labels.join(" · ")}
+
+ )}
+
+
+
+
+
+
Connect Zapier
+
+ Paste the complete MCP URL Zapier gives you, including its token.
+
+
+
+
+
+
Zapier MCP URL
+
onLinkChange(event.target.value)}
+ onKeyDown={(event) => {
+ if (event.key === "Enter" && isZapierLink && !submitting) onConnect();
+ }}
+ placeholder="https://mcp.zapier.com/api/v1/connect?token=…"
+ className="mt-2 h-11"
+ autoFocus
+ />
+
+ The token is part of the URL. Paperclip stores it securely and checks the connection before enabling actions.
+
+ {link.trim() && !isZapierLink && (
+
Paste a valid Zapier URL to continue.
+ )}
+
+
+
+
+ Back
+
+
+ {submitting &&
+
+
(null);
+ const linkSectionRef = useRef(null);
+ const linkInputRef = useRef(null);
+
+ // Arriving from the BYO card: scroll the "Connect with a link" section into
+ // view and focus its input so the paste-URL path is the obvious next step.
+ useEffect(() => {
+ if (!byo || loading) return;
+ linkSectionRef.current?.scrollIntoView({ block: "center" });
+ linkInputRef.current?.focus();
+ }, [byo, loading]);
+ const filtered = useMemo(() => {
+ const q = search.trim().toLowerCase();
+ if (!q) return apps;
+ return apps.filter((a) => a.name.toLowerCase().includes(q));
+ }, [apps, search]);
+ const normalizedLink = normalizeAppLink(linkInput);
+ const matchedEntry = normalizedLink ? getToolAppGalleryEntryForUrl(normalizedLink, apps) : null;
+ const zapierSource = source === "zapier";
+
+ const continueWithLink = () => {
+ const next = normalizeAppLink(linkInput);
+ if (!next) {
+ setLinkError("Paste a full http or https link.");
+ return;
+ }
+ setLinkError(null);
+ onUseLink(next);
+ };
+
+ if (loading) {
+ return (
+
+ {Array.from({ length: 8 }).map((_, i) => (
+
+ );
+ }
+
+ return (
+
+
+
+
+
+ {filtered.map((app) => {
+ const copy = appCopyFor(app.key, app.tagline);
+ const oauth = app.authKind === "oauth";
+ const unavailable = app.availability?.available === false;
+ return (
+
onPick(app)}
+ className={cn(
+ "flex flex-col rounded-xl border border-border bg-card p-4 text-left transition-colors",
+ oauth || unavailable ? "cursor-not-allowed opacity-60" : "hover:border-foreground/30 hover:bg-accent/40",
+ )}
+ >
+ {app.name}
+ {copy.tagline}
+
+ {unavailable ? (
+ Not available on this instance - ask your admin.
+ ) : oauth ? (
+ Sign-in coming soon
+ ) : (
+ Connect →
+ )}
+
+
+ );
+ })}
+
+
+ {filtered.length === 0 && (
+
No apps match “{search}”.
+ )}
+
+
+
+
+
+
+ {zapierSource
+ ? "Paste the complete MCP URL Zapier gives you, including its token."
+ : byo
+ ? "Paste your MCP server’s URL and we’ll walk you through permissions and review."
+ : "Paste a setup link from an app that is not listed here."}
+
+ {!zapierSource && (
+
+ Any remote tool URL works here — including a local MCP server like{" "}
+ http://127.0.0.1:8848/mcp.
+
+ )}
+ {matchedEntry && (
+
+
+
+
This looks like {matchedEntry.name}.
+
+
{
+ setLinkError(null);
+ if (matchedEntry.key === "zapier") {
+ continueWithLink();
+ return;
+ }
+ onPick(matchedEntry);
+ }}
+ >
+ {matchedEntry.availability?.available === false
+ ? "Not available"
+ : matchedEntry.key === "zapier"
+ ? "Continue"
+ : `Use ${matchedEntry.name}`}
+
+
+ )}
+
+
+
+
+ Continue
+
+
+ {linkError &&
{linkError}
}
+
+
+
+
+
More ways to connect
+
+ For tools that aren’t in the gallery. You’ll need details from the tool’s docs.
+
+
+
+
+
+
+
+
+
{title}
+
{description}
+
+ );
+}
+
+function normalizeAppLink(value: string): string | null {
+ try {
+ const parsed = new URL(value.trim());
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+ return parsed.toString();
+ } catch {
+ return null;
+ }
+}
+
+function defaultLinkName(link: string): string | null {
+ try {
+ return new URL(link).hostname.replace(/^www\./, "");
+ } catch {
+ return null;
+ }
+}
+
+function LinkConnectStep({
+ link,
+ name,
+ onNameChange,
+ needsKey,
+ onNeedsKeyChange,
+ keyValue,
+ onKeyChange,
+ submitting,
+ onBack,
+ onConnect,
+}: {
+ link: string;
+ name: string;
+ onNameChange: (next: string) => void;
+ needsKey: boolean;
+ onNeedsKeyChange: (next: boolean) => void;
+ keyValue: string;
+ onKeyChange: (next: string) => void;
+ submitting: boolean;
+ onBack: () => void;
+ onConnect: () => void;
+}) {
+ return (
+
+
+
+
+
+
Connect with a link
+
{link}
+
+
+
+
+
+
Name
+
onNameChange(e.target.value)}
+ placeholder="My app"
+ className="mt-2 h-11"
+ />
+
+ We filled this in from the link. Change it if you’d like.
+
+
+
+
+
Does it need a key?
+
+ onNeedsKeyChange(false)}
+ />
+ onNeedsKeyChange(true)}
+ />
+
+
+ {needsKey
+ ? "Paste the key this app gave you."
+ : "Most apps just work from the link — pick Yes only if the app gave you a key."}
+
+
+
+ {needsKey && (
+
+
+ App key
+
+
+
+
+
+
Your key is stored securely.
+
+ You can replace it anytime from this app’s page.
+
+
+
+
+ )}
+
+
+
+
+ Back
+
+
+
+ We’ll check the link before turning anything on.
+
+
+ {submitting &&
+
+
+
+ {label}
+
+ );
+}
+
+function ConnectionNameField({
+ name,
+ onNameChange,
+}: {
+ name: string;
+ onNameChange: (next: string) => void;
+}) {
+ return (
+
+
Name
+
onNameChange(e.target.value)}
+ placeholder="My app"
+ className="mt-2 h-11"
+ />
+
+ We filled this in from the app. Change it to tell connections apart.
+
+
;
+ onChange: (next: Record) => void;
+ googleSheetsLinks: string;
+ googleSheetsError: string | null;
+ onGoogleSheetsLinksChange: (next: string) => void;
+ submitting: boolean;
+ onBack: () => void;
+ onConnect: () => void;
+}) {
+ const copy = appCopyFor(entry.key, entry.tagline);
+ const fields = entry.credentialFields ?? [];
+ const allFilled = fields.every(
+ (f) => f.required === false || (values[f.configPath]?.trim().length ?? 0) > 0,
+ );
+ const robotEmail = entry.availability?.robotEmail ?? null;
+ const unavailable = entry.availability?.available === false;
+
+ if (isGoogleSheetsEntry(entry)) {
+ const parsed = parseGoogleSheetIds(googleSheetsLinks);
+ const canConnect = !unavailable && Boolean(robotEmail) && googleSheetsLinks.trim().length > 0;
+ return (
+
+
+
+
+
Connect Google Sheets
+
{copy.short}
+
+
+
+
+
+
+ {robotEmail ? (
+
+
Share each sheet with this email
+
+
+ {robotEmail}
+
+
void navigator.clipboard?.writeText(robotEmail)}
+ >
+
+
+
+ In Google Sheets, click Share and add this email as an Editor. Then paste the sheet links below.
+
+
+ ) : (
+
+ Google Sheets is not available on this instance yet.
+
+ )}
+
+
+ Paste links to the sheets you shared
+