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

package/src/modules/access-model/group-files.ts

@@ -4,6 +4,7 @@ import {
   RESERVED_ROLE_NAMES,
   PLUGIN_TOKEN_PREFIX,
   ROLE_TOKEN_PREFIX,
+  GROUP_TOKEN_PREFIX,
   canonicalEmail,
   canonicalRoleName,
   parseYamlSubset,
@@ -58,6 +59,7 @@ export const SYNCED_GROUPS_YAML = 'synced-groups.yaml';
  *   \x00-\x1f  control chars / newlines break line structure outright
  *   `role/…`   reserved: that spelling is the EXPLICIT role token in access
  *              entries — a group carrying it could never be referenced.
+ *   `group/…`  reserved likewise: the EXPLICIT group token.
  */
 export function unsafeNameReason(displayName: string): string | null {
   const trimmed = displayName.trim();
@@ -69,6 +71,9 @@ export function unsafeNameReason(displayName: string): string | null {
   if (canonicalRoleName(trimmed).startsWith(ROLE_TOKEN_PREFIX)) {
     return `starts with the reserved '${ROLE_TOKEN_PREFIX}' prefix (the explicit role token in access entries)`;
   }
+  if (canonicalRoleName(trimmed).startsWith(GROUP_TOKEN_PREFIX)) {
+    return `starts with the reserved '${GROUP_TOKEN_PREFIX}' prefix (the explicit group token in access entries)`;
+  }
   if (canonicalRoleName(trimmed).startsWith(PLUGIN_TOKEN_PREFIX)) {
     return `starts with the reserved '${PLUGIN_TOKEN_PREFIX}' prefix (the plugin-principal token in access entries)`;
   }

package/src/modules/access-model/index.ts

@@ -2,12 +2,28 @@
  * The access model's public entry: what another module imports of it.
  *
  * The module is the grammar of `access.md` (how principals, roles, groups
- * and verbs are spelled), the errors a refused access is reported with, and
- * the gate a change is read through. A consumer outside the module imports
- * from here, not from the files; the files are the module's own layout and
- * free to move. The `access` module's own files predate this entry and still
- * import the files directly — they move here as they are touched.
+ * and verbs are spelled), the errors a refused access is reported with, the
+ * gate a change is read through, and the single-path read verdict every
+ * surface shares, so a module that must hide what a person may not read asks
+ * the same question the file routes ask. A consumer outside the module
+ * imports from here, not from the files; the files are the module's own
+ * layout and free to move. The `access` module's own files predate this
+ * entry and still import the files directly — they move here as they are
+ * touched.
  */
 export * from './access-grammar.js';
 export * from './access-errors.js';
 export type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from './change-gate.js';
+export { canReadWorkspacePath } from './kb-read-filter.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { AccessSpliceError, spliceGrant, spliceRevoke, validatePrincipal } from './access-splice.js';
+export type { Principal, TokenMatch } from './access-splice.js';
+export { creatorPrincipal } from './creator.js';
+export type { CreationGrantPlan, Creator, ICreatorAccess } from './creator.js';
+export { scanFrontmatter } from './frontmatter-lines.js';
+export { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, unsafeNameReason, validateGroupsFile } from './group-files.js';
+export type { GroupsIndex } from './group-files.js';
+export { resolveReadableMap, toKbRelative } from './kb-read-filter.js';
+export { synthesizePluginPrincipals } from './plugin-principals.js';
+export { renderRolesYaml } from './render-roles-yaml.js';
+export { ROLES_YAML_BASENAME, assertRolesYamlParsable, isRolesYamlPath, makeAgentRolesYamlWriteValidator, makeRolesYamlWriteValidator } from './roles-yaml-guard.js';

package/src/modules/access-model/roles-yaml-guard.ts

@@ -25,7 +25,7 @@ import type { FileContent } from '@mastra/core/workspace';
 import { GROUP_REF_PREFIX, canonicalRoleName, parseRolesYaml, parseYamlSubset } from './access-grammar.js';
 import type { GroupsIndex } from './group-files.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
-import type { WriteValidator } from '../kb-fs/locking-filesystem.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 
 /** Repo-relative basename of the roles file (it lives at the KB repo root). */
 export const ROLES_YAML_BASENAME = 'roles.yaml';

package/src/modules/admin/admin-access.routes.ts

@@ -1,6 +1,6 @@
 import express from 'express';
 import type { IAdminAccessService } from './admin.interface.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * The CORE slice of the admin surface: just the admin-status resolver the

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

@@ -1,8 +1,8 @@
-import type { IAccessControl } from '../access/access-control.interface.js';
+import type { IAccessControl } from '../access/index.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('admin');
-import { type WorkspaceService } from '../workspace/workspace.service.js';
+import { type WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
 import type { IAdminAccessService } from './admin.interface.js';

package/src/modules/admin/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the admin module offers the other modules: the contract of the
+ * deployment admin check — a person is an admin iff they hold the `Admin`
+ * role in the knowledge base's `roles.yaml`. Routes that gate on it take the
+ * contract; the implementation is wired by the composition root.
+ */
+export type { IAdminAccessService } from './admin.interface.js';

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

@@ -367,6 +367,7 @@ describe('the HTML views section', () => {
     expect(text).toContain('**No host navigation.**');
     expect(text).toContain('`window.bevel.openNode(href)`');
     expect(text).toContain('`window.bevel.navigate(href)`');
+    expect(text).toContain('`window.bevel.branch` — the branch the page is viewed on');
     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.
@@ -374,6 +375,36 @@ describe('the HTML views section', () => {
     expect(docs).toContain('/workspace/main/Docs/Alice.md');
   });
 
+  // A dashboard that painted one "Loading…" line and then swapped in the whole
+  // board read as broken on a cold load (2026-10-20). These rules are what
+  // agents write pages from; the reference page under them is run by
+  // core-frontend's `liveDataReferencePage.test.ts`.
+  it('tells page authors how a page loads live data without changing shape', async () => {
+    const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
+    expect(text).toContain('### Live data: a page that stays still while it loads');
+    expect(text).toContain('**Render the final page shell in the markup, before any data.**');
+    expect(text).toContain('The loading treatment — placeholder rows, `aria-busy="true"` — sits **inside** the data regions.');
+    expect(text).toContain('**Publish one consistent dataset at a time.**');
+    expect(text).toContain('Until then show no counts, no cards and no empty columns');
+    expect(text).toContain('**Refresh keeps the current board.**');
+    expect(text).toContain('**A failed read fails the whole load, visibly.**');
+    expect(text).toContain('offer a Retry button that runs the same load again');
+    expect(text).toContain('**Read in bounded parallel once the paths are known.**');
+    expect(text).toContain('**Load with `callTool`, not `callToolChain`.**');
+    expect(text).toContain("**The reads are the viewer's own.**");
+    expect(text).toContain('**Link to what the tools named by the path they answered.**');
+    expect(text).toContain('Never put the checkout folder in front of a path a tool answered: it is already there.');
+    expect(text).toContain('plain HTML and one inline script, no build step and no framework');
+    // The rule names the deployment's own checkout folder; the page links on its branch by the tool's path.
+    const docs = section(await composeAgentGuide(DEFAULT_KB_LAYOUT, undefined, { kbDirName: 'kb' }), '## HTML views');
+    expect(docs.replace(/\s+/g, ' ')).toContain('starts with the checkout folder, `kb/Data/Tickets/A.md`');
+    // Each segment of the tool's path encoded on its own, so a name carrying `#` stays a name.
+    expect(docs).toContain(
+      "link.href = '/workspace/' + encodeURIComponent(BRANCH) + '/' + ticket.path.split('/').map(encodeURIComponent).join('/');",
+    );
+    expect(docs).not.toContain('{{');
+  });
+
   it('documents window.bevel.tools: its four functions, the null check, the consent rule and requireTools with its card', async () => {
     const text = section(await composeAgentGuide(DEFAULT_KB_LAYOUT), '## HTML views').replace(/\s+/g, ' ');
     for (const member of [
@@ -387,6 +418,11 @@ describe('the HTML views section', () => {
     }
     expect(text).toContain('`window.bevel.tools` is `null` wherever tools are not available');
     expect(text).toContain('Check it before every use');
+    // The skill page answers a page's tools as the file page does
+    // (htmlToolBridge.ts's host list): the guide says so, and never that a
+    // skill page leaves `tools` null.
+    expect(text).toContain("on the app's file page and on a skill's page");
+    expect(text).not.toMatch(/on a skill page and in any preview/);
     expect(text).toContain('**Reading runs at once; writing asks first.**');
     expect(text).toContain('"<page name> wants to write to the knowledge base"');
     expect(text).toContain('Allow while open and Deny');

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

@@ -1,10 +1,8 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import { GET_AGENT_GUIDE_TOOL } from '../tool-registry/guide-first.js';
-import { TOOL_DESCRIPTION_CAP } from '../tool-registry/description-length.js';
-import { ToolError } from '../tool-helpers/tool.contract.js';
-import { toolDef } from '../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/index.js';
+import { GET_AGENT_GUIDE_TOOL, TOOL_DESCRIPTION_CAP } from '../tool-registry/index.js';
+import { ToolError, toolDef } from '../tool-helpers/index.js';
+import type { ToolHandlerFactory } from '../tool-helpers/index.js';
 import { AGENT_GUIDE_FILE, joinGuideSections, type AgentGuideSectionsReader } from './agent-guide.js';
 
 export { GET_AGENT_GUIDE_TOOL };
@@ -104,10 +102,21 @@ export function registerAgentGuideTool(
   router.post(
     `/agent/tools/${GET_AGENT_GUIDE_TOOL}`,
     toolAuth,
-    toolHandler(async (args) => {
+    toolHandler(async (args, ctx) => {
       const list = await sections();
       const wanted = typeof args.section === 'string' ? args.section.trim() : '';
-      if (!wanted) return { guide: joinGuideSections(list), sections: list.map((s) => ({ id: s.id, title: s.title })) };
+      // A connection made as an agent configuration is told so at the top of the
+      // whole guide: the catalog it describes is narrowed to that agent.
+      // Everything is told nothing new, so its guide is the same text.
+      const connection = ctx.connectionScope?.describe() ?? null;
+      if (!wanted) {
+        const guide = joinGuideSections(list);
+        return {
+          guide: connection ? `> ${connection}\n\n${guide}` : guide,
+          sections: list.map((s) => ({ id: s.id, title: s.title })),
+          ...(connection ? { connection } : {}),
+        };
+      }
       const one = list.find((s) => s.id === wanted);
       if (!one) {
         throw new ToolError(

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

@@ -35,7 +35,7 @@ import {
   type KbLayout,
 } from '@bevel-software/platform-shared';
 import { agentGuideDir } from '../../assets.js';
-import { sharedFileRulesSection } from '../agent-instructions/shared-file-rules.js';
+import { sharedFileRulesSection } from '../agent-instructions/index.js';
 
 /** One section of the guide. */
 export interface AgentGuideSection {

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

@@ -19,4 +19,4 @@ export {
   type RenderedGuideSection,
 } from './agent-guide.js';
 export { GET_AGENT_GUIDE_TOOL, registerAgentGuideTool } from './agent-guide.tools.js';
-export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/guide-first.js';
+export { GUIDE_FIRST_SENTENCE, withGuideFirst } from '../tool-registry/index.js';

package/src/modules/agent-instructions/__tests__/shared-file-rules.test.ts

@@ -51,6 +51,7 @@ describe('the shared file rules are one text, in two places', () => {
     expect(rules.map((r) => r.id)).toEqual([
       'agent-guide',
       'content-kinds',
+      'workspace-tmp',
       'write-mode',
       'images-in-pages',
       'escape-sequences',

package/src/modules/agent-instructions/compose.ts

@@ -90,8 +90,10 @@ export function platformInstructions(layout: KbLayout): string {
  * own cap, and the preamble under its cap plus the marker a cut appends. The
  * test is what makes it a ceiling rather than a hope: a shared rule that grew
  * past it fails before it reaches an agent.
+ *
+ * 14,400 since the shared rules' own cap rose by 400 (the `__tmp__/` ref).
  */
-export const INSTRUCTIONS_CAP = 14_000;
+export const INSTRUCTIONS_CAP = 14_400;
 
 /** The one-line marker that replaces everything past the preamble cap. */
 export const PREAMBLE_TRUNCATION_MARKER = `[preamble truncated at ${PREAMBLE_CAP.toLocaleString('en-US')} characters; shorten ${PREAMBLE_FILE}]`;

package/src/modules/agent-instructions/read-preamble.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe } from '../../shared/fs.contract.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { PREAMBLE_FILE } from './compose.js';
 
 /** The one reader both the hosted proxy and the agent-facing route call. */

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -61,8 +61,12 @@ const PRE_RENAME_AGENTS_FILE = 'CLAUDE.md';
  * of every call rather than of how to write one, and why large, escape-heavy
  * and binary content goes by upload, which three write tools each said in
  * full.
+ *
+ * 7,400 since the `__tmp__/` ref: four tools take it, so what it reaches and
+ * that it is read-only is said once here rather than in each description, and
+ * the section had no room left for it.
  */
-export const SHARED_FILE_RULES_CAP = 7_000;
+export const SHARED_FILE_RULES_CAP = 7_400;
 
 /** One shared rule: how the guide heads it, and the rule itself. */
 export interface SharedFileRule {
@@ -114,6 +118,18 @@ export function sharedFileRules(layout: KbLayout): readonly SharedFileRule[] {
         '`{ image_omitted, note }` stub instead, so read an image outside a chain when you mean to look at it. Any other ' +
         'binary file reads as a one-line description rather than raw bytes.',
     },
+    {
+      // What `__tmp__/` reaches and what it does not (see
+      // `workspace/workspace-tmp.ts`) — four tools take the ref, so it is a
+      // shared rule rather than a sentence in each description.
+      id: 'workspace-tmp',
+      heading: "Files staged in the workspace's tmp folder",
+      body:
+        "`__tmp__/<path>` names ONE file YOU staged in the branch workspace's `tmp/` folder (chat attachments land " +
+        'there; nobody else\'s staged files are reachable). read_file, file_stat, grep (`path`) and copy_file (`src`) ' +
+        'read it as a repository file; it is read-only and never listed — copy_file it to a repository path to keep ' +
+        'it. An entry stays up to seven days.',
+    },
     {
       id: 'write-mode',
       heading: 'What a write may do at a path',