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

package/src/modules/tool-registry/guide-first.ts

@@ -0,0 +1,34 @@
+import type { UtcpTool } from './tool.contract.js';
+
+/** The one tool that returns the platform's guide (see `modules/agent-guide`). */
+export const GET_AGENT_GUIDE_TOOL = 'get_agent_guide';
+
+/**
+ * The sentence every tool of the platform's own OPENS with: what to do before
+ * anything else here. At the front, not the end, because clients cut a long
+ * description from the end and the one instruction that must survive is this
+ * one. The guide's own tool is the one that does not carry it — it IS what
+ * the sentence points at.
+ */
+export const GUIDE_FIRST_SENTENCE = `Call \`${GET_AGENT_GUIDE_TOOL}\` first and read the platform's guide before anything else here.`;
+
+/**
+ * `description` as a client is handed it: the sentence ahead of it, once. A
+ * description that already opens with the sentence is returned as it is, and
+ * an absent or empty one becomes the sentence alone. The ONE place the
+ * sentence is put in front of a description — the registry for the tools it
+ * lists, the MCP service for the meta-tools it builds itself — so the two
+ * cannot drift apart on what "once" means.
+ */
+export function guideFirstDescription(description: string | undefined): string {
+  const own = description ?? '';
+  if (own.startsWith(GUIDE_FIRST_SENTENCE)) return own;
+  return own ? `${GUIDE_FIRST_SENTENCE} ${own}` : GUIDE_FIRST_SENTENCE;
+}
+
+/** `tool` as the catalog lists it: the sentence ahead of its own description, except on the guide's own tool. */
+export function withGuideFirst(tool: UtcpTool): UtcpTool {
+  if (tool.name === GET_AGENT_GUIDE_TOOL) return tool;
+  const description = guideFirstDescription(tool.description);
+  return description === tool.description ? tool : { ...tool, description };
+}

package/src/modules/tool-registry/tool-registry.ts

@@ -5,6 +5,7 @@ import type {
   ToolProvider,
   UtcpTool,
 } from './tool.contract.js';
+import { withGuideFirst } from './guide-first.js';
 
 /**
  * The tool catalog. Modules call `registerExternalTool` / `registerInternalTool`
@@ -13,6 +14,12 @@ import type {
  * catalog only aggregates and lists them — the two manual endpoints serialize
  * each list per request. Insertion order is preserved (static tools first, then
  * provider-built ones); a duplicate static name within a surface throws.
+ *
+ * Every listed tool but the guide's own (`get_agent_guide`, which is what the
+ * sentence points at) opens with the one sentence saying what to do before
+ * any of them (`guide-first.ts`): applied here, at the one place both
+ * surfaces list from, so no module that registers a tool has to remember it
+ * and no surface can serve a tool without it.
  */
 export class ToolRegistry implements IToolRegistry {
   private readonly external = new Map<string, UtcpTool>();
@@ -37,13 +44,13 @@ export class ToolRegistry implements IToolRegistry {
 
   async listExternal(ctx: ToolManualContext = {}): Promise<UtcpTool[]> {
     const dynamic = await Promise.all(this.externalProviders.map((p) => p(ctx)));
-    return [...this.external.values(), ...dynamic];
+    return [...this.external.values(), ...dynamic].map(withGuideFirst);
   }
 
   async listInternal(ctx: ToolManualContext = {}): Promise<UtcpTool[]> {
     const dynamic = await Promise.all(this.internalProviders.map((p) => p(ctx)));
     const lists = await Promise.all(this.internalListProviders.map((p) => p(ctx)));
-    return [...this.internal.values(), ...dynamic, ...lists.flat()];
+    return [...this.internal.values(), ...dynamic, ...lists.flat()].map(withGuideFirst);
   }
 
   private add(into: Map<string, UtcpTool>, tool: UtcpTool, surface: string): void {

package/src/modules/workflow/__tests__/apply-failure.test.ts

@@ -954,7 +954,12 @@ describe('PullRequestService — a recorded or cleared refusal reaches cached li
         ensureRemotesFetched: async () => undefined,
       } as unknown as WorkspaceService,
       {} as unknown as IAccessControl,
-      { changedPathsForPr: async () => ['Plugins/x/SKILL.md'] } as unknown as GitService,
+      {
+        changedPathsAndPairsForPr: async () => ({
+          paths: ['Plugins/x/SKILL.md'],
+          pairs: [{ path: 'Plugins/x/SKILL.md' }],
+        }),
+      } as unknown as GitService,
     );
 
     expect((await svc.listOpenPrs())[0]!.lastApplyFailure).toBeNull();