@lanes-sh/link 0.3.2 → 0.4.0

package/src/connectivity/auth/strategy/index.ts

@@ -1,10 +1,134 @@
+import type { AuthStrategy, AuthStrategyContext } from '../../connector.ts';
+import type { ProviderContext } from '../../context.ts';
+import type { ProviderDefinition } from '../../provider.ts';
+import type { ProviderManifest } from '../../manifest/index.ts';
+
 /**
  * The escape hatch: auth no declarative form should try to express.
  *
- * bunq generates an RSA keypair, runs a three-step handshake, signs every
- * request, and verifies the response signature. That earns code. Nothing is
- * registered yet, so this fails loudly rather than sending an unauthenticated
- * request that would fail confusingly upstream.
+ * A strategy is the one place per-vendor code is permitted outside `local`
+ * providers, and it stays *auth* — a request in, an authorised request out.
+ * The moment one starts translating endpoints, the problem ADR-008 removed has
+ * come back.
+ *
+ * There is no global registry here, and that is deliberate. A strategy is not a
+ * plugin the runtime discovers; it is a property of the provider that needs it,
+ * so it travels on that provider's `ProviderDefinition` the same way an authored
+ * capability does. Two things follow, both of them the point:
+ *
+ *   - this component stays free of vendor names, which is the rule
+ *     `architecture.test.ts` holds over everything a request passes through
+ *   - adding one is still a folder under `providers/` and a line in its index,
+ *     rather than a folder here plus a registration somewhere else
+ */
+
+/**
+ * What `strategyFor` needs from the registry, and no more.
+ *
+ * Structural rather than the real `ProviderRegistry`, so this file states its
+ * dependency as two methods instead of importing a component to name a type.
+ */
+export interface StrategySource {
+  get(id: string): { readonly definition?: ProviderDefinition | undefined } | undefined;
+  list(): readonly { readonly definition?: ProviderDefinition | undefined }[];
+}
+
+/**
+ * The strategy a manifest declares.
+ *
+ * Its own definition first, which is the built-in case: `providers/bunq`
+ * carries the code for the manifest beside it, and the two must agree about
+ * which strategy that is. A manifest naming `strategy: acme` while its
+ * definition carries something else is a wiring mistake that would otherwise
+ * surface as a signature the vendor rejects — a long way from its cause.
+ *
+ * Then any other registered provider that supplies one by that name, which is
+ * the case a declaration-only manifest needs. A workspace YAML in
+ * `providers.d/` is parsed into a `ProviderManifest` and has no definition at
+ * all, so without this it could name a strategy and never reach it — and naming
+ * one is exactly what a manifest is for. It is also the only way to point a
+ * connection at a vendor's sandbox, since a built-in manifest's `options` are
+ * not the operator's to edit.
+ *
+ * Borrowing the *code* is not borrowing the *credential*: the ref still derives
+ * from the manifest's own id, so `bunq_sandbox` reads `bunq_sandbox/<id>` and
+ * cannot reach what `bunq` holds.
+ */
+export function strategyFor(
+  manifest: ProviderManifest,
+  source: StrategySource,
+): AuthStrategy {
+  if (manifest.auth.kind !== 'strategy') {
+    throw new Error(`Provider "${manifest.id}" does not declare a strategy.`);
+  }
+
+  const named = manifest.auth.strategy;
+  const own = source.get(manifest.id)?.definition?.authStrategy;
+
+  if (own) {
+    if (own.id !== named) {
+      throw new Error(
+        `Provider "${manifest.id}" declares auth strategy "${named}" but carries "${own.id}".`,
+      );
+    }
+    return own;
+  }
+
+  const borrowed = source
+    .list()
+    .map((entry) => entry.definition?.authStrategy)
+    .find((strategy) => strategy?.id === named);
+
+  if (!borrowed) refuseStrategy(named);
+  return borrowed;
+}
+
+/**
+ * What a strategy is given, derived from what the provider is given.
+ *
+ * Narrower than a `ProviderContext` on purpose: the connection's own
+ * credentials read-only, its own scoped state, and its logger. Nothing else,
+ * and in particular no storage, no audit logger, and no signal — a strategy
+ * authenticates a request and has no business doing anything a provider does.
+ *
+ * `write` is the one part that varies, and the variation *is* the rule.
+ * Persisting a credential is a setup-time act, so `connect` passes a writer and
+ * the dispatch path does not. Per-request code then cannot store a credential
+ * because there is nothing on the object to store one with, rather than because
+ * somebody remembered not to.
+ *
+ * Takes the three fields it reads rather than a whole `ProviderContext`, so the
+ * two callers can be what they are: dispatch hands over the context it already
+ * built, and `connect` — which has no provider context, because the connection
+ * does not exist yet — assembles the same three from the runtime.
+ */
+export function strategyContextFrom(input: {
+  /** Dispatch hands over the `ProviderContext` it built; `connect` assembles the three itself. */
+  readonly source: Pick<ProviderContext, 'credentials' | 'state' | 'log'>;
+  readonly manifest: ProviderManifest;
+  readonly connectionId: string;
+  readonly profile: string;
+  readonly write?: ((ref: string, value: string) => Promise<void>) | undefined;
+}): AuthStrategyContext {
+  const { source, manifest, connectionId, profile, write } = input;
+
+  return {
+    manifest,
+    connectionId,
+    profile,
+    credentials: source.credentials,
+    state: source.state,
+    log: source.log,
+    options: manifest.auth.kind === 'strategy' ? (manifest.auth.options ?? {}) : {},
+    ...(write ? { write } : {}),
+  };
+}
+
+/**
+ * A manifest asked for a strategy nothing supplies.
+ *
+ * Fails loudly rather than sending an unauthenticated request, which would fail
+ * upstream with an error about the vendor rather than about the wiring.
  */
 export function refuseStrategy(strategy: string): never {
   throw new Error(

package/src/connectivity/connector.ts

@@ -159,6 +159,17 @@ export interface AuthStrategy {
 export interface AuthStrategyContext {
   readonly manifest: ProviderManifest;
   readonly connectionId: string;
+  /**
+   * Which profile this is acting for.
+   *
+   * Nothing about authenticating one request needs it. What needs it is any
+   * strategy that keeps something in process memory: one endpoint serves every
+   * profile in the workspace from one process, so `<provider>.<connection>` is
+   * not a unique key — two profiles each holding a bunq connection called
+   * `main` would share whatever it named. `state` and `credentials` are already
+   * scoped per profile and a cache in front of them must be too.
+   */
+  readonly profile: string;
   /** Read-only, scoped to this connection — the same boundary providers get. */
   readonly credentials: ProviderContext['credentials'];
   /**

package/src/connectivity/index.ts

@@ -48,7 +48,17 @@ export {
  * Everything else is a manifest.
  */
 export type { AuthRequirement, ProviderDefinition } from './provider.ts';
-export { defineLocalProvider, defineProviderWithCapabilities } from './provider.ts';
+export {
+  defineLocalProvider,
+  defineProviderWithCapabilities,
+  defineProviderWithStrategy,
+} from './provider.ts';
+
+/**
+ * The strategy seam. Vendor-free by construction: these three know that a
+ * strategy exists and never which one.
+ */
+export { refuseStrategy, strategyContextFrom, strategyFor } from './auth/strategy/index.ts';
 
 export type {
   ProviderManifest,

package/src/connectivity/manifest/auth.ts

@@ -164,6 +164,25 @@ export const authOAuthSchema = z.object({
    */
   authorize_url: z.url().optional(),
   token_url: z.url().optional(),
+  /**
+   * A loopback redirect to name to the vendor verbatim, for one that matches it
+   * exactly rather than by prefix.
+   *
+   * `connect` normally listens on a port the kernel picks, which works because
+   * most authorization servers accept any loopback port. One that pins the
+   * whole URL cannot: the port it was told in a console months ago is not the
+   * port this run happens to get, and the grant is refused with
+   * `redirect_uri_mismatch`.
+   *
+   * The full URL rather than a port, because the vendor's console decides the
+   * spelling — `localhost` and `127.0.0.1` are different strings to a matcher
+   * even when they are the same host — and the two must be identical.
+   *
+   * Mutually exclusive with `broker`, which answers the same question the other
+   * way: there the redirect is the broker's HTTPS origin and the loopback port
+   * travels in `state`.
+   */
+  redirect_uri: z.url().optional(),
   /**
    * Extra parameters on the authorization request.
    *

package/src/connectivity/manifest/connector.ts

@@ -56,6 +56,27 @@ export const httpConnectorSchema = z.object({
       exclude: z.array(z.string()).default([]),
     })
     .optional(),
+  /**
+   * Sent on every request this connector makes.
+   *
+   * The same field as `mcp`'s above and refused the same way for
+   * `Authorization` — but for the opposite reason. An mcp server chooses its
+   * own tool list and a header is the only way to ask it for less; a REST API
+   * asks for nothing, and this is for what the *vendor* requires of a client
+   * rather than what a caller wants from it.
+   *
+   * The case in hand is a `User-Agent`. Nothing else here sets one, so every
+   * install of this program looks identical to a host that rate-limits by
+   * client — and a service that asks callers to identify themselves throttles
+   * the default agent hardest, which reads as an outage rather than a refusal.
+   *
+   * Precedence is narrowest-wins: `accept` is a default this may override, a
+   * header parameter the operation itself declares overrides this, and
+   * `content-type` is derived from the document and overrides everything —
+   * a blanket header cannot silently change how one operation's body is
+   * encoded.
+   */
+  headers: z.record(z.string(), z.string()).optional(),
 });
 
 /**

package/src/connectivity/manifest/primitives.ts

@@ -16,5 +16,9 @@ export const credentialRef = z
   .string()
   .regex(
     /^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)+$/,
-    'must be a credential reference like "bunq/api_key", not a literal value',
+    // A placeholder rather than a real provider id. The example teaches the
+    // shape either way, and this file is inside the scope
+    // `architecture.test.ts` keeps free of vendor names — an error message that
+    // names one is exactly the "message that assumes a vendor" the rule is for.
+    'must be a credential reference like "acme/api_key", not a literal value',
   );

package/src/connectivity/manifest/provider.ts

@@ -225,6 +225,36 @@ export function defineProvider(input: unknown): ProviderManifest {
     );
   }
 
+  // Two answers to "where does the browser come back to", and a manifest
+  // naming both leaves it to whichever the flow reads first. A broker's
+  // redirect is its own HTTPS origin, with the loopback port carried in
+  // `state`; a fixed redirect is this machine, named exactly. Neither is wrong,
+  // but they cannot both be in force.
+  if (manifest.auth.kind === 'oauth' && manifest.auth.broker && manifest.auth.redirect_uri) {
+    throw new Error(
+      `Provider "${manifest.id}": auth may declare "broker" or "redirect_uri", not both — a brokered flow redirects to the broker and carries the loopback port in state, so a fixed redirect would never be used.`,
+    );
+  }
+
+  // Connector headers are for what the *server* offers as configuration; the
+  // credential is the auth block's, and a manifest setting both would have one
+  // quietly overwrite the other depending on which the transport merged last.
+  //
+  // Checked for every connector that has the field rather than for `mcp` alone.
+  // It was written when `mcp` was the only one, and the reasoning never had
+  // anything to do with which transport carried the header — an `http`
+  // connector naming `Authorization` collides with `auth` in exactly the same
+  // way, and would have validated cleanly.
+  const connectorHeaders =
+    'headers' in manifest.connector ? (manifest.connector.headers ?? {}) : {};
+  for (const name of Object.keys(connectorHeaders)) {
+    if (name.toLowerCase() === 'authorization') {
+      throw new Error(
+        `Provider "${manifest.id}": connector.headers may not set "${name}" — the credential comes from auth, and setting both would leave which one is sent up to merge order.`,
+      );
+    }
+  }
+
   if (manifest.connector.kind === 'mcp') {
     const auth = manifest.auth;
 
@@ -250,18 +280,6 @@ export function defineProvider(input: unknown): ProviderManifest {
         `Provider "${manifest.id}": an mcp connector always sends its token as "Authorization: Bearer", so auth.header ("${auth.header}") cannot be honoured. Remove it, or reach this service with an http connector.`,
       );
     }
-
-    // The third spelling of the same collision. Connector headers are for what
-    // the *server* offers as configuration; the credential is the auth block's,
-    // and a manifest setting both would have one quietly overwrite the other
-    // depending on which the transport merged last.
-    for (const name of Object.keys(manifest.connector.headers ?? {})) {
-      if (name.toLowerCase() === 'authorization') {
-        throw new Error(
-          `Provider "${manifest.id}": connector.headers may not set "${name}" — the credential comes from auth, and setting both would leave which one is sent up to merge order.`,
-        );
-      }
-    }
   }
 
   const names = new Set<string>();

package/src/connectivity/provider.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { SecretRef } from '#secrets';
 import type { Capability } from './capability.ts';
+import type { AuthStrategy } from './connector.ts';
 import type { ProviderContext } from './context.ts';
 import { bundleSchema, defineProvider, type ProviderManifest } from './manifest/index.ts';
 
@@ -32,6 +33,16 @@ export interface ProviderDefinition<
 
   readonly capabilities: readonly Capability[];
 
+  /**
+   * Pluggable auth, for a vendor whose handshake no manifest field can describe.
+   *
+   * Carried here rather than in a registry the runtime searches, because a
+   * strategy belongs to exactly one provider and nothing else may use it. The
+   * manifest declares *that* there is one and names it; this is the code, and
+   * `strategyFor` checks the two agree.
+   */
+  readonly authStrategy?: AuthStrategy;
+
   /**
    * Which credential refs a connection may read. Core turns this into the
    * allowlist behind `ProviderContext.credentials`, so a provider cannot reach
@@ -161,3 +172,47 @@ export function defineProviderWithCapabilities(input: {
     capabilities: input.capabilities,
   };
 }
+
+/**
+ * A manifest-based provider whose authentication is code rather than a field.
+ *
+ * The sibling of `defineProviderWithCapabilities`, and rarer. That one exists
+ * where a vendor's API can do something its *document* cannot express; this one
+ * where a vendor's **handshake** can. Everything else about the provider stays
+ * declared — the connector kind, the operations, the redaction — and the
+ * strategy only ever sees a request on its way out and a response on its way
+ * back.
+ *
+ * ADR-008 puts a number on how much this is allowed to be: roughly 150 lines,
+ * for auth, once. A strategy that grows a second job is the 612-line problem
+ * returning by a different door.
+ */
+export function defineProviderWithStrategy(input: {
+  readonly manifest: ProviderManifest;
+  readonly strategy: AuthStrategy;
+  readonly capabilities?: readonly Capability[];
+}): ProviderDefinition {
+  const { manifest, strategy } = input;
+
+  if (manifest.auth.kind !== 'strategy') {
+    throw new Error(
+      `Provider "${manifest.id}" carries an auth strategy but declares auth.kind "${manifest.auth.kind}". Declare { kind: 'strategy', strategy: '${strategy.id}' }.`,
+    );
+  }
+
+  if (manifest.auth.strategy !== strategy.id) {
+    throw new Error(
+      `Provider "${manifest.id}" declares auth strategy "${manifest.auth.strategy}" but carries "${strategy.id}".`,
+    );
+  }
+
+  return {
+    manifest,
+    // Permissive for the same reason `defineProviderWithCapabilities` is: a
+    // manifest provider's connection is already described by its manifest.
+    configSchema: z.unknown(),
+    connectionSchema: z.unknown(),
+    capabilities: input.capabilities ?? [],
+    authStrategy: strategy,
+  };
+}

package/src/connectivity/transports/factory.ts

@@ -180,6 +180,7 @@ function build(
         ...(manifest.connector.operations?.exclude?.length
           ? { exclude: manifest.connector.operations.exclude }
           : {}),
+        ...(manifest.connector.headers ? { headers: manifest.connector.headers } : {}),
       });
   }
 }

package/src/connectivity/transports/http/index.ts

@@ -26,9 +26,70 @@ export interface HttpConnectorOptions {
   readonly openapi: string;
   readonly include?: readonly string[];
   readonly exclude?: readonly string[];
+  /** Sent on every request. Never `Authorization` — the manifest refuses it. */
+  readonly headers?: Readonly<Record<string, string>>;
   readonly fetch?: typeof globalThis.fetch;
 }
 
+/**
+ * The one body encoding that is not JSON often enough to be worth knowing about.
+ *
+ * A form-encoded write is not a legacy curiosity: it is what a large share of
+ * APIs that predate JSON request bodies still require, and one of them refusing
+ * `application/json` is not a negotiation — the request fails outright, with an
+ * error about the parameters rather than about the encoding.
+ */
+const FORM_ENCODED = 'application/x-www-form-urlencoded';
+
+/**
+ * What the *document* says the body is, rather than what we would prefer.
+ *
+ * `mcp-from-openapi` records the declared media type on each body entry of the
+ * mapper, so this needs nothing threaded through `target` — the mapper is
+ * already cached there, which is what lets a cold instance encode correctly
+ * without re-reading the spec.
+ *
+ * JSON is the default because an operation with no declared request body has no
+ * media type to read, and because it is what this connector always sent.
+ */
+function bodyContentType(mapper: readonly ParameterMapper[]): string {
+  for (const entry of mapper) {
+    if (entry.type !== 'body') continue;
+    const declared = entry.serialization?.contentType;
+    if (declared) return declared;
+  }
+
+  return 'application/json';
+}
+
+/**
+ * Arrays repeat rather than join, for the reason the query string does above.
+ *
+ * A nested object is JSON inside the field, which is the only thing a
+ * form-encoded body can do with one — there is no standard spelling of nesting
+ * here, and every API that accepts one accepts it as a string.
+ */
+function encodeBody(body: Readonly<Record<string, unknown>>, contentType: string): string {
+  if (!contentType.startsWith(FORM_ENCODED)) return JSON.stringify(body);
+
+  const form = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      for (const element of value) {
+        if (element !== undefined && element !== null) form.append(key, String(element));
+      }
+      continue;
+    }
+
+    form.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+  }
+
+  return form.toString();
+}
+
 /**
  * `*` matches any run of characters; anything else is literal.
  *
@@ -148,6 +209,12 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
 
       const url = new URL(options.baseUrl.replace(/\/$/, '') + buildPath(template, args, mapper));
       const headers = new Headers({ accept: 'application/json' });
+
+      // After `accept`, which is a default worth overriding, and before the
+      // operation's own header parameters, which are narrower than a header
+      // declared once for the whole connector.
+      for (const [key, value] of Object.entries(options.headers ?? {})) headers.set(key, value);
+
       const body = collect(args, mapper, 'body');
 
       for (const [key, value] of Object.entries(collect(args, mapper, 'query'))) {
@@ -174,7 +241,11 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
       }
 
       const hasBody = Object.keys(body).length > 0;
-      if (hasBody) headers.set('content-type', 'application/json');
+      const contentType = bodyContentType(mapper);
+      // Last, so it beats a connector-wide header. Which encoding an operation
+      // uses is the document's to state, and a blanket `content-type` that
+      // silently changed it would be a bug nobody could see from the manifest.
+      if (hasBody) headers.set('content-type', contentType);
 
       // Auth is attached by core, from the manifest's auth kind or its strategy.
       // A connector never sees a raw credential.
@@ -182,7 +253,7 @@ export function createHttpConnector(options: HttpConnectorOptions): Connector {
         new Request(url.href, {
           method,
           headers,
-          ...(hasBody ? { body: JSON.stringify(body) } : {}),
+          ...(hasBody ? { body: encodeBody(body, contentType) } : {}),
           signal: context.provider.signal,
         }),
       );

package/src/dispatch/dispatch.ts

@@ -6,8 +6,14 @@ import type { RuntimeState } from '#stores/state';
 import type { PolicyDocument } from '#policy';
 import { RateLimiter, evaluate } from '#policy';
 import type { BlobStore } from '#stores/blobs';
-import type { AnyConnector, CapabilityResult, ConnectorContext, Logger } from '#connectivity';
-import { isToolResult } from '#connectivity';
+import type {
+  AnyConnector,
+  AuthStrategyContext,
+  CapabilityResult,
+  ConnectorContext,
+  Logger,
+} from '#connectivity';
+import { isToolResult, strategyContextFrom, strategyFor } from '#connectivity';
 import type { Config } from '#profile';
 import { buildProviderContext, createProviderLogger } from './context.ts';
 import { stageAttachment, type StagedAttachment, type StageRequest } from './staging.ts';
@@ -252,13 +258,38 @@ export class Dispatcher {
         },
       };
 
+      // A provider whose authentication is code rather than a manifest field.
+      // The strategy stands in for the credential resolver completely: it holds
+      // whatever session the vendor issues, signs the outbound request, and
+      // checks the reply. Looked up once, because both halves of the connector
+      // context come from the same one.
+      const strategy =
+        entry.manifest.auth.kind === 'strategy'
+          ? strategyFor(entry.manifest, this.#deps.registry)
+          : undefined;
+
+      // Derived from the provider context — which is handed the closure below,
+      // so it cannot exist yet. Both are only ever *called* after this block
+      // finishes, and memoising keeps one context per invocation rather than
+      // one per outbound request.
+      let strategyContext: AuthStrategyContext | undefined;
+      const forStrategy = (): AuthStrategyContext =>
+        (strategyContext ??= strategyContextFrom({
+          source: providerContext,
+          manifest: entry.manifest,
+          connectionId: declared.id,
+          profile: this.#deps.config.instance.profile,
+        }));
+
       // One closure, handed to both contexts. A provider that authors a
       // capability its transport cannot express still calls the vendor through
       // the same authorizer the transport would have used.
       const authorize = (outbound: Request): Promise<Request> =>
-        this.#deps.authorizeRequest
-          ? this.#deps.authorizeRequest(providerId, declared.id, outbound)
-          : Promise.resolve(outbound);
+        strategy
+          ? strategy.authorize(outbound, forStrategy())
+          : this.#deps.authorizeRequest
+            ? this.#deps.authorizeRequest(providerId, declared.id, outbound)
+            : Promise.resolve(outbound);
 
       const providerContext = buildProviderContext({
         manifest: entry.manifest,
@@ -288,10 +319,18 @@ export class Dispatcher {
         });
       }
 
+      // Only where the strategy asks for it. A vendor that signs its replies
+      // expects them verified, and the transport clones the response so the
+      // check costs the caller nothing.
+      const verifyResponse = strategy?.verify?.bind(strategy);
+
       const connectorContext: ConnectorContext = {
         manifest: entry.manifest,
         provider: providerContext,
         authorize,
+        ...(verifyResponse
+          ? { verify: (response: Response) => verifyResponse(response, forStrategy()) }
+          : {}),
       };
 
       // The connector owns argument validation: a local provider validates

package/src/providers/bunq/hints.ts

@@ -0,0 +1,43 @@
+/**
+ * What bunq's own descriptions leave out, and an agent has to know.
+ *
+ * Appended to the generated description at discovery. Three things earn a line
+ * here: the distinction that decides whether money moves, the shape of an
+ * amount, and the identifier an agent cannot guess.
+ */
+export const BUNQ_HINTS: Record<string, string> = {
+  List_all_User:
+    'Call this first. Every other bunq tool is addressed under a userID, and this is the only thing that reports it.',
+
+  List_all_MonetaryAccount_for_User:
+    'Returns every account: current, savings, joint, and closed ones. Each is wrapped in a type key ' +
+    '(MonetaryAccountBank, MonetaryAccountSavings, …) and the id inside it is the `monetary-accountID` ' +
+    'the payment tools take. Check `status` is ACTIVE before paying from one.',
+
+  CREATE_Payment_for_User_MonetaryAccount:
+    'This executes immediately and is not reversible. The money leaves the account as soon as bunq accepts the call — ' +
+    'there is no confirmation step, in the app or anywhere else. Use draft-payment instead when a human should see it first. ' +
+    'amount is { "value": "10.00", "currency": "EUR" } — a decimal string, not a number, and never cents. ' +
+    'counterparty_alias is { "type": "IBAN", "value": "<iban>", "name": "<account holder>" }, and for IBAN the name must match ' +
+    'the one on the receiving account. type may also be EMAIL or PHONE_NUMBER for another bunq user.',
+
+  CREATE_DraftPayment_for_User_MonetaryAccount:
+    'Prepares a payment without sending it: it waits in the bunq app until a human approves it, which is the checkpoint ' +
+    'a direct payment does not have. Takes `entries`, an array of { amount, counterparty_alias, description } shaped exactly ' +
+    'like a direct payment, plus number_of_required_accepts (1 for a personal account).',
+
+  UPDATE_DraftPayment_for_User_MonetaryAccount:
+    'Changes a draft that is still pending — status ACCEPTED sends it, REJECTED cancels it. ' +
+    'previous_updated_timestamp is required and comes from reading the draft first; it is what stops two ' +
+    'callers acting on the same draft.',
+
+  CREATE_PaymentBatch_for_User_MonetaryAccount:
+    'Up to 350 payments in one call. Executes immediately, like a direct payment, and is all-or-nothing: bunq rejects ' +
+    'the whole batch if any entry is invalid. `payments` must be an ARRAY of { amount, counterparty_alias, description } ' +
+    'objects, each shaped exactly like a direct payment — bunq\'s specification declares the field as an object rather ' +
+    'than an array, which is wrong, so the schema here cannot tell you that and this line has to.',
+
+  List_all_Payment_for_User_MonetaryAccount:
+    'Newest first, one page at a time. bunq pages with `count`, `older_id` and `newer_id` rather than an offset, ' +
+    'but its specification does not declare them, so this tool returns the most recent page and no more.',
+};