@bevel-software/platform-core-backend 0.28.1 → 0.30.0

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

@@ -475,7 +475,7 @@ export async function createCoreServer(
   // 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);
-  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);
+  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, core.patternMatcher);
   // `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
@@ -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

@@ -17,8 +17,11 @@ import { getDb, type Database } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
 import { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { KbRepository, repositoryDirFor } from '../modules/workspace/kb-repository.js';
+import type { IKbRepository } from '../modules/workspace/kb-repository.contract.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';
@@ -61,6 +64,8 @@ import { SpillStore } from '../modules/workspace/spill-store.js';
 import { AgentUploadStore, assertUploadsRootOutsideWorkspaces } from '../modules/workspace/agent-upload.store.js';
 import { AgentDownloadStore, type IAgentDownloadStore } from '../modules/workspace/agent-download.store.js';
 import { createDownloadFetcherIdentifier } from '../modules/workspace/agent-download.routes.js';
+import { WorkerPatternMatcher } from '../modules/workspace/bounded-matcher.js';
+import type { IPatternMatcher } from '../modules/workspace/pattern-matcher.contract.js';
 import type { Request } from 'express';
 import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
@@ -242,6 +247,8 @@ export interface CoreServices {
   agentUploadStore: AgentUploadStore;
   /** The bytes `request_file_download` captured, held until their one-time link is fetched or expires. */
   agentDownloadStore: IAgentDownloadStore;
+  /** Runs a caller's `grep` pattern off the request thread under a budget; its workers end when the graph stops. */
+  patternMatcher: IPatternMatcher;
   /**
    * Every user a download fetch identifies itself as, by its bearer and its
    * session cookie — none when it carries none that verifies — so the
@@ -569,6 +576,30 @@ export async function createCoreServices(
    * Under the backups root: a persistent volume of its own, and one nothing
    * sweeps (see the runner's `reconcileClonesWithConfiguredRepository`).
    */
+  // Shared mutex so git and diff operations on the same workspace serialize
+  // against each other — a backup-reseed races a concurrent commit otherwise.
+  const workspaceMutex = new WorkspaceMutex();
+  /**
+   * The knowledge base's ONE repository: every branch workspace is a worktree
+   * of it (see `kb-repository.ts`). One instance, handed to the workspace
+   * service, the startup phase and (through the workspace service) the git
+   * layer, so one fetch serves every workspace and the writes to its one
+   * config file are serialized in one place. Git operations in the worktrees
+   * are not serialized against each other beyond the workspace mutex: git's
+   * own locks cover a repository shared by worktrees.
+   *
+   * Under the backups root, like the set-aside copies: a persistent volume in
+   * every shipped compose file, so no new mount is needed, and outside the
+   * workspaces root, where the orphan sweep never sees it. The folder name
+   * starts with a dot, which no branch — and so no backup ledger's workspace
+   * id — can. On hexis-cloud every tenant has its own backups root: one
+   * repository per tenant.
+   */
+  const kbRepository: IKbRepository = new KbRepository({
+    dir: repositoryDirFor(config.workspacesRoot, kbDirName, path.join(config.backupsRoot, '.kb-repository')),
+    kbRepoUrl: () => repositorySource.url(),
+    gitRunner,
+  });
   const replacedWorkingCopiesRoot = path.join(config.backupsRoot, 'replaced-working-copies');
   /**
    * What must leave with a working copy that is set aside, whoever sets it
@@ -634,6 +665,7 @@ export async function createCoreServices(
             );
           });
       }),
+    kbRepository,
   );
   // The KB startup phase: every seeding, scaffolding and migration concern,
   // run through one runner at the deployment's quiet moments (boot + setup
@@ -671,6 +703,9 @@ export async function createCoreServices(
     // The same folder the workspace service sets aside into — see
     // `replacedWorkingCopiesRoot` above for why the two must agree.
     setAsideRoot: replacedWorkingCopiesRoot,
+    // The one repository every branch workspace is a worktree of — the same
+    // instance the workspace service holds (see `kbRepository` above).
+    repository: kbRepository,
     kbDirName,
     templateDir: config.kbTemplateDir,
     defaultBranch: () => kb.defaultBranch,
@@ -740,6 +775,7 @@ export async function createCoreServices(
       'captured download bytes wait there for their one-time links, so a root inside a workspace would let the ' +
       'file tools read them. Point AGENT_UPLOADS_ROOT at a directory whose parent is outside WORKSPACES_ROOT.',
   });
+  const patternMatcher = new WorkerPatternMatcher();
   const agentDownloadStore = new AgentDownloadStore({
     root: agentDownloadsRoot,
     publicBaseUrl: config.publicBackendUrl,
@@ -826,9 +862,6 @@ export async function createCoreServices(
   // registers its listener here, after this returns (see `AccountHooks`).
   const accountHooks = new AccountHooks();
 
-  // Shared mutex so git and diff operations on the same workspace serialize
-  // against each other — a backup-reseed races a concurrent commit otherwise.
-  const workspaceMutex = new WorkspaceMutex();
   // Workflow lifecycle hooks — the ONE registry this composition shares
   // between GitService (advisory commit validation), the agent-access gate
   // (the blocking agentRead / preWrite hooks), and the composition root,
@@ -1288,26 +1321,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.
@@ -1592,6 +1630,7 @@ export async function createCoreServices(
     spillStore,
     agentUploadStore,
     agentDownloadStore,
+    patternMatcher,
     agentDownloadFetcher,
     docExtractService,
     accessControl,

package/src/core/lifecycle.ts

@@ -425,13 +425,18 @@ export interface CoreStopDeps {
   /** The lease loop from {@link holdCommitWorkerLease}: its stop finishes the in-flight commit and releases the lease. */
   commitWorker: Pick<LeaseLoopHandle, 'stop'>;
   /**
-   * Background work to wind down before the pool goes — the join-request
-   * sweep and its jobs, today. The timer is stopped first so nothing new is
-   * scheduled, then the jobs already running are awaited (within the budget)
-   * so the pool is not ended under a clone or a push that is still writing
-   * to it. Optional: a caller that has not built them yet passes nothing.
+   * The plugin join-request jobs, whose sweep must be wound down before the
+   * pool goes. The timer is stopped first so nothing new is scheduled, then
+   * the jobs already running are awaited (within the budget) so the pool is
+   * not ended under a clone or a push that is still writing to it. Optional:
+   * a caller that has not built them yet passes nothing.
+   *
+   * Named as `CoreServices` names it, because the graph IS what is passed
+   * here (`stopCore(graph.core)`): under another name the slot stayed empty,
+   * the sweep outlived every stopped graph, and a multi-tenant host gained
+   * one more sweeper querying an ended pool, every minute, per eviction.
    */
-  backgroundJobs?: { stopSweeping(): void; drain(): Promise<void> };
+  pluginJoinRequestJobs?: { stopSweeping(): void; drain(): Promise<void> };
   /**
    * The agent upload store, whose own sweep deletes staged bytes nobody
    * applied. Stopped with this graph because the next graph for the same
@@ -443,6 +448,12 @@ export interface CoreStopDeps {
   agentUploadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
   /** The agent download store, whose sweep deletes captured bytes nobody fetched — stopped for the same reason. */
   agentDownloadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
+  /**
+   * The grep pattern matcher, whose worker threads are this graph's own: ended
+   * here so a graph a tenant host evicts leaves no worker behind. Optional: a
+   * caller that has not built one passes nothing.
+   */
+  patternMatcher?: { close(): Promise<void> };
   /**
    * The workflow service, for the tidy-up it runs after each sweep (closing
    * empty requests, removing leftover branches): detached from whatever
@@ -532,7 +543,7 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // server is closed (or the tenant is no longer routed to), so this is the
   // earliest point the interval is dead weight. Synchronous and unfailing
   // — it just clears an interval — so it needs no budget of its own.
-  deps.backgroundJobs?.stopSweeping();
+  deps.pluginJoinRequestJobs?.stopSweeping();
   // And the upload store's sweep, for the same reason and in the same breath:
   // synchronous, and it only clears an interval and tells a sweep already
   // running to stop deleting.
@@ -548,11 +559,18 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // Clearing the interval stops future ticks; it does nothing to a job a
   // tick already started, which holds a claim it heartbeats through the
   // pool and is mid-clone or mid-push. Awaited here, in the budget: a job
-  // that finishes releases or marks its row; one that cannot in time is
-  // killed with the process and its claim goes stale for the next sweep
-  // — which is the recovery every crash already gets.
-  if (deps.backgroundJobs) {
-    await bounded(deps.backgroundJobs.drain(), remaining(), 'finishing the background jobs', log);
+  // that finishes releases or marks its row. One that cannot in time is
+  // NOT cancelled — the bounded wait only stops waiting — and what becomes
+  // of it depends on who is stopping: a process shutting down takes it
+  // along; a tenant host evicting one graph ends the pool under it, which
+  // cancels nothing already running — a clone or push in flight finishes
+  // on its own — but its next heartbeat or database write fails, so from
+  // there the job records nothing and stops. Either way its claim goes
+  // stale and the next sweep — the next boot's, or a live graph's — picks
+  // the row up and does the whole thing again, which is the recovery every
+  // crash already gets (and why each step is written to be redone).
+  if (deps.pluginJoinRequestJobs) {
+    await bounded(deps.pluginJoinRequestJobs.drain(), remaining(), 'finishing the join-request jobs', log);
   }
   // The sweep in flight when the interval was cleared: awaited so the next
   // graph for this tenant cannot start staging bytes while a store it has
@@ -569,6 +587,10 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.workflowService) {
     await bounded(deps.workflowService.drainTidy(), remaining(), 'finishing the branch tidy-up', log);
   }
+  // Its workers end with the graph; a search still running is answered busy.
+  if (deps.patternMatcher) {
+    await bounded(deps.patternMatcher.close(), remaining(), 'ending the search workers', log);
+  }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
   await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);