@lanes-sh/link 0.6.10 → 0.7.0

package/src/connectivity/context.ts

@@ -49,7 +49,7 @@ export interface ConnectionInfo {
  * provider can do anything that credential permits. There is no provider
  * sandbox in M1. Installing a third-party provider is equivalent to running
  * arbitrary code with access to that account, and
- * `docs/detailed/creating-a-provider.md` says so plainly.
+ * `https://lanes.sh/docs/link/creating-a-provider` says so plainly.
  */
 export interface ProviderContext {
   readonly connection: ConnectionInfo;

package/src/connectivity/index.ts

@@ -14,7 +14,7 @@
  * This barrel is also the **provider authoring surface**: a provider must be
  * writable without reading the rest of the codebase. If you need something not
  * exported here, that is a bug in this file rather than a reason to reach into
- * another component. See `docs/detailed/creating-a-provider.md`.
+ * another component. See `https://lanes.sh/docs/link/creating-a-provider`.
  */
 
 export type { ScopedStore, Logger, ConnectionInfo, ProviderContext } from './context.ts';

package/src/connectivity/mail/attachments.ts

@@ -5,6 +5,7 @@ import type { BlobStore } from '#stores/blobs';
 import type { ResolvedAttachment } from './message.ts';
 import { getStaged } from './staging.ts';
 import { fetchFromUrl, type AddressLookup } from './url.ts';
+import { basename, guessContentType } from './content-type.ts';
 
 /**
  * Turning a named attachment into bytes.
@@ -21,11 +22,12 @@ import { fetchFromUrl, type AddressLookup } from './url.ts';
  *   url         fetched over HTTPS, with the checks in `url.ts`
  *   handle      bytes staged earlier through the upload route
  *   message_id  an attachment already sitting in the mailbox being used
+ *   uid         the same, addressed the way the mailbox itself addresses it
  *   data        base64 inline — the escape hatch, not the path
  *
  * `path` is deliberately unrestricted: no allowlist, no confinement to a root.
  * The endpoint already holds its owner's credentials, so the filesystem is
- * treated the same way, and `docs/detailed/creating-a-provider.md`'s note that provider
+ * treated the same way, and `https://lanes.sh/docs/link/creating-a-provider`'s note that provider
  * code is trusted code applies here too. What makes that defensible is the audit
  * trail rather than a sandbox — every resolved attachment carries its origin and
  * a SHA-256, and the manifest's `redact` block keeps both, so "was this file ever
@@ -34,7 +36,7 @@ import { fetchFromUrl, type AddressLookup } from './url.ts';
  */
 
 /** The source keys, in the order they are reported when a caller supplies two. */
-const SOURCE_KEYS = ['path', 'url', 'handle', 'message_id', 'data'] as const;
+const SOURCE_KEYS = ['path', 'url', 'handle', 'message_id', 'uid', 'data'] as const;
 
 export const attachmentRefSchema = z
   .strictObject({
@@ -48,10 +50,22 @@ export const attachmentRefSchema = z
       .string()
       .optional()
       .describe('Re-attach an attachment already on a message in this mailbox.'),
+    uid: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        'Re-attach from a message named by its mailbox UID, as search_messages and get_message report it. Pair with mailbox. Prefer this to message_id on a mailbox that has both: it addresses the message directly instead of searching every folder for a header.',
+      ),
+    mailbox: z
+      .string()
+      .optional()
+      .describe('Which mailbox the uid belongs to. Defaults to INBOX.'),
     attachment_id: z
       .string()
       .optional()
-      .describe('Which attachment on that message. Required with message_id where the provider ids them.'),
+      .describe('Which attachment on that message. Required with message_id or uid where the provider ids them.'),
     data: z
       .string()
       .optional()
@@ -61,7 +75,7 @@ export const attachmentRefSchema = z
     filename: z.string().optional().describe('Overrides the name derived from the source.'),
     content_type: z.string().optional().describe('Overrides the type derived from the source.'),
   })
-  .describe('One attachment, named by exactly one of path, url, handle, message_id, or data.');
+  .describe('One attachment, named by exactly one of path, url, handle, message_id, uid, or data.');
 
 export type AttachmentRef = z.infer<typeof attachmentRefSchema>;
 
@@ -82,9 +96,23 @@ export const attachmentsJsonSchema = ((): Record<string, unknown> => {
   return schema;
 })();
 
-/** Pulls bytes for `message_id` out of whatever mailbox the caller is already in. */
+/**
+ * Pulls bytes for `message_id` or `uid` out of the mailbox the caller is already in.
+ *
+ * Two ways to name the message, because the two protocols name it differently
+ * and only one of them can do both. A `uid` is what IMAP itself uses and what
+ * `search_messages` and `get_message` already report, so it addresses a message
+ * directly; a `messageId` has to be *searched* for, folder by folder, and a
+ * server whose `HEADER MESSAGE-ID` matching is unreliable fails that search on a
+ * message it is holding. Gmail's REST API has no uid and takes its own id.
+ *
+ * Exactly one arrives set. An implementation that cannot serve the one it is
+ * given should say so naming the other, rather than returning nothing.
+ */
 export type MailboxAttachmentSource = (reference: {
-  readonly messageId: string;
+  readonly messageId: string | undefined;
+  readonly mailbox: string | undefined;
+  readonly uid: number | undefined;
   readonly attachmentId: string | undefined;
 }) => Promise<{
   readonly bytes: Uint8Array;
@@ -213,21 +241,25 @@ async function bytesFor(
     case 'handle':
       return await fromHandle(ref.handle!, where, options.storage);
 
-    case 'message_id': {
+    case 'message_id':
+    case 'uid': {
       if (!options.mailbox) {
         throw new Error(
-          `${where} uses message_id, which this provider cannot resolve. Fetch the attachment and stage it, or use path or url.`,
+          `${where} uses ${source}, which only a mail connection can resolve — this one holds no mailbox. ` +
+            `Name the file with path, url, or handle instead, or ask the mail connection itself to send it somewhere.`,
         );
       }
       const found = await options.mailbox({
-        messageId: ref.message_id!,
+        messageId: ref.message_id,
+        mailbox: ref.mailbox,
+        uid: ref.uid,
         attachmentId: ref.attachment_id,
       });
       return {
         bytes: found.bytes,
         filename: found.filename,
         contentType: found.contentType,
-        origin: `mailbox:${ref.message_id!}`,
+        origin: source === 'uid' ? `mailbox:${ref.mailbox ?? 'INBOX'}:${ref.uid!}` : `mailbox:${ref.message_id!}`,
       };
     }
 
@@ -307,66 +339,3 @@ function decodeBase64(value: string, where: string): Uint8Array {
     throw new Error(`${where}: data is not valid base64.`);
   }
 }
-
-function basename(path: string): string | null {
-  const name = path.split(/[/\\]/).pop();
-  return name ? decodeURIComponent(name) : null;
-}
-
-/**
- * Type from the filename, since three of the five sources do not report one.
- *
- * A table rather than `Bun.file().type`, which would resolve this in one line:
- * Bun-specific APIs are confined to two named files, and a mail composer is not
- * one of them. Deliberately short — what an attachment actually is, not a mime
- * database. Anything unlisted becomes `application/octet-stream`, which every
- * mail client handles as "a file", so the failure mode is a generic icon rather
- * than a broken attachment.
- */
-const CONTENT_TYPES: Readonly<Record<string, string>> = {
-  pdf: 'application/pdf',
-  txt: 'text/plain',
-  md: 'text/markdown',
-  csv: 'text/csv',
-  html: 'text/html',
-  json: 'application/json',
-  xml: 'application/xml',
-  ics: 'text/calendar',
-  vcf: 'text/vcard',
-  png: 'image/png',
-  jpg: 'image/jpeg',
-  jpeg: 'image/jpeg',
-  gif: 'image/gif',
-  webp: 'image/webp',
-  svg: 'image/svg+xml',
-  heic: 'image/heic',
-  tiff: 'image/tiff',
-  zip: 'application/zip',
-  gz: 'application/gzip',
-  mp3: 'audio/mpeg',
-  m4a: 'audio/mp4',
-  wav: 'audio/wav',
-  mp4: 'video/mp4',
-  mov: 'video/quicktime',
-  doc: 'application/msword',
-  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-  xls: 'application/vnd.ms-excel',
-  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-  ppt: 'application/vnd.ms-powerpoint',
-  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-  // `.pages`, `.numbers` and `.key` are absent on purpose. Their registered
-  // media types carry a vendor name, and `architecture.test.ts` refuses one
-  // anywhere a request passes through — correctly, even though an IANA type is
-  // not the vendor *knowledge* that rule is aimed at. They fall through to
-  // octet-stream, which mail clients show as a file and the recipient's system
-  // opens by extension anyway. Adding them back will fail the suite.
-};
-
-/**
- * Exported because `assets` needs exactly this and the table above must not be
- * copied — its `.pages`/`.numbers` note is a rule the copy would not carry.
- */
-export function guessContentType(filename: string): string {
-  const extension = filename.split('.').pop()?.toLowerCase();
-  return (extension ? CONTENT_TYPES[extension] : undefined) ?? 'application/octet-stream';
-}

package/src/connectivity/mail/content-type.ts

@@ -0,0 +1,71 @@
+/**
+ * What a file is, from its name.
+ *
+ * Split out of `attachments.ts` when that file passed the size budget, and it is
+ * the right seam rather than a convenient one: resolving a *source* into bytes
+ * and deciding what those bytes *are* are separate questions, and only the
+ * second one is a lookup table nobody needs to read.
+ */
+
+export function basename(path: string): string | null {
+  const name = path.split(/[/\\]/).pop();
+  return name ? decodeURIComponent(name) : null;
+}
+
+/**
+ * Type from the filename, since three of the five sources do not report one.
+ *
+ * A table rather than `Bun.file().type`, which would resolve this in one line:
+ * Bun-specific APIs are confined to two named files, and a mail composer is not
+ * one of them. Deliberately short — what an attachment actually is, not a mime
+ * database. Anything unlisted becomes `application/octet-stream`, which every
+ * mail client handles as "a file", so the failure mode is a generic icon rather
+ * than a broken attachment.
+ */
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  pdf: 'application/pdf',
+  txt: 'text/plain',
+  md: 'text/markdown',
+  csv: 'text/csv',
+  html: 'text/html',
+  json: 'application/json',
+  xml: 'application/xml',
+  ics: 'text/calendar',
+  vcf: 'text/vcard',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  heic: 'image/heic',
+  tiff: 'image/tiff',
+  zip: 'application/zip',
+  gz: 'application/gzip',
+  mp3: 'audio/mpeg',
+  m4a: 'audio/mp4',
+  wav: 'audio/wav',
+  mp4: 'video/mp4',
+  mov: 'video/quicktime',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  // `.pages`, `.numbers` and `.key` are absent on purpose. Their registered
+  // media types carry a vendor name, and `architecture.test.ts` refuses one
+  // anywhere a request passes through — correctly, even though an IANA type is
+  // not the vendor *knowledge* that rule is aimed at. They fall through to
+  // octet-stream, which mail clients show as a file and the recipient's system
+  // opens by extension anyway. Adding them back will fail the suite.
+};
+
+/**
+ * Exported because `assets` needs exactly this and the table above must not be
+ * copied — its `.pages`/`.numbers` note is a rule the copy would not carry.
+ */
+export function guessContentType(filename: string): string {
+  const extension = filename.split('.').pop()?.toLowerCase();
+  return (extension ? CONTENT_TYPES[extension] : undefined) ?? 'application/octet-stream';
+}

package/src/connectivity/mail/index.ts

@@ -21,10 +21,10 @@ export { receiptFor } from './message.ts';
 export { composeMime } from './compose.ts';
 
 export type { AttachmentRef, MailboxAttachmentSource, ResolveOptions } from './attachments.ts';
+export { guessContentType } from './content-type.ts';
 export {
   attachmentRefSchema,
   attachmentsJsonSchema,
-  guessContentType,
   resolveAttachments,
 } from './attachments.ts';
 

package/src/connectivity/manifest/provider.ts

@@ -5,6 +5,7 @@ import { connectorSchema } from './connector.ts';
 import { identitySchema } from './identity.ts';
 import { identifier } from './primitives.ts';
 import { setupSchema } from './setup.ts';
+import { connectionVariableSchema, placeholdersInConnector } from './variables.ts';
 
 /**
  * A provider manifest.
@@ -60,6 +61,14 @@ export const providerManifestSchema = z.object({
    * not silently discarded.
    */
   hints: z.record(z.string(), z.string()).optional(),
+  /**
+   * What this connection has to say about *where* the service is.
+   *
+   * Absent for every provider whose address is the same for everybody, which is
+   * almost all of them. Present for a multi-tenant host that carries the tenant,
+   * or anything self-hosted — see `./variables.ts`.
+   */
+  variables: z.array(connectionVariableSchema).default([]),
 });
 
 export type ProviderManifest = z.infer<typeof providerManifestSchema>;
@@ -69,6 +78,9 @@ export type ProviderManifest = z.infer<typeof providerManifestSchema>;
  *
  * The order is read: `#server/mcp`'s instructions emit one paragraph per
  * reachable id in this sequence, so it is the order an agent meets them in.
+ * `entities` is appended rather than inserted alphabetically so that it lands
+ * beside `identity`: the two answer the same question about different people,
+ * and the instructions collapse them into one paragraph when both are reachable.
  */
 export const RESERVED_PROVIDER_IDS: readonly string[] = [
   'memory',
@@ -78,6 +90,7 @@ export const RESERVED_PROVIDER_IDS: readonly string[] = [
   'vault',
   'setup',
   'identity',
+  'entities',
 ];
 
 /**
@@ -104,6 +117,43 @@ export function defineProvider(input: unknown): ProviderManifest {
 
   const manifest = parsed.data;
 
+  // R12 and R13. The two halves of a variable have to agree, and neither failure
+  // is visible without this: a placeholder nothing fills reaches the vendor
+  // verbatim, so the request goes to a host literally called `{site}.zendesk.com`
+  // and fails as DNS rather than as configuration. A variable nothing uses is the
+  // opposite and quieter — `connect` asks the operator a question, stores the
+  // answer, and nothing ever reads it.
+  {
+    // `fs` and `local` are the two that hold no address a caller supplies.
+    // `local` is our own code, and `fs.root` *is* substitutable — a vault path
+    // differs per person — so only `local` is refused here.
+    if (manifest.connector.kind === 'local' && manifest.variables.length > 0) {
+      throw new Error(
+        `Provider "${manifest.id}": a local connector is our own code and has no address to fill in, so it cannot declare variables.`,
+      );
+    }
+
+    const placeholders = placeholdersInConnector(
+      manifest.connector as unknown as Record<string, unknown>,
+    );
+    const declared = new Set(manifest.variables.map((variable) => variable.key));
+
+    const unfilled = placeholders.filter((name) => !declared.has(name));
+    if (unfilled.length > 0) {
+      throw new Error(
+        `Provider "${manifest.id}": the connector names {${unfilled.join('}, {')}} and the manifest declares no variable for ${unfilled.length === 1 ? 'it' : 'them'}. Add one under "variables", or the address is sent to the vendor with the braces still in it.`,
+      );
+    }
+
+    const unused = [...declared].filter((key) => !placeholders.includes(key));
+    if (unused.length > 0) {
+      throw new Error(
+        `Provider "${manifest.id}": variable${unused.length === 1 ? '' : 's'} ${unused.join(', ')} ${unused.length === 1 ? 'appears' : 'appear'} in no address, so connect would ask for ${unused.length === 1 ? 'a value' : 'values'} nothing reads. Put {${unused[0]}} in the connector's address — or drop it.`,
+      );
+    }
+
+  }
+
   if (manifest.auth.kind === 'oauth' && manifest.auth.registration === 'manual') {
     if (!manifest.auth.app) {
       throw new Error(

package/src/connectivity/manifest/variables.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { identifier } from './primitives.ts';
+
+/**
+ * Where a service lives, when that is a property of the connection rather than
+ * of the provider.
+ *
+ * `base_url`, `endpoint` and `host` are one value per manifest, which is right
+ * for a vendor that runs one address for everybody — Gmail is
+ * `gmail.googleapis.com` for every account there has ever been. It is wrong for
+ * two large families:
+ *
+ *   - **multi-tenant SaaS whose host carries the tenant** — Zendesk is
+ *     `<subdomain>.zendesk.com`, Shopify `<shop>.myshopify.com`, Atlassian
+ *     `api.atlassian.com/ex/jira/<cloudid>`
+ *   - **anything self-hosted** — a Nextcloud, a Gitea, a Home Assistant, each at
+ *     an address only its owner knows
+ *
+ * Both were reachable already, but only by hand-writing a YAML manifest per
+ * instance in `providers.d/`. What was impossible was a *built-in* for any of
+ * them, because a built-in cannot know the address. A declared variable is the
+ * missing half: the manifest says a placeholder is there and what fills it, and
+ * the connection supplies the value.
+ *
+ * Deliberately not a credential. A hostname is not a secret and does not belong
+ * in the secret store; it lives in the connection's own `config`, which is what
+ * that field has always been for.
+ */
+
+/**
+ * What a value is allowed to be, and the reason this is not cosmetic.
+ *
+ * A variable is substituted into a URL, so an unconstrained value chooses the
+ * host the operator's credential is sent to: `acme.zendesk.com/../..@evil.test`
+ * in a `{site}` would leave a manifest that reads as Zendesk and authenticates
+ * to somebody else. This is the check that stops that, and it runs at
+ * *substitution* rather than only at the prompt — config is a file that can be
+ * edited by hand, and a deployed revision reads it without ever seeing a prompt.
+ *
+ * One DNS label or path segment: letters, digits, and the three separators that
+ * appear inside real subdomains and tenant ids. No dots by default, because a
+ * dot is how you leave the domain the manifest named; a provider whose value
+ * genuinely contains one says so with its own `pattern`.
+ */
+export const DEFAULT_VARIABLE_PATTERN = '^[A-Za-z0-9][A-Za-z0-9_-]*$';
+
+export const connectionVariableSchema = z.object({
+  /** The name inside the braces. `{site}` is `key: 'site'`. */
+  key: identifier,
+  /** What to call it when asking, in the vendor's own word — "subdomain", not "variable". */
+  label: z.string().min(1),
+  /** One line: what it is and where the operator finds it. */
+  description: z.string().min(1),
+  /** A real-looking value, shown in the prompt and in the refusal. */
+  example: z.string().min(1),
+  /**
+   * Override the default only to *narrow* it or to admit a character the
+   * default excludes — a cloud id with dots, a path segment with slashes. A
+   * pattern that admits `/` or `@` is choosing to trust the value with the host,
+   * and should say why.
+   */
+  pattern: z
+    .string()
+    .default(DEFAULT_VARIABLE_PATTERN)
+    // Anchored here rather than trusted to be anchored, and compiled here
+    // rather than at the first call.
+    //
+    // `test` matches a substring, so an unanchored pattern silently voids the
+    // guarantee this field exists for: `[a-z.]+` accepts `acme.evil.test/@x`,
+    // which is then substituted into the URL the operator's credential is sent
+    // to. Both built-ins anchor; a manifest in `providers.d/` is not obliged to
+    // read this file first, and a security control that depends on remembering
+    // is not one.
+    //
+    // Wrapped rather than refused, because what an author means by a pattern is
+    // always "the value looks like this" — nobody writes one intending a
+    // substring match. An invalid regex is refused, though, and refused at load
+    // rather than surfacing as a raw SyntaxError when a connector is built.
+    .transform((pattern) => (/^\^.*\$$/.test(pattern) ? pattern : `^(?:${pattern})$`))
+    .superRefine((pattern, context) => {
+      try {
+        new RegExp(pattern);
+      } catch (failure) {
+        context.addIssue({
+          code: 'custom',
+          message: `is not a usable regular expression: ${(failure as Error).message}`,
+        });
+      }
+    }),
+});
+
+export type ConnectionVariable = z.infer<typeof connectionVariableSchema>;
+
+/** Every `{name}` in a string, in the order they appear, without duplicates. */
+export function placeholdersIn(text: string): string[] {
+  return [...new Set([...text.matchAll(/\{([a-z][a-z0-9_]*)\}/g)].map((match) => match[1]!))];
+}
+
+/**
+ * Every placeholder anywhere in a connector, however deep.
+ *
+ * A field list was the first shape and it was wrong within one provider: the
+ * `imap` connector's submission host is `smtp.host`, a level down, so a generic
+ * mailbox declaring `{smtp_host}` was refused for using a variable that
+ * "appears in no address". Walking the object has no list to keep in step with
+ * a transport schema, and a `{name}` in a field where it means nothing is
+ * simply never substituted rather than silently wrong.
+ */
+export function placeholdersInConnector(connector: Record<string, unknown>): string[] {
+  const found = new Set<string>();
+
+  const walk = (node: unknown): void => {
+    if (typeof node === 'string') {
+      for (const name of placeholdersIn(node)) found.add(name);
+      return;
+    }
+    if (node === null || typeof node !== 'object') return;
+    for (const value of Object.values(node as Record<string, unknown>)) walk(value);
+  };
+
+  walk(connector);
+  return [...found];
+}
+
+/**
+ * Fill a connector's address in, or say exactly what is wrong.
+ *
+ * Returns the connector untouched when it declares no variables, which is every
+ * provider but a handful — so this costs nothing where it is not used and cannot
+ * quietly reshape a connector that was already complete.
+ */
+export function applyVariables(
+  connector: Record<string, unknown>,
+  variables: readonly ConnectionVariable[],
+  values: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  if (variables.length === 0) return connector;
+
+  const resolved = new Map<string, string>();
+  for (const variable of variables) {
+    const value = values[variable.key];
+    if (typeof value !== 'string' || value === '') {
+      throw new Error(
+        `This connection does not say what "${variable.key}" is (${variable.label}). ` +
+          `Reconnect it, or add it under this connection's config: ${variable.key}: ${variable.example}`,
+      );
+    }
+    if (!new RegExp(variable.pattern).test(value)) {
+      throw new Error(
+        `"${value}" is not a usable ${variable.label} — it must match ${variable.pattern}, ` +
+          `like ${variable.example}. The value is put into the address this connection calls, ` +
+          `so anything that could change the host is refused rather than sent.`,
+      );
+    }
+    resolved.set(variable.key, value);
+  }
+
+  const substitute = (node: unknown): unknown => {
+    if (typeof node === 'string') {
+      return node.replace(/\{([a-z][a-z0-9_]*)\}/g, (whole, name: string) =>
+        resolved.get(name) ?? whole,
+      );
+    }
+    if (node === null || typeof node !== 'object') return node;
+    if (Array.isArray(node)) return node.map(substitute);
+
+    return Object.fromEntries(
+      Object.entries(node as Record<string, unknown>).map(([key, value]) => [key, substitute(value)]),
+    );
+  };
+
+  return substitute(connector) as Record<string, unknown>;
+}

package/src/connectivity/transports/factory.ts

@@ -1,4 +1,5 @@
 import type { AnyConnector, ProviderDefinition, ProviderManifest } from '#connectivity';
+import { applyVariables } from '#connectivity/manifest/variables.ts';
 import type { SecretStore } from '#secrets';
 import type { ProviderRegistry } from '#registry';
 import { basicCredential } from '#connectivity/auth/basic/index.ts';
@@ -22,6 +23,29 @@ import { createMcpConnector } from './mcp/index.ts';
 export interface ConnectorFactoryOptions {
   readonly registry: ProviderRegistry;
   readonly credentials: SecretStore;
+  /**
+   * What one connection says about where its service is.
+   *
+   * Optional, and read only by a provider that declares `variables` — which is
+   * a handful. A caller that omits it is saying every provider it serves has a
+   * fixed address, which was true of all of them until Zendesk-shaped hosts
+   * arrived, and is still true of almost all.
+   */
+  readonly connectionConfig?: (
+    providerId: string,
+    connectionId: string,
+  ) => Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Whether this connection is declared at all.
+   *
+   * Separate from its config, and the distinction is load-bearing: a provider
+   * nobody has connected is not a misconfiguration — every surface that lists
+   * what *could* be connected asks the factory about one — while a row that has
+   * been declared and carries no address is exactly the case worth failing
+   * loudly. Without this the two are indistinguishable, and the quiet answer
+   * wins for both.
+   */
+  readonly isDeclared?: (providerId: string, connectionId: string) => boolean;
 }
 
 /**
@@ -61,7 +85,13 @@ export function connectorFactory(options: ConnectorFactoryOptions): ConnectorFac
     const entry = options.registry.get(providerId);
     if (!entry) return undefined;
 
-    const connector = wrap(entry.definition, build(entry.manifest, entry.definition, connectionId, options));
+    // Filled in before the switch, so no transport case knows this happened —
+    // which is the property worth keeping. A variable changes *where* a
+    // connector points, and nothing about how it speaks.
+    const manifest = fillAddress(entry.manifest, providerId, connectionId, options);
+    if (!manifest) return undefined;
+
+    const connector = wrap(entry.definition, build(manifest, entry.definition, connectionId, options));
     if (connector) cache.set(key, connector);
     return connector;
   };
@@ -82,6 +112,49 @@ export function connectorFactory(options: ConnectorFactoryOptions): ConnectorFac
   return factory;
 }
 
+/**
+ * Substitute what this connection says about where its service is.
+ *
+ * Returns the manifest itself when it declares no variables, which is the
+ * overwhelming majority — so the cost is one array check per connector built,
+ * and a provider with a fixed address cannot be affected by any of this.
+ *
+ * A missing or malformed value throws, and throwing here is deliberate. The
+ * alternative is a connector pointed at `{site}.zendesk.com`, which fails as a
+ * DNS error at the first call and says nothing about the real problem; this
+ * fails at construction, naming the variable and what it should look like.
+ */
+function fillAddress(
+  manifest: ProviderManifest,
+  providerId: string,
+  connectionId: string,
+  options: ConnectorFactoryOptions,
+): ProviderManifest | undefined {
+  if (manifest.variables.length === 0) return manifest;
+
+  const values = options.connectionConfig?.(providerId, connectionId) ?? {};
+
+  // A provider nobody has connected has no address and that is not an error:
+  // the dashboard asks the factory about every provider it lists, and a throw
+  // here took the whole page down rather than showing one as unconnected.
+  //
+  // A *declared* connection missing its address is the opposite, and used to be
+  // silent for the same reason — which is how a `connect` that never wrote the
+  // value produced a provider that was simply, wordlessly dead.
+  if (Object.keys(values).length === 0 && !options.isDeclared?.(providerId, connectionId)) {
+    return undefined;
+  }
+  const connector = applyVariables(
+    manifest.connector as unknown as Record<string, unknown>,
+    manifest.variables,
+    values,
+  );
+
+  // The cast is honest: `applyVariables` rewrites string fields in place and
+  // never touches `kind`, so the union member is the one it started as.
+  return { ...manifest, connector: connector as unknown as ProviderManifest['connector'] };
+}
+
 /**
  * Layer a provider's own capabilities over a remote connector.
  *