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

package/src/modules/kb-fs/locking-filesystem.ts

@@ -187,6 +187,43 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     );
   }
 
+  /**
+   * Write a file whose new content DEPENDS on what it holds: the read, the
+   * computing of the new bytes and the write all happen with the path's lock
+   * held, so what lands is derived from the very bytes it replaces.
+   *
+   * `writeFile` cannot give that. Its content is fixed before the lock is
+   * taken, so a caller that read the file first is writing over a state
+   * anyone may have moved in between: an `edit_file` replacing an empty owner
+   * field with one name would silently overwrite another name written a
+   * moment earlier, and both callers would be told their edit landed.
+   *
+   * `rewrite` receives the file as it is under the lock (null when nothing is
+   * there) and answers the bytes to write. Throwing refuses: nothing is
+   * written, the lock is released untouched, and the caller gets what was
+   * thrown.
+   */
+  async rewriteFile(
+    inputPath: string,
+    rewrite: (current: Buffer | null) => FileContent | Promise<FileContent>,
+  ): Promise<void> {
+    await this.assertNotGitInternals(inputPath);
+    this.assertInsideRepo(inputPath);
+    const validate = this.lockContext.validateWrite;
+    let toWrite: FileContent | null = null;
+    return this.withLock(
+      inputPath,
+      () => super.writeFile(inputPath, toWrite as FileContent),
+      async () => {
+        const next = await rewrite(await this.readIfExists(inputPath));
+        // The pre-disk gate judges the bytes that will land, as it does for
+        // every other write, and here those exist only now.
+        await validate?.(inputPath, next);
+        toWrite = next;
+      },
+    );
+  }
+
   override async appendFile(inputPath: string, content: FileContent): Promise<void> {
     await this.assertNotGitInternals(inputPath);
     this.assertInsideRepo(inputPath);

package/src/modules/mcp/__tests__/mcp.e2e.test.ts

@@ -16,7 +16,8 @@ import { SpillStore } from '../../workspace/spill-store.js';
 import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
-import { PLATFORM_HEADER } from '../../agent-instructions/index.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { platformInstructions } from '../../agent-instructions/index.js';
 import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
 import { registerBevelSecretsVariableLoader } from '../../secrets-vault/secrets-variable-loader.js';
 import type { ForcedRefreshOutcome, ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
@@ -483,13 +484,13 @@ describe('per-request identity: catalog, metering and continuity', () => {
 });
 
 describe('agent instructions over the real transport', () => {
-  it('the initialize result carries the header and the preamble body inline', async () => {
+  it('the initialize result carries the platform text and the preamble body inline', async () => {
     const { baseUrl } = await startPlatform({
       readAgentPreamble: async () => 'Acme builds solar farms.\n\n<!-- private -->Look in Projects/ first.',
     });
     const { client } = await connectSdkClient(baseUrl);
     const instructions = client.getInstructions();
-    expect(instructions).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`);
+    expect(instructions).toBe(`${platformInstructions(DEFAULT_KB_LAYOUT)}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`);
     expect(instructions).not.toContain('private');
   });
 

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

@@ -11,9 +11,13 @@ import { SpillStore } from '../../workspace/spill-store.js';
 import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
-import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../../agent-instructions/index.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { TOOL_PREFIX_LINE, platformInstructions, sharedRulesPointer } from '../../agent-instructions/index.js';
 import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.contract.js';
 
+/** The platform-owned part of the handshake text: the header plus the shared file rules. */
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
+
 /**
  * End-to-end proxy test: a real express app serving the registry-driven tool
  * surface over loopback, a real per-request `UtcpClient` discovering it, and a
@@ -262,6 +266,25 @@ describe('McpService (UTCP→MCP proxy)', () => {
     expect(askSchema.properties.body?.properties?.prompt).toBeDefined();
   });
 
+  it('ends the served call_tool_chain description with the shared-rules pointer', async () => {
+    // What a chained read does to an IMAGE is one of the rules the file tools
+    // share, so it is stated once — in the handshake instructions and in the
+    // managed guide — and the chain, like every file tool, ends with the one
+    // sentence saying where. The clients that drop `instructions` have only
+    // descriptions to go on, so that sentence is their way to the rule.
+    const client = await setup();
+    const { tools } = await client.listTools();
+    const chain = tools.find((t) => t.name === 'call_tool_chain')!;
+    const pointer = sharedRulesPointer(DEFAULT_KB_LAYOUT);
+    expect(chain.description!.endsWith(pointer)).toBe(true);
+    // Once, and not on the two meta-tools that describe the registry rather
+    // than a file.
+    expect(chain.description!.split(pointer)).toHaveLength(2);
+    for (const name of ['list_tools', 'tools_info']) {
+      expect(tools.find((t) => t.name === name)!.description, name).not.toContain(pointer);
+    }
+  });
+
   it('a $defs/$ref tool schema survives tools/list and a real MCP client accepts it', async () => {
     // No tokenId filter for this assertion — an OAuth-style session lists all.
     const client = await setup({ tokenId: null });
@@ -534,6 +557,23 @@ describe('McpService — per-user credential pre-check', () => {
       expect(await toolNames(client)).toEqual(['ask', 'boom', 'call_tool_chain', 'list_tools', 'refy', 'tools_info']);
     });
 
+    /**
+     * The worked example in `call_tool_chain`'s description has to be derived
+     * from the tools THIS caller is actually served. Derived from the unfiltered
+     * catalog it could name a credential-gated tool the filter just removed —
+     * an example a connection-key caller copies and cannot call at all.
+     */
+    it('never writes the worked example against a tool it just hid', async () => {
+      const hidden = await setup({ secretsVault: vault(false), toolManuals: manualsWithUserVar });
+      const chain = (await hidden.listTools()).tools.find((t) => t.name === 'call_tool_chain')!;
+      expect(chain.description).not.toMatch(/return KNOWLEDGE_BASE\.\w+\(/);
+      // The same catalog, with the credential set, does print one — so the
+      // assertion above is the filter at work, not an example that never exists.
+      const served = await setup({ secretsVault: vault(true), toolManuals: manualsWithUserVar });
+      const shown = (await served.listTools()).tools.find((t) => t.name === 'call_tool_chain')!;
+      expect(shown.description).toMatch(/return KNOWLEDGE_BASE\.\w+\(/);
+    });
+
     it('keeps the full listing for an OAuth/JWT session (tokenId null) — the caller configures interactively', async () => {
       const client = await setup({
         secretsVault: vault(false),
@@ -548,17 +588,17 @@ describe('McpService — per-user credential pre-check', () => {
 describe('McpService — agent instructions', () => {
   const KB_TOOLS = ['start_session', 'grep', 'list_files', 'read_file'];
 
-  it('sends the header and the preamble as the session\'s instructions', async () => {
+  it("sends the platform text and the preamble as the session's instructions", async () => {
     const client = await setup({ readAgentPreamble: async () => 'Acme builds solar farms.\n\nProjects live in Projects/.' });
-    expect(client.getInstructions()).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.\n\nProjects live in Projects/.`);
+    expect(client.getInstructions()).toBe(`${PLATFORM}\n\nAcme builds solar farms.\n\nProjects live in Projects/.`);
   });
 
-  it('sends the header alone when no reader is wired', async () => {
+  it('sends the platform text alone when no reader is wired', async () => {
     const client = await setup();
-    expect(client.getInstructions()).toBe(PLATFORM_HEADER);
+    expect(client.getInstructions()).toBe(PLATFORM);
   });
 
-  it('a throwing reader still yields a session, with the header as its instructions and a warning', async () => {
+  it('a throwing reader still yields a session, with the platform text as its instructions and a warning', async () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const client = await setup({
       readAgentPreamble: async () => {
@@ -566,7 +606,7 @@ describe('McpService — agent instructions', () => {
       },
       extraTools: KB_TOOLS,
     });
-    expect(client.getInstructions()).toBe(PLATFORM_HEADER);
+    expect(client.getInstructions()).toBe(PLATFORM);
     // The error itself rides along, so a terminal shows its stack.
     expect(warn).toHaveBeenCalledWith(
       expect.stringContaining('mcp-description.md'),

package/src/modules/mcp/mcp.service.ts

@@ -27,7 +27,7 @@ import {
 } from '@utcp/sdk';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
 import {
-  CODE_MODE_META_TOOLS,
+  codeModeMetaTools,
   META_TOOL_NAMES,
   dispatchMetaTool,
   dispatchToolCall,
@@ -43,6 +43,7 @@ import {
   type SkillSummary,
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
+import type { KbLayout } from '@bevel-software/platform-shared';
 import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
 import {
   scopesCovered,
@@ -65,6 +66,7 @@ import {
   composeAgentInstructions,
   prefixToolDescription,
   PREFIXED_TOOLS,
+  sharedRulesPointer,
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
@@ -91,6 +93,13 @@ export interface McpProxyOptions {
    * carries the platform header alone.
    */
   readAgentPreamble?: AgentPreambleReader;
+  /**
+   * The layout in effect, read per request: the shared file rules name the
+   * managed guide, and a deployment may rename it after boot (the setup save
+   * applies a name without a restart). A GETTER, so nothing snapshots the
+   * pre-setup default. Absent, the rules name `AGENTS.md`.
+   */
+  kbLayout?: () => KbLayout;
   /** Bounds of the downstream (`mcp.json`) connection pool; defaults are 4h idle / 5000 entries. */
   downstreamPool?: Pick<DownstreamPoolOptions<unknown>, 'idleTtlMs' | 'maxEntries' | 'now'>;
   /**
@@ -434,12 +443,26 @@ export class McpService {
       const seen = new Set(META_TOOL_NAMES);
       const dropped: string[] = [];
       const direct: McpTool[] = [];
+      const examplePool: ProxiedTool[] = [];
       for (const t of listed) {
         const entry = toListedTool(t); // logs its own reason on a name/schema drop
         if (!entry) {
           dropped.push(t.mcpName);
           continue;
         }
+        // Kept for the worked example in the meta-tool descriptions: it must
+        // be derived from the tools THIS caller actually gets, not from the
+        // whole catalog, or a connection-key caller is shown an example naming
+        // a credential-gated tool the filter above just removed from its
+        // listing — a copied call that cannot work.
+        //
+        // BEFORE the duplicate drop below, on purpose. A tool dropped from the
+        // LISTING for sharing its name with another is still in the catalog a
+        // chain dispatches to, so the chain sees two tools under one name and
+        // refuses the call as ambiguous. The example has to know about both to
+        // steer clear of either (`chainExample` skips a name two tools share);
+        // shown only the survivor, it took that name for a safe one.
+        examplePool.push(t);
         if (seen.has(entry.name)) {
           dropped.push(`${entry.name} (duplicate)`);
           continue;
@@ -456,18 +479,33 @@ export class McpService {
             : entry,
         );
       }
+      // The meta-tools' examples name the namespace THIS endpoint registers the
+      // knowledge-base tools under, and a tool this caller is really served, so
+      // a chain copied out of the description runs. Built here rather than held
+      // as a constant: the local MCP server registers the same tools under a
+      // different name, and one fixed example is necessarily wrong on one of the
+      // two surfaces.
+      //
+      // The chain's description ends with the same pointer every file tool ends
+      // with: what a chain does with a failure, a large result or an image is
+      // stated once, in the shared rules, and the clients that drop
+      // `instructions` have the description and the guide to go on. Composed
+      // here because the guide's name is this deployment's setting.
+      const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
+        sharedRulesPointer: sharedRulesPointer(this.opts.kbLayout?.()),
+      });
       // Log only when a tool was dropped (name/schema/duplicate) — that's the
       // anomaly worth surfacing, since a downstream client would otherwise hide
       // it by rejecting the whole response.
       if (dropped.length) {
         log.warn(
-          `tools/list: serving ${CODE_MODE_META_TOOLS.length + direct.length} tool(s); ` +
+          `tools/list: serving ${metaTools.length + direct.length} tool(s); ` +
             `dropped ${dropped.length} non-listable: ${dropped.join(', ')}`,
         );
       }
       return {
         // Code-mode meta-tools first, then every validated direct tool.
-        tools: [...CODE_MODE_META_TOOLS, ...direct],
+        tools: [...metaTools, ...direct],
       };
     });
 
@@ -613,13 +651,14 @@ export class McpService {
    * fails over its preamble.
    */
   private async composeAgentInstructions(): Promise<ComposedAgentInstructions> {
+    const layout = this.opts.kbLayout?.();
     const read = this.opts.readAgentPreamble;
-    if (!read) return composeAgentInstructions(null);
+    if (!read) return composeAgentInstructions(null, layout);
     try {
-      return composeAgentInstructions(await read());
+      return composeAgentInstructions(await read(), layout);
     } catch (err) {
-      log.warn('could not read mcp-description.md; this request gets the platform header alone:', { err });
-      return composeAgentInstructions(null);
+      log.warn('could not read mcp-description.md; this request gets the platform text alone:', { err });
+      return composeAgentInstructions(null, layout);
     }
   }
 

package/src/modules/plugins/join-request-records.store.ts

@@ -143,11 +143,14 @@ export class DbJoinRequestStore implements JoinRequestStore {
     pluginKey: string;
   }): Promise<JoinRequestRecord> {
     const requesterEmail = input.requesterEmail.toLowerCase();
+    // Keyed by the blind index throughout: the email column is randomized
+    // ciphertext, so the uniqueness and every lookup go through its index,
+    // which is written and compared with the address.
     const [inserted] = await this.db
       .insert(pluginJoinRequests)
-      .values({ requesterEmail, requesterName: input.requesterName, pluginKey: input.pluginKey })
+      .values({ requesterEmail, requesterEmailBidx: requesterEmail, requesterName: input.requesterName, pluginKey: input.pluginKey })
       .onConflictDoNothing({
-        target: [pluginJoinRequests.requesterEmail, pluginJoinRequests.pluginKey],
+        target: [pluginJoinRequests.requesterEmailBidx, pluginJoinRequests.pluginKey],
       })
       .returning();
     if (inserted) return toRecord(inserted);
@@ -170,7 +173,7 @@ export class DbJoinRequestStore implements JoinRequestStore {
       })
       .where(
         and(
-          eq(pluginJoinRequests.requesterEmail, requesterEmail),
+          eq(pluginJoinRequests.requesterEmailBidx, requesterEmail),
           eq(pluginJoinRequests.pluginKey, input.pluginKey),
         ),
       )
@@ -191,7 +194,7 @@ export class DbJoinRequestStore implements JoinRequestStore {
     const rows = await this.db
       .select()
       .from(pluginJoinRequests)
-      .where(eq(pluginJoinRequests.requesterEmail, requesterEmail.toLowerCase()));
+      .where(eq(pluginJoinRequests.requesterEmailBidx, requesterEmail));
     return rows.map(toRecord);
   }
 

package/src/modules/tool-auth/external-api-key.service.ts

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('external-api-key');
-import { and, asc, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
+import { and, desc, eq, isNotNull, isNull, type SQL } from 'drizzle-orm';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { Database } from '../database/connection.js';
 import { externalApiKeys, users } from '../database/schema.js';
@@ -169,6 +169,11 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
     // Owner joined in so the admin overview is one round-trip; ordered by
     // owner email so per-account grouping is a linear pass, newest key
     // first within an account (same order the owner sees on their own page).
+    // The email half of that order is applied in-process: the column is
+    // ciphertext in the database, where ORDER BY would sort by IV noise. The
+    // sort is stable, so the database's newest-first survives within an owner.
+    // By code unit, not by locale: a collation can call two different
+    // addresses equal, and equal here means "the same owner's group".
     const rows = await this.db
       .select({
         key: externalApiKeys,
@@ -178,7 +183,8 @@ export class ExternalApiKeyService implements IExternalApiKeyService {
       })
       .from(externalApiKeys)
       .innerJoin(users, eq(externalApiKeys.userId, users.id))
-      .orderBy(asc(users.email), desc(externalApiKeys.createdAt));
+      .orderBy(desc(externalApiKeys.createdAt));
+    rows.sort((a, b) => (a.email < b.email ? -1 : a.email > b.email ? 1 : 0));
     return rows.map((row) => ({
       ...toSummary(row.key),
       user: { id: row.userId, email: row.email, name: row.name },

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -183,6 +183,157 @@ describe('ToolManualService', () => {
     expect(manual).toBeNull();
   });
 
+  test('resolves an inline tool that calls Google as a service account, and surfaces the key variable', async () => {
+    // The auth block is what makes the call; the key it names has to reach the
+    // secrets UI as a shared variable or nobody can store it.
+    await writeFile(
+      join(root, wsId, KB_DIR, 'Plugins', 'google_ads.tool'),
+      JSON.stringify({
+        id: 'google_ads',
+        type: 'inline',
+        tools: [
+          {
+            name: 'list_accessible_customers',
+            description: 'List the customers the service account can reach.',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: {
+              call_template_type: 'http',
+              http_method: 'GET',
+              url: 'https://googleads.googleapis.com/v22/customers:listAccessibleCustomers',
+              headers: { 'developer-token': '${DEVELOPER_TOKEN}' },
+              auth: {
+                auth_type: 'google_service_account',
+                credentials: '${GOOGLE_SA_KEY}',
+                scopes: 'https://www.googleapis.com/auth/adwords',
+              },
+            },
+          },
+        ],
+      }),
+    );
+
+    const manual = await svc().resolveInlineManual('user@x.eu', 'google_ads');
+    const tools = (manual as { tools?: { name?: string; tool_call_template?: { auth?: unknown } }[] } | null)?.tools ?? [];
+    expect(tools.map((t) => t.name)).toEqual(['list_accessible_customers']);
+    // The auth block is what makes the call, so resolving must carry it through intact.
+    expect(tools[0]?.tool_call_template?.auth).toEqual({
+      auth_type: 'google_service_account',
+      credentials: '${GOOGLE_SA_KEY}',
+      scopes: 'https://www.googleapis.com/auth/adwords',
+    });
+
+    const summary = (await svc().listAccessible('user@x.eu')).find((m) => m.name === 'google_ads')!;
+    expect(summary.variables?.find((v) => v.name === 'GOOGLE_SA_KEY')?.scope).toBe('admin');
+  });
+
+  test('refuses a Google service-account auth block where no token would be sent, and says where', async () => {
+    // Only the `http` protocol mints the token. On any other template the
+    // block validates and is then sent as no credentials at all, so the file
+    // is refused when it is read rather than left to fail at Google.
+    const serviceAccount = {
+      auth_type: 'google_service_account',
+      credentials: '${GOOGLE_SA_KEY}',
+      scopes: 'https://www.googleapis.com/auth/adwords',
+    };
+    const inlineOver = (callTemplateType: string) =>
+      JSON.stringify({
+        type: 'inline',
+        tools: [
+          {
+            name: 'events',
+            description: 'Stream events.',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: { call_template_type: callTemplateType, url: 'https://api.example.com/events', auth: serviceAccount },
+          },
+        ],
+      });
+    const plugins = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(join(plugins, 'over_sse.tool'), inlineOver('sse'));
+    await writeFile(join(plugins, 'over_streamable.tool'), inlineOver('streamable_http'));
+    // Not on a call template at all: a discovered manual takes only a url and headers.
+    await writeFile(
+      join(plugins, 'discovered.tool'),
+      JSON.stringify({ type: 'http', url: 'https://api.example.com/utcp', auth: serviceAccount }),
+    );
+    // Looking like an `http` call template is not enough: a discovered manual
+    // reads neither a block at its root nor a `tools` list, whatever they say.
+    await writeFile(
+      join(plugins, 'dressed_root.tool'),
+      JSON.stringify({ type: 'http', url: 'https://api.example.com/utcp', call_template_type: 'http', auth: serviceAccount }),
+    );
+    await writeFile(
+      join(plugins, 'unread_tools.tool'),
+      JSON.stringify({ ...JSON.parse(inlineOver('http')), type: 'http', url: 'https://api.example.com/utcp' }),
+    );
+    await writeFile(join(plugins, 'over_http.tool'), inlineOver('http'));
+
+    const catalog = await svc().listAccessibleCatalog('user@x.eu');
+
+    const reasonFor = (file: string) => catalog.invalid.find((i) => i.path === `Plugins/${file}`)?.reason ?? '';
+    expect(reasonFor('over_sse.tool')).toContain('a `sse` call template');
+    expect(reasonFor('over_streamable.tool')).toContain('a `streamable_http` call template');
+    expect(reasonFor('discovered.tool')).toContain("not a call template's `auth`");
+    expect(reasonFor('dressed_root.tool')).toContain('no tool is called through');
+    expect(reasonFor('unread_tools.tool')).toContain('no tool is called through');
+    for (const file of ['over_sse.tool', 'over_streamable.tool', 'discovered.tool', 'dressed_root.tool', 'unread_tools.tool']) {
+      expect(reasonFor(file)).toContain('`call_template_type: http`');
+    }
+    // The one place it works is left alone.
+    expect(reasonFor('over_http.tool')).toBe('');
+    expect(catalog.tools.map((m) => m.name)).toContain('overhttp');
+  });
+
+  test('refuses a `.tool` that holds a service-account key itself, wherever the block sits, and never repeats it', async () => {
+    // A `.tool` is committed and read by everyone who can read the knowledge
+    // base, so the key lives in the vault and the file only names it.
+    const key = JSON.stringify({ type: 'service_account', client_email: 'ads@proj.iam.gserviceaccount.com', private_key: 'MIIEvQIBADANBgkq-NOT-A-REAL-KEY' });
+    const withCredentials = (credentials: unknown, callTemplateType = 'http') =>
+      JSON.stringify({
+        type: 'inline',
+        tools: [
+          {
+            name: 'list',
+            description: 'List.',
+            inputs: { type: 'object', properties: {} },
+            outputs: { type: 'object', properties: {} },
+            tool_call_template: {
+              call_template_type: callTemplateType,
+              http_method: 'GET',
+              url: 'https://googleads.googleapis.com/v22/customers',
+              auth: { auth_type: 'google_service_account', credentials, scopes: 'https://www.googleapis.com/auth/adwords' },
+            },
+          },
+        ],
+      });
+    const plugins = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(join(plugins, 'pasted_key.tool'), withCredentials(key));
+    await writeFile(join(plugins, 'pasted_base64.tool'), withCredentials(Buffer.from(key).toString('base64')));
+    // A variable with the key, or anything else, written around it is still text in the file.
+    await writeFile(join(plugins, 'beside_a_variable.tool'), withCredentials('${GOOGLE_SA_KEY}' + key));
+    // In a block nothing acts on, the key is just as readable: that it is there is said first.
+    await writeFile(join(plugins, 'key_over_sse.tool'), withCredentials(key, 'sse'));
+    await writeFile(join(plugins, 'braced.tool'), withCredentials('${GOOGLE_SA_KEY}'));
+    await writeFile(join(plugins, 'bare.tool'), withCredentials(' $GOOGLE_SA_KEY '));
+
+    const catalog = await svc().listAccessibleCatalog('user@x.eu');
+
+    const reasonFor = (file: string) => catalog.invalid.find((i) => i.path === `Plugins/${file}`)?.reason ?? '';
+    for (const file of ['pasted_key.tool', 'pasted_base64.tool', 'beside_a_variable.tool', 'key_over_sse.tool']) {
+      expect(reasonFor(file), file).toContain('something other than a vault variable as its `credentials`');
+      expect(reasonFor(file), file).toContain('Secrets Vault');
+    }
+    // Nothing of what was pasted comes back in the answer, in either spelling.
+    const answer = JSON.stringify(catalog);
+    expect(answer).not.toMatch(/NOT-A-REAL-KEY|iam\.gserviceaccount/);
+    expect(answer).not.toContain(Buffer.from(key).toString('base64').slice(0, 40));
+    // Either spelling of one variable is what the field is for.
+    expect(reasonFor('braced.tool')).toBe('');
+    expect(reasonFor('bare.tool')).toBe('');
+    expect(catalog.tools.map((m) => m.name)).toEqual(expect.arrayContaining(['braced', 'bare']));
+  });
+
   test('manual names are alphanumeric (no underscores) for variable namespacing', async () => {
     root = await mkdtemp(join(tmpdir(), 'tools2-'));
     const tools = join(root, wsId, KB_DIR, 'Plugins');

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -16,6 +16,9 @@ import {
   DefaultVariableSubstitutor,
   type CallTemplate,
 } from '@utcp/sdk';
+// Also a side effect: loading the package registers the 'google_service_account'
+// auth type, so a `.tool` naming it validates here.
+import { findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey } from '@bevel-software/platform-mcp-core';
 import { descriptorsFromMcpJson } from './mcp-json-discovery.js';
 import type { PluginSource } from '../plugins/discovery/plugin-source.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -1196,6 +1199,40 @@ export function normalizeToolManual(
     descriptor.remote = false;
   }
 
+  // A service account's KEY IS NEVER WRITTEN IN A `.tool`. The file is
+  // knowledge-base content: committed, and read by everyone and every agent
+  // that can read the knowledge base. So `credentials` names the vault
+  // variable and nothing else, and a file that holds anything else there is
+  // refused before the block's placement is even looked at: a key in a block
+  // nothing acts on is just as readable. The refusal does not quote the value.
+  if (holdsLiteralGoogleServiceAccountKey(obj)) {
+    throw new Error(
+      '`auth_type: google_service_account` has something other than a vault variable as its `credentials`. ' +
+        'Write `credentials: ${GOOGLE_SA_KEY}` and store the key in the Secrets Vault under that name: a `.tool` is ' +
+        'read by everyone who can read the knowledge base. If a real key was saved in this file, treat it as ' +
+        'exposed and replace it at Google; removing it here does not take it out of the history.',
+    );
+  }
+
+  // A Google service-account `auth` block works on one thing: an inline tool's
+  // `http` call template. Anywhere else it validates and is then sent as no
+  // credentials at all, so the tool would save cleanly and call Google
+  // unauthenticated, with Google's 401 the only hint. Refused here instead,
+  // naming where the block was found. The templates below are the only ones
+  // this file's tools are called through: a `tools` list on a file that is not
+  // `inline` is never read, so nothing in it counts.
+  const toolCallTemplates =
+    type === 'inline' && Array.isArray(obj.tools)
+      ? obj.tools.map((tool: unknown) => (tool && typeof tool === 'object' ? (tool as Record<string, unknown>).tool_call_template : undefined))
+      : [];
+  const unserved = findUnservedGoogleServiceAccountAuth(obj, toolCallTemplates);
+  if (unserved) {
+    throw new Error(
+      `\`auth_type: google_service_account\` is on ${unserved}, where no token would be sent. ` +
+        "It works only as the `auth` of an inline tool's `tool_call_template` with `call_template_type: http`.",
+    );
+  }
+
   if (type === 'inline') {
     const tools = Array.isArray(obj.tools) ? obj.tools : undefined;
     if (!tools) throw new Error('inline `.tool` must have a `tools` array');