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

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

@@ -3,6 +3,7 @@ import cors from 'cors';
 import path from 'node:path';
 import type { Router, RequestHandler } from 'express';
 import { createAuthRoutes } from '../modules/auth/auth.routes.js';
+import { authCookieSecure } from '../modules/auth/auth.middleware.js';
 import { createWorkspaceRoutes } from '../modules/workspace/workspace.routes.js';
 import {
   createAgentUploadRoutes,
@@ -13,13 +14,18 @@ import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
 import { createWorkflowRoutes } from '../modules/workflow/workflow.routes.js';
-import { createEventsRoutes } from '../modules/workflow/events.routes.js';
+import { createEventAccess, createEventsRoutes, EventDelivery } from '../modules/workflow/index.js';
 import { createAccessRoutes } from '../modules/access/access.routes.js';
 import { createAccessRequestRoutes } from '../modules/access/access-requests.routes.js';
+import { AccessRequestsService } from '../modules/access/access-requests.service.js';
 import { createMcpRoutes } from '../modules/mcp/mcp.routes.js';
 import { createOAuthConsentRoutes } from '../modules/mcp/oauth/oauth-consent.routes.js';
 import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
 import { createManualRoutes } from '../modules/tool-registry/manual.routes.js';
+import {
+  createToolHintsAgentRoutes,
+  createToolHintsRoutes,
+} from '../modules/tool-registry/read-only-hints.js';
 import { createCatalogRevisionRoutes } from './catalog-revision.js';
 import {
   createToolManualsAgentRoutes,
@@ -359,6 +365,9 @@ export async function createCoreServer(
       core.authMiddleware,
       core.authProviders,
       core.config.loginPasswordEnabled,
+      // The cookie's Secure flag follows the scheme the deployment is reached
+      // on, as the SSO providers' does: one rule for every sign-in path.
+      { cookieSecure: authCookieSecure(core.config.publicBackendUrl) },
     ),
   );
 
@@ -378,6 +387,7 @@ export async function createCoreServer(
     core.internalTokenService,
     core.mcpOAuthProvider,
     core.mcpResourceMetadataUrl,
+    core.agentScopeService,
   ));
 
   // Remote sync — `POST /api/sync`, called by a git host's webhook or a
@@ -418,6 +428,7 @@ export async function createCoreServer(
     toolManualService: core.toolManualService,
     accessControl: core.accessControl,
     connectionProbe: core.connectionProbeService,
+    agents: core.agentScopeService,
     stateSecret: core.config.jwtSecret,
     publicBackendUrl: core.config.publicBackendUrl,
     publicFrontendUrl: core.config.publicFrontendUrl,
@@ -539,11 +550,17 @@ export async function createCoreServer(
     agentAccessGate,
     core,
   });
+  // What MCP clients are told about each platform tool's effect: read by the
+  // agent manual (the hosted endpoint) and by `/agent/tool-hints` (hexis-mcp).
+  const { readOnlyHints } = core;
   toolsRouter.use(createManualRoutes(
     core.toolRegistry,
     core.manualAuthMiddleware,
     async (userId) => (await core.authService.getUserById(userId))?.email,
+    readOnlyHints,
+    core.agentScopeService,
   ));
+  toolsRouter.use(createToolHintsAgentRoutes(readOnlyHints, core.manualAuthMiddleware));
   // The aggregated manual list (KB + the caller's accessible `.tool`s) + inline
   // `.tool` sub-manuals. Mounted on the tools router so they share `manualAuth`
   // and sit before the JWT `/api` mounts.
@@ -558,6 +575,7 @@ export async function createCoreServer(
       disk: core.disk,
       pluginIndex: core.pluginIndexService,
     },
+    core.agentScopeService,
   ));
   // What every connected agent is told at session start, as the hosted proxy
   // composes it: read by the local `hexis-mcp` bridge at startup and by the
@@ -572,6 +590,7 @@ export async function createCoreServer(
     skills: core.skillService,
     manualAuth: core.manualAuthMiddleware,
     resolveUserEmail: async (userId) => (await core.authService.getUserById(userId))?.email,
+    agentScope: core.agentScopeService,
     // 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,
@@ -586,6 +605,7 @@ export async function createCoreServer(
     core.secretsVaultService,
     core.manualAuthMiddleware,
     async (userId) => (await core.authService.getUserById(userId))?.email,
+    core.agentScopeService,
   ));
   app.use('/api', toolsRouter);
 
@@ -628,6 +648,7 @@ export async function createCoreServer(
     createPluginCreationRoutes(
       core.pluginProvisionService,
       async (req) => (req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null),
+      core.agentScopeService,
     ),
   );
 
@@ -666,7 +687,19 @@ export async function createCoreServer(
   // cookie — the cookie path is what makes EventSource work, since the
   // browser API can't set headers). Mounted as its own app.use so it
   // doesn't share an outer middleware chain with the JSON routes above.
-  app.use('/api', createEventsRoutes(core.eventBus, core.authMiddleware));
+  // Every event passes the delivery rule on its way to a session: the file
+  // routes' read verdict, read in the server's own checkouts — for an
+  // approval, the target branch's; a target with no checkout at its ref.
+  const eventDelivery = new EventDelivery(createEventAccess({
+    accessControl: core.accessControl,
+    kbDirName: core.kbDirName,
+    getChangeRequest: (number) => core.workflowService.getChangeRequest(number),
+    workspaces: {
+      hasWorkspace: (workspaceId) => core.workspaceService.hasBootstrappedWorkspace(workspaceId),
+      anyWorkspaceId: async () => (await core.workspaceService.findAnyWorkspaceId()) ?? core.kb.defaultWorkspaceId(),
+    },
+  }));
+  app.use('/api', createEventsRoutes(core.eventBus, core.authMiddleware, eventDelivery));
   app.use('/api', core.authMiddleware, createDiffRoutes(
     core.diffService,
     core.authService,
@@ -683,6 +716,7 @@ export async function createCoreServer(
     core.eventBus,
     core.db,
     core.kb,
+    core.disk,
     [core.config.adminEmail],
   ));
   // Asking for Can edit or Owner on an item from its Manage access dialog, and
@@ -711,7 +745,12 @@ export async function createCoreServer(
       skillService: core.skillService,
       accessControl: core.accessControl,
       workflow: core.workflowService,
-      workspaceService: core.workspaceService,
+      requests: new AccessRequestsService({
+        workflow: core.workflowService,
+        workspaceService: core.workspaceService,
+        lifecycle: core.joinRequestsService,
+        kb: core.kb,
+      }),
       joinRequests: core.joinRequestsService,
       kb: core.kb,
       resolveUser: async (req) =>
@@ -747,6 +786,8 @@ export async function createCoreServer(
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
   app.use('/api', core.authMiddleware, createAdminAccessRoutes(core.adminAccess));
+  // The Tools page's read-only toggles: anyone signed in reads, admins write.
+  app.use('/api', core.authMiddleware, createToolHintsRoutes(readOnlyHints, core.adminAccess));
   // Groups admin (manual-mode CRUD; typed refusals in IdP mode) —
   // admin-gated inside.
   app.use('/api', core.authMiddleware, createGroupsAdminRoutes({
@@ -875,6 +916,7 @@ export async function createCoreServer(
       clientNameFor: (st) => core.githubFacade.clientNameFor(st),
       completeConsent: (userId, st) => core.githubFacade.completeConsent(userId, st),
     },
+    agents: core.agentScopeService,
   }));
 
   // What an Owner pastes into Claude's admin settings to register this

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

@@ -34,6 +34,8 @@ import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-f
 import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
 import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
 import { DeploymentSettingsService, retireMergedBranchesOn } from '../modules/settings/deployment-settings.service.js';
+import { ToolReadOnlyHints } from '../modules/tool-registry/read-only-hints.js';
+import type { IToolReadOnlyHints } from '../modules/tool-registry/read-only-hints.contract.js';
 import { KbSyncService } from '../modules/kb-sync/kb-sync.service.js';
 import { NodeFs } from '../modules/kb-fs/node-fs.js';
 import { assertKbDirNameFree } from '../modules/kb-fs/repo-path.js';
@@ -61,27 +63,38 @@ function parseDomainList(raw: string): string[] {
     .filter((d) => d.length > 0);
 }
 import { SpillStore } from '../modules/workspace/spill-store.js';
+import { TmpSweeper } from '../modules/workspace/workspace-tmp.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 {
+  assertRipgrep,
+  DocExtractService,
+  RipgrepPatternMatcher,
+  WorkerDocumentExtractor,
+  type IDocumentExtractor,
+  type IPatternMatcher,
+} from '../modules/workspace/index.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountHooks, type IAccountHooks } from '../modules/auth/account-hooks.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
-import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
+import { authCookieSecure, createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
 import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
+import { AccessMutationService } from '../modules/access/access-mutation.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
 import { ChangeReadGate } from '../modules/access/change-read-gate.js';
 import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
 import { UserAccessRemovalService } from '../modules/access/user-access-removal.service.js';
-import { makeRolesYamlWriteValidator } from '../modules/access-model/roles-yaml-guard.js';
-import { PendingSkillsService, SkillService } from '../modules/skills/index.js';
-import { PendingToolsService, ToolManualService } from '../modules/tool-manuals/index.js';
+import { makeRolesYamlWriteValidator } from '../modules/access-model/index.js';
+// The implementations, from their files: the module entries offer them as
+// types only, so nothing that imports an entry loads a service.
+import { SkillService } from '../modules/skills/skills.service.js';
+import { PendingSkillsService } from '../modules/skills/pending-skills.service.js';
+import { ToolManualService } from '../modules/tool-manuals/tool-manuals.service.js';
+import { PendingToolsService } from '../modules/tool-manuals/pending-tools.service.js';
 import { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
 import { ToolDeleteService } from '../modules/tool-manuals/tool-delete.service.js';
 import {
@@ -98,6 +111,7 @@ import {
   MarketplaceCompilerService,
   KbPluginSource,
 } from '../modules/plugins/index.js';
+import { noAgentConfigurations, type IAgentScopeResolver } from '../modules/agent-scope/index.js';
 import { MarketplaceRepoService } from '../modules/marketplace/index.js';
 import {
   GitHubFacadeCredentialsService,
@@ -122,7 +136,7 @@ import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
-import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import { WorkflowEventBus } from '../modules/workflow/index.js';
 import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { StarterPackService } from '../modules/onboarding/starter-pack.service.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
@@ -248,7 +262,9 @@ 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. */
+  /** Sweeps every workspace's `tmp/` folder of entries older than seven days, hourly; started and stopped with the graph. */
+  tmpSweeper: TmpSweeper;
+  /** Runs a caller's `grep` pattern in ripgrep under a budget; its running searches end when the graph stops. */
   patternMatcher: IPatternMatcher;
   /**
    * Every user a download fetch identifies itself as, by its bearer and its
@@ -256,6 +272,8 @@ export interface CoreServices {
    * download route can refuse a link presented by someone it was not issued to.
    */
   agentDownloadFetcher: (req: Request) => Promise<string[]>;
+  /** Runs every document extraction off the request thread under a budget; its workers end when the graph stops. */
+  documentExtractor: IDocumentExtractor;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -300,6 +318,12 @@ export interface CoreServices {
   pluginJoinRequestJobs: PluginJoinRequestJobs;
   /** Which plugins hold which skills (inline or linked) — see `PluginLinkIndex`. */
   pluginLinkIndex: PluginLinkIndex;
+  /**
+   * Connecting as an agent configuration: the choices offered at consent and key
+   * mint, and the scope every agent surface narrows a connection to — see
+   * `modules/agent-scope`.
+   */
+  agentScopeService: IAgentScopeResolver;
   /** Link / unlink / repair shared skills into plugins. */
   pluginLinksService: PluginLinksService;
   pluginRenameService: PluginRenameService;
@@ -399,6 +423,8 @@ export interface CoreServices {
   /** The Audit log: what every connected agent and key called, and the revoke of an agent's grant. */
   agentAuditService: AgentAuditService;
   toolRegistry: ToolRegistry;
+  /** Each platform tool's and meta-tool's read-only hint, and an admin's overrides of them. */
+  readOnlyHints: IToolReadOnlyHints;
   toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
   manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
   toolHandlerFactory: ReturnType<typeof createToolHandlerFactory>;
@@ -421,6 +447,9 @@ export async function createCoreServices(
   // (see `git-version.ts`): every clone, fetch and refresh below depends on it,
   // so an unsupported binary is better surfaced here than at the first merge.
   await assertGitVersion();
+  // The same for ripgrep, which the grep tool searches with and has no
+  // fallback for (see `ripgrep-version.ts`).
+  await assertRipgrep();
   // What tells this knowledge base's locks, migration ledger and secrets
   // loader apart from another's in the same process and database. Empty for
   // the default schema, so a single-tenant deployment keeps the lock ids and
@@ -756,6 +785,10 @@ export async function createCoreServices(
   // Shared, workspace-independent store for oversized `call_tool_chain` results,
   // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
   const spillStore = new SpillStore(config.spillRoot);
+  // What the chat, the SharePoint reader and tool chains stage in a
+  // workspace's `tmp/` folder lives seven days past its last change; the file
+  // tools read it through the `__tmp__/` ref meanwhile (see workspace-tmp.ts).
+  const tmpSweeper = new TmpSweeper((signal) => workspaceService.sweepTmp(undefined, undefined, signal));
   // The upload route an agent lands files by, so their content never passes
   // through the model. Bytes live BESIDE the workspaces root (never inside
   // one) until the apply commits them or the token expires — checked here
@@ -784,16 +817,16 @@ 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 patternMatcher = new RipgrepPatternMatcher();
   const agentDownloadStore = new AgentDownloadStore({
     root: agentDownloadsRoot,
     publicBaseUrl: config.publicBackendUrl,
     // `<tenant>-down_`: recognisable by shape beside the upload token.
     tokenPrefix: config.uploadTokenPrefix.replace(/up_$/, 'down_'),
   });
-  // Office-document/PDF text extraction for `read_file`/`grep`, cached by
-  // content hash beside the workspaces root (see `DocExtractionCache`).
-  const docExtractService = new DocExtractService(config.docExtractCacheRoot);
+  // The worker threads every office/PDF/email extraction runs in, under a
+  // 10 s budget per file (see `WorkerDocumentExtractor`).
+  const documentExtractor = new WorkerDocumentExtractor();
   // The deployment owner counts as Admin for the two hardcoded `write`
   // rescues (`roles.yaml` and any `access.md`) — the SAME list
   // `AdminAccessService` below is given, so the admin surfaces and the write
@@ -840,6 +873,17 @@ export async function createCoreServices(
   // The link index resolves manifests against the released catalog, and the
   // plugin index counts through it (inline + linked), so it comes first.
   const pluginLinkIndex = new PluginLinkIndex(workspaceService, skillService, accessControl, kb, pluginSource);
+  // What "Connect as" offers and what a connection made as an agent loads:
+  // the distribution's resolver (`CorePorts.agentScope`), made HERE with the
+  // core services it reads through — its configurations behind the person's
+  // read gate, `plugins:` expanded through the link index above — or core's
+  // default, which offers no agent and loads nothing for a path it cannot
+  // read. Made once, before anything consults it: the tool-context resolver
+  // below captures it, as the routes the server mounts do, so there is one
+  // resolver in effect and no later assignment to miss. Core owns the
+  // mechanism and no configuration (see `modules/agent-scope`).
+  const agentScopeService: IAgentScopeResolver =
+    ports.agentScope?.({ workspaceService, accessControl, kb, disk, pluginLinkIndex }) ?? noAgentConfigurations();
   const pluginIndexService = new PluginIndexService(
     workspaceService,
     accessControl,
@@ -952,6 +996,14 @@ export async function createCoreServices(
   // browser sessions. Single instance per Node process — survives across
   // requests, doesn't survive restarts (clients reconnect + resync).
   const eventBus = new WorkflowEventBus();
+  // Office-document/PDF/email text extraction for `read_file`/`grep`, cached
+  // by content hash beside the workspaces root (see `DocExtractionCache`),
+  // failures included. A fresh failure is told to the people looking at the
+  // file: the events route delivers it only to sessions that may read it.
+  const docExtractService = new DocExtractService(config.docExtractCacheRoot, documentExtractor, {
+    onUnreadable: ({ workspaceId, path, reason }) =>
+      eventBus.emit({ kind: 'document-unreadable', workspaceId, path, reason }),
+  });
   // In-process post-commit hook (distinct from the SSE bus): fires once per
   // committed change (batched paths) so catalogs refresh instantly and the
   // id-repair keeps the id namespace collision-free. Subscribers are registered
@@ -1038,6 +1090,7 @@ export async function createCoreServices(
     workspaceService,
     workflowService,
     accessControl,
+    new AccessMutationService(workspaceService, accessControl, kb.kbDirName),
     skillService,
     pluginLinkIndex,
     kb,
@@ -1386,6 +1439,8 @@ export async function createCoreServices(
       // the setup save applies lands without a restart.
       kbLayout: () => kb.layout,
       secretsScope,
+      // Read at listing time, by when the hints below exist.
+      readOnlyOverrides: () => readOnlyHints.overrides(),
     },
     // Pre-dispatch per-user credential check: the vault answers "has this caller
     // set it?" and the manual catalog answers "which user-scoped vars does this
@@ -1454,6 +1509,9 @@ export async function createCoreServices(
   // `internalTokenService` minted above (shared with the agent factories) is
   // the same one the tool-auth middleware verifies internal tokens against.
   const toolRegistry = new ToolRegistry();
+  // What MCP clients are told about each platform tool's effect: its write
+  // declaration, or an admin's override from the Tools page.
+  const readOnlyHints = new ToolReadOnlyHints(toolRegistry, settings);
   const resolveToolContext = createToolContextResolver({
     authService,
     workspaceService,
@@ -1462,6 +1520,7 @@ export async function createCoreServices(
     kbDirName: kbDirName,
     creatorAccess,
     loadActiveGroups,
+    agentScope: agentScopeService,
   });
   const writeAccess = ports.writeAccess ?? alwaysWritable;
   // The branch every tool call runs on is resolved by the handler, before the
@@ -1471,8 +1530,8 @@ export async function createCoreServices(
     defaultBranch: () => kb.defaultBranch,
     isMissing: (branch) => workspaceService.isBranchMissing(branch),
   });
-  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService);
-  const verifyToolToken = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
+  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService, mcpOAuthProvider);
+  const verifyToolToken = createTokenVerifier(externalApiKeyService, internalTokenService, authService, mcpOAuthProvider);
   // Every credential kind this server issues — connection keys, internal
   // tokens and app sessions (bearer or cookie) — so a fetch carrying another
   // user's identity of ANY kind is refused the link.
@@ -1483,7 +1542,7 @@ export async function createCoreServices(
   // Read-only manual endpoints accept the above PLUS a browser JWT, so a
   // logged-in user can browse the catalog with their session. Execution routes
   // keep `toolAuthMiddleware` (no JWT), so a session can read but not invoke.
-  const manualAuthMiddleware = createManualAuthMiddleware(externalApiKeyService, internalTokenService, authService);
+  const manualAuthMiddleware = createManualAuthMiddleware(externalApiKeyService, internalTokenService, authService, mcpOAuthProvider);
 
   // Recovery-bot identity: a synthetic `recovery-bot@bevel.local` user
   // backing (a) the recovery agent's commit authorship and (b) the
@@ -1550,7 +1609,7 @@ export async function createCoreServices(
       settings: () => oidcSettingsFrom(settings),
       publicBackendUrl: config.publicBackendUrl,
       publicFrontendUrl: config.publicFrontendUrl,
-      cookieSecure: config.publicBackendUrl.startsWith('https'),
+      cookieSecure: authCookieSecure(config.publicBackendUrl),
       // A real sign-in proves the values that sign-in used. Recorded against
       // those — under their own key — so it says nothing about any saved
       // since, and cannot overwrite what was recorded about them.
@@ -1594,6 +1653,7 @@ export async function createCoreServices(
     workspaceService,
     workflowService,
     accessControl,
+    disk,
     kbDirName,
     () => kb.defaultBranch,
     eventBus,
@@ -1648,8 +1708,10 @@ export async function createCoreServices(
     spillStore,
     agentUploadStore,
     agentDownloadStore,
+    tmpSweeper,
     patternMatcher,
     agentDownloadFetcher,
+    documentExtractor,
     docExtractService,
     accessControl,
     creatorAccess,
@@ -1668,6 +1730,7 @@ export async function createCoreServices(
     joinRequestsService,
     pluginJoinRequestJobs,
     pluginLinkIndex,
+    agentScopeService,
     pluginLinksService,
     pluginRenameService,
     marketplaceCompiler,
@@ -1708,6 +1771,7 @@ export async function createCoreServices(
     mcpResourceMetadataUrl,
     agentAuditService,
     toolRegistry,
+    readOnlyHints,
     toolAuthMiddleware,
     manualAuthMiddleware,
     toolHandlerFactory,

package/src/core/lifecycle.ts

@@ -6,6 +6,7 @@ import { noteBesideCheckout } from '../modules/workspace/startup/beside-checkout
 import { unregisterBevelSecretsVariableLoader } from '../modules/secrets-vault/secrets-variable-loader.js';
 import type { WorkflowService } from '../modules/workflow/workflow.service.js';
 import type { PluginJoinRequestJobs } from '../modules/plugins/join-request-jobs.service.js';
+import type { TmpSweeper } from '../modules/workspace/workspace-tmp.js';
 import { printable } from '../shared/printable.js';
 import { logger } from '../shared/logging.js';
 
@@ -293,6 +294,8 @@ export interface BootableCore {
   kbStartupRunner: Pick<KbStartupRunner, 'runAll' | 'retryUntilMaintained'>;
   workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches' | 'tidyAfterSweep'>;
   pluginJoinRequestJobs: Pick<PluginJoinRequestJobs, 'startSweeping'>;
+  /** The periodic sweep of every workspace's `tmp/` folder, started here and stopped by {@link stopCore}. */
+  tmpSweeper: Pick<TmpSweeper, 'startSweeping'>;
   /**
    * The startup phase's retry, when the boot survived an unreachable remote
    * and is asking again on a timer; null otherwise. Set by {@link startCore},
@@ -336,6 +339,13 @@ export async function startCore<C extends BootableCore>(
     });
   }
 
+  // The seven-day sweep of every workspace's `tmp/` folder (see
+  // `workspace-tmp.ts`), now and hourly. Needs nothing the startup phase
+  // provides — it reads the workspaces root and nothing else — so it is not
+  // held behind it, and a remote that is down does not leave staged files to
+  // pile up. Stopped by `stopCore`.
+  core.tmpSweeper.startSweeping();
+
   // The KB startup phase — AFTER the distribution's onBoot, because a FATAL
   // template finding raised there must stop the boot before anything seeds
   // from that template; the runner then brings every branch up to this build
@@ -448,12 +458,28 @@ 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 sweep of the workspaces' `tmp/` folders: stopped with this graph, so
+   * an evicted tenant's graph leaves no timer behind, and its sweep in flight
+   * cancelled (it removes nothing more) and then awaited within the stop's
+   * deadline, so the next graph over the same root does not meet it still
+   * walking there — unless one filesystem call outlasts that deadline, after
+   * which the cancelled sweep still removes nothing. Optional: a caller that
+   * has not built one passes nothing.
+   */
+  tmpSweeper?: { 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 document extractor, whose worker threads are this graph's own for the
+   * same reason: ended here, so no extraction worker outlives its graph.
+   * Optional like the matcher.
+   */
+  documentExtractor?: { close(): Promise<void> };
   /**
    * The workflow service, for the tidy-up it runs after each sweep (closing
    * empty requests, removing leftover branches): detached from whatever
@@ -549,6 +575,7 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // running to stop deleting.
   deps.agentUploadStore?.stopSweeping();
   deps.agentDownloadStore?.stopSweeping();
+  deps.tmpSweeper?.stopSweeping();
   // A startup phase still asking for an unreachable remote stops asking:
   // synchronous, and nothing after it must be able to clone into a
   // workspaces folder that is about to belong to nobody.
@@ -581,15 +608,22 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.agentDownloadStore) {
     await bounded(deps.agentDownloadStore.drainSweep(), remaining(), 'finishing the download sweep', log);
   }
+  if (deps.tmpSweeper) {
+    await bounded(deps.tmpSweeper.drainSweep(), remaining(), "finishing the workspaces' tmp sweep", log);
+  }
   // The tidy-up in flight fetches and deletes branches through the pool and
   // the default branch's checkout: awaited, so the next graph for this
   // tenant cannot find a branch deletion still running under it.
   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.
+  // Its ripgrep runs end with the graph; a search still running is answered busy or stopped.
   if (deps.patternMatcher) {
-    await bounded(deps.patternMatcher.close(), remaining(), 'ending the search workers', log);
+    await bounded(deps.patternMatcher.close(), remaining(), 'ending the running searches', log);
+  }
+  // Likewise: an extraction still running is answered busy, and nothing about its file is remembered.
+  if (deps.documentExtractor) {
+    await bounded(deps.documentExtractor.close(), remaining(), 'ending the extraction workers', log);
   }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);

package/src/core/public-config.ts

@@ -85,5 +85,15 @@ export function publicConfig(kb: KbContext, { marketplaceGitUrl, mcpUrl }: Publi
      * there.
      */
     catalogRevision: true as const,
+    /**
+     * This deployment serves `GET /api/agent/tool-hints`, the read-only hint
+     * of every platform tool and code-mode meta-tool (see
+     * modules/tool-registry/read-only-hints.ts). The local `hexis-mcp` bridge
+     * reads it on every `tools/list` only when this is advertised — on the
+     * same terms as the two flags above: an older deployment answers the
+     * unknown route with 401, and an OAuth bridge reads a 401 as an expired
+     * token and refreshes its sign-in on every listing.
+     */
+    toolHints: true as const,
   };
 }

package/src/index.ts

@@ -26,7 +26,7 @@ export {
   type ServerExtensions,
   type ToolSurfaceCtx,
 } from './core/create-core-server.js';
-export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
+export { noopRecoveryAgent, type AgentScopeCollaborators, type CorePorts } from './core/core-ports.js';
 // Logging: the contract, the slot a shell installs its sink into, and the
 // tagged-logger lookup every module logs through. See shared/logging.ts.
 export { setLogger, logger, createConsoleLogger } from './shared/logging.js';

package/src/modules/access/__tests__/access-control.admin-root-floor.test.ts

@@ -242,6 +242,17 @@ describe('Admin write floor at the repository root', () => {
       expect(await fs.readFile(path.join(repo, 'access.md'), 'utf-8')).toContain('write:\n  - Admin');
     });
 
+    it('lets the root drop a GROUP named Admin — group/Admin is never the role', async () => {
+      await write(repo, 'access.md', '---\n---\nwrite:\n  - Admin\n  - group/Admin\n');
+      const group = { kind: 'role' as const, role: 'group/Admin' };
+      await expect(mutation.revoke(WS, 'folder', '', group, ADMIN, 'write')).resolves.toMatchObject({
+        changed: true,
+      });
+      const after = await fs.readFile(path.join(repo, 'access.md'), 'utf-8');
+      expect(after).not.toContain('group/Admin');
+      expect(after).toContain('write:\n  - Admin'); // the role's line is untouched
+    });
+
     it('refuses deny-here on a PERSON who is an admin at the root, with the reason, and writes nothing', async () => {
       const before = await fs.readFile(path.join(repo, 'access.md'), 'utf-8');
       for (const email of [ADMIN, OWNER]) {
@@ -310,6 +321,7 @@ describe('Admin write floor at the repository root', () => {
           { emit: () => {} } as unknown as WorkflowEventBus,
           usersDbDouble(),
           testKbContext({ kbDirName: KB }),
+          new NodeFs(),
         ),
       );
       server = await new Promise<Server>((resolve) => {