@bevel-software/platform-core-backend 0.21.0 → 0.23.0

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

@@ -0,0 +1,218 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolContext } from '../../tool-helpers/tool.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { BranchNotFoundError } from '../../../shared/domain-errors.js';
+import { registerSkillsTools } from '../skills.tools.js';
+import { unmergedSkillNotice } from '../skills.service.js';
+import type { GetSkillOptions, ISkillService, ListSkillsOptions, Skill } from '../skills.contract.js';
+import { AllowedToolsChecker } from '../allowed-tools-check.js';
+import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * The two skill tools reading a draft branch: the input reaches the service,
+ * the branch's own answer comes back with its mark and its first line, the
+ * `allowed-tools` warnings are computed from the BRANCH's version of the
+ * skill, a branch nobody pushed is the file tools' 404, and `branch` with
+ * `version` is refused rather than silently ranked.
+ */
+
+const DRAFT = 'juan/skill-deck';
+const KB_DIR = 'knowledge-base';
+
+const hubspot: ToolManualSummary = { slug: 'hubspot', name: 'hubspot', path: 'Plugins/Sales/hubspot.tool', type: 'inline' };
+const checker = new AllowedToolsChecker(
+  { listExternal: async () => [] },
+  {
+    listAccessible: async () => [hubspot],
+    getDetail: async (): Promise<ToolManualDetail> => ({
+      ...hubspot,
+      description: null,
+      capabilities: [{ name: 'search', description: null }],
+    }),
+  },
+  testKbContext({ kbDirName: KB_DIR }),
+);
+
+/** The released skill and the draft's changed copy of it — only the draft names a tool nobody serves. */
+const released: Skill = {
+  name: 'rfi',
+  description: 'RFI.',
+  path: 'Plugins/Sales/rfi',
+  body: '# RFI',
+  files: [],
+  allowedTools: ['hubspot.search'],
+};
+const onDraft: Skill = {
+  ...released,
+  body: `${unmergedSkillNotice(DRAFT)}\n\n# RFI, rewritten`,
+  allowedTools: ['hubspot.search', 'hubspot.serch'],
+  unmerged: true,
+  branch: DRAFT,
+};
+
+/** What the tools handed the service, so a test can see the branch arrive (or not). */
+let listArgs: [string | undefined, ListSkillsOptions | undefined][] = [];
+let getArgs: [string, string, string | undefined, GetSkillOptions | undefined][] = [];
+
+const skillService: ISkillService = {
+  listSkills: async (userEmail?: string, options?: ListSkillsOptions) => {
+    listArgs.push([userEmail, options]);
+    if (options?.branch === 'juan/typo') throw new BranchNotFoundError('juan/typo');
+    if (options?.branch === DRAFT) {
+      return [
+        { name: 'rfi', description: 'RFI.', path: released.path, unmerged: true, branch: DRAFT },
+        { name: 'make-deck', description: 'Decks.', path: 'Plugins/make-deck', unmerged: true, branch: DRAFT },
+      ];
+    }
+    return [{ name: 'rfi', description: 'RFI.', path: released.path }];
+  },
+  getSkill: async (userEmail: string, name: string, file?: string, options?: GetSkillOptions) => {
+    getArgs.push([userEmail, name, file, options]);
+    if (options?.branch === 'juan/typo') throw new BranchNotFoundError('juan/typo');
+    return { ok: true, kind: 'skill', skill: options?.branch === DRAFT ? onDraft : released };
+  },
+  invalidate: () => {},
+};
+
+let httpServer: HttpServer | undefined;
+let registry: ToolRegistry;
+
+async function start(): Promise<string> {
+  listArgs = [];
+  getArgs = [];
+  registry = new ToolRegistry();
+  const resolve = async (auth: ToolAuth, signal: AbortSignal): Promise<ToolContext> =>
+    ({
+      user: { id: 'u', email: 'e@x', name: 'N' },
+      scope: auth.scope,
+      source: auth.source,
+      abortSignal: signal,
+      workspaceService: {} as never,
+      workflowService: {} as never,
+      events: {} as never,
+      getFilesystem: async () => ({}) as never,
+    }) as unknown as ToolContext;
+  const fakeAuth = (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    req.toolAuth = { source: 'external', userId: 'u', scope: 'read' };
+    next();
+  };
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  registerSkillsTools(registry, router, fakeAuth, createToolHandlerFactory(resolve), skillService, checker);
+  app.use('/api', router);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+const post = (url: string, body: unknown) =>
+  fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: 'Bearer x' },
+    body: JSON.stringify(body),
+  });
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+describe('the skill tools read a branch when asked', () => {
+  it('declares `branch` as an OPTIONAL input on both tools', async () => {
+    await start();
+    const defs = await registry.listExternal({ userEmail: 'e@x' });
+    for (const name of ['list_skills', 'get_skill']) {
+      const def = defs.find((t) => t.name === name)!;
+      // `toolDef` wraps a tool's flat inputs under `body`.
+      const inputs = (def.inputs as { properties: { body: { properties: Record<string, unknown>; required?: string[] } } })
+        .properties.body;
+      expect(inputs.properties.branch).toBeDefined();
+      expect(inputs.required ?? []).not.toContain('branch');
+    }
+  });
+
+  it('list_skills passes the branch on and returns what that branch has, marked', async () => {
+    const base = await start();
+    const body = (await (await post(`${base}/api/agent/tools/list_skills`, { branch: DRAFT })).json()) as {
+      skills: { name: string; unmerged?: boolean; branch?: string }[];
+    };
+    expect(listArgs).toEqual([['e@x', { branch: DRAFT }]]);
+    expect(body.skills.map((s) => s.name)).toEqual(['rfi', 'make-deck']);
+    expect(body.skills.every((s) => s.unmerged === true && s.branch === DRAFT)).toBe(true);
+  });
+
+  it('list_skills without a branch asks for the released catalog', async () => {
+    const base = await start();
+    const body = (await (await post(`${base}/api/agent/tools/list_skills`, {})).json()) as {
+      skills: { name: string; unmerged?: boolean }[];
+    };
+    expect(listArgs).toEqual([['e@x', { branch: undefined }]]);
+    expect(body.skills).toEqual([{ name: 'rfi', description: 'RFI.', path: released.path }]);
+  });
+
+  it('a blank branch is no branch at all: the released catalog answers', async () => {
+    const base = await start();
+    await post(`${base}/api/agent/tools/list_skills`, { branch: '   ' });
+    await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi', branch: '' });
+    expect(listArgs).toEqual([['e@x', { branch: undefined }]]);
+    expect(getArgs[0][3]).toEqual({ version: undefined, branch: undefined });
+  });
+
+  it('get_skill passes the branch on, and the body keeps its unmerged first line', async () => {
+    const base = await start();
+    const body = (await (await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi', branch: DRAFT })).json()) as {
+      skill: { body: string; unmerged?: boolean; branch?: string };
+    };
+    expect(getArgs).toEqual([['e@x', 'rfi', undefined, { version: undefined, branch: DRAFT }]]);
+    expect(body.skill.body.split('\n')[0]).toBe(unmergedSkillNotice(DRAFT));
+    expect(body.skill.unmerged).toBe(true);
+    expect(body.skill.branch).toBe(DRAFT);
+  });
+
+  it('the allowed-tools check runs on the BRANCH version of the skill', async () => {
+    const base = await start();
+    const onBranch = (await (
+      await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi', branch: DRAFT })
+    ).json()) as { warnings: { entry: string; suggestion?: string }[] };
+    // `hubspot.serch` is only in the DRAFT's `allowed-tools`: the warning can
+    // only come from the copy the branch serves.
+    expect(onBranch.warnings.map((w) => w.entry)).toEqual(['hubspot.serch']);
+    expect(onBranch.warnings[0].suggestion).toBe('hubspot.search');
+    const releasedRes = (await (await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi' })).json()) as {
+      warnings: unknown[];
+    };
+    expect(releasedRes.warnings).toEqual([]);
+  });
+
+  it('refuses `branch` together with `version`, naming both, without asking the service', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/get_skill`, { name: 'rfi', branch: DRAFT, version: '1.4.0' });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('`branch` or `version`, not both');
+    expect(getArgs).toEqual([]);
+  });
+
+  it('answers 404 naming a branch that does not exist, on both tools', async () => {
+    const base = await start();
+    for (const [tool, args] of [
+      ['list_skills', { branch: 'juan/typo' }],
+      ['get_skill', { name: 'rfi', branch: 'juan/typo' }],
+    ] as const) {
+      const res = await post(`${base}/api/agent/tools/${tool}`, args);
+      expect(res.status).toBe(404);
+      expect(await res.json()).toMatchObject({
+        kind: 'branch-not-found',
+        branch: 'juan/typo',
+        error: 'There is no branch named juan/typo.',
+      });
+    }
+  });
+});

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -27,15 +27,19 @@ const FOLDER = 'Skills/Eng/deploy';
 
 async function makeHarness(listBranches: IWorkflowService['listBranches']) {
   const workflow = {
-    listChangeRequestsAuthoredBy: vi.fn(async () => []),
+    listChangeRequests: vi.fn(async () => []),
     listBranches: vi.fn(listBranches),
     createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
+    deleteBranch: vi.fn(async () => undefined),
     commitChanges: vi.fn(async () => null),
     openChangeRequest: vi.fn(async () => ({ number: 42 })),
+    getChangeRequestDetail: vi.fn(async () => ({ body: '' })),
   } as unknown as IWorkflowService;
   const workspaceService = {
     getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: workspaceIdForBranch(branch) })),
     readFile: vi.fn(async () => '---\n---\nwrite:\n  - Eve <eve@x.io>\n'),
+    readFileAtRef: vi.fn(async () => null),
+    ensureRemotesFetched: vi.fn(async () => undefined),
     writeFile: vi.fn(async () => undefined),
   } as unknown as WorkspaceService;
   const accessControl = { canWrite: vi.fn(async () => false) } as unknown as IAccessControl;

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -1,10 +1,11 @@
 import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { mkdtemp, rm, mkdir, writeFile, cp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { SkillService } from '../skills.service.js';
+import { SkillService, unmergedSkillNotice } from '../skills.service.js';
+import { BranchNotFoundError } from '../../../shared/domain-errors.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -38,11 +39,20 @@ You answer RFIs.
 
 describe('SkillService', () => {
   let root: string;
+  /**
+   * The branches that have a clone under `root`. A name that is not in here
+   * answers the way the real service does for a branch nobody ever pushed: the
+   * 404 the file tools answer, not an empty workspace.
+   */
+  let clones: Set<string>;
 
-  // WorkspaceService stub: default-branch workspace lives at <root>/<wsId>, the
-  // KB clone at <root>/<wsId>/<KB_DIR>.
+  // WorkspaceService stub: a branch's workspace lives at <root>/<branch's id>,
+  // its KB clone at <root>/<id>/<KB_DIR>.
   const workspaceService = {
-    getOrCreateForBranch: async () => ({ id: wsId }),
+    getOrCreateForBranch: async (branch: string) => {
+      if (!clones.has(branch)) throw new BranchNotFoundError(branch);
+      return { id: workspaceIdForBranch(branch) };
+    },
     getWorkspacePath: async (id: string) => join(root, id),
     readFile: async (id: string, rel: string) => fsReadFile(join(root, id, rel), 'utf-8'),
   } as unknown as WorkspaceService;
@@ -58,6 +68,7 @@ describe('SkillService', () => {
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'skills-'));
+    clones = new Set([DEFAULT_BRANCH]);
     const skills = join(root, wsId, KB_DIR, 'Plugins');
     await mkdir(join(skills, 'rfi', 'scripts'), { recursive: true });
     await writeFile(join(skills, 'rfi', 'SKILL.md'), RFI_SKILL);
@@ -480,4 +491,217 @@ describe('SkillService', () => {
       });
     });
   });
+
+  /**
+   * Reading a DRAFT branch: what an agent needs to try the skill it has just
+   * written, with the answer saying plainly that nobody approved it.
+   *
+   * The draft starts as a copy of the released tree — which is what a clone of
+   * a branch with no skill changes on it is — and each test changes it.
+   */
+  describe('reading a branch', () => {
+    const DRAFT = 'juan/skill-deck';
+    const draftWsId = workspaceIdForBranch(DRAFT);
+    const user = 'user@x.eu';
+    const draftKb = () => join(root, draftWsId, KB_DIR);
+    const named = async (service = svc()) =>
+      Object.fromEntries((await service.listSkills(user, { branch: DRAFT })).map((s) => [s.name, s]));
+
+    const writeDeck = (body = '# Deck\n') =>
+      mkdir(join(draftKb(), 'Plugins', 'make-deck'), { recursive: true }).then(() =>
+        writeFile(join(draftKb(), 'Plugins', 'make-deck', 'SKILL.md'), `---\ndescription: Decks.\n---\n\n${body}`),
+      );
+
+    beforeEach(async () => {
+      await cp(join(root, wsId), join(root, draftWsId), { recursive: true });
+      clones.add(DRAFT);
+    });
+
+    test('a skill that exists only on the branch is listed as unmerged; the released ones are not marked', async () => {
+      await writeDeck();
+      const list = await named();
+      expect(Object.keys(list).sort()).toEqual(['coding-guidelines', 'make-deck', 'rfi']);
+      expect(list['make-deck']).toMatchObject({ unmerged: true, branch: DRAFT, description: 'Decks.' });
+      // The skills the branch shares with the default branch are the released
+      // ones, read through a draft's clone: nothing about them is unapproved.
+      expect(list['rfi'].unmerged).toBeUndefined();
+      expect(list['rfi'].branch).toBeUndefined();
+      expect(list['coding-guidelines'].unmerged).toBeUndefined();
+    });
+
+    test('without a branch the draft-only skill is absent, and nothing carries a mark', async () => {
+      await writeDeck();
+      const list = await svc().listSkills(user);
+      expect(list.map((s) => s.name)).toEqual(['coding-guidelines', 'rfi']);
+      expect(list.some((s) => s.unmerged !== undefined || s.branch !== undefined)).toBe(false);
+    });
+
+    test('get_skill loads the draft-only skill, body starting with the unmerged line', async () => {
+      await writeDeck();
+      const res = await svc().getSkill(user, 'make-deck', undefined, { branch: DRAFT });
+      expect(res.ok && res.kind === 'skill').toBe(true);
+      if (!res.ok || res.kind !== 'skill') return;
+      expect(res.skill.body.split('\n')[0]).toBe(
+        `This skill is read from the unmerged branch "${DRAFT}" and is not approved.`,
+      );
+      expect(res.skill.body.split('\n')[0]).toBe(unmergedSkillNotice(DRAFT));
+      expect(res.skill.body).toContain('# Deck');
+      expect(res.skill).toMatchObject({ unmerged: true, branch: DRAFT, path: 'Plugins/make-deck' });
+      // Without the branch there is no such skill at all.
+      expect(await svc().getSkill(user, 'make-deck')).toEqual({ ok: false, error: 'not_found' });
+    });
+
+    test('a skill changed on the branch loads changed there and released without the branch', async () => {
+      await writeFile(
+        join(draftKb(), 'Plugins', 'rfi', 'SKILL.md'),
+        RFI_SKILL.replace('You answer RFIs.', 'You answer RFIs, in three paragraphs.'),
+      );
+      const service = svc();
+      const draft = await service.getSkill(user, 'rfi', undefined, { branch: DRAFT });
+      expect(draft.ok && draft.kind === 'skill' && draft.skill.body).toContain('in three paragraphs');
+      expect(draft.ok && draft.kind === 'skill' && draft.skill.body.split('\n')[0]).toBe(unmergedSkillNotice(DRAFT));
+      expect(draft.ok && draft.kind === 'skill' && draft.skill.unmerged).toBe(true);
+      expect((await named(service))['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+
+      const released = await service.getSkill(user, 'rfi');
+      expect(released.ok && released.kind === 'skill' && released.skill.body).not.toContain('three paragraphs');
+      expect(released.ok && released.kind === 'skill' && released.skill.body).not.toContain('unmerged');
+      expect(released.ok && released.kind === 'skill' && released.skill.unmerged).toBeUndefined();
+    });
+
+    test('a skill unchanged on the branch carries no mark and no line — it is the released answer', async () => {
+      const service = svc();
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DRAFT })).toEqual(
+        await service.getSkill(user, 'rfi'),
+      );
+      expect(await service.getSkill(user, 'rfi', 'scripts/build_xlsx.py', { branch: DRAFT })).toEqual(
+        await service.getSkill(user, 'rfi', 'scripts/build_xlsx.py'),
+      );
+    });
+
+    test('a bundled file changed on the branch makes the skill unmerged, and rides beside its content', async () => {
+      // The SKILL.md is byte-identical: the difference is in the folder.
+      await writeFile(join(draftKb(), 'Plugins', 'rfi', 'scripts', 'build_xlsx.py'), 'print("xlsx v2")\n');
+      expect((await named())['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+      const file = await svc().getSkill(user, 'rfi', 'scripts/build_xlsx.py', { branch: DRAFT });
+      expect(file).toEqual({
+        ok: true,
+        kind: 'file',
+        file: {
+          name: 'rfi',
+          file: 'scripts/build_xlsx.py',
+          path: 'Plugins/rfi/scripts/build_xlsx.py',
+          // The notice never goes INSIDE a script.
+          content: 'print("xlsx v2")\n',
+          unmerged: true,
+          branch: DRAFT,
+        },
+      });
+    });
+
+    test('an asset added on the branch is a difference too', async () => {
+      await writeFile(join(draftKb(), 'Plugins', 'rfi', 'scripts', 'extra.py'), 'print("new")\n');
+      expect((await named())['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+
+    test('a skill deleted on the branch is absent there and still released without it', async () => {
+      await rm(join(draftKb(), 'Plugins', 'rfi'), { recursive: true });
+      const service = svc();
+      expect(Object.keys(await named(service))).toEqual(['coding-guidelines']);
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DRAFT })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      expect((await service.listSkills(user)).map((s) => s.name)).toContain('rfi');
+    });
+
+    test("access is judged on the branch, with that branch's rules", async () => {
+      // The same caller, the same skill: readable on the default branch,
+      // denied in the draft's own workspace.
+      const perBranch: IAccessControl = {
+        canRead: async () => true,
+        canReadBatch: async (w: string, _e: string, paths: string[]) =>
+          new Map(paths.map((p) => [p, !(w === draftWsId && p.includes('/rfi/'))])),
+      } as unknown as IAccessControl;
+      const service = svc(perBranch);
+      expect(Object.keys(await named(service))).toEqual(['coding-guidelines']);
+      // Not `forbidden`: a draft skill the caller may not read there is one
+      // they must not learn exists.
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DRAFT })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      expect(await service.getSkill(user, 'rfi', 'scripts/build_xlsx.py', { branch: DRAFT })).toEqual({
+        ok: false,
+        error: 'not_found',
+      });
+      // The released answer is untouched by the draft's rules.
+      expect((await service.listSkills(user)).map((s) => s.name)).toContain('rfi');
+      expect((await service.getSkill(user, 'rfi')).ok).toBe(true);
+    });
+
+    test('a branch that does not exist is a 404 naming it, as on the file tools', async () => {
+      const service = svc();
+      await expect(service.listSkills(user, { branch: 'juan/typo' })).rejects.toMatchObject({
+        status: 404,
+        kind: 'branch-not-found',
+        branch: 'juan/typo',
+        message: 'There is no branch named juan/typo.',
+      });
+      await expect(service.getSkill(user, 'rfi', undefined, { branch: 'juan/typo' })).rejects.toMatchObject({
+        status: 404,
+        kind: 'branch-not-found',
+      });
+    });
+
+    test('naming the default branch answers exactly as naming nothing', async () => {
+      await writeDeck();
+      const service = svc();
+      expect(await service.listSkills(user, { branch: DEFAULT_BRANCH })).toEqual(await service.listSkills(user));
+      expect(await service.getSkill(user, 'rfi', undefined, { branch: DEFAULT_BRANCH })).toEqual(
+        await service.getSkill(user, 'rfi'),
+      );
+    });
+
+    test('a branch read is never cached: the next call sees what the agent just wrote', async () => {
+      const service = svc();
+      expect(Object.keys(await named(service))).not.toContain('make-deck');
+      await writeDeck();
+      // Same instance, no `invalidate()`: the released catalog is cached, a
+      // draft is not.
+      expect(Object.keys(await named(service))).toContain('make-deck');
+    });
+
+    // The `unmerged` verdict compares two folder digests, and the released
+    // side of that comparison is memoized per cached catalog (it used to be
+    // re-hashed once per skill per call). These two pin what the memo may and
+    // may not do.
+    test('the memo never makes a draft stale: an edit on the branch is seen on the next call', async () => {
+      const service = svc();
+      expect((await named(service))['rfi'].unmerged).toBeUndefined();
+      await writeFile(join(draftKb(), 'Plugins', 'rfi', 'scripts', 'build_xlsx.py'), 'print("on the branch")\n');
+      // Same instance, no `invalidate()`: the draft's digests are built per
+      // call along with its catalog, so the agent's own last write shows.
+      expect((await named(service))['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+
+    test('the released digests live and die with the released catalog', async () => {
+      const service = svc();
+      expect((await named(service))['rfi'].unmerged).toBeUndefined();
+      // An asset of the RELEASED copy changes. The catalog caches the file
+      // list, not the contents, so this is visible to a digest the moment one
+      // is taken — and the memo holds the pre-change one for the same TTL the
+      // rest of the released answer is held for.
+      await writeFile(join(root, wsId, KB_DIR, 'Plugins', 'rfi', 'scripts', 'build_xlsx.py'), 'print("released")\n');
+      expect((await named(service))['rfi'].unmerged).toBeUndefined();
+      service.invalidate();
+      expect((await named(service))['rfi']).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+
+    test('the global set (no caller) can be read from a branch too', async () => {
+      await writeDeck();
+      const list = await svc().listSkills(undefined, { branch: DRAFT });
+      expect(list.find((s) => s.name === 'make-deck')).toMatchObject({ unmerged: true, branch: DRAFT });
+    });
+  });
 });

package/src/modules/skills/skill-access-requests.routes.ts

@@ -3,16 +3,12 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import {
-  joinBranchFor,
-  type AuthUser,
-  type IWorkflowService,
-} from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { spliceGrant } from '../access-model/access-splice.js';
+import { folderTarget } from '../access/access-requests.contract.js';
+import { AccessRequestsService } from '../access/access-requests.service.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
-import { isAbsence } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { JoinRequestsService } from '../plugins/join-requests.service.js';
@@ -28,13 +24,11 @@ import type { ISkillService } from './skills.contract.js';
  *
  * Why it exists: linking a skill into a plugin needs write on the skill's
  * rules (the link grants the plugin's principal there), and a plugin manager
- * often has no say over a skill some other scope owns. The request is a plain
- * change request whose branch splices `write: <requester>` into the skill
- * folder's `access.md`; the skill's editors see its proposals and accept
- * through the ordinary grant path, and it retires itself once the default
- * branch carries the grant (`JoinRequestsService`, keyed on the skill FOLDER
- * path rather than a plugin name — the branch-name convention takes any
- * exact string).
+ * often has no say over a skill some other scope owns. The request is opened
+ * by the shared `AccessRequestsService` — the same one the Manage access
+ * dialog's Request access uses — keyed on the skill FOLDER path, so this
+ * button and a Can edit request on that same folder are ONE request, shown in
+ * the skill page's banner and in the folder's dialog alike.
  *
  * Fail-closed like the skill catalog: a skill the caller cannot read answers
  * as unknown, and the editors' listing answers `[]` to anyone else.
@@ -49,10 +43,18 @@ export function createSkillAccessRequestRoutes(deps: {
   resolveUser: (req: express.Request) => Promise<AuthUser | null>;
 }): express.Router {
   const { skillService, accessControl, workflow, workspaceService, joinRequests, kb, resolveUser } = deps;
-  const { kbDirName } = kb;
   const router = express.Router();
   const wsId = () => kb.defaultWorkspaceId();
   const rulesOf = (folder: string) => `${folder}/access.md`;
+  // The same opener the Manage access dialog uses, pointed at a skill's
+  // folder. Keyed on that folder's PATH, which is what makes this button and
+  // a Can edit request on the same folder one request rather than two.
+  const requests = new AccessRequestsService({
+    workflow,
+    workspaceService,
+    lifecycle: joinRequests,
+    kb,
+  });
 
   /** The skill the caller may read, by name — or null after answering 404. */
   async function readableSkill(
@@ -82,65 +84,13 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(409).json({ error: 'You can already edit this skill', kind: 'already-writable' });
         return;
       }
-      const branch = joinBranchFor(user.email, folder);
-      // FRESH: a repeated click must find the request the previous one opened,
-      // and the cached listing can trail it — a miss here would send the
-      // retry into a duplicate refusal.
-      const existing = (await workflow.listChangeRequestsAuthoredBy(user.email, { fresh: true })).find(
-        (cr) => cr.state === 'open' && cr.branch === branch,
-      );
-      if (existing) {
-        res.json({ ok: true, number: existing.number });
-        return;
-      }
-      // The branch may already exist (a request listed as closed, a retry
-      // after a failed open). Existence is PROBED, before and — if creation
-      // fails — after: the race shows up as "already exists" locally or as a
-      // rejected push when origin got there first, and a message is not a
-      // contract. A branch that is there is proceeded against; anything else
-      // is a real failure, and a proposal on a branch that was not made would
-      // be worse than the error. STRICT: the list proves absence, and a
-      // listing that could not fetch proves nothing — it throws instead of
-      // serving refs from before the branch was made (or deleted).
-      const branchExists = async () =>
-        (await workflow.listBranches(wsId(), { freshFetch: true, strictFetch: true })).some(
-          (b) => b.name === branch,
-        );
-      if (!(await branchExists())) {
-        try {
-          await workflow.createBranch(wsId(), branch, kb.defaultBranch);
-        } catch (err) {
-          if (!(await branchExists())) throw err;
-        }
-      }
-      const ws = await workspaceService.getOrCreateForBranch(branch);
-      const accessPath = `${kbDirName}/${rulesOf(folder)}`;
-      // Only a PROVEN absence reads as "no rules yet": any other failure must
-      // not be turned into an empty file that a splice then overwrites.
-      const current = await workspaceService.readFile(ws.id, accessPath).catch((err: unknown) => {
-        if (!isAbsence(err)) throw err;
-        return '';
-      });
-      const spliced = spliceGrant(
-        current,
-        'write',
-        { kind: 'user', email: user.email, displayName: user.name },
-        { target: 'folder' },
-      );
-      if (spliced.changed) {
-        await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-        await workflow.commitChanges(ws.id, user, `Request write access to ${name}`);
-      }
-      const detail = await workflow.openChangeRequest(ws.id, user, {
-        sourceBranch: branch,
-        targetBranch: kb.defaultBranch,
-        title: `Access request: ${name}`,
-        description:
-          `${user.name} asked to edit the skill ${name}. An editor of the skill accepts by ` +
-          `granting the access this branch proposes; the request closes itself once ` +
-          `every proposal has landed.`,
+      const { number } = await requests.open({
+        user,
+        target: folderTarget(folder),
+        itemName: name,
+        level: 'write',
       });
-      res.json({ ok: true, number: detail.number });
+      res.json({ ok: true, number });
     } catch (err) {
       if (err instanceof WorkflowDomainError) {
         res.status(err.status).json(domainErrorBody(err));
@@ -171,7 +121,7 @@ export function createSkillAccessRequestRoutes(deps: {
       const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
-      res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
+      res.json({ requests: await joinRequests.list(ctx.folder, folderTarget(ctx.folder), crs, ctx.user) });
     } catch (err) {
       log.error('failed to list access requests:', { err });
       res.status(500).json({ error: 'Failed to list access requests' });
@@ -192,7 +142,7 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(ctx.folder, ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(ctx.folder, folderTarget(ctx.folder), cr, ctx.user) });
     } catch (err) {
       log.error('failed to reconcile an access request:', { err });
       res.status(500).json({ error: 'Failed to reconcile the request' });