@bevel-software/platform-core-backend 0.12.0 → 0.13.1

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

@@ -0,0 +1,243 @@
+import { describe, test, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CallTemplateSerializer, CommunicationProtocol, UtcpClient } from '@utcp/sdk';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { ToolManualService, normalizeToolManual } from '../tool-manuals.service.js';
+import { canExecuteCliTemplates, containsCliCallTemplate } from '../utcp-cli-parse-only.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { utcpNamespacePrefix } from '../../../shared/utcp-namespace.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+/** A shell `.tool` in the shape the KB's `git.tool` uses: fenced YAML, cli templates. */
+const gitTool = (extra = ''): string => `---
+name: git
+type: inline
+description: Git over the local checkout.
+${extra}tools:
+  - name: status
+    description: Porcelain status of a checkout.
+    inputs:
+      type: object
+      properties:
+        cwd: { type: string }
+      required: [cwd]
+    outputs:
+      type: object
+      properties: {}
+    tool_call_template:
+      call_template_type: cli
+      commands:
+        - command: git -C "UTCP_ARG_cwd_UTCP_END" status --porcelain
+          append_to_final_output: true
+---
+
+Notes after the fence are ignored by the parser.
+`;
+
+describe('cli `.tool` manuals — parsed and listed, never executed', () => {
+  test('the hosted process cannot DISPATCH a cli template', async () => {
+    // The claim worth pinning is not "the map lacks a key" — it is that a cli
+    // template actually fails to dispatch. A registry assertion alone would
+    // still pass if some other module re-registered the protocol at runtime, or
+    // if dispatch consulted a different map; this exercises the path a
+    // dispatching caller takes.
+    expect(canExecuteCliTemplates()).toBe(false);
+
+    const template = new CallTemplateSerializer().validateDict({
+      name: 'git',
+      call_template_type: 'cli',
+      commands: [{ command: 'git status', append_to_final_output: true }],
+    });
+    const protocol = CommunicationProtocol.communicationProtocols[template.call_template_type];
+    expect(protocol).toBeUndefined();
+
+    // And a client built in this process refuses it rather than shelling out.
+    const client = await UtcpClient.create(process.cwd(), { variables: {} } as never);
+    try {
+      // The reason, not any reason: a shape or URL error would also reject,
+      // and would leave the guarantee this test exists for unverified.
+      await expect(client.registerManual(template)).rejects.toThrow(
+        /No communication protocol registered for type: 'cli'/,
+      );
+    } finally {
+      // Closing releases the client's communication protocols and their
+      // transports; left open they outlive the test for the whole run.
+      await client.close().catch(() => {});
+    }
+  });
+
+  test('the serializer IS registered, or these files would not parse at all', () => {
+    // The other half of the split: the platform must understand a cli template
+    // well enough to validate and serve it, which is why the package is
+    // imported at all.
+    expect(() =>
+      new CallTemplateSerializer().validateDict({
+        name: 'git',
+        call_template_type: 'cli',
+        commands: [{ command: 'git status' }],
+      }),
+    ).not.toThrow();
+    expect(CommunicationProtocol.communicationProtocols.http).toBeDefined();
+  });
+
+  test('a cyclic document is examined, not blown up on', () => {
+    // A YAML self-alias really does produce a cyclic object. The backstop must
+    // still find the cli template beside the cycle rather than overflow.
+    const cyclic: Record<string, unknown> = { tools: [{ tool_call_template: { call_template_type: 'cli' } }] };
+    cyclic.self = cyclic;
+    expect(containsCliCallTemplate(cyclic)).toBe(true);
+    const benign: Record<string, unknown> = { a: { call_template_type: 'http' } };
+    benign.self = benign;
+    expect(containsCliCallTemplate(benign)).toBe(false);
+  });
+
+  test('a cli call template is found wherever it is nested', () => {
+    expect(containsCliCallTemplate(JSON.parse(JSON.stringify({ a: [{ b: { call_template_type: 'cli' } }] })))).toBe(true);
+    expect(containsCliCallTemplate({ call_template_type: 'http' })).toBe(false);
+    expect(containsCliCallTemplate({ call_template_type: ' CLI ' })).toBe(true);
+    expect(containsCliCallTemplate(null)).toBe(false);
+  });
+
+  test('a shell `.tool` is forced local even without declaring it', () => {
+    const d = normalizeToolManual('git', 'Plugins/git.tool', gitTool());
+    expect(d.remote).toBe(false);
+    expect(d.type).toBe('inline');
+  });
+
+  test('`remote: false` beside a cli template is accepted as written', () => {
+    expect(normalizeToolManual('git', 'Plugins/git.tool', gitTool('remote: false\n')).remote).toBe(false);
+  });
+
+  test('`remote: true` beside a cli template is refused, not corrected', () => {
+    expect(() => normalizeToolManual('git', 'Plugins/git.tool', gitTool('remote: true\n'))).toThrow(/cli.*call template|call template/i);
+  });
+});
+
+describe('a shell `.tool` in a workspace', () => {
+  let root: string;
+
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+
+  const allowAll = {
+    canRead: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'clitools-'));
+    const dir = join(root, wsId, KB_DIR, 'Plugins');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'git.tool'), gitTool());
+  });
+  afterEach(() => rm(root, { recursive: true, force: true }));
+
+  test('is listed to local consumers and withheld from remote ones', async () => {
+    const svc = new ToolManualService(workspaceService, allowAll, KB_DIR);
+    // `list_local_tools` names it, so the local server knows to materialize it.
+    expect(await svc.listLocalOnly('user@x.eu')).toEqual([{ slug: 'git', name: 'git', path: 'Plugins/git.tool' }]);
+    // The hosted proxy's manual set excludes it entirely.
+    expect((await svc.toManualCallTemplates('user@x.eu', { remoteOnly: true })).map((t) => t.name)).toEqual([]);
+    expect((await svc.toManualCallTemplates('user@x.eu')).map((t) => t.name)).toEqual(['git']);
+  });
+
+  test('its embedded cli tools survive manual serialization', async () => {
+    // The whole point of registering the serializer: without it the manual body
+    // fails validation and the local server gets nothing to run.
+    const svc = new ToolManualService(workspaceService, allowAll, KB_DIR);
+    const manual = await svc.resolveInlineManual('user@x.eu', 'git');
+    expect(manual).not.toBeNull();
+    const tools = (manual as { tools: { name: string; tool_call_template: { call_template_type: string } }[] }).tools;
+    expect(tools.map((t) => t.name)).toEqual(['status']);
+    expect(tools[0].tool_call_template.call_template_type).toBe('cli');
+  });
+});
+
+describe('manual namespaces are unique, not merely manual names', () => {
+  let root: string;
+
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+
+  const allowAll = {
+    canRead: async () => true,
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+
+  const pluginsDir = () => join(root, wsId, KB_DIR, 'Plugins');
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'ns-'));
+    await mkdir(pluginsDir(), { recursive: true });
+  });
+  afterEach(() => rm(root, { recursive: true, force: true }));
+
+  /** A `.tool` file. Its `id` grammar is `[a-z0-9_]` — it cannot carry a hyphen. */
+  const writeTool = (file: string, id: string) =>
+    writeFile(join(pluginsDir(), file), JSON.stringify({ id, type: 'inline', tools: [] }));
+
+  /**
+   * An mcp.json server. THIS is the only path a hyphen can enter a manual name:
+   * its grammar allows `-`, so it is the only way to build a real collision.
+   */
+  async function writeMcpServer(folder: string, serverName: string): Promise<void> {
+    await mkdir(join(pluginsDir(), folder), { recursive: true });
+    await writeFile(
+      join(pluginsDir(), folder, 'mcp.json'),
+      JSON.stringify({ mcpServers: { [serverName]: { type: 'streamable-http', url: 'https://v.example/mcp' } } }),
+    );
+  }
+
+  const names = async (): Promise<string[]> =>
+    (await new ToolManualService(workspaceService, allowAll, KB_DIR).listAllSummaries()).map((m) => m.name).sort();
+
+  it('keeps two manuals whose namespaces genuinely differ', async () => {
+    // Underscore-doubling is injective, so `a_b` (a__b_) and `a__b` (a____b_)
+    // are distinct namespaces and both must survive.
+    await writeTool('a.tool', 'a_b');
+    await writeTool('b.tool', 'a__b');
+    expect(await names()).toEqual(['a__b', 'a_b']);
+  });
+
+  it('drops the second of two manuals sharing one namespace', async () => {
+    // `a-b` and `a_b` are different NAMES with the same NAMESPACE `a__b_`, and
+    // therefore one set of vault keys — either able to resolve the other's
+    // secrets. Deduping by raw name let both through; this is the case that
+    // proves the check compares namespaces.
+    await writeMcpServer('Vendor', 'a-b');
+    await writeTool('a.tool', 'a_b');
+    const kept = await names();
+    expect(kept).toHaveLength(1);
+    // mcp.json descriptors are listed before `.tool` files, and the shared
+    // dedupe keeps the first occurrence, so the server is the survivor.
+    expect(kept).toEqual(['a-b']);
+  });
+
+  it('leaves both when the hyphenated name does NOT collide', async () => {
+    // Guards the fix from being over-broad: hyphens stay usable, which matters
+    // because MCP servers in the wild are routinely named with them.
+    await writeMcpServer('Vendor', 'sequential-thinking');
+    await writeTool('a.tool', 'a_b');
+    expect(await names()).toEqual(['a_b', 'sequential-thinking']);
+  });
+
+  it('keeps every surviving namespace distinct', async () => {
+    // The invariant secrets actually depend on, asserted directly.
+    await writeMcpServer('Vendor', 'a-b');
+    await writeTool('a.tool', 'a_b');
+    await writeTool('c.tool', 'other');
+    const kept = await new ToolManualService(workspaceService, allowAll, KB_DIR).listAllSummaries();
+    const namespaces = kept.map((m) => utcpNamespacePrefix(m.name));
+    expect(new Set(namespaces).size).toBe(namespaces.length);
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.mcp-oauth.test.ts

@@ -197,4 +197,99 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
     expect(survived.map((m) => m.name).sort()).toEqual(['jira', 'notion']);
     warn.mockRestore();
   });
+
+  /** An mcp.json server whose plugin.json declares a sign-in by client id alone. */
+  async function writeDeclaredServer(oauth: Record<string, unknown>) {
+    const pluginDir = join(root, wsId, KB_DIR, 'Plugins', 'GTM');
+    await mkdir(pluginDir, { recursive: true });
+    await writeFile(
+      join(pluginDir, 'mcp.json'),
+      JSON.stringify({ mcpServers: { hubspot: { type: 'streamable-http', url: 'https://mcp.hubspot.example/mcp' } } }),
+    );
+    await writeFile(
+      join(pluginDir, 'plugin.json'),
+      JSON.stringify({
+        name: 'gtm',
+        extensions: {
+          'software.bevel.hexis': {
+            mcpServers: {
+              hubspot: {
+                headers: { Authorization: 'Bearer ${HUBSPOT_TOKEN}' },
+                variables: [{ name: 'HUBSPOT_TOKEN', scope: 'user', oauth }],
+              },
+            },
+          },
+        },
+      }),
+    );
+  }
+
+  test('a declared client id without endpoints is completed from the server metadata; a miss lands in setup.reason', async () => {
+    await writeDeclaredServer({ clientId: 'owner-app' });
+    const statusFor = vi.fn(async () => ({ status: 'open' as const }));
+    const providerForDeclaredClient = vi.fn(async () => ({
+      status: 'oauth' as const,
+      provider: {
+        authorizationUrl: 'https://auth.hubspot.example/authorize',
+        tokenUrl: 'https://auth.hubspot.example/token',
+        clientId: 'owner-app',
+        pkce: true,
+        resource: 'https://mcp.hubspot.example/mcp',
+      },
+    }));
+    const svc = svcWith({ statusFor, providerForDeclaredClient });
+    const hubspot = (await svc.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+    // Explicit wins: a declared server is never probed for registration…
+    expect(statusFor).not.toHaveBeenCalledWith('hubspot', expect.anything());
+    expect(providerForDeclaredClient).toHaveBeenCalledWith('hubspot', 'https://mcp.hubspot.example/mcp', 'owner-app');
+    // …its declaration is completed in place — an owner-registered sign-in
+    // with nothing left to explain, so no `reason`.
+    expect(hubspot.setup).toEqual({ kind: 'oauth-manual' });
+    expect(hubspot.variables?.[0].oauth).toEqual({
+      clientId: 'owner-app',
+      authorizationUrl: 'https://auth.hubspot.example/authorize',
+      tokenUrl: 'https://auth.hubspot.example/token',
+      resource: 'https://mcp.hubspot.example/mcp',
+    });
+
+    // When the metadata can't be had, the declaration stays incomplete and the
+    // reason travels with the tool — to the UI banner and to `list_tool_setup`.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const missing = svcWith({
+      statusFor,
+      providerForDeclaredClient: async () => ({
+        status: 'unsupported' as const,
+        reason: 'no authorization-server metadata at https://mcp.hubspot.example',
+      }),
+    });
+    const stuck = (await missing.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+    expect(stuck.setup).toEqual({
+      kind: 'oauth-manual',
+      reason: 'no authorization-server metadata at https://mcp.hubspot.example',
+    });
+    expect(stuck.variables?.[0].oauth).toEqual({ clientId: 'owner-app' });
+    // A port without the declared-client path says so rather than pretending.
+    const legacy = svcWith({ statusFor });
+    const unsupported = (await legacy.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+    expect(unsupported.setup?.reason).toContain('discovery is unavailable');
+    warn.mockRestore();
+  });
+
+  test('a fully declared sign-in is oauth-manual with no reason, and is never probed', async () => {
+    await writeDeclaredServer({
+      clientId: 'owner-app',
+      authorizationUrl: 'https://auth.hubspot.example/authorize',
+      tokenUrl: 'https://auth.hubspot.example/token',
+      pkce: false,
+    });
+    const statusFor = vi.fn(async () => ({ status: 'open' as const }));
+    const providerForDeclaredClient = vi.fn();
+    const svc = svcWith({ statusFor, providerForDeclaredClient });
+    const hubspot = (await svc.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+    expect(hubspot.setup).toEqual({ kind: 'oauth-manual' });
+    expect(providerForDeclaredClient).not.toHaveBeenCalled();
+    expect(statusFor).not.toHaveBeenCalledWith('hubspot', expect.anything());
+    // The declaration is carried verbatim, opt-out included.
+    expect(hubspot.variables?.[0].oauth).toMatchObject({ clientId: 'owner-app', pkce: false });
+  });
 });

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

@@ -266,6 +266,22 @@ describe('ToolManualService', () => {
     expect(await svc().listAccessible('user@x.eu')).toHaveLength(0);
   });
 
+  test('carries oauth.pkce:false and a gated oauth.resource; a `.tool` still needs both endpoints', async () => {
+    await writeOAuthTool(oauthVar({ pkce: false, resource: 'https://api.example.com/mcp' }));
+    const [manual] = await svc().listAccessible('user@x.eu');
+    expect(manual.variables?.[0].oauth).toMatchObject({ pkce: false, resource: 'https://api.example.com/mcp' });
+    // PKCE is the default and is not echoed; only the opt-out is stored.
+    await writeOAuthTool(oauthVar({ pkce: true }));
+    expect((await svc().listAccessible('user@x.eu'))[0].variables?.[0].oauth).not.toHaveProperty('pkce');
+    await writeOAuthTool(oauthVar({ pkce: 'yes' }));
+    expect(await svc().listAccessible('user@x.eu')).toHaveLength(0);
+    await writeOAuthTool(oauthVar({ resource: 'http://localhost/mcp' }));
+    expect(await svc().listAccessible('user@x.eu')).toHaveLength(0);
+    // A `.tool` has no server whose metadata could fill the endpoints in.
+    await writeOAuthTool(oauthVar({ authorizationUrl: undefined }));
+    expect(await svc().listAccessible('user@x.eu')).toHaveLength(0);
+  });
+
   test('parses `remote`: default true, explicit false, rejects non-boolean', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsrem-'));
     const tools = join(root, wsId, KB_DIR, 'Plugins');
@@ -288,7 +304,7 @@ describe('ToolManualService', () => {
     const s = svc();
     expect((await s.toManualCallTemplates('user@x.eu', { remoteOnly: true })).map((t) => t.name).sort()).toEqual(['pub']);
     expect((await s.toManualCallTemplates('user@x.eu')).map((t) => t.name).sort()).toEqual(['loc', 'pub']);
-    expect(await s.listLocalOnly('user@x.eu')).toEqual([{ name: 'loc', path: 'Plugins/loc.tool' }]);
+    expect(await s.listLocalOnly('user@x.eu')).toEqual([{ slug: 'loc', name: 'loc', path: 'Plugins/loc.tool' }]);
     // The local-only manual is still browsable/editable regardless of the remote flag.
     expect((await s.listAccessible('user@x.eu')).map((m) => m.name).sort()).toEqual(['loc', 'pub']);
   });

package/src/modules/tool-manuals/mcp-json-discovery.ts

@@ -106,28 +106,48 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
     if (entry.oauth !== undefined) {
       // OAuth is inherently per-caller (same rule the `.tool` parser
       // enforces): an admin-shared OAuth token would leak one user's token
-      // to all callers. The provider config's required halves must be there
-      // — a sign-in wired to a missing URL is a declaration, not a feature.
+      // to all callers.
       if (!isRecord(entry.oauth) || scope !== 'user') return null;
       const o = entry.oauth;
+      // Confidential material never loads from a file, on either declaration
+      // surface: the `.tool` parser throws on these keys, and silently
+      // dropping one here would leave a plugin.json carrying a secret that
+      // "worked" — the file is portable package data, readable by every
+      // client that loads the plugin.
+      if (o.clientSecret !== undefined || o.client_secret !== undefined || o.secret !== undefined) return null;
       // `clientId` is trimmed and must be non-empty, exactly as the `.tool`
       // parser requires: a whitespace-only value would pass discovery and
       // then fail the owner's client-secret setup with "clientId is
       // required" — an error at the wrong surface, long after the save.
-      if (
-        typeof o.authorizationUrl !== 'string' ||
-        typeof o.tokenUrl !== 'string' ||
-        typeof o.clientId !== 'string' ||
-        !o.clientId.trim()
-      ) {
-        return null;
-      }
+      if (typeof o.clientId !== 'string' || !o.clientId.trim()) return null;
+      // The endpoints are OPTIONAL here, unlike in a `.tool`: an MCP server
+      // publishes its authorization-server metadata, so a declaration that
+      // names only the client id is completed at scan time. Both or neither
+      // — one URL without the other is a half-declaration, not a feature.
+      // An empty string counts as absent (the editor's cleared field).
+      const optionalUrl = (v: unknown): string | undefined | null => {
+        if (v === undefined || v === null) return undefined;
+        if (typeof v !== 'string') return null;
+        const trimmed = v.trim();
+        return trimmed ? trimmed : undefined;
+      };
+      const authorizationUrl = optionalUrl(o.authorizationUrl);
+      const tokenUrl = optionalUrl(o.tokenUrl);
+      const resource = optionalUrl(o.resource);
+      if (authorizationUrl === null || tokenUrl === null || resource === null) return null;
+      if ((authorizationUrl === undefined) !== (tokenUrl === undefined)) return null;
       // The same https + SSRF gate the `.tool` parser runs on these URLs: a
       // sign-in or token exchange aimed at an internal host is a declaration
-      // this surface must refuse exactly like the other one does.
+      // this surface must refuse exactly like the other one does. `resource`
+      // is never fetched, but it names the remote server — same bar.
       try {
-        assertSafeFetchUrl(o.authorizationUrl, { requireHttps: true, label: `${entry.name} oauth.authorizationUrl` });
-        assertSafeFetchUrl(o.tokenUrl, { requireHttps: true, label: `${entry.name} oauth.tokenUrl` });
+        if (authorizationUrl !== undefined) {
+          assertSafeFetchUrl(authorizationUrl, { requireHttps: true, label: `${entry.name} oauth.authorizationUrl` });
+          assertSafeFetchUrl(tokenUrl!, { requireHttps: true, label: `${entry.name} oauth.tokenUrl` });
+        }
+        if (resource !== undefined) {
+          assertSafeFetchUrl(resource, { requireHttps: true, label: `${entry.name} oauth.resource` });
+        }
       } catch {
         return null;
       }
@@ -138,14 +158,18 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
           return null;
         }
       }
+      // PKCE is on unless the declaration says `false`; anything else there is
+      // a malformed flag, not a preference.
+      if (o.pkce !== undefined && typeof o.pkce !== 'boolean') return null;
       oauth = {
-        authorizationUrl: o.authorizationUrl,
-        tokenUrl: o.tokenUrl,
+        ...(authorizationUrl !== undefined ? { authorizationUrl, tokenUrl: tokenUrl! } : {}),
         clientId: o.clientId.trim(),
         ...(Array.isArray(o.scopes) && o.scopes.every((s) => typeof s === 'string')
           ? { scopes: o.scopes as string[] }
           : {}),
         ...(o.authParams !== undefined ? { authParams: o.authParams as Record<string, string> } : {}),
+        ...(o.pkce === false ? { pkce: false } : {}),
+        ...(resource !== undefined ? { resource } : {}),
       };
     }
     out.push({

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -209,7 +209,8 @@ export class McpServerEditService {
       throw new McpServerEditError(
         'The `variables` declaration is malformed — each entry needs a unique, non-reserved ' +
           'alphanumeric/underscore name, a scope of `admin` or `user`, and any `oauth` block must sit ' +
-          'on a `user`-scoped variable with valid https provider URLs and a client id.',
+          'on a `user`-scoped variable with a client id and never a client secret; its provider URLs are ' +
+          'optional (discovered from the server) but must be valid https URLs, both or neither, when given.',
         422,
       );
     }

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

@@ -30,10 +30,17 @@ export type ToolVariableScope = 'admin' | 'user';
  * present, the variable's value is obtained by signing in with this provider
  * (the per-user secret row is `kind:'oauth'`), rather than being typed. The
  * confidential client secret is provisioned separately by a tool writer.
+ *
+ * The endpoints are OPTIONAL for an `mcp.json` server: an MCP-spec server
+ * publishes its authorization-server metadata, so a declaration carrying only
+ * the `clientId` of an owner-registered app is completed at scan time
+ * (`authorizationUrl`/`tokenUrl`/`resource` filled in from that metadata). A
+ * `.tool` manual has no server to ask, so there both URLs are required.
  */
 export interface ToolVariableOAuth {
-  authorizationUrl: string;
-  tokenUrl: string;
+  /** Absent on an mcp.json server ⇒ discovered from the server's OAuth metadata. */
+  authorizationUrl?: string;
+  tokenUrl?: string;
   clientId: string;
   scopes?: string[];
   /**
@@ -45,6 +52,20 @@ export interface ToolVariableOAuth {
    * secret is still provisioned only through the protected route.
    */
   authParams?: Record<string, string>;
+  /**
+   * PKCE (S256) on the authorization-code flow. ON unless explicitly `false`:
+   * the MCP authorization spec requires it, and a provider that doesn't
+   * implement it ignores the extra parameters (RFC 6749 §3.1). Only `false` is
+   * ever stored — absent means the default.
+   */
+  pkce?: boolean;
+  /**
+   * RFC 8707 resource indicator — the MCP server's canonical URL, so the token
+   * is audience-bound. Filled in from the server's metadata for an mcp.json
+   * server; declare it by hand only when the provider demands it and the
+   * endpoints are declared by hand too.
+   */
+  resource?: string;
 }
 
 /**
@@ -74,14 +95,18 @@ export interface ToolVariable {
  *  - `open`         — the server needs no auth; nothing to configure.
  *  - `oauth-auto`   — OAuth was auto-configured; the sign-in appears as a
  *                     `user`-scoped variable, so users just authorize.
- *  - `oauth-manual` — the server needs OAuth but auto-discovery couldn't set it
- *                     up (typically no dynamic client registration, e.g. Google);
- *                     a tool writer must declare the provider in the `.tool` file
- *                     and set its client secret. `reason` says exactly why.
+ *  - `oauth-manual` — the server needs OAuth with an OWNER-REGISTERED client:
+ *                     auto-discovery couldn't register one (typically no dynamic
+ *                     client registration — Google, HubSpot), or the declaration
+ *                     already names a client id. A tool writer declares the
+ *                     sign-in on a `user`-scoped variable (the server editor for
+ *                     an `mcp.json` server; the `variables` block of a `.tool`)
+ *                     and sets its client secret. `reason` is present only while
+ *                     something is still missing, and says exactly what.
  */
 export interface ToolManualSetup {
   kind: 'open' | 'oauth-auto' | 'oauth-manual';
-  /** Why auto-setup didn't complete — present for `oauth-manual`. */
+  /** What still blocks the sign-in — present for an unfinished `oauth-manual`. */
   reason?: string;
 }
 
@@ -224,8 +249,14 @@ export interface IToolManualService {
    * (the remote MCP proxy), LOCAL-ONLY manuals (`remote: false`) are excluded.
    */
   toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]>;
-  /** The `{ name, path }` of the caller's accessible LOCAL-ONLY (`remote: false`) manuals. */
-  listLocalOnly(userEmail: string): Promise<{ name: string; path: string }[]>;
+  /**
+   * The caller's accessible LOCAL-ONLY (`remote: false`) manuals.
+   *
+   * `slug` rides along with `name` and `path` because a local runtime needs
+   * both: `name` is the UTCP namespace its `${VAR}` refs are keyed by, and
+   * `slug` is what addresses the manual on the variable-resolution route.
+   */
+  listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]>;
   /** The embedded UTCP manual for an inline `.tool` (served at `/api/tools/:slug/manual`). */
   resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null>;
   /** Validate a draft `.tool` file's content for the renderer preview. */