@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/dist/modules/tool-manuals/tool-manuals.tools.js

@@ -1,4 +1,5 @@
 import { toolDef } from '../tool-helpers/tool-def.js';
+import { declareRouteTool } from '../tool-helpers/route-tool-schemas.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 /**
  * Registers the tool-manual catalog tools (both surfaces) and hosts their
@@ -14,6 +15,11 @@ import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 export function registerToolManualsTools(registry, router, toolAuth, toolHandler, toolManualService, deps) {
     registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
     registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+    // The def above is built per catalog listing (its description names the
+    // tools configured for THIS caller), so declare the arguments here as well:
+    // a direct REST call that lands before the first listing must be checked
+    // against them too.
+    declareRouteTool('list_local_tools', LIST_LOCAL_TOOLS_INPUTS);
     router.post('/agent/tools/list_local_tools', toolAuth, toolHandler(async (_args, ctx) => ({
         tools: await toolManualService.listLocalOnly(ctx.user.email),
     })));
@@ -26,22 +32,30 @@ export function registerToolManualsTools(registry, router, toolAuth, toolHandler
     const listSetupDef = toolDef({
         name: 'list_tool_setup',
         // What each FIELD means is documented on the field, in `outputs` below:
-        // `setup.kind`, `variables` and `invalid` each carried a paragraph here,
-        // which made this description two thousand characters and so the first
-        // thing a client cut. The description says what the tool answers and the
-        // three things an agent cannot read off a field.
-        description: 'Configuration status of every `.tool` the current user can access: what each tool needs set up and what is ' +
-            'already configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER — a `.tool` it cannot ' +
-            'READ is absent entirely, and every flag is the caller\'s own state. ' +
-            'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool editor, ' +
-            'and users sign in on /connect rather than typing a value. ' +
-            'What gates setting a tool\'s shared secrets is `canWrite` on the `.tool` FILE — per-file access from its ' +
-            'frontmatter `write:`/`owner:` verbs and the access.md chain, NOT a platform role: the people who manage the ' +
-            'file configure the tool. ' +
+        // `setup.kind`, `variables`, `invalid` and `hiddenTools` each carried a
+        // paragraph here, which made this description two thousand characters and
+        // so the first thing a client cut. The description says what the tool
+        // answers and the four things an agent cannot read off a field.
+        //
+        // It sits a few characters under `TOOL_DESCRIPTION_CAP` WITH the guide-first
+        // sentence the registry puts in front of it (`tool-registry/guide-first.ts`)
+        // and the `Call:` line generated ahead of everything,
+        // which is why every sentence here is the short form: the `hiddenTools`
+        // clause and that opener both came out of the same budget, and what a
+        // hidden tool's entry CONTAINS is on the field below rather than here.
+        description: 'Configuration status of every `.tool` the current user can access: what each needs set up and what is ' +
+            'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
+            'READ is absent, and every flag is the caller\'s own. ' +
+            'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool ' +
+            'editor; users sign in on /connect. ' +
+            'Setting a tool\'s shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter ' +
+            '`write:`/`owner:` verbs and the access.md chain), NOT by a platform role: who manages the file configures ' +
+            'the tool. ' +
+            '`hiddenTools` names the tools Hexis hides from agents for an invalid schema. ' +
             'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
-            'draft is not listed, not callable and not signed-in-able until that draft is merged. Pass `branch` (the draft ' +
-            'you wrote the declaration on) and `onBranchOnly` names every tool declared there that the default branch does ' +
-            'not serve yet — open a change request, then ask the user to review and merge it in the app to activate it.',
+            'draft is not listed, callable or signed-in-able until it is merged. Pass `branch` (the draft you wrote the ' +
+            'declaration on) and `onBranchOnly` names every tool declared there that the default branch does not serve ' +
+            'yet — open a change request and ask the user to merge it.',
         path: '/api/agent/tools/list_tool_setup',
         inputs: {
             type: 'object',
@@ -89,6 +103,21 @@ export function registerToolManualsTools(registry, router, toolAuth, toolHandler
                                 type: 'boolean',
                                 description: 'You may write this `.tool` FILE, which is what gates setting its shared secrets.',
                             },
+                            hiddenTools: {
+                                type: 'array',
+                                description: 'Tools of this server kept off every agent surface for an invalid input schema. Empty ' +
+                                    'unless the caller may write this tool.',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        name: { type: 'string', description: 'The name the tool would have been offered under.' },
+                                        path: { type: 'string', description: 'JSON Pointer to the place in the schema that is not valid.' },
+                                        reason: { type: 'string', description: 'Why that place is not valid, in the validator\'s words.' },
+                                        marker: { type: 'string', description: 'The one sentence the tool page shows for this tool.' },
+                                    },
+                                    required: ['name', 'path', 'reason', 'marker'],
+                                },
+                            },
                             variables: {
                                 type: 'array',
                                 description: 'What this tool needs configured, and by whom: per variable, whether the shared (admin) value is ' +
@@ -111,7 +140,7 @@ export function registerToolManualsTools(registry, router, toolAuth, toolHandler
                                 },
                             },
                         },
-                        required: ['slug', 'name', 'path', 'type', 'canWrite', 'variables'],
+                        required: ['slug', 'name', 'path', 'type', 'canWrite', 'hiddenTools', 'variables'],
                     },
                 },
                 invalid: {
@@ -168,27 +197,35 @@ export function registerToolManualsTools(registry, router, toolAuth, toolHandler
         const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
         const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
         const statusByKey = new Map(status.map((s) => [s.key, s]));
-        const tools = await Promise.all(manuals.map(async (m) => ({
-            slug: m.slug,
-            name: m.name,
-            path: m.path,
-            type: m.type,
-            setup: m.setup ?? null,
-            canWrite: await deps.accessControl.canWrite(defaultWs(), ctx.user.email, m.path),
-            variables: (m.variables ?? []).map((v) => {
-                const st = statusByKey.get(varKey(m.name, v.name));
-                const isOAuth = v.oauth != null;
-                return {
-                    name: v.name,
-                    scope: v.scope,
-                    label: v.label ?? null,
-                    oauth: isOAuth,
-                    adminConfigured: st?.adminConfigured ?? false,
-                    userConfigured: st?.userConfigured ?? false,
-                    authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
-                };
-            }),
-        })));
+        const tools = await Promise.all(manuals.map(async (m) => {
+            const canWrite = await deps.accessControl.canWrite(defaultWs(), ctx.user.email, m.path);
+            return {
+                slug: m.slug,
+                name: m.name,
+                path: m.path,
+                type: m.type,
+                setup: m.setup ?? null,
+                canWrite,
+                // The marker goes only to the people who manage the server — the
+                // same verdict that gates setting its shared secrets. A caller who
+                // may only READ the tool is told nothing about it: they cannot fix
+                // the schema, and the tool is simply not among the ones they can call.
+                hiddenTools: canWrite ? (deps.hiddenTools?.hiddenFor(m.name) ?? []) : [],
+                variables: (m.variables ?? []).map((v) => {
+                    const st = statusByKey.get(varKey(m.name, v.name));
+                    const isOAuth = v.oauth != null;
+                    return {
+                        name: v.name,
+                        scope: v.scope,
+                        label: v.label ?? null,
+                        oauth: isOAuth,
+                        adminConfigured: st?.adminConfigured ?? false,
+                        userConfigured: st?.userConfigured ?? false,
+                        authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
+                    };
+                }),
+            };
+        }));
         const onBranchOnly = pending.map((p) => ({ ...p, branch: branch }));
         if (onBranchOnly.length === 0)
             return { tools, invalid, onBranchOnly };
@@ -212,6 +249,8 @@ async function localToolsLine(svc, userEmail) {
         return 'No local-only tools are currently configured.';
     return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
 }
+/** `list_local_tools` takes nothing; a const so the route and the def share one declaration. */
+const LIST_LOCAL_TOOLS_INPUTS = { type: 'object', properties: {}, additionalProperties: false };
 async function buildListLocalToolsDef(svc, userEmail) {
     return toolDef({
         name: 'list_local_tools',
@@ -226,7 +265,7 @@ async function buildListLocalToolsDef(svc, userEmail) {
             'setup by hand. ' +
             (await localToolsLine(svc, userEmail)),
         path: '/api/agent/tools/list_local_tools',
-        inputs: { type: 'object', properties: {}, additionalProperties: false },
+        inputs: LIST_LOCAL_TOOLS_INPUTS,
         outputs: {
             type: 'object',
             properties: {

package/dist/modules/tool-manuals/tool-manuals.tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.tools.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-manuals.tools.js","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.tools.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-registry/description-length.d.ts

@@ -5,9 +5,10 @@
  * where the text specific to the tool sits, after whatever shared preamble it
  * carried. Agents reported `file_stat`, `read_file`, `write_file` and
  * `write_files` arriving ending in "[truncated]". The rules those descriptions
- * shared now live in one place (see `agent-instructions/shared-file-rules.ts`)
- * and each description ends with one sentence pointing there, which is what
- * makes the cap below reachable rather than aspirational.
+ * shared now live in one place (see `agent-instructions/shared-file-rules.ts`,
+ * served in the guide `get_agent_guide` returns) and each description OPENS
+ * with the one sentence sending the agent there (`guide-first.ts`), which is
+ * what makes the cap below reachable rather than aspirational.
  */
 import type { UtcpTool } from './tool.contract.js';
 /**
@@ -20,8 +21,10 @@ import type { UtcpTool } from './tool.contract.js';
  * could answer: no useful description of `move_file` fits in 500. What answers
  * that one is the ORDER of the text, which is why the deployment's purpose line
  * is prepended rather than appended (see `prefixToolDescription`) and why every
- * description now leads with what the tool does and ends with the pointer: a
- * cut at 500 then takes the pointer and leaves the tool. The other cut is the
+ * description now opens with the guide-first sentence and then what the tool
+ * does, with the tool's own detail last: a cut at 500 keeps the sentence and
+ * the tool's first sentence (see `firstSentenceEnd`) and takes the detail,
+ * which the guide states in full anyway. The other cut is the
  * four-figure one agents reported on `file_stat`, `read_file`, `write_file` and
  * `write_files`, and 1,200 sits below it with room to spare.
  *
@@ -51,16 +54,21 @@ export declare const TOOL_DESCRIPTION_CAP = 1200;
  * rather than a comment.
  */
 export declare const CLIENT_SHORT_CUT = 500;
+/** What these measurements read of a tool: its name, its text and the schema its `Call:` line is generated from. */
+export type MeasuredTool = Pick<UtcpTool, 'name' | 'description'> & {
+    inputs?: unknown;
+};
 /**
  * Where the tool's OWN opening sentence ends in the text a client is handed:
- * the purpose prefix counted at its cap, as in {@link clientVisibleLength}, and
- * the pointer not counted at all, since it is the part a short cut is meant to
- * take.
+ * the purpose prefix counted at its cap, as in {@link clientVisibleLength},
+ * and the guide-first sentence every listed tool opens with counted as the
+ * text it is — a client that cuts at 500 must still reach the sentence saying
+ * what the tool does, past that one.
  *
  * A description with no sentence-ending punctuation counts whole — the honest
  * answer for text that never finishes a sentence.
  */
-export declare function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'description'>): number;
+export declare function firstSentenceEnd(tool: MeasuredTool): number;
 /**
  * The length of the description as a CLIENT receives it — which for the four
  * knowledge-base tools includes the deployment's purpose prefix, since the MCP
@@ -69,12 +77,8 @@ export declare function firstSentenceEnd(tool: Pick<UtcpTool, 'name' | 'descript
  * the cap is what an admin may grow their text to without being told, so a
  * description that only fits beside a short prefix does not really fit.
  *
- * The pointer sentence is measured the same way, for the same reason. It ends
- * every file tool's description and its length moves with a DEPLOYMENT SETTING
- * — the guide's file name — so a description measured beside the nine
- * characters of `AGENTS.md` would pass here and arrive cut on a deployment
- * that renamed its guide. Whatever pointer a description actually carries is
- * discounted and charged at {@link SHARED_RULES_POINTER_MAX} instead.
+ * The guide-first sentence every listed tool opens with is already in the
+ * description the registry lists, so it is measured as the text it is.
  */
-export declare function clientVisibleLength(tool: Pick<UtcpTool, 'name' | 'description'>): number;
+export declare function clientVisibleLength(tool: MeasuredTool): number;
 //# sourceMappingURL=description-length.d.ts.map

package/dist/modules/tool-registry/description-length.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"description-length.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-registry/description-length.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC,GAAG,MAAM,CAQrF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC,GAAG,MAAM,CAgBxF"}
+{"version":3,"file":"description-length.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-registry/description-length.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,oHAAoH;AACpH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAkBzF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAa3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAG9D"}

package/dist/modules/tool-registry/description-length.js

@@ -5,13 +5,16 @@
  * where the text specific to the tool sits, after whatever shared preamble it
  * carried. Agents reported `file_stat`, `read_file`, `write_file` and
  * `write_files` arriving ending in "[truncated]". The rules those descriptions
- * shared now live in one place (see `agent-instructions/shared-file-rules.ts`)
- * and each description ends with one sentence pointing there, which is what
- * makes the cap below reachable rather than aspirational.
+ * shared now live in one place (see `agent-instructions/shared-file-rules.ts`,
+ * served in the guide `get_agent_guide` returns) and each description OPENS
+ * with the one sentence sending the agent there (`guide-first.ts`), which is
+ * what makes the cap below reachable rather than aspirational.
  */
+import { callLine, splitCallLine } from '@bevel-software/platform-mcp-core';
 import { TOOL_PREFIX_CAP } from '@bevel-software/platform-shared';
 import { PREFIXED_TOOLS } from '../agent-instructions/compose.js';
-import { SHARED_RULES_POINTER_MAX, sharedRulesPointer } from '../agent-instructions/shared-file-rules.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
+import { GUIDE_FIRST_SENTENCE } from './guide-first.js';
 /**
  * The ceiling on what a client is handed for one tool, enforced by
  * `__tests__/tool-description-length.test.ts`.
@@ -22,8 +25,10 @@ import { SHARED_RULES_POINTER_MAX, sharedRulesPointer } from '../agent-instructi
  * could answer: no useful description of `move_file` fits in 500. What answers
  * that one is the ORDER of the text, which is why the deployment's purpose line
  * is prepended rather than appended (see `prefixToolDescription`) and why every
- * description now leads with what the tool does and ends with the pointer: a
- * cut at 500 then takes the pointer and leaves the tool. The other cut is the
+ * description now opens with the guide-first sentence and then what the tool
+ * does, with the tool's own detail last: a cut at 500 keeps the sentence and
+ * the tool's first sentence (see `firstSentenceEnd`) and takes the detail,
+ * which the guide states in full anyway. The other cut is the
  * four-figure one agents reported on `file_stat`, `read_file`, `write_file` and
  * `write_files`, and 1,200 sits below it with room to spare.
  *
@@ -53,24 +58,45 @@ export const TOOL_DESCRIPTION_CAP = 1_200;
  * rather than a comment.
  */
 export const CLIENT_SHORT_CUT = 500;
+/**
+ * The `Call:` line a client is handed ahead of everything else, and the blank
+ * line after it — counted, because it is part of what a client cuts. Taken
+ * from the description when it already opens with one (a meta-tool is built
+ * with its line), generated from the tool's inputs under the namespace the
+ * hosted endpoint serves otherwise, as mcp-core's `withCallExample` does at
+ * listing time. The rest of the description comes back beside it.
+ */
+function splitServedCallLine(tool) {
+    const { call, rest } = splitCallLine(tool.description ?? '');
+    const line = call ?? callLine(`${EXTERNAL_KB_MANUAL_NAME}.${tool.name}`, tool.inputs);
+    // The blank line after it only when something follows it.
+    const followed = rest !== '' || PREFIXED_TOOLS.has(tool.name);
+    return { callChars: line.length + (followed ? 2 : 0), rest };
+}
 /**
  * Where the tool's OWN opening sentence ends in the text a client is handed:
- * the purpose prefix counted at its cap, as in {@link clientVisibleLength}, and
- * the pointer not counted at all, since it is the part a short cut is meant to
- * take.
+ * the purpose prefix counted at its cap, as in {@link clientVisibleLength},
+ * and the guide-first sentence every listed tool opens with counted as the
+ * text it is — a client that cuts at 500 must still reach the sentence saying
+ * what the tool does, past that one.
  *
  * A description with no sentence-ending punctuation counts whole — the honest
  * answer for text that never finishes a sentence.
  */
 export function firstSentenceEnd(tool) {
-    const prefix = PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0;
-    const description = tool.description ?? '';
+    const { callChars, rest: description } = splitServedCallLine(tool);
+    const prefix = callChars + (PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP + 2 : 0);
     if (description === '')
         return prefix;
-    const pointer = sharedRulesPointer();
-    const own = description.endsWith(pointer) ? description.slice(0, -pointer.length) : description;
+    // The opener and whatever whitespace follows it: `guideFirstDescription`
+    // joins with one space, and leaves a description that already opens with
+    // the sentence as it came — a newline after it is still the opener's.
+    const opener = description.startsWith(GUIDE_FIRST_SENTENCE)
+        ? GUIDE_FIRST_SENTENCE.length + (description.slice(GUIDE_FIRST_SENTENCE.length).match(/^\s*/)?.[0].length ?? 0)
+        : 0;
+    const own = description.slice(opener);
     const firstSentence = own.match(/^[\s\S]*?[.!?](?=\s|$)/)?.[0] ?? own;
-    return prefix + firstSentence.length;
+    return prefix + opener + firstSentence.length;
 }
 /**
  * The length of the description as a CLIENT receives it — which for the four
@@ -80,29 +106,23 @@ export function firstSentenceEnd(tool) {
  * the cap is what an admin may grow their text to without being told, so a
  * description that only fits beside a short prefix does not really fit.
  *
- * The pointer sentence is measured the same way, for the same reason. It ends
- * every file tool's description and its length moves with a DEPLOYMENT SETTING
- * — the guide's file name — so a description measured beside the nine
- * characters of `AGENTS.md` would pass here and arrive cut on a deployment
- * that renamed its guide. Whatever pointer a description actually carries is
- * discounted and charged at {@link SHARED_RULES_POINTER_MAX} instead.
+ * The guide-first sentence every listed tool opens with is already in the
+ * description the registry lists, so it is measured as the text it is.
  */
 export function clientVisibleLength(tool) {
-    const own = tool.description?.length ?? 0;
+    const { callChars, rest } = splitServedCallLine(tool);
+    return callChars + ownVisibleLength(tool.name, rest);
+}
+/** {@link clientVisibleLength} without the `Call:` line: the purpose prefix and the tool's own text. */
+function ownVisibleLength(name, description) {
+    const own = description.length;
     // A prefixed tool with no description of its own is still handed the prefix,
     // and nothing else — `prefixToolDescription` sends the prefix alone, with no
     // blank line after it. Measuring that as zero would under-report the only
     // text the client got.
     if (own === 0)
-        return PREFIXED_TOOLS.has(tool.name) ? TOOL_PREFIX_CAP : 0;
-    // The pointer at its worst case rather than at this layout's: swap the one
-    // it carries for the longest it could be. A description that does not end
-    // with it (`start_session`, the proxied tools) is charged nothing.
-    const pointer = sharedRulesPointer();
-    const atWorstPointer = tool.description.endsWith(pointer)
-        ? own - pointer.length + SHARED_RULES_POINTER_MAX
-        : own;
+        return PREFIXED_TOOLS.has(name) ? TOOL_PREFIX_CAP : 0;
     // `+ 2` for the blank line `prefixToolDescription` puts between the two.
-    return PREFIXED_TOOLS.has(tool.name) ? atWorstPointer + TOOL_PREFIX_CAP + 2 : atWorstPointer;
+    return PREFIXED_TOOLS.has(name) ? own + TOOL_PREFIX_CAP + 2 : own;
 }
 //# sourceMappingURL=description-length.js.map

package/dist/modules/tool-registry/description-length.js.map

@@ -1 +1 @@
-{"version":3,"file":"description-length.js","sourceRoot":"","sources":["../../../src/modules/tool-registry/description-length.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAG1G;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAA4C;IAC3E,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;IAC3C,IAAI,WAAW,KAAK,EAAE;QAAE,OAAO,MAAM,CAAC;IACtC,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;IAChG,MAAM,aAAa,GAAG,GAAG,CAAC,KAAK,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IACtE,OAAO,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA4C;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,uBAAuB;IACvB,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,2EAA2E;IAC3E,0EAA0E;IAC1E,mEAAmE;IACnE,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;IACrC,MAAM,cAAc,GAAG,IAAI,CAAC,WAAY,CAAC,QAAQ,CAAC,OAAO,CAAC;QACxD,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC,MAAM,GAAG,wBAAwB;QACjD,CAAC,CAAC,GAAG,CAAC;IACR,yEAAyE;IACzE,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;AAC/F,CAAC"}
+{"version":3,"file":"description-length.js","sourceRoot":"","sources":["../../../src/modules/tool-registry/description-length.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-registry/guide-first.d.ts

@@ -0,0 +1,27 @@
+import type { UtcpTool } from './tool.contract.js';
+/** The one tool that returns the platform's guide (see `modules/agent-guide`). */
+export declare 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 declare const GUIDE_FIRST_SENTENCE = "Call `get_agent_guide` 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.
+ *
+ * Behind a `Call:` line, never ahead of it: the call example is the first
+ * line of every description (see mcp-core's `withCallExample`), and the
+ * sentence opens what follows it.
+ */
+export declare function guideFirstDescription(description: string | undefined): string;
+/** `tool` as the catalog lists it: the sentence ahead of its own description, except on the guide's own tool. */
+export declare function withGuideFirst(tool: UtcpTool): UtcpTool;
+//# sourceMappingURL=guide-first.d.ts.map

package/dist/modules/tool-registry/guide-first.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-first.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-registry/guide-first.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,0FAAoG,CAAC;AAEtI;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7E;AAED,iHAAiH;AACjH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAIvD"}

package/dist/modules/tool-registry/guide-first.js

@@ -0,0 +1,40 @@
+import { splitCallLine } from '@bevel-software/platform-mcp-core';
+/** 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.
+ *
+ * Behind a `Call:` line, never ahead of it: the call example is the first
+ * line of every description (see mcp-core's `withCallExample`), and the
+ * sentence opens what follows it.
+ */
+export function guideFirstDescription(description) {
+    const { call, rest } = splitCallLine(description ?? '');
+    if (call !== null)
+        return `${call}\n\n${guideFirstDescription(rest)}`;
+    const own = rest;
+    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) {
+    if (tool.name === GET_AGENT_GUIDE_TOOL)
+        return tool;
+    const description = guideFirstDescription(tool.description);
+    return description === tool.description ? tool : { ...tool, description };
+}
+//# sourceMappingURL=guide-first.js.map

package/dist/modules/tool-registry/guide-first.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-first.js","sourceRoot":"","sources":["../../../src/modules/tool-registry/guide-first.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAGlE,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,oBAAoB,mEAAmE,CAAC;AAEtI;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAA+B;IACnE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACxD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,GAAG,IAAI,OAAO,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC;IACjB,IAAI,GAAG,CAAC,UAAU,CAAC,oBAAoB,CAAC;QAAE,OAAO,GAAG,CAAC;IACrD,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,oBAAoB,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,oBAAoB,CAAC;AACvE,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,cAAc,CAAC,IAAc;IAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,oBAAoB;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,WAAW,GAAG,qBAAqB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC5D,OAAO,WAAW,KAAK,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,CAAC;AAC5E,CAAC"}

package/dist/modules/tool-registry/tool-registry.d.ts

@@ -6,6 +6,12 @@ import type { IToolRegistry, ToolListProvider, ToolManualContext, ToolProvider,
  * 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 declare class ToolRegistry implements IToolRegistry {
     private readonly external;

package/dist/modules/tool-registry/tool-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-registry/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;GAOG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsB;IACxD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA0B;IAEhE,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI;IAKzD,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI;IAKzD,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIjD,YAAY,CAAC,GAAG,GAAE,iBAAsB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK9D,YAAY,CAAC,GAAG,GAAE,iBAAsB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMpE,OAAO,CAAC,GAAG;CAMZ"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-registry/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsB;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsB;IACxD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA0B;IAEhE,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI;IAKzD,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI;IAKzD,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIjD,YAAY,CAAC,GAAG,GAAE,iBAAsB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAK9D,YAAY,CAAC,GAAG,GAAE,iBAAsB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMpE,OAAO,CAAC,GAAG;CAMZ"}

package/dist/modules/tool-registry/tool-registry.js

@@ -1,3 +1,4 @@
+import { withGuideFirst } from './guide-first.js';
 /**
  * The tool catalog. Modules call `registerExternalTool` / `registerInternalTool`
  * (both, for a `both` tool) with a self-describing UTCP `Tool` def, or a
@@ -5,6 +6,12 @@
  * 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 {
     external = new Map();
@@ -29,12 +36,12 @@ export class ToolRegistry {
     }
     async listExternal(ctx = {}) {
         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 = {}) {
         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);
     }
     add(into, tool, surface) {
         if (into.has(tool.name)) {

package/dist/modules/tool-registry/tool-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../../../src/modules/tool-registry/tool-registry.ts"],"names":[],"mappings":"AAQA;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACN,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IACvC,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IACvC,iBAAiB,GAAmB,EAAE,CAAC;IACvC,iBAAiB,GAAmB,EAAE,CAAC;IACvC,qBAAqB,GAAuB,EAAE,CAAC;IAEhE,oBAAoB,CAAC,IAA6B;QAChD,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC7D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,oBAAoB,CAAC,IAA6B;QAChD,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC7D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,qBAAqB,CAAC,QAA0B;QAC9C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAyB,EAAE;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7E,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAyB,EAAE;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/E,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAEO,GAAG,CAAC,IAA2B,EAAE,IAAc,EAAE,OAAe;QACtE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,aAAa,OAAO,gBAAgB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;CACF"}
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../../../src/modules/tool-registry/tool-registry.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IACN,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IACvC,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IACvC,iBAAiB,GAAmB,EAAE,CAAC;IACvC,iBAAiB,GAAmB,EAAE,CAAC;IACvC,qBAAqB,GAAuB,EAAE,CAAC;IAEhE,oBAAoB,CAAC,IAA6B;QAChD,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC7D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,oBAAoB,CAAC,IAA6B;QAChD,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YAC7D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,qBAAqB,CAAC,QAA0B;QAC9C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAyB,EAAE;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7E,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAAyB,EAAE;QAC5C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/E,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtF,CAAC;IAEO,GAAG,CAAC,IAA2B,EAAE,IAAc,EAAE,OAAe;QACtE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,aAAa,OAAO,gBAAgB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC;CACF"}