@lanes-sh/link 0.1.0

package/src/server/mcp/instructions.ts

@@ -0,0 +1,245 @@
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import type { MergedCapability } from './visibility.ts';
+
+/**
+ * What the endpoint says about itself, in the `initialize` response.
+ *
+ * A client that has just connected holds sixty tools with good individual
+ * descriptions and no account of what the thing *is* — that there is memory
+ * worth consulting before answering from nothing, that a skill is the owner's
+ * own procedure rather than a suggestion, that `profile` is how someone keeps
+ * work and personal apart and is therefore never a field to guess at. Every one
+ * of those is a habit, and a habit does not fit in a tool description.
+ *
+ * MCP has one field for this and we were not using it. It is the only channel
+ * that reaches a client with no skills directory and no config we may write —
+ * so it carries the part that must arrive everywhere, and the bundled skill
+ * carries the longer form for the two harnesses that can hold one.
+ *
+ * **Generated, not written.** The prose below is fixed; the facts under it are
+ * this principal's, computed from the same policy-filtered set the tools were
+ * registered from. It is rebuilt per request over HTTP, so it cannot describe a
+ * profile that has gone away or omit one that was added.
+ *
+ * Two constraints on editing it:
+ *
+ * - **Length is a recurring cost.** This lands in the system prompt of every
+ *   session, so a paragraph added here is paid for on every request forever.
+ *   `instructions.test.ts` holds a budget.
+ * - **No vendor may be named.** `src/architecture.test.ts` forbids it anywhere
+ *   under `server/`, and rightly: the list below is whatever the owner has
+ *   connected, and prose that named one would be wrong for everybody else.
+ */
+
+/**
+ * The habits, in the order they are needed.
+ *
+ * Routing first because it gates every call; refusals last because that is when
+ * an agent is most tempted to improvise. Second person, and specific about what
+ * *not* to do — "ask which profile" is advice, "do not default to the first" is
+ * a rule.
+ *
+ * **Four of these are conditional**, and that is a correctness property rather
+ * than a saving. This used to be one fixed string that told every client to
+ * consult memory, invoke skills, and guard vault values — on an endpoint
+ * granting none of the three, which is the common case for a workspace that
+ * connected a mailbox and nothing else. Prose describing tools that are not
+ * there is worse than absent prose: it is a promise the tool list contradicts,
+ * and an agent resolves that by guessing. The saving is real too, and it is
+ * what pays for `SETUP` fitting inside the budget below.
+ *
+ * The opening no longer enumerates what is here for the same reason. The
+ * listing at the end says what is reachable, computed rather than asserted.
+ */
+const OPENING = `This endpoint is one place to reach what its owner has chosen to expose. It
+authenticates, applies permissions, and records what happened, so you do not
+have to.`;
+
+const ROUTING = `**Routing.** Every tool takes \`profile\` and \`connection\`. A profile is how
+someone separates work from personal — when it is ambiguous which one is meant,
+ask. Do not default to whichever is listed first.`;
+
+const MEMORY = `**Memory is worth consulting.** Before concluding you do not know something
+about this person or their work, search it. Writing to memory is a separate
+grant, and what you write is served back to every later session — including to
+a different agent — so write when asked to remember something, not by habit.`;
+
+const SKILLS = `**Skills are the owner's procedures**, surfaced as prompts rather than tools.
+That is deliberate: a procedure is selected by the person, not chosen by the
+model, and you cannot read one's body. They belong to one profile, so a skill
+you saw under one is not available under another. If a task has a skill for it,
+say so and let them invoke it rather than improvising your own version.`;
+
+const VAULT = `**Vault values are credentials.** Use one to do the thing that needs it. Do not
+quote it back, summarise it, or write it anywhere.`;
+
+/**
+ * The one that exists because its absence was observed, not predicted.
+ *
+ * Asked to connect a second mailbox, a client with no setup surface and no
+ * skill answered that it could not and then invented the procedure — edit the
+ * profile YAML, run "the auth command" — neither of which is a thing. It had
+ * no way to know `setup_overview` answers exactly that, so the instruction has
+ * to arrive here: this is the only channel that reaches a client which has
+ * merely been pointed at the URL.
+ */
+const SETUP = `**What is set up is answerable.** Before saying something cannot be reached, or
+that an account must be added, call \`setup_overview\` — then \`setup_provider\`
+for the exact command. Running it is the owner's to do; inventing it is not.`;
+
+const FILES = `**Files are named, not carried.** Where a tool takes attachments, give a path, an
+HTTPS URL, or an attachment already on another message; the endpoint reads the
+bytes. Never encode a file into a call — that is the thing this replaces.`;
+
+const REFUSAL = `**A refused call is the permission system working**, not an obstacle to route
+around. Report what was refused and let the owner decide whether to widen it.
+Every call, including a refused one, is recorded.`;
+
+/** Which paragraph each owner-layer provider brings, when it is reachable. */
+const OWNER_HABITS: Record<string, string> = {
+  memory: MEMORY,
+  skills: SKILLS,
+  vault: VAULT,
+  setup: SETUP,
+};
+
+/**
+ * The whole string's ceiling, and the only budget there is.
+ *
+ * This lands in the system prompt of every session against this endpoint, so a
+ * paragraph added here is paid for on every request forever. Needing to raise
+ * it is the prompt to ask whether the paragraph belongs in the skill instead,
+ * where it is loaded only when relevant.
+ *
+ * Exported because the test asserted `2000` as a literal while the code
+ * reserved room against a second, differently-derived number — so the two could
+ * disagree, and did. There is no separate listing allowance any more: `spent`
+ * measures the prose that was actually assembled, and `spent + form.length` is
+ * exactly the final length, because `join` adds the same two characters the
+ * reduce already counted.
+ */
+export const MAX_INSTRUCTIONS = 2000;
+
+/** Which of the owner-layer providers this principal can actually reach. */
+function ownerProviders(merged: ReadonlyMap<string, MergedCapability>): string[] {
+  const present = new Set<string>();
+
+  for (const id of merged.keys()) {
+    const provider = id.slice(0, id.indexOf('.'));
+    if (RESERVED_PROVIDER_IDS.includes(provider)) present.add(provider);
+  }
+
+  return RESERVED_PROVIDER_IDS.filter((id) => present.has(id));
+}
+
+/**
+ * The connections each profile contributes, deduplicated.
+ *
+ * Taken from `merged` rather than from each profile's config, so it lists what
+ * is *reachable* rather than what is configured. A connection the principal has
+ * no grant for is not registered on any tool, and announcing it here would
+ * describe a door that does not open.
+ */
+function connectionsByProfile(
+  profiles: readonly string[],
+  merged: ReadonlyMap<string, MergedCapability>,
+): Map<string, string[]> {
+  const found = new Map<string, Set<string>>();
+
+  for (const entry of merged.values()) {
+    for (const [profile, connections] of entry.reachable) {
+      const known = found.get(profile) ?? new Set<string>();
+      for (const connection of connections) known.add(connection);
+      found.set(profile, known);
+    }
+  }
+
+  // Ordered by the served list rather than by discovery, so the listing is
+  // stable between requests and reads the same as everywhere else.
+  const listed = new Map<string, string[]>();
+  for (const profile of profiles) {
+    const known = found.get(profile);
+    if (known) listed.set(profile, [...known].sort());
+  }
+
+  return listed;
+}
+
+/**
+ * Profile *names*, not runtimes: this needs the order they are served in and
+ * nothing else, and a signature that asked for more would imply it reads more.
+ */
+export function serverInstructions(
+  profiles: readonly string[],
+  merged: ReadonlyMap<string, MergedCapability>,
+): string {
+  const reachable = connectionsByProfile(profiles, merged);
+  const owner = ownerProviders(merged);
+
+  // Assembled per principal, because the owner layer is granted per principal.
+  // `ownerProviders` is already ordered by `RESERVED_PROVIDER_IDS`, so the
+  // paragraphs keep one order between requests rather than discovery order.
+  const sections = [
+    OPENING,
+    ROUTING,
+    ...owner.map((id) => OWNER_HABITS[id]).filter((habit): habit is string => habit !== undefined),
+    FILES,
+    REFUSAL,
+  ];
+
+  if (reachable.size === 0) {
+    // Not an error state worth hiding: a workspace with no connection yet, or a
+    // principal granted nothing, both land here, and saying so beats a heading
+    // with nothing under it.
+    sections.push(
+      'Nothing is reachable through this endpoint yet — no connection is both configured and permitted.',
+    );
+    return sections.join('\n\n');
+  }
+
+  const lines = [...reachable].map(
+    ([profile, connections]) => `  ${profile}: ${connections.join(', ')}`,
+  );
+  const listing = `Reachable now, by profile:\n${lines.join('\n')}`;
+
+  // The prose above varies per principal; this listing grows with the workspace.
+  // Either can be the half that does not fit, so all three widths are measured
+  // against the one ceiling rather than against a reserve guessed in advance —
+  // which is how a workspace of one profile and one mailbox ended up being told
+  // "1 profiles" with a hundred characters of the budget unspent.
+  //
+  // Summarising rather than truncating, and safe to do: every tool carries the
+  // connections it accepts in its own `connection` enum, which is the
+  // authoritative list. This paragraph is orientation, so a count and the profile
+  // names lose nothing an agent cannot get exactly.
+  const total = [...reachable.values()].reduce((sum, list) => sum + list.length, 0);
+  const names = [...reachable.keys()];
+  const tail = "Each tool's `connection` argument lists the ones it accepts.";
+  const plural = names.length === 1 ? 'profile' : 'profiles';
+
+  // Widest first. The last is bounded — it names no profile — which is what
+  // makes the ceiling hold for a workspace of any size.
+  const forms = [
+    listing,
+    `Reachable now: ${total} connections across ${names.join(', ')}. ${tail}`,
+    `Reachable now: ${total} connections across ${names.length} ${plural}. ${tail}`,
+  ];
+
+  const spent = sections.reduce((count, section) => count + section.length + 2, 0);
+
+  // Every candidate is checked, including the last: it is shorter than naming
+  // twenty profiles but not shorter than naming one, so choosing it unmeasured
+  // both overran the budget in one direction and wasted it in the other. If
+  // nothing fits, the shortest is the most honest thing left to say.
+  sections.push(
+    forms.find((form) => spent + form.length < MAX_INSTRUCTIONS) ??
+      forms.reduce((shortest, form) => (form.length < shortest.length ? form : shortest)),
+  );
+
+  // No trailing "the owner's own material is here too, under: …" line any more.
+  // Each of those providers now brings its own paragraph when it is reachable,
+  // so the list repeated what the prose had just said — and it swept `setup`
+  // in with memory, skills and vault, which it is not: it holds none of the
+  // owner's material and only describes what the others are.
+  return sections.join('\n\n');
+}

package/src/server/mcp/naming.ts

@@ -0,0 +1,39 @@
+/**
+ * Capability ids on the wire.
+ *
+ * MCP tool names are restricted to `[A-Za-z0-9_-]`, so the dotted capability id
+ * becomes `gmail_search` on the wire. The dotted form stays canonical
+ * everywhere it matters — config, policy rules, audit records — because that is
+ * what an operator reads and writes. Only the wire name is transliterated, and
+ * the mapping is total and reversible because provider ids and capability names
+ * both exclude `-`.
+ */
+
+export const SERVER_NAME = 'lanes-link';
+
+export function toolNameFor(capabilityId: string): string {
+  return capabilityId.replace(/\./g, '_');
+}
+
+/**
+ * Recover the capability id a wire name came from.
+ *
+ * Splitting on the first `_` was reversible while a capability name was one
+ * segment. It stopped being so when OpenAPI operationIds arrived dotted:
+ * `gmail_users_drafts_send` splits to `gmail.users_drafts_send`, which names
+ * nothing. That only shows up in the audit record for a refused tool — a log
+ * entry saying an agent tried something that does not exist, spelled wrongly,
+ * is worse than useless.
+ *
+ * So the known ids are consulted first, and the split is the fallback for a
+ * name matching no capability at all — where an approximate spelling is the
+ * best available and the attempt is what matters.
+ */
+export function capabilityIdForToolName(toolName: string, known?: Iterable<string>): string {
+  for (const id of known ?? []) {
+    if (toolNameFor(id) === toolName) return id;
+  }
+
+  const index = toolName.indexOf('_');
+  return index === -1 ? toolName : `${toolName.slice(0, index)}.${toolName.slice(index + 1)}`;
+}

package/src/server/mcp/prompts.ts

@@ -0,0 +1,78 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import { isPromptResult } from '#connectivity';
+import { toolNameFor } from './naming.ts';
+import { resolveScope } from './routing.ts';
+import { describeWithConnections, type BuildServerOptions, type MergedCapability } from './visibility.ts';
+
+/**
+ * Prompts — the owner's own procedures, surfaced as slash commands.
+ *
+ * Unlike a resource, a prompt *does* have arguments, so routing goes in them —
+ * ADR-001 rather than ADR-006's URI workaround. Both are optional and default
+ * when there is only one candidate, because a prompt's arguments are typically
+ * filled in by a person choosing a slash command, and making them type two
+ * routing strings to reach their only account would be a poor trade for
+ * consistency.
+ */
+export function registerPrompt(
+  server: McpServer,
+  id: string,
+  entry: MergedCapability,
+  capability: Extract<NonNullable<MergedCapability['capability']>, { kind: 'prompt' }>,
+  options: BuildServerOptions,
+): void {
+  const profiles = [...entry.reachable.keys()];
+  const connections = [...new Set([...entry.reachable.values()].flat())];
+
+  const shape: Record<string, z.ZodType> = {};
+
+  for (const argument of capability.arguments ?? []) {
+    const declared = z.string().describe(argument.description);
+    shape[argument.name] = argument.required ? declared : declared.optional();
+  }
+
+  shape['profile'] = z
+    .string()
+    .optional()
+    .describe(`Which profile to act within: ${profiles.join(', ')}. Omit if there is one.`);
+  shape['connection'] = z
+    .string()
+    .optional()
+    .describe(`Which configured account: ${connections.join(', ')}. Omit if there is one.`);
+
+  server.registerPrompt(
+    toolNameFor(id),
+    {
+      ...(capability.title ? { title: capability.title } : {}),
+      description: describeWithConnections(capability.description, entry.reachable),
+      argsSchema: z.object(shape),
+    },
+    async (args: Record<string, unknown>) => {
+      const { profile, connection, ...rest } = args;
+      const scope = resolveScope(entry, profile, connection);
+      if ('error' in scope) throw new Error(scope.error);
+
+      const outcome = await options.profiles.get(scope.profile)!.dispatcher.invoke({
+        principal: options.principal,
+        capabilityId: id,
+        connectionKey: scope.connectionKey,
+        arguments: rest,
+        clientLabel: options.clientLabel,
+      });
+
+      // A prompt has no `isError` to carry a refusal in, so a denial is a
+      // protocol error. That is the honest mapping: there is no partial prompt
+      // to hand back, and the message still says why.
+      if (!outcome.ok) throw new Error(outcome.message);
+      if (!isPromptResult(outcome.result)) throw new Error(`${id} did not return a prompt`);
+
+      return {
+        messages: outcome.result.messages.map((message) => ({
+          role: message.role,
+          content: { type: 'text' as const, text: message.text },
+        })),
+      };
+    },
+  );
+}

package/src/server/mcp/resources.ts

@@ -0,0 +1,106 @@
+import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/server';
+import { isResourceListResult, isResourceResult } from '#connectivity';
+import type { DispatchOutcome } from '#dispatch';
+import { toolNameFor } from './naming.ts';
+import { scopeResourceUri } from './routing.ts';
+import type { BuildServerOptions, MergedCapability } from './visibility.ts';
+
+/**
+ * Resources — read-oriented context, addressed rather than called.
+ *
+ * One registration per (profile, connection): a resource URI carries no
+ * argument to route on, so both have to live in the URI itself — ADR-006. A
+ * read still goes through the dispatcher like everything else, so a resource is
+ * policy-checked, rate-limited, and audited on exactly the terms a tool is.
+ */
+export function registerResource(
+  server: McpServer,
+  id: string,
+  entry: MergedCapability,
+  capability: Extract<NonNullable<MergedCapability['capability']>, { kind: 'resource' }>,
+  options: BuildServerOptions,
+): void {
+  for (const [profile, reachable] of entry.reachable) {
+    const runtime = options.profiles.get(profile)!;
+
+    for (const connectionKey of reachable) {
+      const connectionId = connectionKey.slice(connectionKey.indexOf('.') + 1);
+      const scope = { profile, connectionId };
+      const scoped = scopeResourceUri(capability.uriTemplate, scope);
+
+      const dispatch = (args: Record<string, unknown>): Promise<DispatchOutcome> =>
+        runtime.dispatcher.invoke({
+          principal: options.principal,
+          capabilityId: id,
+          connectionKey,
+          arguments: args,
+          clientLabel: options.clientLabel,
+        });
+
+      const metadata = {
+        description: `${capability.description} (${profile}: ${connectionKey})`,
+        ...(capability.mimeType ? { mimeType: capability.mimeType } : {}),
+      };
+
+      // `uri` is the whole argument — the provider recovers its own template
+      // variables from it and never sees the routing segments core prepended.
+      const read = async (uri: URL) => {
+        const outcome = await dispatch({ uri: uri.href });
+        if (!outcome.ok) throw new Error(outcome.message);
+        if (!isResourceResult(outcome.result)) {
+          throw new Error(`${id} did not return resource contents`);
+        }
+
+        return {
+          contents: outcome.result.contents.map((part) => ({
+            // The requested URI, not whatever the provider echoed: MCP requires
+            // them to match, and a provider returning its own unscoped form
+            // would produce contents a client cannot re-read.
+            uri: uri.href,
+            ...(part.mimeType ?? capability.mimeType
+              ? { mimeType: part.mimeType ?? capability.mimeType! }
+              : {}),
+            text: part.text,
+          })),
+        };
+      };
+
+      const name = `${toolNameFor(id)}_${profile}_${connectionId}`;
+
+      // A template with nothing to expand is a static resource, and the SDK
+      // wants it registered as one — that is what puts it in `resources/list`
+      // without a list callback.
+      if (!scoped.includes('{')) {
+        server.registerResource(name, scoped, metadata, read);
+        continue;
+      }
+
+      server.registerResource(
+        name,
+        new ResourceTemplate(scoped, {
+          // `undefined` is a deliberate value here, not an omission: the SDK
+          // requires the key so that forgetting to enumerate is a decision
+          // rather than an oversight. A provider omits `list` when its resource
+          // space is unbounded.
+          list: capability.list
+            ? async () => {
+                const outcome = await dispatch({});
+                if (!outcome.ok) throw new Error(outcome.message);
+                if (!isResourceListResult(outcome.result)) return { resources: [] };
+
+                return {
+                  resources: outcome.result.resources.map((resource) => ({
+                    name: resource.name,
+                    uri: scopeResourceUri(resource.uri, scope),
+                    ...(capability.mimeType ? { mimeType: capability.mimeType } : {}),
+                  })),
+                };
+              }
+            : undefined,
+        }),
+        metadata,
+        read,
+      );
+    }
+  }
+}

package/src/server/mcp/routing.ts

@@ -0,0 +1,117 @@
+import { isResource } from '#connectivity';
+import type { MergedCapability, ProfileRuntime } from './visibility.ts';
+
+/**
+ * Getting the profile and the connection into an address.
+ *
+ * A tool takes them as injected arguments (ADR-001). A resource has no argument
+ * to route on, so they go into the URI; a prompt has arguments but is typically
+ * filled in by a person choosing a slash command, so they are optional there and
+ * default when there is only one candidate.
+ */
+
+/**
+ * Put the profile and the connection into a resource URI.
+ *
+ * They have to go somewhere that works for *any* template, not just one that
+ * happens to spell `{key}`, so they are inserted as the first two path segments
+ * directly after the authority: `example://note/{key}` becomes
+ * `example://note/personal/a/{key}`, and `memory://entry/{id}` becomes
+ * `memory://entry/personal/owner/{id}`.
+ *
+ * The previous form substituted the literal token `{key}`, which meant any
+ * provider naming its variable anything else — every provider except `example` —
+ * registered a URI with no routing in it at all, and two connections would have
+ * collided on one address.
+ */
+export function scopeResourceUri(
+  uriOrTemplate: string,
+  scope: { profile: string; connectionId: string },
+): string {
+  const separator = uriOrTemplate.indexOf('://');
+  if (separator === -1) return uriOrTemplate;
+
+  const scheme = uriOrTemplate.slice(0, separator + 3);
+  const rest = uriOrTemplate.slice(separator + 3);
+  const slash = rest.indexOf('/');
+  const authority = slash === -1 ? rest : rest.slice(0, slash);
+  const path = slash === -1 ? '' : rest.slice(slash);
+
+  return `${scheme}${authority}/${scope.profile}/${scope.connectionId}${path}`;
+}
+
+/** `scheme://authority`, or empty for anything not shaped like that. */
+function originOf(uri: string): string {
+  const separator = uri.indexOf('://');
+  if (separator === -1) return '';
+
+  const rest = uri.slice(separator + 3);
+  const slash = rest.indexOf('/');
+  return uri.slice(0, separator + 3) + (slash === -1 ? rest : rest.slice(0, slash));
+}
+
+/**
+ * Route the `resource_link`s a tool hands back.
+ *
+ * A provider names its own resources — `memory://entry/deploy_window` — because
+ * it does not know, and must not learn, which profile or connection it is
+ * serving. Core does. Without this, `memory.search` returns addresses that look
+ * like resources and cannot be read, which is worse than returning none.
+ *
+ * Scoped **only** for a link whose scheme and authority match one of this
+ * provider's own resource templates. A link to somewhere else — an `https://`
+ * document a vendor returned — is left exactly as the vendor wrote it; inserting
+ * routing segments into someone else's URL would corrupt it.
+ */
+export function resourceLinkRouter(
+  runtime: ProfileRuntime,
+  capabilityId: string,
+  profile: string,
+  connectionKey: string,
+): (uri: string) => string {
+  const providerId = capabilityId.slice(0, capabilityId.indexOf('.'));
+  const definition = runtime.registry.get(providerId)?.definition;
+  if (!definition) return (uri) => uri;
+
+  const origins = new Set(
+    definition.capabilities
+      .filter(isResource)
+      .map((capability) => originOf(capability.uriTemplate)),
+  );
+  if (origins.size === 0) return (uri) => uri;
+
+  const connectionId = connectionKey.slice(connectionKey.indexOf('.') + 1);
+
+  return (uri) =>
+    origins.has(originOf(uri)) ? scopeResourceUri(uri, { profile, connectionId }) : uri;
+}
+
+/**
+ * Which profile and connection a prompt call meant.
+ *
+ * Same refusal a tool gets when a profile and a connection belong to different
+ * profiles, for the same reason: the enums are a union, and routing a `work`
+ * account through `personal` would cross exactly the boundary profiles exist to
+ * hold.
+ */
+export function resolveScope(
+  entry: MergedCapability,
+  profile: unknown,
+  connection: unknown,
+): { profile: string; connectionKey: string } | { error: string } {
+  const profiles = [...entry.reachable.keys()];
+  const name = typeof profile === 'string' ? profile : (profiles.length === 1 ? profiles[0]! : '');
+
+  const reachable = entry.reachable.get(name);
+  if (!reachable) {
+    return { error: `Name a profile: ${profiles.join(', ')}` };
+  }
+
+  const key =
+    typeof connection === 'string' ? connection : (reachable.length === 1 ? reachable[0]! : '');
+  if (!reachable.includes(key)) {
+    return { error: `Name a connection within profile "${name}": ${reachable.join(', ')}` };
+  }
+
+  return { profile: name, connectionKey: key };
+}

package/src/server/mcp/schema.ts

@@ -0,0 +1,78 @@
+/**
+ * Making a discovered schema safe to publish.
+ *
+ * Two problems, both arriving from vendors rather than from us, and both fixed
+ * here rather than per-provider so an upstream MCP server and a hand-written
+ * workspace manifest get the same treatment as Google's specs.
+ */
+
+/**
+ * Property names a tool schema may use.
+ *
+ * The Anthropic API enforces `^[a-zA-Z0-9_.-]{1,64}$` on every property key,
+ * and rejects the **entire** `tools` array when one fails — so a single bad key
+ * anywhere takes down every provider on the endpoint, not just its own. Google's
+ * specs ship `$.xgafv`, which is exactly that.
+ */
+const LEGAL_PROPERTY = /^[a-zA-Z0-9_.-]{1,64}$/;
+
+/**
+ * JSON Schema's own `format` values.
+ *
+ * Anything else is an OpenAPI or vendor annotation — `int64`, `uint64`,
+ * `float`, `byte`, Google's `google` — and a validator that does not recognise
+ * it logs a warning for every occurrence, every time a schema is compiled.
+ * Google's specs carry six such formats, which is where "unknown format uint64
+ * ignored" comes from.
+ */
+const STANDARD_FORMATS = new Set([
+  'date-time', 'date', 'time', 'duration',
+  'email', 'idn-email', 'hostname', 'idn-hostname',
+  'ipv4', 'ipv6', 'uri', 'uri-reference', 'uri-template',
+  'iri', 'iri-reference', 'uuid', 'regex',
+  'json-pointer', 'relative-json-pointer',
+]);
+
+/**
+ * **Illegal property names are dropped.** Dropping rather than renaming: the
+ * name is what the connector maps back to a request parameter, so a renamed key
+ * would arrive upstream as something the vendor does not recognise. A *required*
+ * property is left in place, to fail loudly rather than register a tool that can
+ * never be called correctly.
+ *
+ * **Non-standard `format` values are dropped.** They are annotations a JSON
+ * Schema validator has no rule for; it ignores them and says so, once per
+ * occurrence per compile. Removing them loses nothing — `type` still carries the
+ * constraint that matters — and removes a stream of warnings that buries
+ * anything worth reading.
+ */
+export function sanitizeSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  const walk = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(walk);
+    if (node === null || typeof node !== 'object') return node;
+
+    const record = node as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+
+    const required = new Set((record['required'] as string[] | undefined) ?? []);
+
+    for (const [key, value] of Object.entries(record)) {
+      if (key === 'format' && typeof value === 'string' && !STANDARD_FORMATS.has(value)) continue;
+
+      if (key === 'properties' && value !== null && typeof value === 'object') {
+        out[key] = Object.fromEntries(
+          Object.entries(value as Record<string, unknown>)
+            .filter(([name]) => LEGAL_PROPERTY.test(name) || required.has(name))
+            .map(([name, child]) => [name, walk(child)]),
+        );
+        continue;
+      }
+
+      out[key] = walk(value);
+    }
+
+    return out;
+  };
+
+  return walk(schema) as Record<string, unknown>;
+}