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

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

@@ -17,6 +17,10 @@ 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 { AccountLinkService } from '../modules/embed/account-link.service.js';
+import { EmbedService } from '../modules/embed/embed.service.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';
 import { KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
 import { GroupsToPluginsStep } from '../modules/workspace/startup/steps/groups-to-plugins.step.js';
@@ -26,7 +30,7 @@ import { PersonalSpacesStep } from '../modules/workspace/startup/steps/personal-
 import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-files.step.js';
 import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
 import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
-import { DeploymentSettingsService } from '../modules/settings/deployment-settings.service.js';
+import { DeploymentSettingsService, retireMergedBranchesOn } from '../modules/settings/deployment-settings.service.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';
@@ -55,17 +59,21 @@ function parseDomainList(raw: string): string[] {
 }
 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 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';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
-import { createAuthMiddleware } from '../modules/auth/auth.middleware.js';
+import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
 import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.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 { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
@@ -110,6 +118,7 @@ import { ReviewWorkflowService } from '../modules/workflow/review-workflow/revie
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
 import { WorkflowEventBus } from '../modules/workflow/event-bus.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';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
 import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
@@ -132,6 +141,7 @@ import {
 } from '../modules/tool-auth/internal-token.service.js';
 import {
   createToolAuthMiddleware,
+  createTokenVerifier,
   createManualAuthMiddleware,
 } from '../modules/tool-auth/tool-auth.middleware.js';
 import { unmeteredLlmUsage, type ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
@@ -229,6 +239,14 @@ export interface CoreServices {
   spillStore: SpillStore;
   /** The bytes an agent uploaded, held until `apply_file_upload` lands them or their token expires. */
   agentUploadStore: AgentUploadStore;
+  /** The bytes `request_file_download` captured, held until their one-time link is fetched or expires. */
+  agentDownloadStore: IAgentDownloadStore;
+  /**
+   * Every user a download fetch identifies itself as, by its bearer and its
+   * session cookie — none when it carries none that verifies — so the
+   * download route can refuse a link presented by someone it was not issued to.
+   */
+  agentDownloadFetcher: (req: Request) => Promise<string[]>;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -258,6 +276,11 @@ export interface CoreServices {
   toolDeleteService: ToolDeleteService;
   pluginIndexService: PluginIndexService;
   pluginProvisionService: PluginProvisionService;
+  /**
+   * "What does your team do?" — the starter pack a new knowledge base's admin
+   * may fill it from, and the record of what was chosen. See modules/onboarding.
+   */
+  starterPackService: StarterPackService;
   joinRequestsService: JoinRequestsService;
   /**
    * Records a join request and finishes it in the background. Its `sweep()`
@@ -335,6 +358,14 @@ export interface CoreServices {
   connectionProbeService: ConnectionProbeService;
   externalApiKeyService: ExternalApiKeyService;
   internalTokenService: InternalTokenService;
+  /**
+   * The embed surface: the token-minted page a chat host frames, and the
+   * account links that let an outside identity reach it. Exposed so an
+   * overlay can mint for its own consumers and register a node-id resolver.
+   */
+  embedService: EmbedService;
+  /** The MCP Apps this deployment serves — the `open_page` view and its sandbox metadata. */
+  mcpAppService: IMcpAppService;
   mcpService: McpService;
   mcpAuthMiddleware: ReturnType<typeof createMcpAuthMiddleware>;
   mcpOAuthProvider: BevelOAuthProvider;
@@ -685,6 +716,29 @@ export async function createCoreServices(
     publicBaseUrl: config.publicBackendUrl,
     tokenPrefix: config.uploadTokenPrefix,
   });
+  // The way OUT: bytes `request_file_download` captured, held beside the
+  // upload root — outside every workspace, for the same reason — until their
+  // one-time link is fetched or expires.
+  const agentDownloadsRoot = path.resolve(config.agentUploadsRoot, '..', 'agent-downloads');
+  // An upload root that is itself named `agent-downloads` would make the two
+  // stores one directory, each sweeping the other's files.
+  if (agentDownloadsRoot === path.resolve(config.agentUploadsRoot)) {
+    throw new Error(
+      'AGENT_UPLOADS_ROOT must not be a directory named `agent-downloads`: that name, beside it, is the agent download root.',
+    );
+  }
+  await assertUploadsRootOutsideWorkspaces(agentDownloadsRoot, config.workspacesRoot, {
+    name: 'The agent download root (`agent-downloads`, beside AGENT_UPLOADS_ROOT)',
+    why:
+      '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 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);
@@ -869,6 +923,9 @@ export async function createCoreServices(
     // it reach every hook point.
     workflowHooks,
   );
+  // The leftover-branch cleanup asks the Deployment page at every round, so
+  // switching it off there applies without a restart.
+  workflowService.leftoverCleanupEnabled = () => retireMergedBranchesOn(settings.resolve('retireMergedBranches'));
 
   // Join requests: derived entirely from two copies of a plugin's `access.md`
   // (the request's branch vs the default branch), so it holds no state — it
@@ -1053,6 +1110,27 @@ export async function createCoreServices(
     [config.adminEmail],
   );
 
+  // The starter-pack question: one commit on the default branch through the
+  // same batch write the roles admin uses, the choice kept as a deployment
+  // setting. Read by its routes and by `start_session`'s first-run note.
+  const starterPackService = new StarterPackService({
+    packsDir: config.starterPacksDir,
+    kb,
+    workspaceService,
+    workflow: workflowService,
+    adminAccess,
+    settings,
+    accessControl,
+    disk,
+    pluginSource,
+    pluginLocks: pluginProvisionService,
+    events: eventBus,
+    fileChanges: fileChangeNotifier,
+    // Its own lock: one starter-pack choice at a time, a concern no other
+    // service's mutex serialises.
+    choosing: new WorkspaceMutex(),
+  });
+
   // In-app update check: lazily compares the running release version against
   // the newest published GitHub release, only when an admin's browser asks —
   // no timers, so a deployment nobody looks at makes zero calls. The flag
@@ -1152,9 +1230,13 @@ export async function createCoreServices(
   // Connection keys also come as GitHub-shaped links (`gho_…`, kind
   // `github-link`): the same key, minted by the marketplace facade below when
   // a person connects an account on claude.ai, told apart by its stored kind.
-  const externalApiKeyService = new ExternalApiKeyService(db, config.externalApiKeyPrefix, {
-    [GITHUB_LINK_KEY_KIND]: GITHUB_LINK_KEY_SPEC,
-  });
+  const externalApiKeyService = new ExternalApiKeyService(
+    db,
+    config.externalApiKeyPrefix,
+    { [GITHUB_LINK_KEY_KIND]: GITHUB_LINK_KEY_SPEC },
+    // A key's first use tells its owner's open tabs that the agent arrived.
+    eventBus,
+  );
 
   // The facade that lets products which sync marketplaces only from a GitHub
   // Enterprise Server (claude.ai, Cowork) add the per-user marketplace:
@@ -1192,6 +1274,34 @@ export async function createCoreServices(
   const agentAuditService = new AgentAuditService(db, externalApiKeyService, () =>
     retentionDaysFrom(settings.resolve('auditRetentionDays')),
   );
+  // The embed surface. It reads files through the workspace service and
+  // 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),
+  );
+  // The `ui://` view `open_page` carries, with the one origin it may frame:
+  // this deployment own public origin.
+  const mcpAppService = new McpAppService({ publicFrontendUrl: config.publicFrontendUrl });
   const mcpService = new McpService(
     {
       // Loopback to our own REST tool surface — 127.0.0.1 (not localhost) to pin
@@ -1225,6 +1335,9 @@ export async function createCoreServices(
     (bearer) => mcpOAuthProvider.revokeByAccessToken(bearer),
     // Every attributable call lands in the Audit log through this.
     agentAuditService,
+    // The views the endpoint serves over resources/read, and the tools that
+    // carry them.
+    mcpAppService,
   );
   // A changed secret invalidates what the proxy built from the old value for
   // that user (null = shared secret → everyone): remembered manual failures,
@@ -1247,6 +1360,8 @@ export async function createCoreServices(
     stateSecret: config.jwtSecret,
     publicFrontendUrl: config.publicFrontendUrl,
     tokenPrefix: config.mcpOAuthTokenPrefix,
+    // An agent connection's first use tells its owner's open tabs the agent arrived.
+    events: eventBus,
   });
   // RFC 9728 pointer carried on every MCP 401 challenge so OAuth-capable
   // clients discover the AS. Single source of truth for the resource id.
@@ -1283,8 +1398,22 @@ export async function createCoreServices(
     loadActiveGroups,
   });
   const writeAccess = ports.writeAccess ?? alwaysWritable;
-  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext, writeAccess);
+  // The branch every tool call runs on is resolved by the handler, before the
+  // tool: the default read live (a rename in the settings is the next call's
+  // default), the existence asked without cloning anything.
+  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext, writeAccess, {
+    defaultBranch: () => kb.defaultBranch,
+    isMissing: (branch) => workspaceService.isBranchMissing(branch),
+  });
   const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService);
+  const verifyToolToken = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
+  // 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.
+  const agentDownloadFetcher: (req: Request) => Promise<string[]> = createDownloadFetcherIdentifier(
+    { verifyToolToken, verifySession: (token) => authService.verifyToken(token) },
+    readAuthCookie,
+  );
   // 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.
@@ -1452,6 +1581,8 @@ export async function createCoreServices(
     kbDirName,
     spillStore,
     agentUploadStore,
+    agentDownloadStore,
+    agentDownloadFetcher,
     docExtractService,
     accessControl,
     creatorAccess,
@@ -1466,6 +1597,7 @@ export async function createCoreServices(
     agentGuideSections: agentGuideSectionsReader,
     pluginIndexService,
     pluginProvisionService,
+    starterPackService,
     joinRequestsService,
     pluginJoinRequestJobs,
     pluginLinkIndex,
@@ -1499,6 +1631,8 @@ export async function createCoreServices(
     connectionProbeService,
     externalApiKeyService,
     internalTokenService,
+    embedService,
+    mcpAppService,
     mcpService,
     mcpAuthMiddleware,
     mcpOAuthProvider,

package/src/core/lifecycle.ts

@@ -291,7 +291,7 @@ export interface BootableCore {
   config: { workspacesRoot: string };
   kbDirName: string;
   kbStartupRunner: Pick<KbStartupRunner, 'runAll' | 'retryUntilMaintained'>;
-  workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches'>;
+  workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches' | 'tidyAfterSweep'>;
   pluginJoinRequestJobs: Pick<PluginJoinRequestJobs, 'startSweeping'>;
   /**
    * The startup phase's retry, when the boot survived an unreachable remote
@@ -390,7 +390,11 @@ export async function startCore<C extends BootableCore>(
         crLog.info(`closed ${n} change request${n === 1 ? '' : 's'} with a deleted branch`);
       }
     })
-    .catch((err) => crLog.warn('deleted-branch sweep failed:', { err }));
+    .catch((err) => crLog.warn('deleted-branch sweep failed:', { err }))
+    // Then the tidy-up: open requests that propose nothing are closed, and the
+    // branches merged requests left behind removed (behind its own setting).
+    // Fails safe on a failed fetch, and never throws.
+    .then(() => core.workflowService.tidyAfterSweep());
 
   // Recorded join requests that are still owed, resumed — now, and then on a
   // timer. SEQUENCED AFTER the startup phase for the same reason as the sweep
@@ -437,6 +441,15 @@ export interface CoreStopDeps {
    * Optional: a caller that has not built one passes nothing.
    */
   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 workflow service, for the tidy-up it runs after each sweep (closing
+   * empty requests, removing leftover branches): detached from whatever
+   * started it, so stopped and awaited here before the pool goes. Optional:
+   * a caller that has not built one passes nothing.
+   */
+  workflowService?: { stopTidying(): void; drainTidy(): Promise<void> };
   /** The startup phase's retry, if the boot left one asking — see {@link BootableCore.startupRetry}. */
   startupRetry?: { stop(): void } | null;
   /** The database — its pool is ended last, once nothing above can still need it. */
@@ -524,10 +537,14 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // synchronous, and it only clears an interval and tells a sweep already
   // running to stop deleting.
   deps.agentUploadStore?.stopSweeping();
+  deps.agentDownloadStore?.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.
   deps.startupRetry?.stop();
+  // The post-sweep tidy-up: no new round, and the one under way stops at its
+  // next request or branch. Synchronous.
+  deps.workflowService?.stopTidying();
   // 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
@@ -543,6 +560,15 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.agentUploadStore) {
     await bounded(deps.agentUploadStore.drainSweep(), remaining(), 'finishing the upload sweep', log);
   }
+  if (deps.agentDownloadStore) {
+    await bounded(deps.agentDownloadStore.drainSweep(), remaining(), 'finishing the download 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);
+  }
   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);

package/src/core-config.ts

@@ -1,7 +1,7 @@
 import dotenv from 'dotenv';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { defaultKbTemplateDir } from './assets.js';
+import { defaultKbTemplateDir, defaultStarterPacksDir } from './assets.js';
 import { assertKeyDecodesTo32Bytes } from './shared/token-crypto.js';
 import { DEFAULT_GIT_TIMEOUT_MS } from './modules/workflow/git/node-git-runner.js';
 import { DEFAULT_DB_SCHEMA, assertSchemaName } from './modules/database/connection.js';
@@ -103,11 +103,13 @@ export interface TenantConfig {
   readonly gitUsername: string;
   readonly gitToken: string;
   readonly kbTemplateDir: string;
+  readonly starterPacksDir: string;
   readonly updateCheckEnabled: boolean;
   readonly loginPasswordEnabled: boolean;
   readonly allowedEmailDomains: string[];
   readonly secretsEncKey: string;
   readonly internalTokenSecret: string;
+  readonly embedSharedSecret: string;
   readonly trustProxy: string;
   readonly gitTimeoutMs: number;
   readonly publicBackendUrl: string;
@@ -276,6 +278,14 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * existing one. Override with `KB_TEMPLATE_DIR`.
    */
   readonly kbTemplateDir: string;
+  /**
+   * Filesystem path to the starter packs a new knowledge base's admin may
+   * pick from (the `starter-packs/` folder shipped inside this package — see
+   * `defaultStarterPacksDir()`): one folder per team, each a `pack.yaml` with
+   * the pages and the plugin it adds. A distribution offers its own with
+   * `STARTER_PACKS_DIR`; a folder holding no valid pack offers none.
+   */
+  readonly starterPacksDir: string;
   /**
    * In-app update check. When true (default), `GET /api/update-check` lazily
    * asks api.github.com for the newest Hexis release — only when an admin's
@@ -337,6 +347,17 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * independently of user sessions.
    */
   readonly internalTokenSecret: string;
+  /**
+   * The shared secret the Atlassian connector presents to \`POST
+   * /api/embed/token\` (\`EMBED_SHARED_SECRET\`). Unset on a deployment that
+   * has no connector pointed at it, which 404s that one route — the embed
+   * surface itself needs no secret, because the MCP App mints through the
+   * authenticated MCP session instead.
+   *
+   * There is deliberately NO framing setting beside it: any site may frame
+   * the embed page (see the embed module), so there is no allowlist to keep.
+   */
+  readonly embedSharedSecret: string;
   /**
    * Express `trust proxy` setting, from `TRUST_PROXY`: the number of reverse
    * proxy hops in front of this backend (e.g. `1`), or an address/CIDR list
@@ -477,6 +498,7 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     // Default: the `kb-template/` folder shipped inside this package (works
     // both from src/ and compiled dist/ — see assets.ts).
     this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
+    this.starterPacksDir = process.env.STARTER_PACKS_DIR || defaultStarterPacksDir();
     this.updateCheckEnabled =
       (process.env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false';
     this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
@@ -503,6 +525,7 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     // key never gets past this line.
     assertKeyDecodesTo32Bytes(this.secretsEncKey, secretsKeySource);
     this.internalTokenSecret = (process.env.INTERNAL_TOKEN_SECRET || '').trim();
+    this.embedSharedSecret = (process.env.EMBED_SHARED_SECRET || '').trim();
     // Setting DOMAIN declares "the bundled Caddy `https` profile fronts this
     // deployment" — one proxy hop, and the public origin IS that domain. The
     // three values below therefore default from it, so `DOMAIN=x.example.com`

package/src/index.ts

@@ -47,8 +47,8 @@ export {
   type LeasedWorker,
 } from './core/lifecycle.js';
 
-// Packaged assets (migrations/, kb-template/, agent-guide/) + the migration runners.
-export { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
+// Packaged assets (migrations/, kb-template/, agent-guide/, starter-packs/) + the migration runners.
+export { agentGuideDir, coreMigrationsDir, defaultKbTemplateDir, defaultStarterPacksDir } from './assets.js';
 export {
   runCoreMigrations,
   runEnterpriseMigrations,

package/src/modules/access/__tests__/access-control.service.test.ts

@@ -216,6 +216,25 @@ describe('AccessControlService', () => {
     expect(await svc.canWrite(workspaceId, 'ali@bevel.software', 'Knowledge/Secret/Foo.md')).toBe(false);
   });
 
+  // What deleting a nested access.md (delete_file, or the app's delete) does:
+  // the folder falls back to its parent's rules, nothing else to undo.
+  it('once a nested access.md is deleted, its folder follows the parent\'s rules', async () => {
+    const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
+    await writeFile(repo, 'roles.yaml', ROLES_YAML);
+    await writeFile(repo, 'access.md', '---\nread:\n  - everyone\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Team/access.md', '---\nread:\n  - deny Felix Kissel <felix@example.com>\n---\n');
+    await writeFile(repo, 'Team/plan.md', 'plan');
+
+    const svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR, new NodeFs());
+    expect(await svc.canRead(workspaceId, 'felix@example.com', 'Team/plan.md')).toBe(false);
+
+    await fs.rm(path.join(repo, 'Team/access.md'));
+    svc.invalidate(workspaceId);
+
+    expect(await svc.canRead(workspaceId, 'felix@example.com', 'Team/plan.md')).toBe(true);
+    expect(await svc.canWrite(workspaceId, 'felix@example.com', 'Team/plan.md')).toBe(false);
+  });
+
   it('closeness beats tier: a closer everyone grant overrides a farther email deny', async () => {
     const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
     await writeFile(repo, 'roles.yaml', ROLES_YAML);

package/src/modules/access/access-control.interface.ts

@@ -263,6 +263,19 @@ export interface IAccessControl {
     relativePath: string,
   ): Promise<boolean>;
 
+  /**
+   * Batched `canDownload` — one config load per call, the same resolution
+   * as the single form, each path's own frontmatter `download:` rules
+   * included. A folder download judges every file it would pack through
+   * this, so a folder of a thousand files costs one model load, not a
+   * thousand.
+   */
+  canDownloadBatch(
+    workspaceId: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean>>;
+
   /**
    * True iff `userEmail` is an `owner` of `relativePath` per the current
    * access tree, resolved from the `owner:` lists alone (the `write` /

package/src/modules/access/access-control.service.ts

@@ -1581,6 +1581,22 @@ export class AccessControlService implements IAccessControl {
     return hasPermissionResolved(model, 'download', userEmail, relativePath, own);
   }
 
+  async canDownloadBatch(
+    workspaceId: string,
+    userEmail: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean>> {
+    const model = await this.loadModel(workspaceId);
+    const repoDir = await this.repoDir(workspaceId);
+    // Parallel own-entries reads, memoized — same shape as `canWriteBatch`.
+    const owns = await Promise.all(relativePaths.map((p) => this.cachedOwnEntries(workspaceId, repoDir, p)));
+    const result = new Map<string, boolean>();
+    relativePaths.forEach((p, i) => {
+      result.set(p, hasPermissionResolved(model, 'download', userEmail, p, owns[i]));
+    });
+    return result;
+  }
+
   async canOwnerBatch(
     workspaceId: string,
     userEmail: string,

package/src/modules/access/directory-sync-bot.ts

@@ -35,7 +35,7 @@ export async function ensureDirectorySyncBot(db: Database): Promise<AuthUser> {
     .returning();
   if (inserted.length > 0) {
     const row = inserted[0];
-    log.info(`created sync-bot user id=${row.id} email=${row.email}`);
+    log.info(`created sync-bot user id=${row.id}`);
     return { id: row.id, email: row.email, name: row.name, avatarUrl: row.avatarUrl ?? undefined };
   }
   const [row] = await db

package/src/modules/agent-guide/__tests__/agent-guide.test.ts

@@ -299,6 +299,18 @@ describe('what the guide tells an agent', () => {
     expect(prose).toContain('add people to existing roles, and use a GROUP for a task- or team-scoped set of people');
   });
 
+  it('describes delete_branch where it says what an agent does with branches', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### An agent proposes and syncs; a person merges');
+    const prose = text.replace(/\s+/g, ' ');
+    expect(prose).toContain('`delete_branch`');
+    expect(prose).toContain('Only its author');
+    expect(prose).toContain('`dryRun: true`');
+    expect(prose).toContain('`discardUnmerged: true`');
+    expect(prose).toContain('that proposes nothing is closed by the delete');
+    expect(prose).toContain('its author can withdraw it, or an Admin can decline it, in the app');
+    expect(prose).toContain('`lastCommit`');
+  });
+
   it('documents giving a role to a group, with an example that parses as a valid roles.yaml', async () => {
     const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '### Giving a role to a group');
     const prose = text.replace(/\s+/g, ' ');
@@ -326,3 +338,49 @@ describe('what the guide tells an agent', () => {
     expect(parsed.index.byEmail.get('pat@example.com')?.has('role/admin')).toBe(false);
   });
 });
+
+/**
+ * The HTML views section: what an agent writing a live page is told about the
+ * frame. Its link rules are pinned against the renderer by core-frontend's
+ * `htmlViewsGuide.test.ts`, which reads the same file; what is pinned here is
+ * that it is served like every other section and that a distribution may
+ * reshape it.
+ */
+describe('the HTML views section', () => {
+  it('is served on its own, inside the whole guide, titled "HTML views"', async () => {
+    const sections = await agentGuideSections(DEFAULT_KB_LAYOUT);
+    const html = sections.find((s) => s.id === 'html-views')!;
+    expect(html.title).toBe('HTML views');
+    expect(html.body).not.toContain('{{');
+    expect(await composeAgentGuide(DEFAULT_KB_LAYOUT)).toContain(html.body);
+    // After the tool manuals, before the conventions.
+    const ids = sections.map((s) => s.id);
+    expect(ids.indexOf('html-views')).toBe(ids.indexOf('tool-manuals') + 1);
+  });
+
+  it('describes the frame, the two members core puts on window.bevel, and a fragment that scrolls the page', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    expect(text).toContain('**No network.**');
+    expect(text).toContain('**Inline scripts and styles only.**');
+    expect(text).toContain('**Scripts run as ES modules**');
+    expect(text).toContain('**No browser storage.**');
+    expect(text).toContain('**No host navigation.**');
+    expect(text).toContain('`window.bevel.openNode(href)`');
+    expect(text).toContain('`window.bevel.navigate(href)`');
+    expect(text).toContain('A distribution may add data members of its own to `window.bevel`');
+    expect(text).toContain('**A bare fragment scrolls the page.**');
+    // Rendered for the deployment's layout like every other section.
+    const docs = section(await composeAgentGuide({ ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'Docs' }), '## HTML views');
+    expect(docs).toContain('/workspace/main/Docs/Alice.md');
+  });
+
+  it('lets a distribution replace the section or drop it', async () => {
+    const replaced = await composeAgentGuide(DEFAULT_KB_LAYOUT, (sections) =>
+      sections.map((s) => (s.id === 'html-views' ? { id: s.id, body: '## HTML views\n\nOurs, graph-aware.\n' } : s)),
+    );
+    expect(section(replaced, '## HTML views').trim()).toBe('Ours, graph-aware.');
+    const dropped = await agentGuideSections(DEFAULT_KB_LAYOUT, (sections) => sections.filter((s) => s.id !== 'html-views'));
+    expect(dropped.map((s) => s.id)).not.toContain('html-views');
+    expect(joinGuideSections(dropped)).not.toContain('## HTML views');
+  });
+});

package/src/modules/agent-guide/__tests__/agent-guide.tools.test.ts

@@ -9,7 +9,8 @@ import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolContext } from '../../tool-helpers/tool.contract.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
 import { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from '../agent-guide.tools.js';
-import type { RenderedGuideSection } from '../agent-guide.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { agentGuideSections, joinGuideSections, type RenderedGuideSection } from '../agent-guide.js';
 
 let server: Server | null = null;
 
@@ -186,4 +187,21 @@ describe('get_agent_guide', () => {
     sectionsNow(SECTIONS);
     expect(await describedAs()).toContain('`introduction` (Knowledge base)');
   });
+
+  it('returns the platform\'s HTML views section on its own, and inside the whole guide', async () => {
+    const { call, registry, sectionsNow } = await serve();
+    const platform = await agentGuideSections(DEFAULT_KB_LAYOUT);
+    sectionsNow([...platform]);
+    const html = platform.find((s) => s.id === 'html-views')!;
+    expect(await call({ section: 'html-views' })).toEqual({
+      status: 200,
+      body: { guide: html.body, section: 'html-views', title: 'HTML views' },
+    });
+    const whole = await call();
+    expect(whole.body.guide).toBe(joinGuideSections(platform));
+    expect(String(whole.body.guide)).toContain('## HTML views');
+    // The description lists it, so an agent knows it can ask for it.
+    const def = (await registry.listExternal()).find((t) => t.name === GET_AGENT_GUIDE_TOOL)!;
+    expect(def.description).toContain('`html-views`');
+  });
 });

package/src/modules/agent-guide/agent-guide.ts

@@ -79,6 +79,13 @@ export type AgentGuideReader = () => Promise<string>;
 /** The computed section: the rules every file tool shares. */
 export const WORKING_WITH_FILES_SECTION_ID = 'working-with-files';
 
+/**
+ * What to do on a knowledge base nobody has written in yet: the section the
+ * `firstRun` note `start_session` answers with points at (see
+ * workspace/first-run.ts, which names it by this constant).
+ */
+export const NEW_KNOWLEDGE_BASE_SECTION_ID = 'new-knowledge-base';
+
 /**
  * Core's sections, in reading order. Every id but the shared-rules one names
  * a file in the package's `agent-guide/` folder.
@@ -91,8 +98,10 @@ export const CORE_SECTION_IDS: readonly string[] = Object.freeze([
   'access-control',
   'skills',
   'tool-manuals',
+  'html-views',
   'conventions',
   'finding-things',
+  NEW_KNOWLEDGE_BASE_SECTION_ID,
 ]);
 
 /**

package/src/modules/agent-guide/index.ts

@@ -1,6 +1,7 @@
 export {
   AGENT_GUIDE_FILE,
   CORE_SECTION_IDS,
+  NEW_KNOWLEDGE_BASE_SECTION_ID,
   PLATFORM_GUIDE_SEPARATOR,
   WORKING_WITH_FILES_SECTION_ID,
   agentGuideSections,