@bevel-software/platform-core-backend 0.26.0 → 0.27.0

package/migrations/meta/_journal.json

@@ -120,6 +120,13 @@
       "when": 1790933605784,
       "tag": "0016_pii_encryption",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1791359019161,
+      "tag": "0017_atlassian_account_links",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,6 +24,8 @@
     "migrations",
     "kb-template",
     "agent-guide",
+    "mcp-app",
+    "starter-packs",
     "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
@@ -53,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.26.0",
-    "@bevel-software/platform-shared": "0.26.0"
+    "@bevel-software/platform-shared": "0.27.0",
+    "@bevel-software/platform-mcp-core": "0.27.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/packaged-assets-ship.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir } from '../assets.js';
+import { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir, defaultStarterPacksDir, mcpAppDir } from '../assets.js';
 
 /**
  * Every asset folder this package reads at run time has to reach the places
@@ -17,18 +17,30 @@ import { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir } from '../asset
  * any tool on the deployment failed, and every agent surface with it
  * (2026-10-06). A folder named here and missing from either list fails this
  * test instead.
+ *
+ * `mcp-app/` was the same omission one release later — caught here rather
+ * than on a deployment. It holds the `ui://` view `resources/read` serves, so
+ * an image without it answered `tools/list` with no view on `open_page` and
+ * `resources/list` with nothing, and the page-in-chat quietly degraded to
+ * text on every real build.
  */
 const packageRoot = fileURLToPath(new URL('../..', import.meta.url));
 const repoRoot = path.resolve(packageRoot, '..', '..');
 
 /** The folders assets.ts locates, as names under the package root. */
-const ASSET_DIRS = [coreMigrationsDir(), defaultKbTemplateDir(), agentGuideDir()].map((dir) =>
+const ASSET_DIRS = [
+  coreMigrationsDir(),
+  defaultKbTemplateDir(),
+  agentGuideDir(),
+  mcpAppDir(),
+  defaultStarterPacksDir(),
+].map((dir) =>
   path.basename(dir),
 );
 
 describe('the asset folders this package reads at run time', () => {
-  it('are the three assets.ts names', () => {
-    expect(ASSET_DIRS.sort()).toEqual(['agent-guide', 'kb-template', 'migrations']);
+  it('are the four assets.ts names', () => {
+    expect(ASSET_DIRS.sort()).toEqual(['agent-guide', 'kb-template', 'mcp-app', 'migrations', 'starter-packs']);
   });
 
   it('exist in the source tree', () => {

package/src/assets.ts

@@ -3,8 +3,9 @@ import { fileURLToPath } from 'node:url';
 
 /**
  * Locations of the assets shipped INSIDE this package (`files` in
- * package.json): the squashed core migration history (`migrations/`) and the
- * KB seed template (`kb-template/`). Both live at the PACKAGE ROOT, and this
+ * package.json): the squashed core migration history (`migrations/`), the
+ * KB seed template (`kb-template/`) and the starter packs (`starter-packs/`).
+ * All live at the PACKAGE ROOT, and this
  * module is a direct child of either `src/` (in-repo / tsx) or `dist/`
  * (compiled) — so one `..` hop from the module URL reaches the package root
  * in BOTH layouts. Resolved lazily so bundlers that rewrite `import.meta.url`
@@ -33,3 +34,28 @@ export function defaultKbTemplateDir(): string {
 export function agentGuideDir(): string {
   return path.join(packageRoot(), 'agent-guide');
 }
+
+/**
+ * The MCP App views this deployment serves over `resources/read` — one static
+ * HTML file each, no build step. Beside `agent-guide/` and `kb-template/` for
+ * the same reason: a build and the published source find it at the same
+ * place, and `tsc` copies nothing that is not TypeScript.
+ *
+ * The backend serves these as BYTES and never imports frontend code — the
+ * view's whole job is to load the deployment's embed bundle into its own
+ * document (hosts forbid framing the deployment, see `mcp-app.ts`), where the
+ * app's renderers then draw the page.
+ */
+export function mcpAppDir(): string {
+  return path.join(packageRoot(), 'mcp-app');
+}
+
+/**
+ * The starter packs a new knowledge base may be filled from — one folder per
+ * team (`engineering/`, `sales/`, …), each a `pack.yaml` beside the pages and
+ * the plugin it adds (see `modules/onboarding/starter-packs.ts`). Beside
+ * `kb-template/` for the same reason: read at run time, shipped as files.
+ */
+export function defaultStarterPacksDir(): string {
+  return path.join(packageRoot(), 'starter-packs');
+}

package/src/core/__tests__/catalog-revision.test.ts

@@ -47,6 +47,14 @@ describe('catalogRevision', () => {
     );
   });
 
+  it('moves when an MCP App view changes by a byte, and not when the same view is read again', () => {
+    const view = { uri: 'ui://hexis/page.html', text: '<html>v1</html>' };
+    const base = catalogRevision([manualLine('serper')], [skill()], [view]);
+    expect(catalogRevision([manualLine('serper')], [skill()], [{ ...view }])).toBe(base);
+    expect(catalogRevision([manualLine('serper')], [skill()], [{ ...view, text: '<html>v2</html>' }])).not.toBe(base);
+    expect(catalogRevision([manualLine('serper')], [skill()], [])).not.toBe(base);
+  });
+
   describe('a manual added, changed or removed', () => {
     const base = catalogRevision([manualLine('serper')], []);
 
@@ -115,6 +123,8 @@ describe('GET /agent/catalog-revision', () => {
     skills: SkillSummary[];
     userId?: string | undefined;
     resolveUserEmail?: (userId: string) => Promise<string | undefined>;
+    /** The served views, or a manifest read that fails. */
+    mcpApps?: { manifest(): Promise<{ resources: { uri: string; text: string }[] }> };
   }): Promise<{
     url: string;
     catalogFingerprints: ReturnType<typeof vi.fn>;
@@ -132,6 +142,7 @@ describe('GET /agent/catalog-revision', () => {
           next();
         },
         resolveUserEmail: deps.resolveUserEmail ?? (async () => 'someone@example.com'),
+        ...(deps.mcpApps ? { mcpApps: deps.mcpApps } : {}),
       }),
     );
     http = app.listen(0);
@@ -174,6 +185,35 @@ describe('GET /agent/catalog-revision', () => {
     expect(catalogFingerprints).not.toHaveBeenCalled();
   });
 
+  it('folds the served MCP App views into the revision, so a changed view moves it', async () => {
+    const view = { uri: 'ui://hexis/page.html', text: '<html>v1</html>' };
+    const { url } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [skill()],
+      userId: 'u1',
+      mcpApps: { manifest: async () => ({ resources: [view] }) },
+    });
+    const body = (await (await fetch(`${url}/agent/catalog-revision`)).json()) as { revision: string };
+    expect(body.revision).toBe(catalogRevision([manualLine('serper')], [skill()], [view]));
+    expect(body.revision).not.toBe(catalogRevision([manualLine('serper')], [skill()]));
+  });
+
+  it('answers the no-views revision when the manifest cannot be read, rather than failing', async () => {
+    const { url } = await mount({
+      manuals: [manualLine('serper')],
+      skills: [skill()],
+      userId: 'u1',
+      mcpApps: {
+        manifest: async () => {
+          throw new Error('the view file is gone');
+        },
+      },
+    });
+    const res = await fetch(`${url}/agent/catalog-revision`);
+    expect(res.status).toBe(200);
+    expect(((await res.json()) as { revision: string }).revision).toBe(catalogRevision([manualLine('serper')], [skill()]));
+  });
+
   it('does not fail the request when the email lookup throws', async () => {
     const { url } = await mount({
       manuals: [manualLine('serper')],

package/src/core/__tests__/gated-boot.test.ts

@@ -50,6 +50,7 @@ function bootable(runAll: () => Promise<void>) {
     } as BootableCore['kbStartupRunner'],
     workflowService: {
       closeChangeRequestsWithDeletedBranches: async () => 0,
+      tidyAfterSweep: async () => ({ closedEmpty: 0, removedLeftovers: 0 }),
     } as BootableCore['workflowService'],
     pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
     startupRetry: null,

package/src/core/__tests__/lifecycle.test.ts

@@ -453,6 +453,14 @@ describe('stopCore', () => {
             order.push('startupRetry.stop');
           },
         },
+        workflowService: {
+          stopTidying() {
+            order.push('workflowService.stopTidying');
+          },
+          async drainTidy() {
+            order.push('workflowService.drainTidy');
+          },
+        },
         db: {
           $client: {
             async end() {
@@ -473,8 +481,10 @@ describe('stopCore', () => {
       'backgroundJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
+      'workflowService.stopTidying',
       'backgroundJobs.drain',
       'agentUploadStore.drainSweep',
+      'workflowService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -515,8 +525,10 @@ describe('stopCore', () => {
     expect(g.order).toEqual([
       'backgroundJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
+      'workflowService.stopTidying',
       'backgroundJobs.drain',
       'agentUploadStore.drainSweep',
+      'workflowService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -530,8 +542,10 @@ describe('stopCore', () => {
       'backgroundJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
+      'workflowService.stopTidying',
       'backgroundJobs.drain',
       'agentUploadStore.drainSweep',
+      'workflowService.drainTidy',
       'db.end',
     ]);
   });

package/src/core/catalog-revision.ts

@@ -57,11 +57,19 @@ function skillFingerprint(s: SkillSummary): string {
 export function catalogRevision(
   manuals: readonly string[],
   skills: readonly SkillSummary[],
+  /**
+   * The MCP App views this deployment serves, by their bytes: a release that
+   * changes a view and nothing else must still move the revision, or a local
+   * server already running keeps serving the view it read at startup.
+   */
+  views: readonly { uri: string; text: string }[] = [],
 ): string {
   const lines = [
     ...[...manuals].sort(),
-    '\u0001', // separates the two lists, so a line can never migrate between them
+    '\u0001', // separates the lists, so a line can never migrate between them
     ...skills.map(skillFingerprint).sort(),
+    '\u0001',
+    ...views.map((v) => `${v.uri}\u0000${createHash('sha256').update(v.text).digest('hex')}`).sort(),
   ];
   return createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 32);
 }
@@ -82,6 +90,8 @@ export function createCatalogRevisionRoutes(deps: {
   manualAuth: RequestHandler;
   /** Connection-key/internal-token user id → email, for the per-caller ACL. */
   resolveUserEmail: (userId: string) => Promise<string | undefined>;
+  /** The MCP App views served; absent on a deployment that serves none. */
+  mcpApps?: { manifest(): Promise<{ resources: readonly { uri: string; text: string }[] }> };
 }): express.Router {
   const router = express.Router();
 
@@ -95,8 +105,11 @@ export function createCatalogRevisionRoutes(deps: {
       const [manuals, skills] = email
         ? await Promise.all([deps.toolManuals.catalogFingerprints(email), deps.skills.listSkills(email)])
         : [[], []];
+      // A manifest that cannot be read counts as no views, which is also what
+      // the MCP endpoint serves in that state.
+      const views = deps.mcpApps ? ((await deps.mcpApps.manifest().catch(() => null))?.resources ?? []) : [];
       res.json({
-        revision: catalogRevision(manuals, skills),
+        revision: catalogRevision(manuals, skills, views),
         tools: manuals.length,
         skills: skills.length,
       });

package/src/core/create-core-server.ts

@@ -8,6 +8,7 @@ import {
   createAgentUploadRoutes,
   isAgentUploadRawBodyPath,
 } from '../modules/workspace/agent-upload.routes.js';
+import { createAgentDownloadRoutes } from '../modules/workspace/agent-download.routes.js';
 import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals.middleware.js';
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
@@ -26,7 +27,8 @@ import {
   registerToolManualsTools,
 } from '../modules/tool-manuals/index.js';
 import { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
-import { registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+import { changeRequestScope, registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+import { createOnboardingRoutes } from '../modules/onboarding/onboarding.routes.js';
 import { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
 import { registerAgentGuideTool } from '../modules/agent-guide/index.js';
 import { RECOVERY_BOT_EMAIL } from '../modules/workflow/recovery-bot.js';
@@ -55,6 +57,7 @@ import { createUpdateCheckRoutes } from '../modules/update-check/update-check.ro
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createConnectionKeysAdminRoutes } from '../modules/tool-auth/connection-keys-admin.routes.js';
 import { createAuditRoutes } from '../modules/audit/audit.routes.js';
+import { createAgentConnectionRoutes } from '../modules/audit/agent-connection.routes.js';
 import { createAgentRestAuditMiddleware } from '../modules/audit/agent-rest-audit.middleware.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../modules/tool-manuals/tool-manuals.contract.js';
 import { createSetupRoutes, isComplete } from '../modules/settings/setup.routes.js';
@@ -79,6 +82,10 @@ import { createReadiness } from './readiness.js';
 import { createAgentInstructionsRoutes } from '../modules/agent-instructions/index.js';
 import type { CoreServices } from './create-core-services.js';
 import { createWriteAccessRoutes, createWriteGateMiddleware } from '../modules/write-access/write-access.js';
+import { createEmbedRoutes, createEmbedLinkRoutes } from '../modules/embed/embed.routes.js';
+import { registerEmbedTools } from '../modules/embed/embed.tools.js';
+import { createMcpAppRoutes } from '../modules/embed/mcp-app.routes.js';
+import { isSandboxReachableOrigin } from '../modules/embed/mcp-app.js';
 
 type ExpressApp = ReturnType<typeof express>;
 
@@ -86,6 +93,11 @@ type ExpressApp = ReturnType<typeof express>;
  * The context handed to {@link ServerExtensions.tools}: everything an overlay
  * needs to register its own tool defs + endpoint routes on the unified tool
  * surface, exactly like the core modules do.
+ *
+ * A tool that works on a branch declares it on its `toolDef` (`branch:
+ * 'required'` or, read-only tools only, `'defaults-to-default-branch'`), and
+ * `toolHandler` resolves the branch before the tool runs — see "The branch"
+ * in `modules/tool-helpers/index.ts`.
  */
 export interface ToolSurfaceCtx {
   registry: CoreServices['toolRegistry'];
@@ -457,12 +469,33 @@ export async function createCoreServer(
   // every save surface (agent write tools, the app's PUT /file) and on
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
-  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb);
+  // `delete_branch` sees change requests as `get_change_request` does.
+  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee);
   // The five read tools over change requests. Separate from the workflow tools
   // because they are the only ones that gate their whole payload on the
   // caller's read access, so they take the access service and nothing else.
   registerChangeRequestReadTools(core.toolRegistry, toolsRouter, ta, th, core.accessControl, core.kb);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide);
+  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide, core.agentDownloadStore, core.starterPackService, core.disk);
+  // `open_page` — the knowledge-base page shown inside a chat. Registered
+  // here, on the same router as the file tools, because it answers with
+  // `read_file`'s own read: the read hook, the access gate and the
+  // not-found refusal come from that registration rather than from a copy.
+  registerEmbedTools(core.toolRegistry, toolsRouter, ta, th, {
+    embedService: core.embedService,
+    kb: core.kb,
+    readForTool: workspaceTools.readForTool,
+    // A host's https sandbox cannot load from a plain-http deployment, so
+    // the tool answers the text and the app address and says so.
+    canBeReached: () => isSandboxReachableOrigin(core.config.publicFrontendUrl),
+    appUrlFor: (repoRelative, slug) => core.embedService.appUrlFor(repoRelative, slug),
+    // The read is `read_file`'s, so the notes a deployment registers for the
+    // gated tools reach this one as well.
+    notes: agentAccessGate.notes,
+  });
+  // The app manifest and the view bytes, for the LOCAL MCP server: it bridges
+  // a host to this deployment over HTTP and has no other way to learn which
+  // tools carry a view. Same router, same `manualAuth` as `all-tools`.
+  toolsRouter.use(createMcpAppRoutes(core.mcpAppService, core.manualAuthMiddleware));
   // The guide on its own, beside the file tools that serve it by name.
   registerAgentGuideTool(core.toolRegistry, toolsRouter, ta, th, core.agentGuideSections);
   // The agent upload route, on the same router as the tool endpoints so it
@@ -472,6 +505,10 @@ export async function createCoreServer(
   // no workspace and writes into none; every access, platform-file and branch
   // rule is applied later by `apply_file_upload`.
   toolsRouter.use(createAgentUploadRoutes({ uploads: core.agentUploadStore }));
+  // Its outgoing twin, mounted the same way and for the same reason: the
+  // one-time link is the whole credential an agent's `curl` carries. Every
+  // file behind it was judged when `request_file_download` issued it.
+  toolsRouter.use(createAgentDownloadRoutes({ downloads: core.agentDownloadStore, identify: core.agentDownloadFetcher }));
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker);
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
@@ -528,6 +565,9 @@ export async function createCoreServer(
     skills: core.skillService,
     manualAuth: core.manualAuthMiddleware,
     resolveUserEmail: async (userId) => (await core.authService.getUserById(userId))?.email,
+    // The views move the revision too: a release that changes a view and no
+    // manual would otherwise leave a running local server on the old one.
+    mcpApps: core.mcpAppService,
   }));
   // The only core route that returns secret VALUES: a local `.tool`'s declared
   // variables, for the local MCP server that will execute it. It re-reads the
@@ -554,6 +594,12 @@ export async function createCoreServer(
   // Non-JWT overlay surfaces that sit between the tools router and the
   // JWT-protected `/api` routes (LLM proxy, embed, upload — see the phase
   // doc on ServerExtensions.postTools).
+  // The embed surface, ahead of every JWT mount and of the static
+  // catch-all: its data routes authenticate by the embed token ALONE (a
+  // session reaching them must be refused, not honoured), and the two SPA
+  // routes need their framing headers stamped before `index.html` is served.
+  app.use(createEmbedRoutes(core.embedService));
+
   ext.postTools?.(app, core);
 
   // The plugin creation doors — `POST /api/plugins`, `POST /api/plugins/personal`
@@ -729,6 +775,18 @@ export async function createCoreServer(
     core.authMiddleware,
     createAuditRoutes(core.agentAuditService, core.externalApiKeyService, core.adminAccess),
   );
+  // The onboarding's "is your agent connected yet?" — the caller's own
+  // agents only, read off the same connections and keys the Audit log lists.
+  app.use('/api', core.authMiddleware, createAgentConnectionRoutes(core.agentAuditService));
+  // "What does your team do?" — the starter-pack question a new knowledge
+  // base's admin is asked, and the pack it adds (admin-gated inside).
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createOnboardingRoutes(core.starterPackService, async (req) =>
+      req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null,
+    ),
+  );
   // First-run setup. Mounted with the other authed routes but touching NO
   // workspace — it has to work on a deployment that has no knowledge base yet,
   // which is the whole reason it exists. The startup runner rides along for
@@ -821,6 +879,12 @@ export async function createCoreServer(
   }));
 
   // JWT-protected overlay routes.
+  // Linking an outside account to the signed-in user, and managing those
+  // links. Under the JWT middleware, deliberately: the link acts AS the
+  // session, which is exactly why the page it is called from refuses every
+  // framing ancestor.
+  app.use('/api', core.authMiddleware, createEmbedLinkRoutes(core.embedService));
+
   ext.authed?.(app, core);
 
   // In production, serve the frontend static build