@bevel-software/platform-core-backend 0.22.0 → 0.24.0

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

@@ -3,6 +3,7 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
 import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { parseDocument } from 'yaml';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
@@ -13,6 +14,7 @@ import { TtlCache } from '../../shared/ttl-cache.js';
 import type {
   GetSkillOptions,
   ISkillService,
+  ListSkillsOptions,
   GetSkillResult,
   Skill,
   SkillHistorySource,
@@ -37,12 +39,43 @@ interface ParsedSkill {
 }
 
 /**
- * Reads skills from the DEFAULT-branch workspace (never the caller's branch), so
- * the catalog is one global, released set. Results are cached briefly and on a
- * merge to default the cache should be dropped via `invalidate()`.
+ * One branch's skills and where they were read from. The workspace rides along
+ * because every later question — may this caller read the skill, what does its
+ * folder contain, what is in its history — has to be asked of the SAME clone
+ * the skills were scanned out of, never of whichever branch happens to be the
+ * default.
+ */
+interface Catalog {
+  wsId: string;
+  /** Absolute path of that workspace's KB clone; empty when there was none to read. */
+  kbRoot: string;
+  skills: ParsedSkill[];
+  /**
+   * Folder digests computed out of THIS catalog's clone, by skill folder —
+   * filled lazily by `digestOf`, so it lives exactly as long as the catalog
+   * does. On the released catalog that is the cache's TTL (and a merge to
+   * default drops both together); on a branch catalog, which is never cached,
+   * it is one call.
+   */
+  digests: Map<string, Promise<string | null>>;
+}
+
+/**
+ * Reads skills from the DEFAULT-branch workspace, so the catalog is one global,
+ * released set. Results are cached briefly and on a merge to default the cache
+ * should be dropped via `invalidate()`.
+ *
+ * A caller may instead NAME a branch (`branch` on either method) and read the
+ * skills as they are on that draft — what an agent needs to try a skill it has
+ * just written, before anyone has approved it. That read is deliberately
+ * austere: no cache (the draft changes under the agent's own hands), access
+ * judged in that branch's own clone with that branch's rules, a 404 for a
+ * branch nobody pushed, and everything the default branch does not already
+ * serve marked `unmerged` — with one line at the top of a body saying it is
+ * not approved.
  */
 export class SkillService implements ISkillService {
-  private readonly cache: TtlCache<ParsedSkill[]>;
+  private readonly cache: TtlCache<Catalog>;
   /**
    * Where a `version` is read from — git, attached by the composition root
    * once the git service exists (it is built after this one). Without it a
@@ -73,16 +106,21 @@ export class SkillService implements ISkillService {
     this.cache.invalidate();
   }
 
-  async listSkills(userEmail?: string): Promise<SkillSummary[]> {
-    const skills = await this.scan();
-    const summaries = skills.map((s) => s.summary);
-    if (!userEmail) return summaries;
-    const allowed = await this.readable(userEmail, summaries.map((s) => s.path));
-    // Fail closed: keep a skill only on an explicit `true` verdict — a missing
-    // entry counts as denied, matching the KB's default-deny read model (and the
-    // tool-manuals catalog). `!== false` would silently EXPOSE a skill any time
-    // the checker skips a path.
-    return summaries.filter((s) => allowed.get(`${s.path}/SKILL.md`) === true);
+  async listSkills(userEmail?: string, options: ListSkillsOptions = {}): Promise<SkillSummary[]> {
+    const { catalog, branch } = await this.catalogFor(options.branch);
+    const visible = userEmail ? await this.readableSkills(catalog, userEmail) : catalog.skills;
+    if (branch === undefined) return visible.map((s) => s.summary);
+    // Marking reads both copies of a folder, so it happens only here, on a
+    // branch read that asked for it — the released catalog every other surface
+    // takes never pays for it. The released catalog is resolved ONCE for the
+    // whole listing: per skill, a cold cache would start one scan of the
+    // default branch per skill.
+    const released = await this.defaultCatalog();
+    return Promise.all(
+      visible.map(async (s) =>
+        (await this.differs(released, catalog, s)) ? { ...s.summary, unmerged: true as const, branch } : s.summary,
+      ),
+    );
   }
 
   async getSkill(
@@ -92,10 +130,12 @@ export class SkillService implements ISkillService {
     options: GetSkillOptions = {},
   ): Promise<GetSkillResult> {
     if (!isSafeSkillName(name)) return { ok: false, error: 'not_found' };
-    const found = (await this.scan()).find((s) => s.summary.name === name);
+    const { catalog, branch } = await this.catalogFor(options.branch);
+    const found = catalog.skills.find((s) => s.summary.name === name);
+    // A skill the branch deleted is not a skill as far as this answer goes:
+    // the same `not_found` a name nobody ever used gets.
     if (!found) return { ok: false, error: 'not_found' };
 
-    const wsId = this.kb.defaultWorkspaceId();
     // Through `readable`, not a bare `canRead`: the two gates must never
     // disagree. `canRead` reads a file's own frontmatter rules off disk on
     // every call while `canReadBatch` resolves them through a per-workspace
@@ -109,19 +149,51 @@ export class SkillService implements ISkillService {
     // rules would be authorized against the previous verdict until the memo
     // expires. It is not: `registerCatalogCacheInvalidation` drops the gate on
     // the same default-branch signal that drops this catalog, so the listing
-    // and the load are refreshed by one event or by neither.
-    const allowed = await this.readable(userEmail, [found.summary.path]);
+    // and the load are refreshed by one event or by neither. A branch read
+    // caches no catalog of its own, so the same pair of gates still answers
+    // for it — in that branch's workspace, where its own rules live.
+    const allowed = await this.readable(catalog.wsId, userEmail, [found.summary.path]);
     if (allowed.get(`${found.summary.path}/SKILL.md`) !== true) {
-      return { ok: false, error: 'forbidden' };
+      // On the default branch: `forbidden` — the skill is released, everyone
+      // knows the catalog has it, and naming the refusal is what sends the
+      // caller to ask for access.
+      //
+      // On a draft: the same answer a name nobody ever used gets. A skill
+      // being written on a branch the caller cannot read there is one they
+      // must not learn exists either, and the listing already hides it — a
+      // load that answered `forbidden` would confirm it by the back door.
+      return { ok: false, error: branch === undefined ? 'forbidden' : 'not_found' };
     }
 
+    const result = await this.serve(catalog, found, name, file, options.version);
+    if (branch === undefined || !result.ok) return result;
+    // The mark and the line say "nobody approved this", so they go on exactly
+    // what the default branch does not already serve. A skill the branch never
+    // touched IS the released one — read through a draft's clone, but the same
+    // bytes — and claiming otherwise would teach agents to ignore the warning.
+    if (!(await this.differs(await this.defaultCatalog(), catalog, found))) return result;
+    return asUnmerged(result, branch);
+  }
+
+  /**
+   * The skill (or the one bundled file, or the copy a `version` names) out of
+   * the catalog it was found in. Everything the caller is allowed to see has
+   * been settled by `getSkill`; this only reads.
+   */
+  private async serve(
+    catalog: Catalog,
+    found: ParsedSkill,
+    name: string,
+    file: string | undefined,
+    version: string | undefined,
+  ): Promise<GetSkillResult> {
     // A version other than the one on disk now is read out of history —
     // after the access check above, which is the caller's access to the skill
     // as it is now. The version on disk IS the latest, whatever it is called,
     // so asking for it by name answers from disk like asking for nothing.
-    const wanted = options.version?.trim();
+    const wanted = version?.trim();
     if (wanted !== undefined && wanted.length > 0 && wanted !== found.summary.version) {
-      return this.getSkillAtVersion(wsId, found, name, wanted, file);
+      return this.getSkillAtVersion(catalog.wsId, found, name, wanted, file);
     }
 
     if (file !== undefined) {
@@ -131,7 +203,7 @@ export class SkillService implements ISkillService {
       // the ignore rules, so a path that is not in it is one they hid.
       if (!found.files.includes(repoPath)) return { ok: false, error: 'not_found' };
       try {
-        const content = await this.workspaceService.readFile(wsId, `${this.kbDirName}/${repoPath}`);
+        const content = await this.workspaceService.readFile(catalog.wsId, `${this.kbDirName}/${repoPath}`);
         return { ok: true, kind: 'file', file: { name, file, path: repoPath, content } };
       } catch {
         return { ok: false, error: 'not_found' };
@@ -150,8 +222,9 @@ export class SkillService implements ISkillService {
   // --- internal ---------------------------------------------------------------
 
   /**
-   * The skill as it was at the most recent default-branch commit whose
-   * `SKILL.md` declared `wanted` — walking that file's history newest first,
+   * The skill as it was at the most recent commit of `wsId`'s clone whose
+   * `SKILL.md` declared `wanted` — the default branch's history, or a named
+   * branch's own — walking that file's history newest first,
    * so a version that was published, superseded and republished answers with
    * its latest copy. Every version the walk met is collected on the way, so
    * a miss can say what there is to ask for.
@@ -213,40 +286,150 @@ export class SkillService implements ISkillService {
    * The ONE read gate both surfaces resolve through, keyed by each skill's
    * `SKILL.md`. Shared so `listSkills` and `getSkill` can only ever give the
    * same verdict about the same skill — see the note at the `getSkill` call.
+   *
+   * `wsId` is the workspace the skills were READ from, so a branch's answer is
+   * judged by the `roles.yaml`, groups and `access.md` tree that branch has —
+   * which is the point: a draft may be where a skill's access rules are being
+   * changed, and judging it by the default branch's rules would answer about a
+   * tree the caller is not reading.
    */
-  private async readable(userEmail: string, skillFolders: string[]): Promise<Map<string, boolean>> {
-    return this.accessControl.canReadBatch(
-      this.kb.defaultWorkspaceId(),
-      userEmail,
-      skillFolders.map((p) => `${p}/SKILL.md`),
-    );
+  private async readable(
+    wsId: string,
+    userEmail: string,
+    skillFolders: string[],
+  ): Promise<Map<string, boolean>> {
+    return this.accessControl.canReadBatch(wsId, userEmail, skillFolders.map((p) => `${p}/SKILL.md`));
+  }
+
+  /** The skills of `catalog` this caller may read, by the gate above. */
+  private async readableSkills(catalog: Catalog, userEmail: string): Promise<ParsedSkill[]> {
+    const allowed = await this.readable(catalog.wsId, userEmail, catalog.skills.map((s) => s.summary.path));
+    // Fail closed: keep a skill only on an explicit `true` verdict — a missing
+    // entry counts as denied, matching the KB's default-deny read model (and the
+    // tool-manuals catalog). `!== false` would silently EXPOSE a skill any time
+    // the checker skips a path.
+    return catalog.skills.filter((s) => allowed.get(`${s.summary.path}/SKILL.md`) === true);
   }
 
-  private async scan(): Promise<ParsedSkill[]> {
+  /**
+   * The catalog an answer comes out of, and the branch to MARK it with —
+   * `branch` undefined when the answer is the released one, so every surface
+   * that names no branch is answered exactly as it was before this input
+   * existed.
+   */
+  private async catalogFor(branch?: string): Promise<{ catalog: Catalog; branch?: string }> {
+    const named = branch?.trim();
+    // A blank branch is a missing one, and the safe reading of a missing
+    // branch is the released catalog: it serves only approved skills. A name
+    // that is REAL but unknown is not reinterpreted that way — it is the 404
+    // `readBranch` lets through. Naming the default branch is the same answer
+    // as naming nothing, mark included: there is nothing unmerged about it.
+    if (!named || named === this.kb.defaultBranch) return { catalog: await this.defaultCatalog() };
+    return { catalog: await this.readBranch(named), branch: named };
+  }
+
+  private async defaultCatalog(): Promise<Catalog> {
     const cached = this.cache.get();
     if (cached) return cached;
-    // Token first: a merge's `invalidate()` can land while `scanDisk` is still
+    // Token first: a merge's `invalidate()` can land while the scan is still
     // reading the pre-merge tree, and storing that read afterwards would undo
     // the drop for a full TTL.
     const token = this.cache.begin();
-    const skills = await this.scanDisk();
-    this.cache.set(skills, token);
-    return skills;
+    const catalog = await this.readDefault();
+    this.cache.set(catalog, token);
+    return catalog;
   }
 
-  private async scanDisk(): Promise<ParsedSkill[]> {
-    // Ensure the default-branch clone exists, then scan its Skills/ and
-    // Plugins/ roots. Any failure (no workspace, no such dir) degrades to an
-    // empty catalog — the manual/tools must never break because skills can't
-    // be read.
+  /**
+   * The default branch's catalog. A workspace that cannot be resolved degrades
+   * to an empty one — the manual/tools must never break because skills can't
+   * be read. A NAMED branch does not degrade: see `readBranch`.
+   */
+  private async readDefault(): Promise<Catalog> {
     let wsId: string;
     try {
       wsId = (await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch)).id;
     } catch {
-      return [];
+      return { wsId: this.kb.defaultWorkspaceId(), kbRoot: '', skills: [], digests: new Map() };
     }
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+    return { wsId, kbRoot, skills: await this.scanTree(kbRoot), digests: new Map() };
+  }
+
+  /**
+   * One branch's clone, scanned. Deliberately NOT cached and deliberately NOT
+   * degraded:
+   *  - no cache, because the caller of a branch read is usually the agent that
+   *    just wrote the skill, and a minute-old answer would hide its own work;
+   *  - no degrading, because a branch nobody ever pushed must answer the 404
+   *    the file tools answer (`BranchNotFoundError`, naming the branch) — an
+   *    empty list would read as "that branch has no skills", which is a
+   *    different and untrue statement.
+   *
+   * Resolving the workspace clones the branch on first use, so a call naming a
+   * branch for the first time waits for a clone.
+   */
+  private async readBranch(branch: string): Promise<Catalog> {
+    const wsId = (await this.workspaceService.getOrCreateForBranch(branch)).id;
+    const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
+    return { wsId, kbRoot, skills: await this.scanTree(kbRoot), digests: new Map() };
+  }
+
+  /**
+   * Does this skill, as the branch has it, differ from the `released` copy —
+   * by the content of its FOLDER? It is absent from the released catalog (or
+   * listed there at another path), or one of the files the two catalogs list
+   * for it differs byte for byte.
+   *
+   * Reading both folders is the price of saying something true, and it is paid
+   * only on a branch read: a skill folder is instructions plus a few assets.
+   * A file that cannot be read on either side counts as a difference — unable
+   * to prove the branch's copy is the released one, the honest answer is that
+   * it is not approved.
+   *
+   * Both sides go through `digestOf`, so the RELEASED side is read once per
+   * cached catalog rather than once per skill per call: a listing of N skills
+   * used to re-hash all N released folders on every call, and each `getSkill`
+   * re-hashed one of them again.
+   */
+  private async differs(released: Catalog, branchCatalog: Catalog, skill: ParsedSkill): Promise<boolean> {
+    const mirror = released.skills.find((s) => s.summary.name === skill.summary.name);
+    if (!mirror || mirror.summary.path !== skill.summary.path) return true;
+    const [onBranch, onDefault] = await Promise.all([
+      this.digestOf(branchCatalog, skill),
+      this.digestOf(released, mirror),
+    ]);
+    return onBranch === null || onDefault === null || onBranch !== onDefault;
+  }
+
+  /**
+   * One skill folder's digest in one catalog's clone, computed at most once
+   * for that catalog. The folder path is a unique key within a catalog — a
+   * folder holds one `SKILL.md`, so it yields one skill — and the file list
+   * the digest covers comes from that same catalog's scan.
+   *
+   * Memoizing means a released folder's ASSETS are now as stale as the rest
+   * of the catalog that names them: both are refreshed by the TTL and dropped
+   * together by `invalidate()` on a merge to the default branch. A branch
+   * catalog is built per call and so is its memo, which is what a draft read
+   * needs — the agent's own last write must show.
+   */
+  private digestOf(catalog: Catalog, skill: ParsedSkill): Promise<string | null> {
+    const key = skill.summary.path;
+    const memo = catalog.digests.get(key);
+    if (memo) return memo;
+    // The promise, not the value: skills asked for at once share one read.
+    // A rejection is dropped rather than kept — `folderDigest` answers `null`
+    // for a file it cannot read, so a throw here is a defect, and holding it
+    // would answer with it for the catalog's whole life.
+    const pending = folderDigest(catalog.kbRoot, skill);
+    catalog.digests.set(key, pending);
+    pending.catch(() => catalog.digests.delete(key));
+    return pending;
+  }
 
+  /** Scan one clone's `Skills/` and `Plugins/` roots into a catalog's skills. */
+  private async scanTree(kbRoot: string): Promise<ParsedSkill[]> {
     // Skills may be grouped in category subfolders (each carrying its own
     // access.md), so a SKILL.md can live at any depth under either root. Walk
     // the tree and treat every folder that directly contains a SKILL.md as a
@@ -344,6 +527,60 @@ export class SkillService implements ISkillService {
 
 // --- helpers ------------------------------------------------------------------
 
+/**
+ * The one line a skill read from an unmerged branch begins with. Exported
+ * because the tool surface documents it and the tests assert it: there is one
+ * sentence, in one place, and an agent that has read it once recognises it.
+ */
+export function unmergedSkillNotice(branch: string): string {
+  return `This skill is read from the unmerged branch "${branch}" and is not approved.`;
+}
+
+/**
+ * Say, on the answer itself, that it came off a branch that changed this skill.
+ *
+ * The body gets the line because the body is what an agent reads and acts on;
+ * a bundled file gets the flags beside its content, never a sentence inside it
+ * (prepending prose to a script is a syntax error, not a warning).
+ */
+function asUnmerged(result: Extract<GetSkillResult, { ok: true }>, branch: string): GetSkillResult {
+  if (result.kind === 'file') {
+    return { ...result, file: { ...result.file, unmerged: true, branch } };
+  }
+  return {
+    ...result,
+    skill: {
+      ...result.skill,
+      unmerged: true,
+      branch,
+      body: `${unmergedSkillNotice(branch)}\n\n${result.skill.body}`,
+    },
+  };
+}
+
+/**
+ * A digest of a skill folder as its own catalog lists it: `SKILL.md` plus
+ * every bundled file, each hashed under its relative name so a renamed,
+ * added or dropped asset is a difference too — and so a file one branch's
+ * ignore rules hide is one as well. `null` when a listed file cannot be read,
+ * which the caller treats as "cannot prove it is the released copy".
+ */
+async function folderDigest(kbRoot: string, skill: ParsedSkill): Promise<string | null> {
+  if (!kbRoot) return null;
+  const folder = skill.summary.path;
+  const rels = ['SKILL.md', ...skill.files.map((f) => f.slice(folder.length + 1))].sort();
+  const hash = createHash('sha256');
+  for (const rel of rels) {
+    hash.update(`${rel}\0`);
+    try {
+      hash.update(await fs.readFile(path.join(kbRoot, folder, ...rel.split('/'))));
+    } catch {
+      return null;
+    }
+  }
+  return hash.digest('hex');
+}
+
 /**
  * Skill names are folder names; reject anything that could escape the folder.
  *

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

@@ -1,11 +1,25 @@
 import type { Router, RequestHandler } from 'express';
 import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
-import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import { ToolError, type ToolContext } 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 { ISkillService } from './skills.contract.js';
 import type { IAllowedToolsChecker } from './allowed-tools-check.js';
 
+/**
+ * The optional `branch` both skill tools declare. Optional on purpose, unlike
+ * the required `branch` of the KB file tools: a skill read is answered by the
+ * released catalog by default, and naming a branch is the caller asking for
+ * something nobody has approved yet.
+ */
+const BRANCH_SKILLS_INPUT = {
+  type: 'string' as const,
+  description:
+    'Optional: a draft branch to read the skills from instead of the released (default) branch — ' +
+    'the branch you are working on. You must be able to read the branch and the skill on it; ' +
+    'a branch that does not exist answers 404 naming it. Omit it for the approved skills.',
+};
+
 /**
  * Registers the two skill tools (both surfaces) and hosts their endpoints.
  *
@@ -14,6 +28,13 @@ import type { IAllowedToolsChecker } from './allowed-tools-check.js';
  * what exists right in the tool catalog, no `list_skills` round-trip needed, and
  * it auto-updates as the default-branch catalog changes. The hosted routes are
  * static; only the description text is dynamic.
+ *
+ * Both tools take an optional `branch`. Without it they answer from the
+ * released (default-branch) catalog — what the descriptions name, what the
+ * browser menu lists and what the MCP prompt surface serves. With it they read
+ * the skills as they are on that draft and say which of them nobody has
+ * approved, so an agent can try the skill it just wrote without waiting for a
+ * merge.
  */
 export function registerSkillsTools(
   registry: IToolRegistry,
@@ -32,8 +53,8 @@ export function registerSkillsTools(
   router.post(
     '/agent/tools/list_skills',
     toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => ({
-      skills: await skillService.listSkills(ctx.user.email),
+    toolHandler(async (args, ctx: ToolContext) => ({
+      skills: await skillService.listSkills(ctx.user.email, { branch: branchArg(args) }),
     })),
   );
 
@@ -44,14 +65,38 @@ export function registerSkillsTools(
       const name = typeof args.name === 'string' ? args.name : '';
       const file = typeof args.file === 'string' ? args.file : undefined;
       const version = typeof args.version === 'string' ? args.version : undefined;
+      const branch = branchArg(args);
       if (!name) return { error: 'missing_name' };
-      const result = await skillService.getSkill(ctx.user.email, name, file, { version });
+      // Refused rather than ranked: a `version` is a point in the released
+      // 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) {
+        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.',
+          400,
+        );
+      }
+      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) };
     }),
   );
 }
 
+/**
+ * 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
+ * as absent, which answers from the default branch — the approved one. The
+ * resolution of a real name, and the 404 for one the platform never heard of,
+ * belong to the workspace layer, exactly as on the file tools.
+ */
+function branchArg(args: Record<string, unknown>): string | undefined {
+  const branch = args.branch;
+  return typeof branch === 'string' && branch.trim().length > 0 ? branch : undefined;
+}
+
 /** "Currently available skills: `a`, `b`." (or a no-skills note), filtered to what the caller may read. */
 async function availableSkillsLine(skillService: ISkillService, userEmail?: string): Promise<string> {
   const skills = await skillService.listSkills(userEmail);
@@ -67,9 +112,16 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
       'for a skill that declares one, its current `version` (its SKILL.md `metadata.version`, else a ' +
       'top-level `version`, else `lifecycle.version`). ' +
       '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. ' +
       (await availableSkillsLine(skillService, userEmail)),
     path: '/api/agent/tools/list_skills',
-    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    inputs: {
+      type: 'object',
+      properties: { branch: BRANCH_SKILLS_INPUT },
+      additionalProperties: false,
+    },
     outputs: {
       type: 'object',
       properties: {
@@ -88,6 +140,13 @@ async function buildListSkillsDef(skillService: ISkillService, userEmail?: strin
                   'else `lifecycle.version` in its SKILL.md); absent when it declares none.',
               },
               path: { type: 'string' },
+              unmerged: {
+                type: 'boolean',
+                description:
+                  'Only when `branch` was passed, and only on a skill that differs from the released one ' +
+                  '(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.' },
             },
           },
         },
@@ -104,7 +163,7 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
       '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. ' +
+      'one the skill declared, or `branch` names a draft to load it from. ' +
       (await availableSkillsLine(skillService, userEmail)),
     path: '/api/agent/tools/get_skill',
     inputs: {
@@ -126,6 +185,7 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
             'recent commit that declared that version; a version the skill never declared answers ' +
             '`version_not_found` with the versions it did declare.',
         },
+        branch: BRANCH_SKILLS_INPUT,
       },
       required: ['name'],
       additionalProperties: false,
@@ -134,8 +194,20 @@ async function buildGetSkillDef(skillService: ISkillService, userEmail?: string)
       type: 'object',
       description: 'On success carries `skill` (or `file` when `file` was passed); on failure carries `error`.',
       properties: {
-        skill: { type: 'object', description: 'The loaded skill: name, description, body, files, ….' },
-        file: { type: 'object', description: 'A bundled file: name, file, path, content.' },
+        skill: {
+          type: 'object',
+          description:
+            '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.',
+        },
+        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).',
+        },
         warnings: {
           type: 'array',
           description:

package/src/modules/tool-auth/__tests__/manual-auth.middleware.test.ts

@@ -8,6 +8,7 @@ import { InternalTokenService } from '../internal-token.service.js';
 import { createManualAuthMiddleware } from '../tool-auth.middleware.js';
 import type { IExternalApiKeyService } from '../external-api-key.interface.js';
 import type { AuthService } from '../../auth/auth.service.js';
+import { AuthBackendError } from '../../auth/account-admission.js';
 
 /**
  * The manual endpoints (`/agent/utcp`, `/agent/internal/utcp`) accept a browser
@@ -17,6 +18,8 @@ import type { AuthService } from '../../auth/auth.service.js';
  */
 const KEY = 'bevel_validkey';
 const JWT = 'browser-jwt';
+/** A valid session, presented while its account cannot be looked up. */
+const JWT_DURING_OUTAGE = 'browser-jwt-during-outage';
 
 const fakeExternalApiKeys = {
   looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
@@ -25,10 +28,12 @@ const fakeExternalApiKeys = {
 } as unknown as IExternalApiKeyService;
 
 const fakeAuth = {
-  verifyToken: (t: string) => {
+  resolveSession: async (t: string) => {
     if (t === JWT) return { userId: 'u-jwt', email: 'jwt@x' };
+    if (t === JWT_DURING_OUTAGE) throw new AuthBackendError(new Error('the database is down'));
     throw new Error('bad jwt');
   },
+  isActive: async () => true,
 } as unknown as AuthService;
 
 let server: HttpServer | undefined;
@@ -75,6 +80,14 @@ describe('createManualAuthMiddleware (read-only manual endpoints)', () => {
     expect((await get(base, '/api/agent/utcp', 'garbage')).status).toBe(401);
   });
 
+  it('answers 500, not 401, when the session’s account cannot be looked up', async () => {
+    const { base } = await start();
+    const r = await get(base, '/api/agent/utcp', JWT_DURING_OUTAGE);
+    // A 401 would sign a valid caller out over an outage.
+    expect(r.status).toBe(500);
+    expect(r.headers.get('www-authenticate')).toBeNull();
+  });
+
   it('refuses the INTERNAL manual to a browser JWT (403) but allows an internal token', async () => {
     const { base, intToken } = await start();
     expect((await get(base, '/api/agent/internal/utcp', JWT)).status).toBe(403);