@bevel-software/platform-core-backend 0.33.0 → 0.34.0

package/migrations/meta/_journal.json

@@ -155,6 +155,20 @@
       "when": 1792491290917,
       "tag": "0021_data_migrations_ledger",
       "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1792657514328,
+      "tag": "0022_session_version",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1793089896833,
+      "tag": "0023_agent_path",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.33.0",
+  "version": "0.34.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.33.0",
-    "@bevel-software/platform-shared": "0.33.0"
+    "@bevel-software/platform-mcp-core": "0.34.0",
+    "@bevel-software/platform-shared": "0.34.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/pg-scratch.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * `openMigratedScratchDb` owns the pool it opens until it hands the handle
+ * over: when the migrations fail, the caller never receives `close`, so the
+ * helper must close the pool itself and let the error through. No Postgres
+ * here — the connection, the migrations and the `pg` admin client are stubs,
+ * since the subject is the helper's ownership of what it opened, not the
+ * database.
+ */
+
+const stubs = vi.hoisted(() => ({
+  db: { kind: 'fake-db' },
+  createDb: vi.fn(),
+  closeDb: vi.fn(async () => {}),
+  runCoreMigrations: vi.fn(async () => {}),
+  adminQuery: vi.fn(async () => ({ rows: [] })),
+}));
+
+vi.mock('../modules/database/connection.js', () => ({
+  createDb: stubs.createDb,
+  closeDb: stubs.closeDb,
+}));
+vi.mock('../modules/database/migrate.js', () => ({
+  runCoreMigrations: stubs.runCoreMigrations,
+}));
+vi.mock('../assets.js', () => ({ coreMigrationsDir: () => '/migrations' }));
+vi.mock('pg', () => ({
+  default: {
+    Client: class {
+      connect = async () => {};
+      query = stubs.adminQuery;
+      end = async () => {};
+    },
+  },
+}));
+
+// Read once, at import: a URL the stubbed admin client will never dial.
+process.env.TEST_DATABASE_URL = 'postgres://scratch:scratch@127.0.0.1:1/admin';
+const { openMigratedScratchDb } = await import('./pg-scratch.js');
+
+describe('openMigratedScratchDb', () => {
+  beforeEach(() => {
+    stubs.createDb.mockReturnValue(stubs.db);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    stubs.runCoreMigrations.mockResolvedValue(undefined);
+  });
+
+  it('hands the migrated database over with a close the caller owns', async () => {
+    const opened = await openMigratedScratchDb('hexis_owned');
+    expect(opened.db).toBe(stubs.db);
+    expect(stubs.runCoreMigrations).toHaveBeenCalledWith(stubs.db, '/migrations');
+    // The pool stays open until the caller closes it.
+    expect(stubs.closeDb).not.toHaveBeenCalled();
+    await opened.close();
+    expect(stubs.closeDb).toHaveBeenCalledWith(stubs.db);
+  });
+
+  it('closes the pool it opened when the migrations fail, and lets the failure through', async () => {
+    stubs.runCoreMigrations.mockRejectedValueOnce(new Error('migration 0022 failed'));
+    await expect(openMigratedScratchDb('hexis_failed')).rejects.toThrow('migration 0022 failed');
+    // Closed by the helper: the caller never received a handle to close.
+    expect(stubs.closeDb).toHaveBeenCalledTimes(1);
+    expect(stubs.closeDb).toHaveBeenCalledWith(stubs.db);
+  });
+});

package/src/__tests__/pg-scratch.ts

@@ -1,5 +1,8 @@
 import { randomBytes } from 'node:crypto';
 import pg from 'pg';
+import { closeDb, createDb, type Database } from '../modules/database/connection.js';
+import { runCoreMigrations } from '../modules/database/migrate.js';
+import { coreMigrationsDir } from '../assets.js';
 
 /**
  * The one fixture for tests that cross a real Postgres. They run where
@@ -9,6 +12,11 @@ import pg from 'pg';
  * of its own, made by {@link scratchDatabaseUrl} and dropped by
  * {@link dropScratchDatabases}; the database the URL names is only connected
  * to, never written.
+ *
+ * A test that wants the schema as a deployment has it opens the database
+ * through {@link openMigratedScratchDb}: this fixture is the one place
+ * outside the database module that knows how a core database is connected
+ * to and migrated, so a module's test need not import those files itself.
  */
 export const PG_ADMIN_URL = process.env.TEST_DATABASE_URL;
 
@@ -38,6 +46,29 @@ export async function scratchDatabaseUrl(prefix: string): Promise<string> {
   return url.toString();
 }
 
+/**
+ * A scratch database at the current core schema — created, connected to with
+ * the PII key given (a fresh random one when none is), and every core
+ * migration run — as a module's test wants it. `close` ends the connection;
+ * {@link dropScratchDatabases} drops the database afterwards as for any other.
+ */
+export async function openMigratedScratchDb(
+  prefix: string,
+  opts: { piiKey?: string } = {},
+): Promise<{ db: Database; close: () => Promise<void> }> {
+  const piiKey = opts.piiKey ?? randomBytes(32).toString('base64');
+  const db = createDb(await scratchDatabaseUrl(prefix), { piiKey });
+  try {
+    await runCoreMigrations(db, coreMigrationsDir());
+  } catch (err) {
+    // The caller never receives the handle on this path, so the pool is
+    // closed here; the database itself is dropped with the others.
+    await closeDb(db);
+    throw err;
+  }
+  return { db, close: () => closeDb(db) };
+}
+
 /** Drop every scratch database this file made; for `afterAll`, with {@link PG_TEST_TIMEOUT}. */
 export async function dropScratchDatabases(): Promise<void> {
   const names = created.splice(0);

package/src/__tests__/slow-ripgrep.ts

@@ -0,0 +1,65 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
+
+/**
+ * A ripgrep that never finishes a TREE search, for the suites about the
+ * search budget and about stopping: an `rg` put first on this process's PATH,
+ * where the server finds its ripgrep. A run reading stdin (the pattern check,
+ * a document's text) is handed to the real `rg`, so a pattern is judged as it
+ * always is; a walk records its process id and sleeps for a minute, which no
+ * budget waits out — or, given `walkMs`, sleeps that long and then finishes
+ * having found nothing, which is how a suite spends a budget in parts.
+ *
+ * `alive()` answers which of the walks it started are still running, so a
+ * suite can assert that a stopped search left no process behind. `remove()`
+ * puts the PATH back.
+ */
+export interface SlowRipgrep {
+  alive(): Promise<number[]>;
+  remove(): Promise<void>;
+}
+
+export async function slowRipgrep(opts: { walkMs?: number } = {}): Promise<SlowRipgrep> {
+  const seconds = opts.walkMs === undefined ? '60' : (opts.walkMs / 1000).toFixed(3);
+  const real = (await promisify(execFile)('sh', ['-c', 'command -v rg'])).stdout.trim();
+  const dir = await mkdtemp(join(tmpdir(), 'slow-rg-'));
+  const pids = join(dir, 'pids');
+  const binary = join(dir, 'rg');
+  await writeFile(
+    binary,
+    [
+      '#!/bin/sh',
+      'for a in "$@"; do last="$a"; done',
+      `if [ "$last" = "-" ]; then exec '${real}' "$@"; fi`,
+      `echo $$ >> '${pids}'`,
+      `exec sleep ${seconds}`,
+      '',
+    ].join('\n'),
+  );
+  await chmod(binary, 0o755);
+  const path = process.env.PATH;
+  process.env.PATH = `${dir}${delimiter}${path ?? ''}`;
+  return {
+    async alive() {
+      const started = (await readFile(pids, 'utf8').catch(() => ''))
+        .split('\n')
+        .filter(Boolean)
+        .map(Number);
+      return started.filter((pid) => {
+        try {
+          process.kill(pid, 0);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+    },
+    async remove() {
+      process.env.PATH = path;
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}

package/src/core/__tests__/boot-without-ripgrep.test.ts

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createCoreServices } from '../../index.js';
+import type { TenantConfig } from '../../core-config.js';
+
+/**
+ * The server's boot, through the package's own entry, on a PATH that carries
+ * git and no ripgrep: it refuses to build any service, naming the binary.
+ */
+describe('booting without ripgrep', () => {
+  const path = process.env.PATH;
+  let bin = '';
+  afterEach(async () => {
+    process.env.PATH = path;
+    if (bin) await rm(bin, { recursive: true, force: true });
+    bin = '';
+  });
+
+  it('refuses to start, naming rg and the Dockerfile that installs it', async () => {
+    const git = (await promisify(execFile)('sh', ['-c', 'command -v git'])).stdout.trim();
+    bin = await mkdtemp(join(tmpdir(), 'no-rg-'));
+    await symlink(git, join(bin, 'git'));
+    process.env.PATH = bin;
+    // The binaries are checked before the configuration is read, so none is needed.
+    const err = (await createCoreServices({} as TenantConfig).catch((e: unknown) => e)) as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toMatch(/^ripgrep \(`rg`\) is required on the server's PATH but could not be run: .*ENOENT/);
+    expect(err.message).toContain('The Hexis Dockerfile installs it');
+  });
+});

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

@@ -4,6 +4,7 @@ import type { Server } from 'node:http';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { SkillSummary } from '../../modules/skills/skills.contract.js';
 import { catalogRevision, createCatalogRevisionRoutes } from '../catalog-revision.js';
+import { agentFile, agentScopeOver, inMemoryKb, type InMemoryKb } from '../../modules/agent-scope/__tests__/in-memory-kb.js';
 
 /**
  * The fingerprint a long-lived client polls to learn that the released catalog
@@ -228,3 +229,91 @@ describe('GET /agent/catalog-revision', () => {
     expect(await res.json()).toEqual({ revision: catalogRevision([], []), tools: 0, skills: 0 });
   });
 });
+
+describe('GET /agent/catalog-revision, for a connection made as an .agent file', () => {
+  let http: Server | null = null;
+
+  afterEach(async () => {
+    if (http) await new Promise<void>((resolve) => http!.close(() => resolve()));
+    http = null;
+  });
+
+  const lines = [
+    ['ops', 'ops', 'Plugins/Ops/ops.tool', 'http', 'remote', '', 's'].join('\u0000'),
+    ['crm', 'crm', 'Plugins/Sales/crm.tool', 'http', 'remote', '', 's'].join('\u0000'),
+  ];
+  const paths = ['Plugins/Ops/ops.tool', 'Plugins/Sales/crm.tool'];
+  const skills = [skill({ name: 'notes', path: 'Skills/Release/notes' }), skill({ name: 'pitch', path: 'Skills/Sales/pitch' })];
+
+  async function mount(kb: InMemoryKb, agentPath: string | undefined) {
+    // The two services narrow by the predicate they are handed, AFTER their
+    // own read gate — stood in for here by the lists above, all readable.
+    const catalogFingerprints = vi.fn(async (_email: string, within?: (p: string) => boolean) =>
+      lines.filter((_, i) => !within || within(paths[i]!)),
+    );
+    const listSkills = vi.fn(async (_email: string, opts?: { within?: (p: string) => boolean }) =>
+      skills.filter((s) => !opts?.within || opts.within(s.path)),
+    );
+    const agentScope = agentScopeOver(kb);
+    const resolve = vi.spyOn(agentScope, 'resolve');
+    const app = express();
+    app.use(
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints } as never,
+        skills: { listSkills } as never,
+        manualAuth: (req, _res, next) => {
+          req.toolAuth = { userId: 'u1', ...(agentPath ? { agentPath } : {}) } as never;
+          next();
+        },
+        resolveUserEmail: async () => 'ada@example.com',
+        agentScope,
+      }),
+    );
+    http = app.listen(0);
+    await new Promise<void>((r) => http!.once('listening', r));
+    const url = `http://127.0.0.1:${(http.address() as AddressInfo).port}/agent/catalog-revision`;
+    const read = async () =>
+      (await (await fetch(url)).json()) as { revision: string; tools: number; skills: number; connection?: unknown };
+    return { read, catalogFingerprints, listSkills, resolve };
+  }
+
+  it('Everything is the revision it always was: nothing resolved, nothing narrowed, no `connection`', async () => {
+    const { read, catalogFingerprints, listSkills, resolve } = await mount(inMemoryKb({}), undefined);
+    expect(await read()).toEqual({ revision: catalogRevision(lines, skills), tools: 2, skills: 2 });
+    expect(catalogFingerprints).toHaveBeenCalledWith('ada@example.com');
+    expect(listSkills).toHaveBeenCalledWith('ada@example.com');
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it("is the fingerprint of what the agent loads, and names the agent", async () => {
+    const kb = inMemoryKb({ 'Agents/ops.agent': agentFile('name: ops\nconnectors: [Plugins/Ops]\nskills: [Skills/Release]') });
+    const { read } = await mount(kb, 'Agents/ops.agent');
+    const body = await read();
+    expect(body.tools).toBe(1);
+    expect(body.skills).toBe(1);
+    expect(body.connection).toEqual({ agent: { path: 'Agents/ops.agent', name: 'ops' } });
+    expect(body.revision).not.toBe(catalogRevision(lines, skills));
+  });
+
+  it('moves at the next read after the .agent file is edited — no reconnect', async () => {
+    const kb = inMemoryKb({ 'Agents/ops.agent': agentFile('connectors: [Plugins/Ops]') });
+    const { read } = await mount(kb, 'Agents/ops.agent');
+    const before = await read();
+    expect(await read()).toEqual(before);
+    kb.files.set('Agents/ops.agent', agentFile('connectors: [Plugins/Ops]\nskills: [Skills/Sales]'));
+    const after = await read();
+    expect(after.revision).not.toBe(before.revision);
+    expect(after.skills).toBe(1);
+    // Even an edit that changes nothing listed moves it: the file is the configuration.
+    kb.files.set('Agents/ops.agent', agentFile('connectors: [Plugins/Ops]\nskills: [Skills/Sales]\ndescription: now described'));
+    expect((await read()).revision).not.toBe(after.revision);
+  });
+
+  it('a deleted file is an empty catalog with the reason, never Everything', async () => {
+    const { read } = await mount(inMemoryKb({}), 'Agents/gone.agent');
+    const body = await read();
+    expect(body.tools).toBe(0);
+    expect(body.skills).toBe(0);
+    expect((body.connection as { unavailable?: string }).unavailable).toMatch(/no longer exists or which you can no longer read/);
+  });
+});

package/src/core/__tests__/damaged-document.tools.test.ts

@@ -16,7 +16,7 @@ import { RoutineWritePolicyService } from '../../modules/workspace/routine-write
 import { WorkflowHooks } from '../../modules/workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../../modules/workspace/agent-access.gate.js';
 import { SpillStore } from '../../modules/workspace/spill-store.js';
-import { WorkerPatternMatcher } from '../../modules/workspace/bounded-matcher.js';
+import { RipgrepPatternMatcher } from '../../modules/workspace/index.js';
 import { DocExtractService, type UnreadableDocument } from '../../modules/workspace/file-readers/doc-extract.service.js';
 import type { IDocumentExtractor } from '../../modules/workspace/file-readers/document-extractor.contract.js';
 import { WorkerDocumentExtractor, type WorkerDocumentExtractorOptions } from '../../modules/workspace/file-readers/extract-in-worker.js';
@@ -82,7 +82,7 @@ async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {})
   };
   const told: UnreadableDocument[] = [];
   const docExtract = new DocExtractService(join(tempDir, '.doc-extract'), counting, { onUnreadable: (d) => told.push(d) });
-  const matcher = new WorkerPatternMatcher();
+  const matcher = new RipgrepPatternMatcher();
 
   const registry = new ToolRegistry();
   const resolve = async (auth: ToolAuth, signal: AbortSignal, sessionId?: string): Promise<ToolContext> => ({

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

@@ -37,7 +37,7 @@ afterEach(async () => {
 
 /** A core whose startup phase fails in a way the test picks. */
 function bootable(runAll: () => Promise<void>) {
-  const retries = { started: 0 };
+  const retries = { started: 0, tmpSweeps: 0 };
   const core: BootableCore = {
     config: { workspacesRoot },
     kbDirName: 'knowledge-base',
@@ -53,6 +53,11 @@ function bootable(runAll: () => Promise<void>) {
       tidyAfterSweep: async () => ({ closedEmpty: 0, removedLeftovers: 0 }),
     } as BootableCore['workflowService'],
     pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
+    tmpSweeper: {
+      startSweeping() {
+        retries.tmpSweeps += 1;
+      },
+    },
     startupRetry: null,
   };
   return { core, retries };
@@ -79,6 +84,8 @@ describe('startCore over a repository the host will not serve', () => {
     // that is granted access to it, needs no settings change on this side.
     expect(retries.started).toBe(1);
     expect(core.startupRetry).not.toBeNull();
+    // The tmp sweep reads the workspaces root alone, so a gated boot still runs it.
+    expect(retries.tmpSweeps).toBe(1);
   });
 
   it('comes up gated when the host rejected the credentials', async () => {

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

@@ -5,7 +5,10 @@ import { createShutdown, stopCore, withStartupTask, type LeasedWorker } from '..
 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';
-import { WorkerPatternMatcher } from '../../modules/workspace/bounded-matcher.js';
+import { realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { RipgrepPatternMatcher } from '../../modules/workspace/index.js';
+import { slowRipgrep } from '../../__tests__/slow-ripgrep.js';
 
 /** A lease the suite scripts: what each `tryAcquire` answers, and a way to lose it. */
 function fakeLease(answers: boolean[]) {
@@ -510,6 +513,24 @@ describe('stopCore', () => {
     expect(drained).toBeLessThan(g.order.indexOf('db.end'));
   });
 
+  it('stops the workspaces\' tmp sweep with the graph: the timer cleared, the sweep in flight awaited before the pool goes', async () => {
+    const g = graph();
+    const tmpSweeper = {
+      stopSweeping() {
+        g.order.push('tmpSweeper.stopSweeping');
+      },
+      async drainSweep() {
+        g.order.push('tmpSweeper.drainSweep');
+      },
+    };
+    await stopCore({ ...g.core, tmpSweeper } as never);
+    const stopped = g.order.indexOf('tmpSweeper.stopSweeping');
+    const drained = g.order.indexOf('tmpSweeper.drainSweep');
+    expect(stopped).toBeGreaterThanOrEqual(0);
+    expect(stopped).toBeLessThan(drained);
+    expect(drained).toBeLessThan(g.order.indexOf('db.end'));
+  });
+
   it('forgets the graph\'s secrets scope, so a descriptor that outlives it resolves nothing', async () => {
     const g = graph();
     registerBevelSecretsVariableLoader(
@@ -538,19 +559,31 @@ describe('stopCore', () => {
     ]);
   });
 
-  it('ends the grep matcher\'s workers, so an evicted graph leaves no search running behind it', async () => {
+  it('ends the grep matcher\'s running searches, so an evicted graph leaves no ripgrep running behind it', async () => {
     const g = graph();
-    const patternMatcher = new WorkerPatternMatcher();
-    // A search holding a worker for its whole 5 s budget when the graph is stopped.
-    const running = patternMatcher.search('^(a+)+$', '').matchingLines([`${'a'.repeat(39)}!`], 1);
-    await new Promise((r) => setTimeout(r, 100));
-    const started = Date.now();
-    await stopCore({ ...g.core, patternMatcher } as never);
-    await expect(running).rejects.toMatchObject({ status: 503, details: { code: 'search_busy' } });
-    expect(Date.now() - started).toBeLessThan(1_000);
-    // Closed for good: nothing after the stop starts a worker.
-    await expect(patternMatcher.search('b', '').matchingLines(['b'], 1)).rejects.toMatchObject({ status: 503 });
-    expect(g.order.at(-1)).toBe('db.end');
+    const slow = await slowRipgrep();
+    const patternMatcher = new RipgrepPatternMatcher();
+    try {
+      // A tree search that would hold its ripgrep for the whole 5 s budget when the graph is stopped.
+      const search = await patternMatcher.search('needle', { ignoreCase: false });
+      // A scope's cwd is canonical: where the temp folder is a link (macOS),
+      // the raw spelling would read as a root that has moved, and walk nothing.
+      const cwd = await realpath(tmpdir());
+      const running = (async () => {
+        for await (const file of search.files({ cwd, root: '.' }, { only: ['hit.md'], maxLinesPerFile: 1 })) void file;
+      })();
+      while ((await slow.alive()).length === 0) await new Promise((r) => setTimeout(r, 20));
+      const started = Date.now();
+      await stopCore({ ...g.core, patternMatcher } as never);
+      await expect(running).rejects.toMatchObject({ status: 503, details: { code: 'search_busy' } });
+      expect(Date.now() - started).toBeLessThan(1_000);
+      expect(await slow.alive()).toEqual([]);
+      // Closed for good: nothing after the stop starts a search.
+      await expect(patternMatcher.search('b', { ignoreCase: false })).rejects.toMatchObject({ status: 503 });
+      expect(g.order.at(-1)).toBe('db.end');
+    } finally {
+      await slow.remove();
+    }
   });
 
   it('does not wait past the budget for a worker that never stops, and still ends the pool', async () => {

package/src/core/catalog-revision.ts

@@ -4,6 +4,7 @@ import { logger } from '../shared/logging.js';
 import type { ISkillService, SkillSummary } from '../modules/skills/skills.contract.js';
 import type { IToolManualService } from '../modules/tool-manuals/tool-manuals.contract.js';
 import '../modules/tool-auth/tool-auth.middleware.js'; // Express Request augmentation (req.toolAuth)
+import { resolveConnectionScope, type IAgentScopeResolver } from '../modules/agent-scope/index.js';
 
 const log = logger('catalog-revision');
 
@@ -65,6 +66,14 @@ export function catalogRevision(
    * server already running keeps serving the view it read at startup.
    */
   views: readonly { uri: string; text: string }[] = [],
+  /**
+   * The connection's agent configuration — its path and the digest of its bytes, or
+   * why it cannot be used (`ConnectionScope.fingerprint`) — so an edit of
+   * the file is a new revision even when it changes nothing listed (a new
+   * skill entry that names nothing yet still moves it). Absent for
+   * Everything, whose revision is exactly what it was before agents existed.
+   */
+  agent: string | null = null,
 ): string {
   const lines = [
     ...[...manuals].sort(),
@@ -72,6 +81,7 @@ export function catalogRevision(
     ...skills.map(skillFingerprint).sort(),
     '\u0001',
     ...views.map((v) => `${v.uri}\u0000${createHash('sha256').update(v.text).digest('hex')}`).sort(),
+    ...(agent !== null ? ['\u0001', agent] : []),
   ];
   return createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 32);
 }
@@ -90,6 +100,8 @@ export function createCatalogRevisionRoutes(deps: {
   toolManuals: Pick<IToolManualService, 'catalogFingerprints'>;
   skills: Pick<ISkillService, 'listSkills'>;
   manualAuth: RequestHandler;
+  /** Resolves the scope of a connection made as an agent configuration (`modules/agent-scope`). */
+  agentScope?: Pick<IAgentScopeResolver, 'resolve'>;
   /** 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. */
@@ -104,16 +116,26 @@ export function createCatalogRevisionRoutes(deps: {
       // No resolvable caller is an EMPTY catalog, not a failure: that is what
       // both list surfaces answer such a caller, so the fingerprint agrees
       // with them rather than inventing a third verdict.
+      // A connection made as an agent configuration is fingerprinted over what IT
+      // loads, plus the file itself; Everything asks exactly what it always did.
+      const scope = await resolveConnectionScope(deps.agentScope, email, req.toolAuth?.agentPath);
+      const connectors = scope.connectorFilter();
+      const within = scope.skillFilter();
       const [manuals, skills] = email
-        ? await Promise.all([deps.toolManuals.catalogFingerprints(email), deps.skills.listSkills(email)])
+        ? await Promise.all([
+            connectors ? deps.toolManuals.catalogFingerprints(email, connectors) : deps.toolManuals.catalogFingerprints(email),
+            within ? deps.skills.listSkills(email, { within }) : 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 ?? []) : [];
+      const connection = scope.toWire();
       res.json({
-        revision: catalogRevision(manuals, skills, views),
+        revision: catalogRevision(manuals, skills, views, scope.fingerprint()),
         tools: manuals.length,
         skills: skills.length,
+        ...(connection ? { connection } : {}),
       });
     } catch (err) {
       log.error('catalog-revision failed:', { err });

package/src/core/core-ports.ts

@@ -10,7 +10,34 @@ 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 { IAgentScopeResolver } from '../modules/agent-scope/index.js';
 import type { EmbedNodeIdResolver } from '../modules/embed/embed.interface.js';
+import type { IWorkspaceService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../modules/access/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+import type { ITreeWalker } from '../shared/fs.contract.js';
+import type { IPluginLinkIndex } from '../modules/plugins/index.js';
+
+/**
+ * The core services a distribution's agent-scope resolver reads through,
+ * handed to `CorePorts.agentScope` when core makes it: the clones of the
+ * branches, the person's read gate, the branch model and knowledge-base
+ * layout, the disk walk that finds its configurations, and the plugin link
+ * index that says which plugins a `plugins:`-style entry stands for.
+ *
+ * Each is the service's CONTRACT, not its class: a resolver written against
+ * these runs on any implementation of them — core's own services in a
+ * deployment, a stand-in in a distribution's tests — and a resolver that
+ * needs more than a contract offers asks for the contract to grow, not for
+ * the class.
+ */
+export interface AgentScopeCollaborators {
+  workspaceService: IWorkspaceService;
+  accessControl: IAccessControl;
+  kb: KbContext;
+  disk: ITreeWalker;
+  pluginLinkIndex: IPluginLinkIndex;
+}
 
 /**
  * Every seam the enterprise overlay can fill in the CORE composition
@@ -112,6 +139,21 @@ export interface CorePorts {
    * `modules/agent-guide`.
    */
   agentGuide?: AgentGuideHook;
+  /**
+   * THIS distribution's agent configurations: what "Connect as" offers beside
+   * Everything, and what a connection made as one of them loads (see
+   * `modules/agent-scope`). Core owns the mechanism and no configuration —
+   * the file kind, where it lives and what its definition says are the
+   * distribution's, as the file kinds registered for access verbs are. A
+   * factory, since a resolver reads through core services that exist only
+   * once core is built: called ONCE, during construction, with those
+   * services (`AgentScopeCollaborators`), and its answer is the one resolver
+   * every surface consults from then on — the tool contexts, which capture it
+   * at construction, as much as the routes the server mounts later. Core
+   * default: `noAgentConfigurations()` — nothing is offered, and a connection
+   * recorded as some path loads nothing, never Everything.
+   */
+  agentScope?: (core: AgentScopeCollaborators) => IAgentScopeResolver;
   /**
    * Mirror this composition's branch model and knowledge-base layout onto the
    * shared package's PROCESS-WIDE live bindings (`DEFAULT_BRANCH`,