@withone/cli 1.39.1 → 1.41.0

package/README.md

@@ -312,9 +312,9 @@ one sync install && one sync doctor
 ```
 
 ```bash
-# Discover → init (one command: infer + auto-resolve key + auto-test) → run
+# Discover → init (one command: infer + late-bound connection + auto-test) → run
 one sync models stripe
-one sync init stripe balanceTransactions    # connectionKey auto-resolved, test auto-run
+one sync init stripe balanceTransactions    # connection: { platform } baked in, test auto-run
 one sync run stripe --since 90d
 
 # Query, search, SQL
@@ -332,6 +332,8 @@ one sync run stripe --full-refresh
 
 > **Sync uses passthrough actions only.** Profiles referencing a custom/composer action are rejected at runtime. `sync models` already filters to passthrough-only; if a model has no passthrough list endpoint, compose a flow instead of syncing.
 
+> **Connections are late-bound.** Profiles use `"connection": { "platform": "<name>", "tag"?: "..." }` instead of literal `connectionKey` strings. The key is resolved at sync time, so `one add <platform>` (re-auth) doesn't break the profile. `tag` only needed for multi-account platforms (e.g. two Gmail accounts).
+
 | Subcommand | What it does |
 |------------|-------------|
 | `install` / `doctor` | Install + verify the SQLite engine |

package/dist/{chunk-MNJJE4PJ.js → chunk-A5AFLKCQ.js}

@@ -98,6 +98,42 @@ var OneApi = class {
   async deleteConnection(id) {
     await this.requestFull({ path: `/vault/connections/${id}`, method: "DELETE" });
   }
+  /**
+   * Resolve a late-bound `ConnectionRef` to a current `Connection`. Pass
+   * `cache` (a pre-fetched connection list) when resolving many refs in a
+   * loop, so each resolve doesn't repeat the listConnections round-trip.
+   *
+   * Errors are deliberately verbose: a sync profile or flow that fails to
+   * resolve a connection should surface *why* (no match / wrong tag /
+   * ambiguous) so the agent can fix the ref without trial and error.
+   */
+  async resolveConnection(ref, cache) {
+    const all = cache ?? await this.listConnections();
+    const platformLower = ref.platform.toLowerCase();
+    const candidates = all.filter((c) => c.platform.toLowerCase() === platformLower);
+    if (candidates.length === 0) {
+      throw new Error(
+        `No connection found for platform "${ref.platform}". Run 'one add ${ref.platform}' to connect.`
+      );
+    }
+    let matches = candidates;
+    if (ref.tag) {
+      matches = candidates.filter((c) => c.tags?.includes(ref.tag));
+      if (matches.length === 0) {
+        const availableTags = candidates.flatMap((c) => c.tags ?? []);
+        throw new Error(
+          `No "${ref.platform}" connection has tag "${ref.tag}". Available tags: ${availableTags.length > 0 ? availableTags.join(", ") : "(none)"}.`
+        );
+      }
+    }
+    if (matches.length > 1) {
+      const tagList = matches.map((c) => c.tags?.length ? c.tags.join(",") : "(no tag)").join("; ");
+      throw new Error(
+        `Multiple "${ref.platform}" connections found (tags: ${tagList}). Add a "tag" field to the connection ref to disambiguate.`
+      );
+    }
+    return matches[0];
+  }
   async listPlatforms() {
     const allPlatforms = [];
     let page = 1;
@@ -775,7 +811,29 @@ async function executeActionStep(step, context, api, permissions, allowedActionI
   const action = step.action;
   const platform = resolveValue(action.platform, context);
   const actionId = resolveValue(action.actionId, context);
-  const connectionKey = resolveValue(action.connectionKey, context);
+  const hasKey = action.connectionKey !== void 0 && action.connectionKey !== null && action.connectionKey !== "";
+  const hasRef = !!action.connection?.platform;
+  if (hasKey && hasRef) {
+    throw new Error(
+      `Action step "${step.id}" has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    );
+  }
+  if (!hasKey && !hasRef) {
+    throw new Error(
+      `Action step "${step.id}" must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").`
+    );
+  }
+  let connectionKey;
+  if (hasKey) {
+    connectionKey = resolveValue(action.connectionKey, context);
+  } else {
+    const ref = resolveValue(action.connection, context);
+    if (!context._connections) {
+      context._connections = await api.listConnections();
+    }
+    const conn = await api.resolveConnection(ref, context._connections);
+    connectionKey = conn.key;
+  }
   const data = action.data ? resolveValue(action.data, context) : void 0;
   const pathVars = action.pathVars ? resolveValue(action.pathVars, context) : void 0;
   const queryParams = action.queryParams ? resolveValue(action.queryParams, context) : void 0;
@@ -1079,7 +1137,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-OVOGDXNR.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-26LNPU4F.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1625,7 +1683,8 @@ var FLOW_SCHEMA = {
       fields: {
         platform: { type: "string", required: true, description: "Platform name (kebab-case)" },
         actionId: { type: "string", required: true, description: "Action ID from `actions search`" },
-        connectionKey: { type: "string", required: true, description: "Connection key (use $.input selector)" },
+        connection: { type: "object", required: false, description: "Late-bound connection ref { platform, tag? } \u2014 survives re-auth. Exactly one of `connection` or `connectionKey` must be set." },
+        connectionKey: { type: "string", required: false, description: "Literal connection key (or $.input selector). Legacy form \u2014 prefer `connection: { platform, tag? }`. Exactly one of `connection` or `connectionKey` must be set." },
         data: { type: "object", required: false, description: "Request body (POST/PUT/PATCH)" },
         pathVars: { type: "object", required: false, description: "URL path variables" },
         queryParams: { type: "object", required: false, description: "Query parameters" },
@@ -1638,7 +1697,7 @@ var FLOW_SCHEMA = {
         action: {
           platform: "stripe",
           actionId: "conn_mod_def::xxx::yyy",
-          connectionKey: "$.input.stripeConnectionKey",
+          connection: { platform: "stripe" },
           data: { query: "email:'{{$.input.customerEmail}}'" }
         }
       }
@@ -1687,7 +1746,7 @@ var FLOW_SCHEMA = {
         type: "condition",
         condition: {
           expression: "$.steps.search.response.data.length > 0",
-          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey", data: { text: "Found!" } } }],
+          then: [{ id: "notify", name: "Send notification", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" }, data: { text: "Found!" } } }],
           else: [{ id: "logMiss", name: "Log not found", type: "transform", transform: { expression: "'Not found'" } }]
         }
       }
@@ -1711,7 +1770,7 @@ var FLOW_SCHEMA = {
         loop: {
           over: "$.steps.listOrders.response.data",
           as: "order",
-          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey", data: { amount: "$.loop.order.total" } } }]
+          steps: [{ id: "createInvoice", name: "Create invoice", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" }, data: { amount: "$.loop.order.total" } } }]
         }
       }
     },
@@ -1729,8 +1788,8 @@ var FLOW_SCHEMA = {
         type: "parallel",
         parallel: {
           steps: [
-            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connectionKey: "$.input.stripeKey" } },
-            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connectionKey: "$.input.slackKey" } }
+            { id: "getStripe", name: "Get Stripe data", type: "action", action: { platform: "stripe", actionId: "...", connection: { platform: "stripe" } } },
+            { id: "getSlack", name: "Get Slack data", type: "action", action: { platform: "slack", actionId: "...", connection: { platform: "slack" } } }
           ]
         }
       }
@@ -1782,7 +1841,7 @@ var FLOW_SCHEMA = {
         while: {
           condition: "$.steps.paginate.output.lastResult.nextPageToken != null",
           maxIterations: 50,
-          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey" } }]
+          steps: [{ id: "fetchPage", name: "Fetch next page", type: "action", action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" } } }]
         }
       }
     },
@@ -1806,7 +1865,7 @@ var FLOW_SCHEMA = {
       configKey: "paginate",
       description: "Auto-paginate API results into a single array",
       fields: {
-        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, connectionKey)" },
+        action: { type: "object", required: true, description: "Action config (same shape as action step: platform, actionId, plus exactly one of `connection` or `connectionKey`)" },
         pageTokenField: { type: "string", required: true, description: "Dot-path in response to next page token" },
         resultsField: { type: "string", required: true, description: "Dot-path in response to results array" },
         inputTokenParam: { type: "string", required: true, description: "Dot-path in action config where page token is injected" },
@@ -1817,7 +1876,7 @@ var FLOW_SCHEMA = {
         name: "Fetch all Gmail messages",
         type: "paginate",
         paginate: {
-          action: { platform: "gmail", actionId: "...", connectionKey: "$.input.gmailKey", queryParams: { maxResults: 100 } },
+          action: { platform: "gmail", actionId: "...", connection: { platform: "gmail" }, queryParams: { maxResults: 100 } },
           pageTokenField: "nextPageToken",
           resultsField: "messages",
           inputTokenParam: "queryParams.pageToken",
@@ -2015,12 +2074,6 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
   "description": "What this flow does",
   "version": "1",
   "inputs": {
-    "connectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Platform connection key",
-      "connection": { "platform": "stripe" }
-    },
     "param": {
       "type": "string",
       "required": true,
@@ -2035,7 +2088,7 @@ The only differences: (1) prepend the stdin-read line, (2) replace \`return X\`
       "action": {
         "platform": "stripe",
         "actionId": "conn_mod_def::xxx::yyy",
-        "connectionKey": "$.input.connectionKey",
+        "connection": { "platform": "stripe" },
         "data": { "query": "{{$.input.param}}" }
       }
     }
@@ -2129,13 +2182,13 @@ Pipes can be applied to any value (objects/arrays are JSON-stringified first for
 
 ### When to use bare selectors vs \`{{...}}\` interpolation
 
-- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
+- **Bare selectors** (\`$.input.x\`): Use for fields the engine resolves directly \u2014 \`connectionKey\`, the \`tag\` (or \`platform\`) inside \`connection\`, \`over\`, \`path\`, \`expression\`, \`condition\`, and any field where the entire value is a single selector. The resolved value keeps its original type (object, array, number).
 - **Interpolation** (\`{{$.input.x}}\`): Use inside string values where the selector is embedded in text \u2014 e.g., \`"Hello {{$.steps.getUser.response.name}}"\`. The resolved value is always stringified. Use this in \`data\`, \`pathVars\`, and \`queryParams\` when mixing selectors with literal text.
 - **Rule of thumb**: If the value is purely a selector, use bare. If it's a string containing a selector, use \`{{...}}\`.
 
 ### Selectors vs expressions
 
-Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
+Selectors in data fields (\`data\`, \`queryParams\`, \`pathVars\`, \`connectionKey\`, \`connection.tag\`) are **dot-path lookups only** \u2014 they do not support JavaScript operators like \`||\` or \`&&\`. For default values, use the \`default\` field on the input definition:
 
 \`\`\`json
 { "inputs": { "maxResults": { "type": "number", "default": 10 } } }
@@ -2255,9 +2308,30 @@ A \`flow\` step's \`flow.key\` accepts selectors and Handlebars interpolations,
 
 Conditional execution: \`"if": "$.steps.prev.response.data.length > 0"\`
 
-## Input Connection Auto-Resolution
+## Connection Resolution \u2014 late-bound by default
+
+Action steps reference a platform connection in one of two forms:
+
+\`\`\`json
+// preferred \u2014 late-bound, survives re-auth
+"connection": { "platform": "gmail" }
+
+// multi-account: disambiguate with the connection's tag
+"connection": { "platform": "gmail", "tag": "work@example.com" }
+
+// legacy \u2014 works for backwards compat, breaks on re-auth
+"connectionKey": "live::gmail::default::abc123..."
+\`\`\`
+
+The engine resolves the \`connection\` ref once per flow run (cached for the run's lifetime) by calling \`listConnections\` and matching on platform + optional tag. Resolution errors fail the step with a clear message \u2014 \`No connection found for platform "X"\`, \`Multiple "X" connections found (tags: ...). Add a "tag" field\`, or \`No "X" connection has tag "Y"\`.
 
-When an input has \`"connection": { "platform": "stripe" }\`, the flow engine can automatically resolve the connection key at execution time. If the user has exactly one connection for that platform, the engine fills in the key without requiring \`-i connectionKey=...\`. If multiple connections exist, the user must specify which one. This is metadata for tooling \u2014 it does not affect the flow JSON structure, but it makes execution more convenient.
+Both \`platform\` and \`tag\` accept \`$.input.x\` selectors so a flow can be parameterised per-execution (e.g. multi-tenant orchestrators that pass the user's email as the tag).
+
+The validator rejects any action that sets both forms or neither, at \`flow validate\` and \`flow execute\` time.
+
+### Optional input metadata: connection-key auto-resolve (legacy)
+
+For flows that still use literal \`connectionKey\` strings via inputs, an input declaration can carry a \`"connection": { "platform": "..." }\` hint so \`flow execute\` auto-fills a single matching connection's key. New flows don't need this \u2014 switch the action's connection form to \`{ platform, tag? }\` and skip the input entirely.
 
 ## Complete Example: Fetch Data, Transform, Notify
 
@@ -2268,18 +2342,6 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
   "description": "Fetch recent contacts from CRM, build a summary, post to Slack",
   "version": "1",
   "inputs": {
-    "crmConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "CRM platform connection key",
-      "connection": { "platform": "attio" }
-    },
-    "slackConnectionKey": {
-      "type": "string",
-      "required": true,
-      "description": "Slack connection key",
-      "connection": { "platform": "slack" }
-    },
     "slackChannel": {
       "type": "string",
       "required": true,
@@ -2294,7 +2356,7 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
       "action": {
         "platform": "attio",
         "actionId": "ATTIO_LIST_PEOPLE_ACTION_ID",
-        "connectionKey": "$.input.crmConnectionKey",
+        "connection": { "platform": "attio" },
         "queryParams": { "limit": "10" }
       }
     },
@@ -2313,7 +2375,7 @@ When an input has \`"connection": { "platform": "stripe" }\`, the flow engine ca
       "action": {
         "platform": "slack",
         "actionId": "SLACK_SEND_MESSAGE_ACTION_ID",
-        "connectionKey": "$.input.slackConnectionKey",
+        "connection": { "platform": "slack" },
         "data": {
           "channel": "$.input.slackChannel",
           "text": "{{$.steps.buildSummary.output.summary}}"

package/dist/{flow-runner-OVOGDXNR.js → flow-runner-26LNPU4F.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-MNJJE4PJ.js";
+} from "./chunk-A5AFLKCQ.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   resolveFlowPath,
   saveFlow,
   validateActionInput
-} from "./chunk-MNJJE4PJ.js";
+} from "./chunk-A5AFLKCQ.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -3269,10 +3269,13 @@ function validateStepsArray(steps, pathPrefix, errors) {
           const a = value;
           if (!a.platform) errors.push({ path: `${fieldPath}.platform`, message: 'Action must have "platform"' });
           if (!a.actionId) errors.push({ path: `${fieldPath}.actionId`, message: 'Action must have "actionId"' });
-          if (!a.connectionKey) errors.push({ path: `${fieldPath}.connectionKey`, message: 'Action must have "connectionKey"' });
+          validateConnectionForm(a, fieldPath, errors);
         }
       }
     }
+    if (descriptor.type === "action") {
+      validateConnectionForm(config2, `${path17}.${configKey}`, errors);
+    }
     if (descriptor.type === "code") {
       const hasSource = typeof config2.source === "string" && config2.source.length > 0;
       const hasModule = typeof config2.module === "string" && config2.module.length > 0;
@@ -3300,6 +3303,43 @@ function validateStepsArray(steps, pathPrefix, errors) {
     }
   }
 }
+function validateConnectionForm(config2, pathPrefix, errors) {
+  const hasKey = config2.connectionKey !== void 0 && config2.connectionKey !== null && config2.connectionKey !== "";
+  const conn = config2.connection;
+  const hasRef = !!conn && typeof conn === "object" && !Array.isArray(conn) && typeof conn.platform === "string" && conn.platform.length > 0;
+  if (hasKey && hasRef) {
+    errors.push({
+      path: pathPrefix,
+      message: `Action has both "connectionKey" and "connection" \u2014 set exactly one. Prefer "connection: { platform, tag? }" so re-auth doesn't break the flow.`
+    });
+    return;
+  }
+  if (!hasKey && !hasRef) {
+    errors.push({
+      path: pathPrefix,
+      message: 'Action must set "connection: { platform: <name> }" (or legacy "connectionKey: <key>").'
+    });
+    return;
+  }
+  if (hasRef) {
+    const c = conn;
+    if (c.tag !== void 0 && typeof c.tag !== "string") {
+      errors.push({
+        path: `${pathPrefix}.connection.tag`,
+        message: '"connection.tag" must be a string when set'
+      });
+    }
+    const allowed = /* @__PURE__ */ new Set(["platform", "tag"]);
+    for (const k of Object.keys(c)) {
+      if (!allowed.has(k)) {
+        errors.push({
+          path: `${pathPrefix}.connection.${k}`,
+          message: `Unknown field "${k}" in connection ref. Allowed: platform, tag.`
+        });
+      }
+    }
+  }
+}
 function detectFlatConfigHint(step, descriptor) {
   const requiredFields = Object.entries(descriptor.fields).filter(([, fd]) => fd.required).map(([name]) => name);
   const flatFields = requiredFields.filter((f) => f in step);
@@ -4107,14 +4147,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "My Workflow",
     description: "A basic workflow with a single action step",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key for the platform",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "step1",
@@ -4123,7 +4156,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey",
+          connection: { platform: "PLATFORM_NAME" },
           data: {}
         }
       }
@@ -4134,14 +4167,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "Conditional Workflow",
     description: "Fetch data, then branch based on results",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetch",
@@ -4150,7 +4176,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4184,14 +4210,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "Loop Workflow",
     description: "Fetch a list, then process each item",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetchList",
@@ -4200,7 +4219,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4233,14 +4252,7 @@ var SCAFFOLD_TEMPLATES = {
     name: "AI Analysis Workflow",
     description: "Fetch data, analyze with Claude, and send results",
     version: "1",
-    inputs: {
-      connectionKey: {
-        type: "string",
-        required: true,
-        description: "Connection key for data source",
-        connection: { platform: "PLATFORM_NAME" }
-      }
-    },
+    inputs: {},
     steps: [
       {
         id: "fetchData",
@@ -4249,7 +4261,7 @@ var SCAFFOLD_TEMPLATES = {
         action: {
           platform: "PLATFORM_NAME",
           actionId: "ACTION_ID_FROM_SEARCH",
-          connectionKey: "$.input.connectionKey"
+          connection: { platform: "PLATFORM_NAME" }
         }
       },
       {
@@ -4732,12 +4744,24 @@ function readProfile(platform, model) {
   }
 }
 function writeProfile(profile) {
-  const required = ["platform", "model", "connectionKey", "actionId", "idField", "pagination"];
+  const required = ["platform", "model", "actionId", "idField", "pagination"];
   for (const field of required) {
     if (!profile[field]) {
       throw new Error(`Missing required field: ${field}`);
     }
   }
+  const hasKey = !!profile.connectionKey;
+  const hasRef = !!profile.connection?.platform;
+  if (hasKey && hasRef) {
+    throw new Error(
+      "Profile has both `connectionKey` and `connection` \u2014 set exactly one. Prefer `connection: { platform, tag? }` so re-auth doesn't break the profile."
+    );
+  }
+  if (!hasKey && !hasRef) {
+    throw new Error(
+      'Missing connection: set `connection: { platform: "<name>" }` (or legacy `connectionKey: "<key>"`).'
+    );
+  }
   if (profile.resultsPath === void 0) {
     throw new Error('Missing required field: resultsPath (use "" or "$" for root-array responses)');
   }
@@ -4748,6 +4772,16 @@ function writeProfile(profile) {
   const filePath = profilePath(profile.platform, profile.model);
   fs8.writeFileSync(filePath, JSON.stringify(profile, null, 2));
 }
+async function resolveProfileConnectionKey(api, profile, cache2) {
+  if (profile.connectionKey) return profile.connectionKey;
+  if (!profile.connection?.platform) {
+    throw new Error(
+      `Profile ${profile.platform}/${profile.model} has no connectionKey or connection ref.`
+    );
+  }
+  const conn = await api.resolveConnection(profile.connection, cache2);
+  return conn.key;
+}
 function writeDraftProfile(platform, model, draft) {
   fs8.mkdirSync(PROFILES_DIR, { recursive: true });
   const filePath = profilePath(platform, model);
@@ -4773,7 +4807,9 @@ function generateTemplate(platform, model, actionId) {
   return {
     platform,
     model,
-    connectionKey: "FILL_IN",
+    // Late-bound ref — survives re-auth. Use { platform, tag } when the
+    // platform has multiple connections (e.g. multiple Gmail accounts).
+    connection: { platform },
     actionId: actionId ?? "FILL_IN",
     resultsPath: "FILL_IN",
     idField: "FILL_IN",
@@ -5833,6 +5869,7 @@ async function syncModel(api, profile, options) {
       "--full-refresh and --since cannot be used together. --full-refresh always fetches the whole collection."
     );
   }
+  const connectionKey = await resolveProfileConnectionKey(api, profile);
   const lock = options.dryRun ? null : acquireSyncLock(platform, model);
   const existingState = getModelState(platform, model);
   if (existingState?.status === "syncing" && !options.dryRun && !isAgentMode()) {
@@ -5960,7 +5997,7 @@ async function syncModel(api, profile, options) {
           const result = await api.executePassthroughRequest({
             platform,
             actionId: profile.actionId,
-            connectionKey: profile.connectionKey,
+            connectionKey,
             pathVariables: profile.pathVars,
             queryParams: currentPageQueryParams,
             headers: currentPageHeaders,
@@ -6169,7 +6206,7 @@ async function syncModel(api, profile, options) {
         profile.enrich,
         model,
         profile.idField,
-        profile.connectionKey,
+        connectionKey,
         platform,
         {
           transform: profile.transform,
@@ -6275,6 +6312,18 @@ async function testSyncProfile(api, profile) {
     if (limitLocation === "body") bodyParams[limitParam] = pageSize;
     else queryParams[limitParam] = pageSize;
   }
+  let connectionKey;
+  try {
+    connectionKey = await resolveProfileConnectionKey(api, profile);
+    checks.push({ name: "connection resolves", ok: true });
+  } catch (err) {
+    checks.push({
+      name: "connection resolves",
+      ok: false,
+      detail: err instanceof Error ? err.message : String(err)
+    });
+    return report;
+  }
   let actionDetails;
   try {
     actionDetails = await api.getActionDetails(profile.actionId);
@@ -6300,7 +6349,7 @@ async function testSyncProfile(api, profile) {
     const result = await api.executePassthroughRequest({
       platform: profile.platform,
       actionId: profile.actionId,
-      connectionKey: profile.connectionKey,
+      connectionKey,
       pathVariables: profile.pathVars,
       queryParams,
       data: Object.keys(bodyParams).length > 0 ? bodyParams : void 0
@@ -7459,11 +7508,11 @@ async function syncInitCommand(platform, model, options) {
           (c) => c.platform === platform
         );
         if (platformConns.length === 1) {
-          template.connectionKey = platformConns[0].key;
-          inferred?.reasoning.push(`connectionKey: auto-resolved (only one ${platform} connection)`);
+          inferred?.reasoning.push(`connection: { platform: "${platform}" } resolves to the single available connection`);
         } else if (platformConns.length > 1) {
+          const tags = platformConns.map((c) => c.tags?.join(",") ?? "(no tag)").join("; ");
           inferred?.reasoning.push(
-            `connectionKey: ${platformConns.length} connections found \u2014 pick one from \`one list\``
+            `connection: ${platformConns.length} ${platform} connections found (tags: ${tags}). Add a \`tag\` field to the connection ref to disambiguate.`
           );
         }
       } catch {
@@ -7547,6 +7596,11 @@ Run with --config to save:
       ...patch.pagination ?? {}
     }
   };
+  if (patch.connection && !patch.connectionKey) {
+    delete profile.connectionKey;
+  } else if (patch.connectionKey && !patch.connection) {
+    delete profile.connection;
+  }
   try {
     writeProfile(profile);
     if (isAgentMode()) {
@@ -8638,12 +8692,12 @@ one --agent sync models stripe
 # 2. Init \u2014 one command does everything:
 #    - resolves action ID
 #    - infers pagination, resultsPath, idField, pathVars from knowledge
-#    - auto-resolves connectionKey (when only one connection exists)
+#    - sets connection: { platform } so the profile survives re-auth
 #    - auto-runs sync test if profile is complete
 one --agent sync init stripe balanceTransactions
 # Response includes _complete:true and _test results when fully resolved.
-# If connectionKey wasn't auto-resolved (multiple connections), patch it:
-one --agent sync init stripe balanceTransactions --config '{"connectionKey":"<from one list>"}'
+# Multi-account platforms (e.g. two Gmail connections) need a tag:
+one --agent sync init gmail gmailThreads --config '{"connection":{"platform":"gmail","tag":"work@example.com"}}'
 
 # 3. Sync
 one --agent sync run stripe
@@ -8654,10 +8708,29 @@ one --agent sync search "refund" --platform stripe
 one --agent sync sql stripe "SELECT count(*) FROM balanceTransactions"
 \`\`\`
 
+## Connection Resolution \u2014 late-bound by default
+
+Sync profiles use a late-bound connection ref instead of a hardcoded key, so re-auth (which always mints a new key) doesn't break the profile:
+
+\`\`\`json
+// recommended \u2014 survives re-auth
+"connection": { "platform": "gmail" }
+
+// multi-account: disambiguate with the connection's tag
+"connection": { "platform": "gmail", "tag": "work@example.com" }
+
+// legacy \u2014 still works for backwards compat, but breaks on re-auth
+"connectionKey": "live::gmail::default::abc123..."
+\`\`\`
+
+The resolver runs at \`sync test\` and \`sync run\` time. Resolution errors (no connection, ambiguous tag, missing tag with multiple connections) surface as the first check in the test report, before any HTTP call.
+
+To migrate an existing profile: replace the \`connectionKey\` field with \`connection: { platform: "<platform>" }\`. Tags only needed when more than one connection exists for the platform.
+
 ## Auto-Inference
 
 \`sync init\` without \`--config\` does all of this automatically:
-- **connectionKey** \u2014 auto-resolved when there's exactly one connection for the platform
+- **connection** \u2014 defaults to \`{ platform: "<platform>" }\` (late-bound). When multiple connections exist, init surfaces the available tags so the agent can add one to the ref.
 - **Pagination** \u2014 Stripe id-pagination, Notion body-cursor, HubSpot/Google token, offset, link. Inapplicable fields stripped (no nextPath for offset, no passAs for none)
 - **resultsPath** \u2014 generic keys (data, results, items) + platform-specific (model name stripped of platform prefix: attioCompanies \u2192 companies). Use \`""\`, \`"$"\`, or \`"."\` for responses that return a bare array at the root (e.g. Hacker News \`/v0/topstories.json\`); primitive array elements are auto-wrapped as \`{ [idField]: value }\`.
 - **idField** \u2014 id, _id, uuid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.39.1",
+  "version": "1.41.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/profiles/attio/attioCompanies.json

@@ -2,7 +2,7 @@
   "description": "Attio companies — CRM company records with domains, industry, and custom attributes",
   "platform": "attio",
   "model": "attioCompanies",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "attio" },
   "actionId": "conn_mod_def::GJt0lFZ6kpk::attio-companies-list",
   "resultsPath": "companies",
   "idField": "id",

package/profiles/attio/attioPeople.json

@@ -2,7 +2,7 @@
   "description": "Attio people — CRM contact records with emails, phone numbers, and custom attributes",
   "platform": "attio",
   "model": "attioPeople",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "attio" },
   "identityKey": "primary_email_address",
   "actionId": "conn_mod_def::GJt0lFZ6kpk::attio-people-list",
   "resultsPath": "people",

package/profiles/fathom/meetings.json

@@ -2,7 +2,7 @@
   "description": "Fathom meetings — recorded meetings with transcripts, summaries, action items, and attendees",
   "platform": "fathom",
   "model": "meetings",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "fathom" },
   "actionId": "conn_mod_def::fathom::meetings-list",
   "resultsPath": "items",
   "idField": "recording_id",

package/profiles/gmail/gmailThreads.json

@@ -2,7 +2,7 @@
   "description": "Gmail email threads — primary inbox with full message bodies (no attachments)",
   "platform": "gmail",
   "model": "gmailThreads",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "gmail" },
   "actionId": "conn_mod_def::GJ3ok-Q0D40::oLWNlcx4QDORaL_18z-MsQ",
   "resultsPath": "threads",
   "idField": "id",

package/profiles/google-calendar/events.json

@@ -2,7 +2,7 @@
   "description": "Google Calendar events — meetings, appointments, and all-day events with attendees and location",
   "platform": "google-calendar",
   "model": "events",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "google-calendar" },
   "actionId": "conn_mod_def::GJ5x5pOh2TU::gcal-events-list",
   "resultsPath": "items",
   "idField": "id",

package/profiles/hacker-news/topStories.json

@@ -2,7 +2,7 @@
   "description": "Hacker News top story IDs — up to 500 item IDs at /v0/topstories.json (root-array response, primitives wrapped as { id })",
   "platform": "hacker-news",
   "model": "topStories",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "hacker-news" },
   "actionId": "conn_mod_def::GJ3108Dwmm4::avAMAq7HQtW6PT8JhPg5vA",
   "resultsPath": "",
   "idField": "id",

package/profiles/notion/search.json

@@ -2,7 +2,7 @@
   "description": "Notion pages and databases — full workspace search with titles, properties, and metadata",
   "platform": "notion",
   "model": "search",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "notion" },
   "actionId": "conn_mod_def::GJ5En67fz04::-CJAS419SVWm7L2l6brp6A",
   "resultsPath": "results",
   "idField": "id",

package/profiles/stripe/balanceTransactions.json

@@ -2,7 +2,7 @@
   "description": "Stripe balance transactions — payments, refunds, payouts, and fees with amount, currency, and status",
   "platform": "stripe",
   "model": "balanceTransactions",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "stripe" },
   "actionId": "conn_mod_def::GGx6clhYjSQ::3kEaM3HQTA2JRfW3DzXC4g",
   "resultsPath": "data",
   "idField": "id",

package/profiles/stripe/customers.json

@@ -2,7 +2,7 @@
   "description": "Stripe customers — customer records with email, name, payment methods, and subscription status",
   "platform": "stripe",
   "model": "customers",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "stripe" },
   "actionId": "conn_mod_def::GGx6clhYjSQ::customers-list",
   "resultsPath": "data",
   "idField": "id",

package/skills/one/SKILL.md

@@ -175,6 +175,8 @@ one sync schedule add stripe --every 1h
 
 **Sync rejects custom actions** — profiles must use passthrough. `sync init` only surfaces passthrough models; `sync run` aborts if the list or enrich action is tagged `custom`. If no passthrough exists, compose a flow instead.
 
+**Connections are late-bound** — profiles use `"connection": { "platform": "<name>" }`, not literal `connectionKey` strings. The key is resolved at sync time, so `one add <platform>` (re-auth) doesn't break the profile. For multi-account platforms, add `"tag": "<connection-tag>"` to disambiguate. Don't hardcode connection keys in profiles.
+
 **Advanced features** (enrich, transform, exclude, identityKey, hooks, --full-refresh, --where-sql delete, cursor resume): run `one guide sync` for the full reference.
 
 ## Beyond Single Actions

package/skills/one/references/flows.md

@@ -282,12 +282,19 @@ The `if`, `unless`, `condition.expression`, `while.condition`, `transform.expres
   "action": {
     "platform": "stripe",
     "actionId": "conn_mod_def::xxx::yyy",
-    "connectionKey": "$.input.stripeConnectionKey",
+    "connection": { "platform": "stripe" },
     "data": { "query": "email:'{{$.input.customerEmail}}'" }
   }
 }
 ```
 
+**Connection forms.** Each action step sets exactly one of:
+
+- **`connection: { platform: "<name>", "tag"?: "<tag>" }`** (preferred) — late-bound, resolved at flow-execute time. Survives re-auth (which always mints a new key). Use `tag` to disambiguate when a platform has multiple connections (e.g. multi-account Gmail). Both `platform` and `tag` accept `$.input.x` selectors so flows can be parameterised per-execution.
+- **`connectionKey: "<literal-or-selector>"`** (legacy) — passes the key string straight through. Still supported for backwards compat, but breaks on re-auth and forces manual edits across every flow that references the stale key. Migrate to `connection` when convenient.
+
+The validator rejects an action that sets both forms (or neither) at `flow validate` and `flow execute` time.
+
 ### `transform` — JS expression (implicit return)
 
 ```json