feat(copilot-app): no-access screens, MCP deep-links, ticket refresh (#315) (#3215)

* feat(copilot-app): no-access screens, MCP deep-links, ticket refresh

* fix(copilot-app): guard refresh paths against stale-fetch races

* fix(copilot-app): address PR review feedback (race, errors, tests)

* chore(agents-api): regenerate OpenAPI snapshot for AppListResponse role + tenantHasAnyApps

* fix(copilot-app): mount-path UX polish, fetchApps tests, tenantHasAnyApps consistency

GitOrigin-RevId: e348e84a8a92bb565474c5c2bad6c5ec37ec3e71

Co-authored-by: omar-inkeep <omar@inkeep.com>

Author: inkeep-oss-sync[bot]

.changeset/retail-blush-trout.md

@@ -0,0 +1,6 @@
+---
+"@inkeep/agents-core": patch
+"@inkeep/agents-api": patch
+---
+
+Return tenant role on apps list response

agents-api/__snapshots__/openapi.json

@@ -1251,6 +1251,17 @@
           },
           "pagination": {
             "$ref": "#/components/schemas/Pagination"
+          },
+          "role": {
+            "enum": [
+              "owner",
+              "admin",
+              "member"
+            ],
+            "type": "string"
+          },
+          "tenantHasAnyApps": {
+            "type": "boolean"
           }
         },
         "required": [

agents-api/src/__tests__/manage/routes/tenantAppsAuthz.test.ts

@@ -100,7 +100,14 @@ describe('GET /manage/tenants/:tenantId/apps — project access filtering', () =
     const res = await app.request('/manage/tenants/tenant-1/apps');
 
     expect(res.status).toBe(200);
-    expect(listAppsPaginatedMock).not.toHaveBeenCalled();
+    // The main scoped listing is short-circuited; only the unscoped
+    // tenantHasAnyApps probe runs (one call, with `limit: 1`).
+    expect(listAppsPaginatedMock).toHaveBeenCalledTimes(1);
+    expect(listAppsPaginatedMock).toHaveBeenCalledWith({
+      scopes: { tenantId: 'tenant-1' },
+      pagination: { page: 1, limit: 1 },
+      type: undefined,
+    });
 
     const body = await res.json();
     expect(body.data).toEqual([]);
@@ -151,3 +158,149 @@ describe('GET /manage/tenants/:tenantId/apps — project access filtering', () =
     });
   });
 });
+
+describe('GET /manage/tenants/:tenantId/apps — role and tenantHasAnyApps response fields', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    listAppsPaginatedMock.mockResolvedValue(emptyPage);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns role and tenantHasAnyApps=true when a member with no project access is in a tenant with apps elsewhere', async () => {
+    listUsableProjectIdsMock.mockResolvedValue([]);
+    // The handler's early-return path runs the unscoped tenantHasAnyApps probe.
+    listAppsPaginatedMock.mockResolvedValueOnce({
+      data: [{ id: 'app-elsewhere' }],
+      pagination: { page: 1, limit: 1, total: 1, pages: 1 },
+    });
+
+    const app = buildHarness({ userId: 'user-no-projects', tenantRole: 'member' });
+    const res = await app.request('/manage/tenants/tenant-1/apps?type=support_copilot');
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.data).toEqual([]);
+    expect(body.role).toBe('member');
+    expect(body.tenantHasAnyApps).toBe(true);
+    // Only the unscoped probe runs — main listing is short-circuited.
+    expect(listAppsPaginatedMock).toHaveBeenCalledTimes(1);
+    expect(listAppsPaginatedMock).toHaveBeenCalledWith({
+      scopes: { tenantId: 'tenant-1' },
+      pagination: { page: 1, limit: 1 },
+      type: 'support_copilot',
+    });
+  });
+
+  it('returns tenantHasAnyApps=false when a member with no project access is in a tenant with zero apps', async () => {
+    listUsableProjectIdsMock.mockResolvedValue([]);
+    listAppsPaginatedMock.mockResolvedValueOnce(emptyPage);
+
+    const app = buildHarness({ userId: 'user-no-projects', tenantRole: 'member' });
+    const res = await app.request('/manage/tenants/tenant-1/apps');
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.data).toEqual([]);
+    expect(body.role).toBe('member');
+    expect(body.tenantHasAnyApps).toBe(false);
+  });
+
+  it('fires a second unscoped query when a member has projects but the scoped result is empty', async () => {
+    listUsableProjectIdsMock.mockResolvedValue(['proj-a']);
+    // First call (scoped to user's projects) returns empty.
+    listAppsPaginatedMock.mockResolvedValueOnce(emptyPage);
+    // Second call (unscoped tenant probe) finds apps elsewhere.
+    listAppsPaginatedMock.mockResolvedValueOnce({
+      data: [{ id: 'app-elsewhere' }],
+      pagination: { page: 1, limit: 1, total: 1, pages: 1 },
+    });
+
+    const app = buildHarness({ userId: 'user-non-admin', tenantRole: 'member' });
+    const res = await app.request('/manage/tenants/tenant-1/apps');
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.data).toEqual([]);
+    expect(body.role).toBe('member');
+    expect(body.tenantHasAnyApps).toBe(true);
+    expect(listAppsPaginatedMock).toHaveBeenCalledTimes(2);
+    expect(listAppsPaginatedMock).toHaveBeenNthCalledWith(1, {
+      scopes: { tenantId: 'tenant-1', projectIds: ['proj-a'] },
+      pagination: { page: 1, limit: 10 },
+      type: undefined,
+    });
+    expect(listAppsPaginatedMock).toHaveBeenNthCalledWith(2, {
+      scopes: { tenantId: 'tenant-1' },
+      pagination: { page: 1, limit: 1 },
+      type: undefined,
+    });
+  });
+
+  it('skips the second query and returns tenantHasAnyApps=true when the scoped result is non-empty', async () => {
+    listUsableProjectIdsMock.mockResolvedValue(['proj-a']);
+    listAppsPaginatedMock.mockResolvedValueOnce({
+      data: [
+        {
+          id: 'app-a',
+          tenantId: 'tenant-1',
+          projectId: 'proj-a',
+          name: 'A',
+          type: 'support_copilot',
+          enabled: true,
+          config: { type: 'support_copilot', supportCopilot: {} },
+          defaultAgentId: null,
+          defaultProjectId: 'proj-a',
+          lastUsedAt: null,
+          createdAt: '2025-01-01T00:00:00.000Z',
+          updatedAt: '2025-01-01T00:00:00.000Z',
+        },
+      ],
+      pagination: { page: 1, limit: 10, total: 1, pages: 1 },
+    });
+
+    const app = buildHarness({ userId: 'user-non-admin', tenantRole: 'member' });
+    const res = await app.request('/manage/tenants/tenant-1/apps');
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.data).toHaveLength(1);
+    expect(body.role).toBe('member');
+    expect(body.tenantHasAnyApps).toBe(true);
+    // No second probe — non-empty result is authoritative.
+    expect(listAppsPaginatedMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns role=admin and tenantHasAnyApps=false without a second query when an admin sees an empty list', async () => {
+    listAppsPaginatedMock.mockResolvedValue(emptyPage);
+
+    const app = buildHarness({ userId: 'user-admin', tenantRole: 'admin' });
+    const res = await app.request('/manage/tenants/tenant-1/apps');
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.data).toEqual([]);
+    expect(body.role).toBe('admin');
+    // Admins see the whole tenant, so empty is authoritative — no extra DB hit.
+    expect(body.tenantHasAnyApps).toBe(false);
+    expect(listAppsPaginatedMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns role=owner and tenantHasAnyApps=true for an owner with apps', async () => {
+    listAppsPaginatedMock.mockResolvedValueOnce({
+      data: [{ id: 'app-a' }],
+      pagination: { page: 1, limit: 10, total: 1, pages: 1 },
+    });
+
+    const app = buildHarness({ userId: 'user-owner', tenantRole: 'owner' });
+    const res = await app.request('/manage/tenants/tenant-1/apps');
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.role).toBe('owner');
+    expect(body.tenantHasAnyApps).toBe(true);
+    expect(listAppsPaginatedMock).toHaveBeenCalledTimes(1);
+  });
+});

agents-api/src/domains/manage/routes/tenantApps.ts

@@ -4,6 +4,7 @@ import {
   commonGetErrorResponses,
   listAppsPaginated,
   listUsableProjectIds,
+  type OrgRole,
   OrgRoles,
   PaginationQueryParamsSchema,
   sanitizeAppConfig,
@@ -63,9 +64,28 @@ app.openapi(
     if (!isOrgAdmin) {
       projectIds = userId ? await listUsableProjectIds({ userId, tenantId }) : [];
       if (projectIds.length === 0) {
+        // Member with no project memberships. Empty list either way; check
+        // whether the tenant has any apps of this type so the client can
+        // distinguish "you don't have access to existing apps" from "no
+        // apps exist yet".
+        //
+        // Intentional information-disclosure tradeoff: a member with zero
+        // project access can learn whether the tenant has any apps of this
+        // type via `tenantHasAnyApps`. Within their own tenant, that single
+        // boolean is acceptable disclosure to drive correct empty-state UX
+        // (ask admin to add me vs ask admin to set up Copilot). If a future
+        // deploy needs strict project-boundary silos, this branch should
+        // be revisited.
+        const tenantWide = await listAppsPaginated(runDbClient)({
+          scopes: { tenantId },
+          pagination: { page: 1, limit: 1 },
+          type,
+        });
         return c.json({
           data: [],
           pagination: { page, limit, total: 0, pages: 0 },
+          role: tenantRole as OrgRole,
+          tenantHasAnyApps: tenantWide.pagination.total > 0,
         });
       }
     }
@@ -78,9 +98,30 @@ app.openapi(
 
     const sanitizedData = result.data.map((app) => sanitizeAppConfig(app));
 
+    // Skip the second query when we already know: a non-empty list means
+    // apps exist, and an admin's empty result is authoritative because
+    // their scope is the whole tenant.
+    let tenantHasAnyApps: boolean;
+    if (result.pagination.total > 0) {
+      // Use total, not sanitizedData.length: page 2+ with results on page 1
+      // would spuriously fall through to the unscoped query below otherwise.
+      tenantHasAnyApps = true;
+    } else if (isOrgAdmin) {
+      tenantHasAnyApps = false;
+    } else {
+      const tenantWide = await listAppsPaginated(runDbClient)({
+        scopes: { tenantId },
+        pagination: { page: 1, limit: 1 },
+        type,
+      });
+      tenantHasAnyApps = tenantWide.pagination.total > 0;
+    }
+
     return c.json({
       data: sanitizedData,
       pagination: result.pagination,
+      role: tenantRole as OrgRole,
+      tenantHasAnyApps,
     });
   }
 );

packages/agents-core/src/validation/schemas.ts

@@ -2883,6 +2883,21 @@ export const AppListResponse = z
   .object({
     data: z.array(AppApiResponseSelectSchema),
     pagination: PaginationSchema,
+    /**
+     * The caller's organization role. Set on tenant-wide list responses so
+     * the client can branch UX (admin "create one" vs member "ask admin")
+     * when `data` is empty. Omitted on project-scoped list responses where
+     * role isn't a meaningful signal.
+     */
+    role: z.enum(['owner', 'admin', 'member']).optional(),
+    /**
+     * Whether the tenant has ANY apps of the requested type, regardless of
+     * the caller's project memberships. Lets a member with an empty list
+     * distinguish "I don't have access to existing apps" from "no apps
+     * exist anywhere yet". Set on tenant-wide responses; omitted on
+     * project-scoped responses.
+     */
+    tenantHasAnyApps: z.boolean().optional(),
   })
   .openapi('AppListResponse');
 export const CredentialReferenceListResponse = z