@bevel-software/platform-core-backend 0.28.0 → 0.29.0

package/kb-template/access.md

@@ -14,7 +14,8 @@ owner:
 #
 # Verbs are read, write, download and owner. `owner` implies the rest and
 # `write` implies `read`. Read is default-deny: a folder with no `read:` grant
-# is invisible to everyone except admins, who read through `write: Admin`.
+# is invisible to everyone except admins, who may always change what is under
+# the root and so may always see it, unless a nearer access.md excludes them.
 #
 # Each entry is a grant (a bare principal) or a denial (the lowercase word
 # `deny`, a space, then the principal — capitalised forms like `Deny` are

package/mcp-app/page.html

@@ -72,6 +72,26 @@
          * owns the view; later ones are ignored.
          */
         var loading = false;
+        /**
+         * What the view calls `open_page` with to renew its token: the path
+         * and heading the result that owns the view echoed. Null until then,
+         * and when the result echoed no path (nothing to ask for).
+         */
+        var pageArgs = null;
+        /** The deployment the owning result named; a renewed token must name the same one. */
+        var deployment = null;
+        /**
+         * Whether the host runs a server tool for the view (`tools/call`,
+         * app to host): true or false when the handshake's reply said so in
+         * `hostCapabilities.serverTools`, null when it said nothing — then
+         * the view tries once, and a refusal is the answer.
+         */
+        var serverTools = null;
+        /** Replies the view is waiting for, by request id. */
+        var pending = {};
+        var callCount = 0;
+        /** The one renewal in flight, shared by every call refused meanwhile. */
+        var renewing = null;
 
         /** The name the deployment's Vite build gives the embed entry. */
         var EMBED_ENTRY = 'embed';
@@ -90,6 +110,14 @@
          * part of the conversation rather than the whole screen.
          */
         var PREFERRED_HEIGHT = 640;
+        /** The tool that minted the token, and the one that renews it. */
+        var OPEN_PAGE_TOOL = 'open_page';
+        /**
+         * How long a renewal waits for the host before it gives up and the
+         * view says it has expired. A host that never answers must not leave
+         * a save spinning.
+         */
+        var RENEW_TIMEOUT_MS = 20000;
 
         function send(message) {
           // The host is this view's parent; it told us its origin on the
@@ -128,6 +156,87 @@
           });
         }
 
+        /**
+         * Ask the host to call one of this server's tools for the view, over
+         * the connection the chat already holds — and so as the identity
+         * that connection authenticated. Resolves with the CallToolResult;
+         * rejects when the host refuses or does not answer in time.
+         */
+        function callServerTool(name, args) {
+          return new Promise(function (resolve, reject) {
+            callCount += 1;
+            var id = 'call-' + callCount;
+            var timer = setTimeout(function () {
+              delete pending[id];
+              var silent = new Error('the chat app did not answer');
+              silent.timedOut = true;
+              reject(silent);
+            }, RENEW_TIMEOUT_MS);
+            pending[id] = function (message) {
+              clearTimeout(timer);
+              delete pending[id];
+              if (message.error || !message.result) reject(message.error || new Error('no result'));
+              else resolve(message.result);
+            };
+            send({ jsonrpc: '2.0', id: id, method: 'tools/call', params: { name: name, arguments: args } });
+          });
+        }
+
+        /**
+         * A fresh token for the page this view shows, or null when there is
+         * none to be had. The view cannot mint one — minting needs the
+         * identity, which lives on the chat's connection — so it asks the
+         * host to call `open_page` again for the same path and heading and
+         * takes the token out of the `embedUrl` it answers. That call goes
+         * through `open_page`'s own gate: a reader whose access was
+         * withdrawn is refused there exactly as on a first call, and gets
+         * null here.
+         *
+         * Null without asking when the host said it runs no server tools for
+         * a view, or after a host that said nothing refused once. The bundle
+         * calls this at most once per refused call (see `embed-config.ts`).
+         */
+        function renew() {
+          if (renewing) return renewing;
+          if (serverTools === false || !pageArgs || !deployment) return Promise.resolve(null);
+          // Every Hexis tool takes its arguments under `body`; flat ones are
+          // refused ("takes its arguments under body") and no token comes back.
+          renewing = callServerTool(OPEN_PAGE_TOOL, { body: pageArgs })
+            .then(
+              function (result) {
+                var data = (result && result.structuredContent) || {};
+                if (result && result.isError) return null;
+                var url;
+                try {
+                  url = new URL(data.embedUrl);
+                } catch (err) {
+                  return null;
+                }
+                // The same deployment, or nothing: the bundle already runs
+                // against this one, and its API is the token's.
+                if (baseOf(url) !== deployment) return null;
+                var token = url.searchParams.get('token');
+                if (!token) return null;
+                var handoff = window[HANDOFF_GLOBAL];
+                if (handoff && typeof handoff === 'object') handoff.token = token;
+                return token;
+              },
+              function (err) {
+                // The host refused the call: one that said nothing about
+                // server tools has now said no. One that did not answer in
+                // time has said nothing, and is asked again on the next
+                // refused call.
+                if (serverTools === null && !(err && err.timedOut)) serverTools = false;
+                return null;
+              },
+            )
+            .then(function (token) {
+              renewing = null;
+              return token;
+            });
+          return renewing;
+        }
+
         /** The text blocks of a CallToolResult, one line each. */
         function textOf(result) {
           var out = [];
@@ -226,8 +335,15 @@
           }
           if (loading) return;
           loading = true;
+          deployment = base;
+          // What the view calls `open_page` with again when the token runs
+          // out: the arguments this result was answered for, as it echoed them.
+          if (typeof data.path === 'string' && data.path) {
+            pageArgs = { path: data.path };
+            if (typeof data.heading === 'string' && data.heading) pageArgs.heading = data.heading;
+          }
           // The handoff, before the bundle: it reads this the moment it runs.
-          window[HANDOFF_GLOBAL] = { baseUrl: base, token: token, openLink: openLink };
+          window[HANDOFF_GLOBAL] = { baseUrl: base, token: token, openLink: openLink, renew: renew };
 
           fetch(base + MANIFEST_PATH, { credentials: 'omit' })
             .then(function (res) {
@@ -302,6 +418,13 @@
           if (event.source !== window.parent) return;
           if (hostOrigin === null && event.origin) hostOrigin = event.origin;
 
+          // A reply to a request the view sent (a server tool call): it has
+          // the request's id and no method of its own.
+          if (!message.method && typeof message.id === 'string' && pending[message.id]) {
+            pending[message.id](message);
+            return;
+          }
+
           if (message.method === 'ui/notifications/tool-result') {
             // The params ARE the CallToolResult. A `result` wrapper is
             // accepted too, for a host that wrapped it.
@@ -314,16 +437,25 @@
             // whole of the layout; nothing to recompute.
             return;
           }
-          // The handshake's reply carries the host's capabilities. Nothing
-          // here depends on them, but a host that sends the first tool result
-          // only after the handshake completes needs us to have sent it.
-          if (message.id === INITIALIZE_ID) {
+          // The handshake's reply carries the host's capabilities. The one
+          // read here is `serverTools`: whether the host runs this server's
+          // tools for the view, which is how the view renews its token. And a
+          // host that sends the first tool result only after the handshake
+          // completes needs us to have sent it.
+          if (!message.method && message.id === INITIALIZE_ID) {
             // A rejected handshake is not advertised as ready — and the
             // reader is told, rather than left at "Opening the page…".
             if (message.error || !message.result) {
               if (!shown) say('The chat app refused to open this page.');
               return;
             }
+            // Only a `serverTools` the host named decides: present is yes,
+            // false or null is no. Capabilities that leave it out have said
+            // nothing about it, and the view tries once.
+            var caps = message.result.hostCapabilities;
+            if (caps && typeof caps === 'object' && caps.serverTools !== undefined) {
+              serverTools = !!caps.serverTools;
+            }
             send({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} });
             if (!shown) say('Opening the page…');
           }
@@ -337,9 +469,11 @@
           params: {
             protocolVersion: '2026-01-26',
             appInfo: { name: 'hexis-knowledge-page', version: '1.0.0' },
-            // Asks the host for nothing: no tool calls, no messages, no
-            // model context. Links go out through ui/open-link, which every
-            // host offers.
+            // Declares nothing. The extension has no way for a view to say
+            // it CALLS server tools (`tools` here would mean the view
+            // exposes tools of its own); whether the host runs them for a
+            // view is the host's to say, in the reply's `serverTools`.
+            // Links go out through ui/open-link, which every host offers.
             appCapabilities: {},
           },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.28.0",
+  "version": "0.29.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",
@@ -55,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.28.0",
-    "@bevel-software/platform-shared": "0.28.0"
+    "@bevel-software/platform-mcp-core": "0.29.0",
+    "@bevel-software/platform-shared": "0.29.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/__tests__/compose-embed.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest';
+import { testKbContext, TEST_BRANCH_MODEL } from '../../__tests__/kb-context.js';
+import { makeRolesYamlWriteValidator } from '../../modules/access-model/roles-yaml-guard.js';
+import { createFileReaderRegistry } from '../../modules/workspace/file-readers/file-reader.registry.js';
+import type { DocExtractOutcome, DocExtractService } from '../../modules/workspace/file-readers/doc-extract.service.js';
+import { composeEmbedService, type EmbedComposition } from '../compose-embed.js';
+import { EmbedRefParseError } from '../../modules/embed/embed-link.js';
+
+const KB = 'knowledge-base';
+const BRANCH = TEST_BRANCH_MODEL.defaultBranch;
+const REPO = 'Data/Thing.md';
+const USER = { id: 'u-1', email: 'alice@bevel.software', name: 'Alice' };
+
+/** The composition root's deps, as mocks: enough to mint and to say who is looking. */
+function deps(): EmbedComposition {
+  const extract = async (): Promise<DocExtractOutcome> => ({ ok: false, message: 'no documents here' });
+  return {
+    config: { jwtSecret: 'test-jwt-secret', embedSharedSecret: '', publicFrontendUrl: 'https://hexis.example', kbDirName: KB },
+    kb: testKbContext({ kbDirName: KB }),
+    workspaceService: {
+      getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch), kbDirName: KB })),
+      isFile: vi.fn(async (_id: string, wsPath: string) => wsPath === `${KB}/${REPO}`),
+      readFileBinary: vi.fn(async () => Buffer.from('# Thing\n')),
+      writeFile: vi.fn(async () => undefined),
+      withPathTurn: vi.fn(async (_id: string, _p: string, op: () => Promise<unknown>) => op()),
+    },
+    accessControl: { canRead: vi.fn(async () => true), canWrite: vi.fn(async () => true) } as never,
+    authService: { getUserById: vi.fn(async () => USER), isEmailDomainAllowed: () => true, isActive: async () => true },
+    workflowService: {} as never,
+    gitService: {} as never,
+    accountLinks: { getUserId: async () => null, link: async () => undefined, listForUser: async () => [], unlink: async () => true },
+    readers: createFileReaderRegistry({ extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService),
+    validateWrite: makeRolesYamlWriteValidator(KB),
+  };
+}
+
+/**
+ * The composition root is the one place the distribution's ports reach the
+ * embed. Pinned here through that composition, not by handing the service a
+ * resolver directly: a node-id reference resolves through the port when one
+ * is registered, and is refused when none is — which is what a core-only
+ * deployment ships.
+ */
+describe('composeEmbedService', () => {
+  // The app's copy-link form: the full address of a node, which is its id.
+  const NODE_LINK = `https://hexis.example/workspace/${encodeURIComponent(BRANCH)}/abc-123`;
+
+  it('resolves a node-id reference through the registered port, and mints for the file it names', async () => {
+    const embedNodeIdResolver = vi.fn(async (id: string) => (id === 'abc-123' ? REPO : null));
+    const service = composeEmbedService(deps(), { embedNodeIdResolver });
+    const { token } = await service.mintForUser({ userId: USER.id, reference: NODE_LINK });
+    expect(embedNodeIdResolver).toHaveBeenCalledWith('abc-123');
+    expect((await service.viewerOf(token)).repoRelative).toBe(REPO);
+    // An id the graph does not know is refused as a dead reference.
+    await expect(service.mintForUser({ userId: USER.id, reference: 'nope-1' })).rejects.toThrow(EmbedRefParseError);
+  });
+
+  it('refuses a node-id reference when no port is registered — core has no graph', async () => {
+    const service = composeEmbedService(deps(), {});
+    await expect(service.mintForUser({ userId: USER.id, reference: NODE_LINK })).rejects.toThrow(EmbedRefParseError);
+    // A path reference is untouched by the absence of a resolver.
+    const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
+    expect((await service.viewerOf(token)).repoRelative).toBe(REPO);
+  });
+});

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

@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest';
-import { createShutdown, holdCommitWorkerLease, holdable, stopCore, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import { createShutdown, stopCore, withStartupTask, type LeasedWorker } from '../../index.js';
+// The lease helpers are the module's own, not on the entry point: their
+// ordering is pinned here, where the module is the unit under test.
+import { holdCommitWorkerLease, holdable } from '../lifecycle.js';
 import { BevelSecretsVariableLoader, registerBevelSecretsVariableLoader } from '../../modules/secrets-vault/secrets-variable-loader.js';
 import type { AdvisoryLease } from '../../modules/database/advisory-lock.js';
 
@@ -254,12 +257,12 @@ describe('createShutdown', () => {
             order.push('commitWorker.stop');
           },
         },
-        backgroundJobs: {
+        pluginJoinRequestJobs: {
           stopSweeping() {
-            order.push('backgroundJobs.stopSweeping');
+            order.push('pluginJoinRequestJobs.stopSweeping');
           },
           async drain() {
-            order.push('backgroundJobs.drain');
+            order.push('pluginJoinRequestJobs.drain');
           },
         },
         agentUploadStore: {
@@ -296,12 +299,12 @@ describe('createShutdown', () => {
     expect(d.order).toEqual([
       'server.close',
       'server.closeAllConnections',
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       // The upload sweep is stopped in the same breath as the other timers,
       // and drained before the pool goes: a graph that is stopping must not
       // leave a sweep walking the staging root its replacement will stage into.
       'agentUploadStore.stopSweeping',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
@@ -311,8 +314,8 @@ describe('createShutdown', () => {
   it('waits for the jobs a tick already started before the pool goes, within the budget', async () => {
     const d = deps();
     let release: () => void = () => undefined;
-    d.deps.backgroundJobs!.drain = () => {
-      d.order.push('backgroundJobs.drain');
+    d.deps.pluginJoinRequestJobs!.drain = () => {
+      d.order.push('pluginJoinRequestJobs.drain');
       return new Promise<void>((resolve) => {
         release = resolve;
       });
@@ -326,9 +329,9 @@ describe('createShutdown', () => {
     expect(d.order).toEqual([
       'server.close',
       'server.closeAllConnections',
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
     ]);
     release();
     await done;
@@ -348,7 +351,7 @@ describe('createShutdown', () => {
     // `commitWorker.stop` — which awaits an in-flight commit and can take
     // most of the shutdown budget — would start fresh clone/commit/push work
     // that the process exit immediately after kills mid-git.
-    const stopped = d.order.indexOf('backgroundJobs.stopSweeping');
+    const stopped = d.order.indexOf('pluginJoinRequestJobs.stopSweeping');
     expect(stopped).toBeGreaterThanOrEqual(0);
     expect(stopped).toBeLessThan(d.order.indexOf('commitWorker.stop'));
     expect(stopped).toBeLessThan(d.order.indexOf('db.end'));
@@ -357,7 +360,7 @@ describe('createShutdown', () => {
   it('shuts down cleanly when no background jobs were built yet', async () => {
     const d = deps();
     // A stop that lands mid-boot: the services exist, the jobs do not.
-    delete (d.deps as { backgroundJobs?: unknown }).backgroundJobs;
+    delete (d.deps as { pluginJoinRequestJobs?: unknown }).pluginJoinRequestJobs;
     delete (d.deps as { agentUploadStore?: unknown }).agentUploadStore;
     const shutdown = createShutdown(d.deps as never);
     const done = shutdown('SIGTERM');
@@ -374,8 +377,8 @@ describe('createShutdown', () => {
 
   it('does not wait past the budget for jobs that never finish, and still ends the pool', async () => {
     const d = deps();
-    d.deps.backgroundJobs!.drain = () => {
-      d.order.push('backgroundJobs.drain');
+    d.deps.pluginJoinRequestJobs!.drain = () => {
+      d.order.push('pluginJoinRequestJobs.drain');
       return new Promise<void>(() => undefined); // a clone that never returns
     };
     const shutdown = createShutdown(d.deps as never, { deadlineMs: 60 });
@@ -384,7 +387,7 @@ describe('createShutdown', () => {
     d.finishClose();
     await done;
     expect(d.order.slice(-4)).toEqual([
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
@@ -400,9 +403,9 @@ describe('createShutdown', () => {
     expect(d.order).toEqual([
       'server.close',
       'server.closeAllConnections',
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'commitWorker.stop',
       'db.end',
@@ -432,12 +435,12 @@ describe('stopCore', () => {
             order.push('commitWorker.stop');
           },
         },
-        backgroundJobs: {
+        pluginJoinRequestJobs: {
           stopSweeping() {
-            order.push('backgroundJobs.stopSweeping');
+            order.push('pluginJoinRequestJobs.stopSweeping');
           },
           async drain() {
-            order.push('backgroundJobs.drain');
+            order.push('pluginJoinRequestJobs.drain');
           },
         },
         agentUploadStore: {
@@ -478,11 +481,11 @@ describe('stopCore', () => {
     const g = graph();
     await stopCore(g.core as never);
     expect(g.order).toEqual([
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
       'workflowService.stopTidying',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'workflowService.drainTidy',
       'commitWorker.stop',
@@ -523,10 +526,10 @@ describe('stopCore', () => {
     const core = { ...g.core, startupRetry: null, secretsScope: undefined };
     await stopCore(core as never);
     expect(g.order).toEqual([
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'workflowService.stopTidying',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'workflowService.drainTidy',
       'commitWorker.stop',
@@ -539,11 +542,11 @@ describe('stopCore', () => {
     const core = { ...g.core, commitWorker: { stop: () => new Promise<void>(() => undefined) } };
     await stopCore(core as never, { deadlineMs: 50 });
     expect(g.order).toEqual([
-      'backgroundJobs.stopSweeping',
+      'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
       'workflowService.stopTidying',
-      'backgroundJobs.drain',
+      'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
       'workflowService.drainTidy',
       'db.end',

package/src/core/catalog-revision.ts

@@ -29,10 +29,12 @@ const log = logger('catalog-revision');
  */
 
 /**
- * A skill's line: everything `list_skills` shows about it on an AGENT
+ * A skill's line: what `list_skills` shows about the skill ITSELF on an AGENT
  * surface. Not `plugins`, which only the browser route decorates onto the
  * catalog — a field no agent-facing listing carries cannot be a change one
- * owes a refresh for.
+ * owes a refresh for. Not `canWrite` either: it is a verdict about the caller,
+ * judged per call by the tool, not part of the skill, and it is never on the
+ * summaries this digest reads.
  */
 function skillFingerprint(s: SkillSummary): string {
   return [s.name, s.path, s.version ?? '', s.description].join('\u0000');

package/src/core/compose-embed.ts

@@ -0,0 +1,50 @@
+import type { IGitService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { KbContext } from '../shared/kb-context.js';
+import type { IAccessControl } from '../modules/access/access-control.interface.js';
+import type { WriteValidator } from '../modules/kb-fs/index.js';
+import type { FileReaderRegistry } from '../modules/workspace/index.js';
+import type { CorePorts } from './core-ports.js';
+import type { IAccountLinkService } from '../modules/embed/account-link.service.js';
+import type { EmbedAuthPort, EmbedWorkspacePort } from '../modules/embed/embed.interface.js';
+import { EmbedService, type EmbedConfig } from '../modules/embed/embed.service.js';
+
+/** What the composition root hands the embed: the services it reads and writes through. */
+export interface EmbedComposition {
+  config: EmbedConfig;
+  kb: KbContext;
+  workspaceService: EmbedWorkspacePort;
+  accessControl: IAccessControl;
+  authService: EmbedAuthPort;
+  workflowService: IWorkflowService;
+  gitService: IGitService;
+  accountLinks: IAccountLinkService;
+  /** The SAME extension-to-reader registry `read_file` dispatches on. */
+  readers: FileReaderRegistry;
+  /** The SAME pre-disk gate the file editor and the agent tools run. */
+  validateWrite: WriteValidator;
+}
+
+/**
+ * The embed service as the composition root builds it — the one place the
+ * distribution's ports reach it. Lives in `core/`, beside the composition
+ * root it serves: the ports are core's contract with a distribution, and a
+ * module never reaches up into core. A node-id reference (`/workspace/<branch>/
+ * <id>`, the app's copy-link form) resolves only where a node graph is: the
+ * distribution's, when it registers `ports.embedNodeIdResolver`; core has
+ * none and refuses such a reference.
+ */
+export function composeEmbedService(deps: EmbedComposition, ports: Pick<CorePorts, 'embedNodeIdResolver'>): EmbedService {
+  return new EmbedService(
+    deps.config,
+    deps.kb,
+    deps.workspaceService,
+    deps.accessControl,
+    deps.authService,
+    deps.workflowService,
+    deps.gitService,
+    deps.accountLinks,
+    deps.readers,
+    deps.validateWrite,
+    ports.embedNodeIdResolver ?? null,
+  );
+}

package/src/core/core-ports.ts

@@ -10,6 +10,7 @@ import type { IAccountAdmission } from '../modules/auth/account-admission.js';
 import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
 import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
+import type { EmbedNodeIdResolver } from '../modules/embed/embed.interface.js';
 
 /**
  * Every seam the enterprise overlay can fill in the CORE composition
@@ -138,6 +139,15 @@ export interface CorePorts {
    * `modules/write-access/write-access.ts`.
    */
   writeAccess?: IWriteAccess;
+  /**
+   * How an embed reference that is a bare NODE ID (`/workspace/<branch>/<id>`,
+   * the app's copy-link form) becomes the repository path it names. Core has
+   * no node graph, so core refuses such a reference; a distribution with one
+   * answers from it, and the Atlassian connector's links to nodes mint as
+   * they did when that distribution served the embed itself. Returns null
+   * for an id that names nothing. See `modules/embed/embed.interface.ts`.
+   */
+  embedNodeIdResolver?: EmbedNodeIdResolver;
 }
 
 /**

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

@@ -509,7 +509,13 @@ export async function createCoreServer(
   // 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);
+  registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker, {
+    accessControl: core.accessControl,
+    defaultWorkspaceId: () => core.kb.defaultWorkspaceId(),
+    // A skill's files as committed on the default branch, for the whole-skill
+    // verdict: the same clone and the same git the skill's history is read from.
+    committedFiles: core.gitService,
+  });
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
   registerPluginsTools(core.toolRegistry, core.kb);

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

@@ -18,7 +18,8 @@ import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
 import { WorkspaceService } from '../modules/workspace/workspace.service.js';
 import { AccountLinkService } from '../modules/embed/account-link.service.js';
-import { EmbedService } from '../modules/embed/embed.service.js';
+import type { EmbedService } from '../modules/embed/embed.service.js';
+import { composeEmbedService } from './compose-embed.js';
 import { McpAppService, type IMcpAppService } from '../modules/embed/mcp-app.js';
 import { createFileReaderRegistry } from '../modules/workspace/file-readers/file-reader.registry.js';
 import { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
@@ -1288,26 +1289,31 @@ export async function createCoreServices(
   // judges them with the same access resolver the app file page uses, so what
   // a reader may see and change inside a chat is what they may see and change
   // in the app — never a second answer to the same question.
-  const embedService = new EmbedService(
-    // The RESOLVED checkout folder, not the env's: `config.kbDirName` is only
-    // the environment value, empty on a deployment that took the default or
-    // named it in setup, and every path the embed builds starts with it.
-    { ...config, kbDirName },
-    kb,
-    workspaceService,
-    accessControl,
-    authService,
-    workflowService,
-    gitService,
-    new AccountLinkService(db),
-    // The SAME extension-to-reader registry `read_file` dispatches on, so the
-    // embed answer to "is this text, or bytes a renderer fetches?" cannot
-    // disagree with what a read of the file returns.
-    createFileReaderRegistry(docExtractService),
-    // The SAME pre-disk gate the file editor and the agent tools run: a
-    // `roles.yaml` that would not parse is refused before it is written, from
-    // a chat exactly as from the app.
-    makeRolesYamlWriteValidator(kbDirName),
+  const embedService = composeEmbedService(
+    {
+      // The RESOLVED checkout folder, not the env's: `config.kbDirName` is only
+      // the environment value, empty on a deployment that took the default or
+      // named it in setup, and every path the embed builds starts with it.
+      config: { ...config, kbDirName },
+      kb,
+      workspaceService,
+      accessControl,
+      authService,
+      workflowService,
+      gitService,
+      accountLinks: new AccountLinkService(db),
+      // The SAME extension-to-reader registry `read_file` dispatches on, so the
+      // embed answer to "is this text, or bytes a renderer fetches?" cannot
+      // disagree with what a read of the file returns.
+      readers: createFileReaderRegistry(docExtractService),
+      // The SAME pre-disk gate the file editor and the agent tools run: a
+      // `roles.yaml` that would not parse is refused before it is written, from
+      // a chat exactly as from the app.
+      validateWrite: makeRolesYamlWriteValidator(kbDirName),
+    },
+    // A node-id reference resolves only where a node graph is: the
+    // distribution's, when it registers one (`ports.embedNodeIdResolver`).
+    ports,
   );
   // The `ui://` view `open_page` carries, with the one origin it may frame:
   // this deployment own public origin.