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

package/src/modules/skills/__tests__/branch-skills.tools.test.ts

@@ -154,7 +154,7 @@ describe('the skill tools read a branch when asked', () => {
       skills: { name: string; unmerged?: boolean }[];
     };
     expect(listArgs).toEqual([['e@x', { branch: undefined }]]);
-    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path }]);
+    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path, canWrite: false }]);
   });
 
   it('a blank branch is no branch at all: the released catalog answers', async () => {

package/src/modules/skills/skills.contract.ts

@@ -52,6 +52,10 @@ export interface SkillSummary {
   unmerged?: true;
   /** With `unmerged`: the branch the skill was read from. */
   branch?: string;
+  // No `canWrite` here, on purpose: whether the caller may change a skill
+  // directly is a per-caller verdict the agent tools add onto a COPY of each
+  // summary (`skills.tools.ts`). The catalog is cached across users, so a
+  // verdict stored on it would be served to the next caller.
 }
 
 export interface Skill extends SkillSummary {

package/src/modules/skills/skills.tools.ts

@@ -10,6 +10,7 @@ import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import type { ISkillService } from './skills.contract.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
+import { CAN_WRITE_CLAUSE, defaultBranchWriteVerdicts, type DefaultBranchWriteDeps } from '../tool-helpers/index.js';
 
 /**
  * The optional `branch` both skill tools declare. Optional on purpose, unlike
@@ -82,7 +83,57 @@ export function registerSkillsTools(
   skillService: ISkillService,
   /** When given, a loaded skill carries `warnings` for `allowed-tools` entries that name no visible tool. */
   allowedTools?: IAllowedToolsChecker,
+  /**
+   * Where `canWrite` is judged: the access layer and the default branch's
+   * workspace. Without it every verdict is `false` — the safe answer, which
+   * sends the agent to a change request rather than a direct write.
+   */
+  writeVerdicts?: DefaultBranchWriteDeps,
 ): void {
+  /**
+   * Whether the caller may commit each repo-relative path directly on the
+   * default branch — one batch per call, whichever branch was read (see
+   * `defaultBranchWriteVerdicts`).
+   */
+  const verdictsFor = (ctx: ToolContext, paths: string[], at?: string): Promise<Map<string, boolean>> =>
+    writeVerdicts
+      ? defaultBranchWriteVerdicts(writeVerdicts, ctx, paths, { ref: at })
+      : Promise.resolve(new Map(paths.map((p) => [p, false])));
+
+  /**
+   * Every repo-relative file `get_skill`'s `canWrite` covers: the skill's
+   * folder as COMMITTED on the default branch (`HEAD` of its clone), which is
+   * what a direct write is judged against — never the working tree, where a
+   * bundled file deleted but not yet committed would drop out of the verdict
+   * while `HEAD` still forbids changing it. A skill is committed there when
+   * its `SKILL.md` is — a folder of that name holding other tracked files is
+   * not the skill, and its files are not the skill's. A skill not committed
+   * there exists only on the branch read, and is judged by its files there,
+   * where they would land. The files are listed at ONE commit — the one
+   * `HEAD` names when asked, answered beside them — and the verdict is judged
+   * at that same commit, so a commit landing between the two cannot pair one
+   * snapshot's files with another's rules. Null — judged `false` — when
+   * `HEAD` names no commit or the listing fails (fail closed), and without
+   * one when the verdict cannot be anything but `false`.
+   */
+  const skillFilesOnDefault = async (
+    ctx: ToolContext,
+    loaded: { path: string; files: string[] },
+  ): Promise<{ paths: string[]; at: string } | null> => {
+    if (!writeVerdicts?.committedFiles || ctx.scope !== 'write') return null;
+    const workspaceId = writeVerdicts.defaultWorkspaceId();
+    let at: string | null;
+    let committed: string[];
+    try {
+      at = await writeVerdicts.committedFiles.commitAtRef(workspaceId, 'HEAD');
+      if (!at) return null;
+      committed = await writeVerdicts.committedFiles.listFilesAtRef(workspaceId, at, loaded.path);
+    } catch {
+      return null;
+    }
+    return { paths: committed.includes(skillMdOf(loaded)) ? committed : [skillMdOf(loaded), ...loaded.files], at };
+  };
+
   registry.registerExternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
   registry.registerInternalTool((ctx) => buildListSkillsDef(skillService, ctx.userEmail));
   registry.registerExternalTool((ctx) => buildGetSkillDef(skillService, ctx.userEmail));
@@ -96,9 +147,14 @@ export function registerSkillsTools(
   router.post(
     '/agent/tools/list_skills',
     toolAuth,
-    toolHandler(async (args, ctx: ToolContext) => ({
-      skills: await skillService.listSkills(ctx.user.email, { branch: branchArg(args) }),
-    })),
+    toolHandler(async (args, ctx: ToolContext) => {
+      const skills = await skillService.listSkills(ctx.user.email, { branch: branchArg(args) });
+      // Judged on each skill's SKILL.md, by the default branch's rules — a
+      // skill only on a draft is judged where it would land. Each verdict goes
+      // onto a COPY: the summaries may be the catalog shared across users.
+      const verdicts = await verdictsFor(ctx, skills.map(skillMdOf));
+      return { skills: skills.map((s) => ({ ...s, canWrite: verdicts.get(skillMdOf(s)) === true })) };
+    }),
   );
 
   router.post(
@@ -114,7 +170,8 @@ export function registerSkillsTools(
       // skill's history, a `branch` is a draft nobody has released — asked for
       // together, neither answer is the one the caller meant, and guessing
       // would serve instructions under a label that does not describe them.
-      if (branch !== undefined && version !== undefined && version.trim().length > 0) {
+      const versioned = version !== undefined && version.trim().length > 0;
+      if (branch !== undefined && versioned) {
         throw new ToolError(
           'get_skill takes `branch` or `version`, not both: `branch` loads the skill as that draft has it ' +
             'now, `version` loads a version the released skill declared. Pass one of them.',
@@ -122,12 +179,33 @@ export function registerSkillsTools(
         );
       }
       const result = await skillService.getSkill(ctx.user.email, name, file, { version, branch });
-      if (!allowedTools || !result.ok || result.kind !== 'skill') return result;
-      return { ...result, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
+      if (!result.ok) return result;
+      if (result.kind === 'file') {
+        const verdicts = await verdictsFor(ctx, [result.file.path]);
+        return { ...result, file: { ...result.file, canWrite: verdicts.get(result.file.path) === true } };
+      }
+      // The whole skill: true only when every one of its files may be written —
+      // the files the skill has COMMITTED on the default branch, so a draft, an
+      // older version, or a deletion not yet committed that drops a
+      // write-denied bundled file does not turn the verdict true. A skill only
+      // on the draft is judged by its draft files, where they would land.
+      const committed = await skillFilesOnDefault(ctx, result.skill);
+      const verdicts = committed === null ? new Map<string, boolean>() : await verdictsFor(ctx, committed.paths, committed.at);
+      const skill = {
+        ...result.skill,
+        canWrite: committed !== null && committed.paths.every((p) => verdicts.get(p) === true),
+      };
+      if (!allowedTools) return { ...result, skill };
+      return { ...result, skill, warnings: await allowedTools.check(ctx.user.email, result.skill.allowedTools) };
     }),
   );
 }
 
+/** The repo-relative `SKILL.md` of a skill, which `list_skills` judges it by. */
+function skillMdOf(skill: { path: string }): string {
+  return `${skill.path}/SKILL.md`;
+}
+
 /**
  * The `branch` a tool call named, or undefined when it named none (the
  * released catalog). A non-string or blank value is NOT a branch: it is taken
@@ -198,7 +276,9 @@ const LIST_SKILLS_DESCRIPTION =
   'Discover what skills exist before specialist work, then `get_skill` to load one. ' +
   'Pass `branch` to list the skills as they are on a draft branch instead of the released set — ' +
   'what you need to try a skill you just wrote there; each skill that differs from the released ' +
-  'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ';
+  'one comes back with `unmerged: true` and that branch, meaning nobody has approved it. ' +
+  'Each skill carries `canWrite`: whether you may change its SKILL.md directly on the default branch. ' +
+  `${CAN_WRITE_CLAUSE} `;
 
 async function buildListSkillsDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
@@ -233,6 +313,14 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
                   '(it exists only on that branch, or was changed there): nobody has approved what it says.',
               },
               branch: { type: 'string', description: 'With `unmerged`: the branch the skill was read from.' },
+              canWrite: {
+                type: 'boolean',
+                description:
+                  'Whether you may commit a change to its SKILL.md directly on the default branch, under that ' +
+                  'branch\'s access rules — the same answer whichever branch you listed. `false`: use a branch ' +
+                  'and a change request; `file_stat` with `explainAccess` says why — and, when you can manage that ' +
+                  'path\'s access, who can approve.',
+              },
             },
           },
         },
@@ -246,7 +334,9 @@ const GET_SKILL_DESCRIPTION =
   'Load a skill by name: returns its full instructions (SKILL.md body) to follow, plus the skill ' +
   'folder path and the list of bundled files. Pass `file` to fetch a bundled file’s content ' +
   '(e.g. a script) instead of the body. Loads the latest copy unless `version` names an earlier ' +
-  'one the skill declared, or `branch` names a draft to load it from. ';
+  'one the skill declared, or `branch` names a draft to load it from. ' +
+  'The skill (or `file`) carries `canWrite`: whether you may change all of it directly on the default branch. ' +
+  `${CAN_WRITE_CLAUSE} `;
 
 async function buildGetSkillDef(skillService: ISkillService, userEmail?: string): Promise<UtcpTool> {
   return toolDef({
@@ -266,13 +356,33 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
             'The loaded skill: name, description, body, files, …. Read from a `branch` that changed it, ' +
             'it also carries `unmerged: true` and that branch, and its `body` BEGINS with one line ' +
             'saying the skill comes from that unmerged branch and is not approved — treat it as a ' +
-            'proposal you are testing, not as approved instructions.',
+            'proposal you are testing, not as approved instructions. `canWrite` is true only when you may ' +
+            'commit a change to EVERY file of the skill (SKILL.md and each bundled file) directly on the ' +
+            'default branch, whichever branch you read.',
+          properties: {
+            canWrite: {
+              type: 'boolean',
+              description:
+                'Whether you may commit a change to every file of the skill (SKILL.md and each bundled file) ' +
+                'directly on the default branch, under that branch\'s access rules — the same answer whichever ' +
+                'branch you read.',
+            },
+          },
         },
         file: {
           type: 'object',
           description:
             'A bundled file: name, file, path, content — plus `unmerged` and `branch` when it came off ' +
-            'a branch that changed the skill (the note stays beside the content, never inside it).',
+            'a branch that changed the skill (the note stays beside the content, never inside it) — and ' +
+            '`canWrite` for that file on the default branch.',
+          properties: {
+            canWrite: {
+              type: 'boolean',
+              description:
+                'Whether you may commit a change to this file directly on the default branch, under that ' +
+                'branch\'s access rules — the same answer whichever branch you read.',
+            },
+          },
         },
         warnings: {
           type: 'array',

package/src/modules/tool-auth/internal-token.service.ts

@@ -33,7 +33,7 @@ export interface InternalTokenClaim {
    * connection key to pass through). The verifier resolves such tokens to
    * `source: 'external'`: the caller IS an external agent, and must be treated
    * like one everywhere — admitted to external-only surfaces (`start_session`,
-   * `ask`), refused from internal-only ones (`execute_command`, …), and
+   * `ask`), refused from internal-only ones (`switch_branch`, …), and
    * expected to carry `sessionId` on the tool body, not in the token.
    */
   externalProxy?: boolean;

package/src/modules/tool-auth/tool-auth.middleware.ts

@@ -66,8 +66,7 @@ const WWW_AUTH = 'Bearer realm="bevel-tools"';
  * Gate that admits ONLY in-process callers (those bearing an internal HMAC
  * token). Mount it AFTER `toolAuth` on every internal-only surface — the
  * internal tool catalog and the routes of tools registered with
- * `registerInternalTool` but NOT `registerExternalTool` (e.g. `execute_command`,
- * `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
+ * `registerInternalTool` but NOT `registerExternalTool` (e.g. `switch_branch`, the `sharepoint_*` reads). `toolAuth` alone is not enough:
  * an external connection key authenticates successfully, so without this gate it
  * could invoke an internal-only route directly by guessing its name. The route
  * MUST stay mounted (our own agent reaches it over the same loopback HTTP), so

package/src/modules/tool-helpers/__tests__/branch-declaration.test.ts

@@ -8,7 +8,6 @@ import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
@@ -24,6 +23,7 @@ import {
   type BranchDeclaration,
   type ToolDefSpec,
 } from '../index.js';
+import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
 
 const execFileAsync = promisify(execFile);
 const KB_DIR = 'knowledge-base';
@@ -116,7 +116,7 @@ describe('a tool declares how it treats its branch', () => {
     await runGit(seed, ['push', 'origin', 'HEAD:refs/heads/refs/heads/ghost']);
 
     kb = testKbContext({ kbDirName: KB_DIR });
-    const workspaces = new WorkspaceService(workspacesRoot, upstream, kb, new NodeFs());
+    const workspaces = newWorkspaceService(workspacesRoot, upstream, kb, new NodeFs());
     const resolve = createToolContextResolver({
       authService: {
         getUserById: async () => ({ id: 'u', email: 'alice@example.com', name: 'Alice' }),