@adrata/adrata-mcp 1.0.8 → 1.0.30

package/tools/provisioning/onboarding-tools.js

@@ -0,0 +1,730 @@
+/**
+ * Provisioning: seating a workspace user, and the onboarding link that reaches them.
+ *
+ * # Why this pack exists
+ *
+ * Adrata is onboarding real customers, and the act an AE actually performs is
+ * "mint a link and drop it in the Zoom chat". Until now MCP could not perform
+ * it at all, for two separate reasons that look like one:
+ *
+ *   1. **There is no purpose-built tool.** The only route to seating was the
+ *      chat tool `invite_user` reached through `adrata_ai_tool_execute`, which
+ *      `tool-annotations.js` classifies `legacy_bridge`. It takes ONE email
+ *      (`"required": ["email"]` in routes-ai `.../definitions/specialized/
+ *      workspace_defs.rs`) and carries no adaptive payload whatsoever.
+ *
+ *   2. **That route cannot complete a write from here, by design.** Measured
+ *      2026-09-06 against `routes-ai/src/tools/ai_crm_tools/mod.rs:427`:
+ *
+ *          if !interactive_human {
+ *              return Err(AppError::Forbidden(
+ *                  "Machine principals cannot approve AI CRM writes; an
+ *                   interactive human session must authorize the action"))
+ *          }
+ *
+ *      Every MCP client is a machine principal, so `invite_user` through the
+ *      bridge previews forever and seats nobody. That is the "capability
+ *      nothing can reach" class from `.claude/CLAUDE.md`: reading the tool
+ *      catalogue makes you believe seating works from MCP, and the failure
+ *      arrives only at the last step.
+ *
+ * So this pack is not a convenience wrapper over a working path. It is the
+ * first path from MCP that can finish.
+ *
+ * # Why there is ONE tool and not two
+ *
+ * The obvious shape is a `seat_user` tool plus a `create_onboarding_link`
+ * tool. It is the wrong shape here, and the reason is written down in
+ * `code/api/src/routes/v1/entities/org/workspace/invitations.rs`:
+ *
+ *   > There were two ways to seat a workspace user and only one of them
+ *   > invited anybody. [...] Measured in production on 2026-08-31:
+ *   > `noah@adrata.com` was seated as an admin, the row was real and
+ *   > `list_users` confirmed it, and the invitee's inbox was empty.
+ *
+ * Seating and inviting are one operation because `POST /workspace/members/
+ * invite` does both in one call: it finds-or-creates the user, adds the
+ * membership, and mints the token. A separate "seat without a link" tool would
+ * reconstruct the exact defect that module exists to prevent, one layer up.
+ * One invitation, one tool.
+ *
+ * # The scope story, which is better than it looks and worse than it reads
+ *
+ * `/workspace` sits in `GRANDFATHERED_UNMAPPED` (middleware `scope_guard/
+ * grandfathered.rs`), so `required_scopes_for` returns an empty vec and this
+ * route needs NO OAuth scope. The default grant can therefore call it — there
+ * is no `write:integrations`-shaped trap here, and the tool is reachable today.
+ *
+ * That register is explicitly "A DEBT REGISTER, NOT A PERMANENT EXEMPTION",
+ * and paying the debt down is where the danger is. Workspace administration
+ * would naturally map to an `admin:*` scope, and `access/oauth.js` records —
+ * with its own measurement — that `admin:*` is **permanently ungrantable**
+ * through this client: `consented_scope_grant` refuses every `admin:`-prefixed
+ * scope before it consults the client registration, under every role including
+ * `super_admin`. So mapping `/workspace` to `admin:workspace` would not be a
+ * #2435-shaped outage that heals when the API catches up; it would kill this
+ * tool permanently. Whoever pays that debt down must map member-invite to a
+ * NON-admin write scope (`write:members`, say) and add it to
+ * `OAUTH_WRITE_SCOPE`, or accept that MCP provisioning stops working.
+ *
+ * The real gate today is not a scope at all: `invite_member` requires the
+ * caller to be a workspace admin (`is_workspace_admin`), so a seller's
+ * connection gets a 403 from the handler regardless of what it holds.
+ *
+ * # The token is a credential
+ *
+ * An invite URL seats its bearer in the workspace. It is treated the way the
+ * companion migration treats it — `20270106005522_workspace_invitation_records
+ * .sql` stores only the token's SHA-256 and says why:
+ *
+ *   > Anyone holding the token can seat themselves in the workspace.
+ *
+ * Consequences honoured here: the URL is returned to the caller once and is
+ * never written to a log line, never put in an error message, and never placed
+ * in a preview (a preview has minted nothing, so it has no URL to leak). The
+ * replay ledger below holds URLs in memory only, and `redactInviteUrl` is the
+ * only shape allowed anywhere diagnostic.
+ */
+
+import { createHash } from 'node:crypto';
+
+import {
+  isLiveWrite,
+  missingLiveWriteFields,
+  liveWriteRefusal,
+} from '../../governance/governed-args.js';
+
+/**
+ * The ONE minting endpoint. Named as a constant because the whole argument
+ * above depends on there being exactly one, and a second literal elsewhere in
+ * this file would be the first step back to two paths.
+ */
+export const INVITE_PATH = '/api/v1/workspace/members/invite';
+export const SEATS_PATH = '/api/v1/workspace/members';
+
+/**
+ * Launch identifiers must match the column's own CHECK constraint:
+ *
+ *     launch TEXT CHECK (launch IS NULL OR launch ~ '^[a-z][a-z0-9_]{0,63}$')
+ *
+ * Validated here rather than left to the database because the failure
+ * otherwise arrives as a 500 with a constraint name in it, after the user has
+ * already been created — the invite handler creates the user BEFORE it mints,
+ * so a late rejection leaves a seated user with no link. That is the same
+ * half-invited state the `managerId` pre-check in `members.rs` was written to
+ * avoid, and it deserves the same treatment.
+ *
+ * The vocabulary itself is deliberately NOT enumerated here. The migration
+ * explains why the column is free text: "The set of launches is a product
+ * decision that will move faster than migrations." An enum in this file would
+ * reintroduce exactly that coupling, one process further out.
+ */
+/**
+ * The role that makes somebody the operator of their own workspace, and the
+ * reason `role` on this tool is REQUIRED rather than defaulted.
+ *
+ * # The contradiction this constant exists to close
+ *
+ * This tool used to default the seat to `seller`. `canOfferTeamInvite`
+ * (`code/desktop/src/renderer/src/features/chat/team-invite-admin.ts`) accepts
+ * only `admin`, on an owner ruling of 2026-09-06 — "admins only, keep the
+ * routing as is" — because all three routes the offer opens end at an
+ * admin-gated server call, and offering somebody an action the server answers
+ * 403 to is worse than staying silent.
+ *
+ * Neither decision is wrong on its own. Together they made the team-invite
+ * offer dead for everybody minted the default way, and the two halves are
+ * wired to each other more tightly than that: the offer only fires for a
+ * `launch`, and a `launch` is set ONLY on an invitation minted here
+ * (`launch.ts`: "It is set on the invitation during the sale"). So the
+ * trigger's population was exactly this tool's output, and the gate's
+ * population excluded all of it. A feature whose trigger and whose gate are
+ * wired to disjoint populations has no audience at all.
+ *
+ * # Why REQUIRED, rather than flipping the default to `admin`
+ *
+ * Because the tool genuinely cannot know, and both guesses are wrong in
+ * opposite directions:
+ *
+ *  - Defaulting `seller` silently under-grants the buyer, who is the person
+ *    the AE just sold to and the one who will add their own team. That is the
+ *    defect above: it costs the whole growth loop and shows up as nothing.
+ *  - Defaulting `admin` silently over-grants everybody else. An AE seating
+ *    three people at a customer during a pilot would mint three workspace
+ *    admins nobody decided to create. A grant that widens by default is the
+ *    failure direction you cannot take back.
+ *
+ * **"First member" is not derivable here, and that was checked rather than
+ * assumed.** `create_workspace` seats its creator as `admin` in the same
+ * transaction (`workspace_repo/core.rs`: `INSERT INTO workspace_users ...
+ * VALUES ($1, $2, $3, 'admin', NOW())`), so the seat list is NEVER empty at
+ * mint time and a "no seats yet" rule can never fire. `workspace_users`
+ * carries no `first`, `owner` or `seq` column — only `joinedAt` — so "the
+ * first customer seat" would have to be a heuristic about which existing seat
+ * is the AE's, which is an identity guess dressed as a fact.
+ *
+ * The server keeps its own `seller` default (`members.rs`, and a second route
+ * in `admin/security/core/handlers.rs`) and should: least privilege is right
+ * for a general-purpose member-invite endpoint reached by many callers. What
+ * was wrong was a THIRD default, in a tool whose audience is one specific
+ * person, disagreeing silently with the gate downstream of it.
+ *
+ * So this tool asks. It costs the caller one field, the preview prints the
+ * answer before anything is written, and no seat is ever granted by omission.
+ *
+ * # Why this value is `admin` exactly
+ *
+ * `team-invite-admin.ts` argues the point in full: `workspace_users.role` is
+ * free-form TEXT, and the two server gates do not accept identically — REST
+ * normalizes `workspace_admin` and `owner` up to admin, while chat's
+ * `RoleTier::from_auth_role` matches only `admin`, `super_admin` and `owner`
+ * literally. `admin` is the one spelling BOTH accept and the only one
+ * `normalize_assignable_role` will write. `onboarding-tools.test.js` binds
+ * this constant to that module's real offer set so the two cannot drift apart
+ * again in silence.
+ */
+export const WORKSPACE_SETUP_ROLE = 'admin';
+
+/** The ordinary seat: somebody joining a team that already exists. */
+export const WORKSPACE_MEMBER_ROLE = 'seller';
+
+const LAUNCH_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+const SOURCE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+const PREPARED_NOTE_MAX = 2000;
+const MAX_PREPARED_ACCOUNTS = 100;
+
+/** Matches `idempotency_key TEXT CHECK (char_length BETWEEN 8 AND 255)`. */
+const IDEMPOTENCY_KEY_MIN = 8;
+const IDEMPOTENCY_KEY_MAX = 255;
+
+/**
+ * How many replay entries to keep. Bounded because each entry holds a live
+ * credential: an unbounded map would accumulate every invite URL the process
+ * has ever minted, turning a long-lived MCP server into a token store nobody
+ * decided to build.
+ */
+const REPLAY_LEDGER_MAX = 256;
+
+/**
+ * Render an invite URL safe for a log, an error, or a report.
+ *
+ * The token is the entire secret, so this keeps the origin and path — enough
+ * to tell a reader which environment minted it — and destroys the rest.
+ * Nothing in this pack may print an invite URL any other way.
+ */
+export function redactInviteUrl(url) {
+  if (!url) return null;
+  try {
+    const parsed = new URL(String(url));
+    return `${parsed.origin}${parsed.pathname}?token=[redacted]`;
+  } catch {
+    return '[redacted invite url]';
+  }
+}
+
+/**
+ * A stable fingerprint of what a call would mint.
+ *
+ * Keys are sorted so that argument order cannot make two identical requests
+ * look different — a caller who names `launch` before `email` must not get a
+ * second invitation for it. Arrays are NOT sorted: the order of
+ * `preparedAccountIds` is caller-meaningful and a reorder is a different
+ * prepared workspace.
+ */
+export function fingerprintInvitation(body) {
+  const canonical = JSON.stringify(body, Object.keys(body).sort());
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+/**
+ * In-process replay safety for minting.
+ *
+ * # Why this is here and not only at the API
+ *
+ * Criterion: repeating an identical call with the same idempotency key must
+ * return the same URL and must not mint a second invitation. Measured against
+ * the deployed route on 2026-09-06, `invite_member` reads no `Idempotency-Key`
+ * header at all — it calls `uuid::Uuid::new_v4()` unconditionally, so a second
+ * identical call mints a SECOND token to the same person. The seat is
+ * idempotent (`find_user_by_email` reuses the row); the credential is not.
+ *
+ * The companion migration adds the server-side answer —
+ * `workspace_invitation_records_idempotency_idx`, unique on
+ * `(workspace_id, idempotency_key)` — but that column is written by route code
+ * that is still in flight. Until it lands, a client-side ledger is the only
+ * thing standing between a retried tool call and a second live credential
+ * mailed to the same person.
+ *
+ * # What this is NOT
+ *
+ * It is process-local and memory-only. A restarted server, a second MCP
+ * process, or a call made through any other client will not see these entries,
+ * so this is a guard and not a guarantee. It is deliberately not persisted:
+ * writing invite URLs to disk to improve deduplication would trade a bounded
+ * in-memory credential for an unbounded on-disk one, which is a worse problem
+ * than the one being solved. The `Idempotency-Key` header is sent on every
+ * live call regardless, so the moment the server honours it the authoritative
+ * check is the server's and this becomes a fast path.
+ *
+ * Keyed by workspace as well as key, so one tenant's idempotency key can never
+ * resolve to another tenant's minted invitation.
+ */
+export function createReplayLedger({ max = REPLAY_LEDGER_MAX } = {}) {
+  const entries = new Map();
+
+  // JSON-encoded rather than concatenated with a separator. An idempotency key
+  // is caller-supplied and may contain the separator, so `a` + sep + `b c` and
+  // `a b` + sep + `c` would collide — and a collision here means one tenant's
+  // key resolving to another tenant's minted invitation, which is the exact
+  // boundary this composition exists to hold.
+  const compose = (workspaceId, idempotencyKey) =>
+    JSON.stringify([workspaceId || 'unknown-workspace', idempotencyKey]);
+
+  return {
+    get(workspaceId, idempotencyKey) {
+      return entries.get(compose(workspaceId, idempotencyKey)) ?? null;
+    },
+    remember(workspaceId, idempotencyKey, record) {
+      // Oldest-first eviction. A Map iterates in insertion order, so the first
+      // key is the oldest; dropping it bounds the number of live credentials
+      // held in memory at any moment.
+      if (entries.size >= max) {
+        const oldest = entries.keys().next().value;
+        if (oldest !== undefined) entries.delete(oldest);
+      }
+      entries.set(compose(workspaceId, idempotencyKey), record);
+      return record;
+    },
+    get size() {
+      return entries.size;
+    },
+  };
+}
+
+/**
+ * Validate the adaptive payload before anything is created.
+ *
+ * Returns an array of human-readable problems. Empty means valid. Checked
+ * client-side because `invite_member` creates the user row BEFORE it mints,
+ * so a constraint rejection at the database leaves a seated user holding no
+ * link — visible in `list_members`, unable to sign in. Exactly the state the
+ * production incident on 2026-08-31 produced.
+ */
+export function validateOnboardingArgs(args = {}) {
+  const problems = [];
+
+  const email = String(args.email ?? '').trim();
+  if (!email) problems.push('email is required');
+  else if (!email.includes('@') || email.length < 3 || email.length > 320) {
+    problems.push(`email "${email}" is not a usable address`);
+  }
+
+  // The seat is a grant, and this tool has no honest default for it. Refusing
+  // here rather than substituting is the whole of WORKSPACE_SETUP_ROLE's
+  // argument: the caller knows which person they just sold to and the tool
+  // does not. Checked before the write for the same reason every other clause
+  // in this function is — the invite route creates the user row before it
+  // mints, so a late refusal leaves a seated user with no link.
+  const role = String(args.role ?? '').trim();
+  if (!role) {
+    problems.push(
+      'role is required and has no default, because both possible defaults are wrong in opposite'
+        + ` directions. Say "${WORKSPACE_SETUP_ROLE}" for the person setting the workspace up — the`
+        + ' buyer, who will be adding their own team and who is the only role offered the team invite'
+        + ` — or "${WORKSPACE_MEMBER_ROLE}" for somebody joining a team that already exists.`
+        + ' Guessing here either silently denies the buyer their own team or silently makes a'
+        + ' teammate an admin nobody decided to create',
+    );
+  }
+
+  if (args.launch !== undefined && args.launch !== null) {
+    const launch = String(args.launch);
+    if (!LAUNCH_PATTERN.test(launch)) {
+      problems.push(
+        `launch "${launch}" must be a short lower-case identifier matching ${LAUNCH_PATTERN.source}`
+          + ' — it is an identifier for a loop, not a sentence describing one',
+      );
+    }
+  }
+
+  if (args.source !== undefined && args.source !== null) {
+    const source = String(args.source);
+    if (!SOURCE_PATTERN.test(source)) {
+      problems.push(`source "${source}" must match ${SOURCE_PATTERN.source}`);
+    }
+  }
+
+  if (args.preparedAccountIds !== undefined && args.preparedAccountIds !== null) {
+    const ids = args.preparedAccountIds;
+    if (!Array.isArray(ids)) problems.push('preparedAccountIds must be an array of company ids');
+    else {
+      if (ids.length > MAX_PREPARED_ACCOUNTS) {
+        problems.push(
+          `preparedAccountIds holds ${ids.length} ids; at most ${MAX_PREPARED_ACCOUNTS} accounts can be prepared for one person`,
+        );
+      }
+      if (ids.some((id) => typeof id !== 'string' || !id.trim())) {
+        problems.push('preparedAccountIds must contain non-empty company id strings');
+      }
+    }
+  }
+
+  if (args.preparedNote !== undefined && args.preparedNote !== null) {
+    const note = String(args.preparedNote);
+    if (note.length > PREPARED_NOTE_MAX) {
+      problems.push(
+        `preparedNote is ${note.length} characters; the column is bounded at ${PREPARED_NOTE_MAX}`
+          + ' so it cannot become a place to stash a transcript',
+      );
+    }
+  }
+
+  if (args.idempotencyKey !== undefined && args.idempotencyKey !== null) {
+    const key = String(args.idempotencyKey).trim();
+    if (key && (key.length < IDEMPOTENCY_KEY_MIN || key.length > IDEMPOTENCY_KEY_MAX)) {
+      problems.push(
+        `idempotencyKey must be ${IDEMPOTENCY_KEY_MIN}-${IDEMPOTENCY_KEY_MAX} characters`
+          + ` (got ${key.length}); the storage column enforces the same bound`,
+      );
+    }
+  }
+
+  return problems;
+}
+
+/** The exact body this tool would send. Kept in one place so preview and live write cannot drift. */
+export function buildInvitationBody(args = {}) {
+  const body = {
+    email: String(args.email ?? '').trim(),
+    // NO DEFAULT, deliberately. See WORKSPACE_SETUP_ROLE. An absent role
+    // reaches the server as the empty string and is refused there by name,
+    // rather than quietly becoming a grant nobody chose.
+    role: String(args.role ?? '').trim(),
+  };
+  if (args.managerId) body.managerId = args.managerId;
+
+  // ── The adaptive payload ────────────────────────────────────────────────
+  // INTEGRATION POINT (2026-09-06): these four fields are sent and the
+  // DEPLOYED endpoint ignores them. `InviteMemberRequest` in
+  // `code/api/src/routes/v1/entities/org/workspace/members.rs` declares
+  // exactly `email`, `role` and `manager_id`; serde drops unknown fields
+  // silently, so the call succeeds, a link is minted, and the launch is
+  // simply not recorded. They are sent anyway rather than withheld, because
+  // the route change carrying `InvitationContext` is in flight on
+  // `feature/onboarding-grant-record` and the wire shape should not need a
+  // second edit when it lands.
+  //
+  // What this means for a caller TODAY, and it is stated in the tool's own
+  // response rather than only here: the seat and the link are real, and the
+  // adaptive configuration is not yet durable.
+  //
+  // Note also that `InviteMemberRequest` carries no
+  // `#[serde(rename_all = "camelCase")]` — `manager_id` works only because it
+  // declares `alias = "managerId"` by hand. Any new field added there needs
+  // the same treatment or the camelCase name silently does nothing, which is
+  // the defect class `.claude/CLAUDE.md` records against the document-ingest
+  // route (422 `missing field file_base64`).
+  if (args.launch) body.launch = String(args.launch);
+  if (Array.isArray(args.preparedAccountIds) && args.preparedAccountIds.length > 0) {
+    body.preparedAccountIds = args.preparedAccountIds.map((id) => String(id));
+  }
+  if (args.preparedNote) body.preparedNote = String(args.preparedNote);
+  body.source = args.source ? String(args.source) : 'mcp_provisioning';
+
+  return body;
+}
+
+export function registerProvisioningTools(
+  server,
+  {
+    z,
+    api,
+    ok,
+    validateApiBridgeRequest,
+    buildMutationHeaders,
+    getGrantedScope = () => undefined,
+    getWorkspaceId = () => null,
+    ledger = createReplayLedger(),
+  },
+) {
+  server.tool(
+    'list_workspace_seats',
+    'List the people already seated in the connected workspace, with their role. Read-only.'
+      + ' Check this BEFORE minting an onboarding link: re-inviting somebody who already holds a live'
+      + ' invitation is refused by a unique index (one live invitation per address per workspace), and'
+      + ' the useful action for an existing seat is a resend rather than a second link.'
+      + ' Scoped to the connected workspace by the API from the token; there is no parameter that can'
+      + ' widen it to another tenant.',
+    {},
+    async () => {
+      const response = await api('GET', SEATS_PATH);
+      const seats = response?.data ?? response ?? [];
+      return ok({ workspaceId: getWorkspaceId(), seats, count: Array.isArray(seats) ? seats.length : null });
+    },
+  );
+
+  server.tool(
+    'create_onboarding_link',
+    'Seat a person in the connected workspace and mint the adaptive onboarding link an AE drops into a'
+      + ' Zoom chat. One call does both: the user row, the membership, and the setup link are a single'
+      + ' operation, because seating without inviting is the production defect that'
+      + ' `workspace/invitations.rs` exists to prevent (a real admin was seated in 2026-08-31 with an'
+      + ' empty inbox and no way to sign in).'
+      + ' Name the launch this person should land in and the accounts prepared for them, so they arrive'
+      + ' in a configured workspace rather than an empty one.'
+      + ` Say who they are: role is REQUIRED and has no default. "${WORKSPACE_SETUP_ROLE}" is the person`
+      + ' standing the workspace up — the buyer, who will add their own team, and the only role Adrata'
+      + ` ever offers the team invite to. "${WORKSPACE_MEMBER_ROLE}" is somebody joining a team that`
+      + ' already exists.'
+      + ' THE RETURNED URL IS A CREDENTIAL: anyone holding it can seat themselves in this workspace.'
+      + ' Treat it like a password, deliver it over a channel you trust, and do not paste it into a log,'
+      + ' a ticket, or a shared document.'
+      + ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a'
+      + ' reason, and an idempotencyKey — reuse the SAME key on retry and the same link is returned'
+      + ' rather than a second credential being mailed to the same person.'
+      + ' This route requires no OAuth write scope (the /workspace family is grandfathered unmapped), so'
+      + ' approval and audit are the client-side gate; the API separately requires the connected user to'
+      + ' be a workspace admin and answers 403 otherwise.',
+    {
+      email: z.string().describe('The person to seat. The invitation is addressed here.'),
+      role: z
+        .string()
+        .describe(
+          'REQUIRED, and there is deliberately no default — the two candidates are wrong in opposite'
+            + ` directions. Pass "${WORKSPACE_SETUP_ROLE}" for the person setting this workspace up: the`
+            + ' buyer you just sold to, who will be adding their own team. They are the ONLY role Adrata'
+            + ' ever offers the team invite to, so seating them any other way means they cannot bring'
+            + ` anybody in. Pass "${WORKSPACE_MEMBER_ROLE}" for somebody joining a team that already`
+            + ' exists. Other canonical assignable roles are accepted (seller_manager, manager, leader,'
+            + ' operations, enablement, csm, account_manager, marketing, finance, viewer); the API'
+            + ' rejects anything else by name, before it creates anybody.',
+        ),
+      launch: z
+        .string()
+        .optional()
+        .describe(
+          'Which onboarding loop this person lands in, as a short lower-case identifier'
+            + ' (^[a-z][a-z0-9_]{0,63}$). Omit it rather than guessing: an absent launch is the honest'
+            + ' cold case and is stored as NULL, whereas a wrong one silently lands somebody in the'
+            + ' wrong loop.',
+        ),
+      preparedAccountIds: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'Company ids prepared for this person before they ever sign in, so their first screen has'
+            + ' their accounts on it. Order is meaningful and preserved.',
+        ),
+      preparedNote: z
+        .string()
+        .optional()
+        .describe('Context the configuring seller wants carried into the launch. Bounded at 2000 characters.'),
+      managerId: z
+        .string()
+        .optional()
+        .describe(
+          'Optional reporting line. Must already be a member of this workspace — the API validates it'
+            + ' BEFORE creating anything, so a bad id cannot leave a half-invited user behind.',
+        ),
+      source: z
+        .string()
+        .optional()
+        .describe('How this invitation came to exist, for reading the funnel later. Defaults to mcp_provisioning.'),
+      dryRun: z
+        .boolean()
+        .optional()
+        .describe('Defaults to true. Returns a preview naming the launch and the prepared accounts and mints nothing.'),
+      approved: z
+        .boolean()
+        .optional()
+        .describe('Required (true) for a live write. Records that the caller confirmed minting a credential.'),
+      reason: z.string().optional().describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
+      idempotencyKey: z
+        .string()
+        .optional()
+        .describe(
+          'Required for a live write, 8-255 characters. Sent as Idempotency-Key. Reusing it with an'
+            + ' IDENTICAL request replays the first link; reusing it with a DIFFERENT request is refused'
+            + ' rather than silently minting or silently replaying the wrong invitation.',
+        ),
+    },
+    async (args) => {
+      const problems = validateOnboardingArgs(args);
+      if (problems.length > 0) {
+        return ok({
+          error: true,
+          executed: false,
+          minted: false,
+          problems,
+          message:
+            `Nothing was sent. ${problems.length} problem(s) with the invitation: ${problems.join('; ')}.`
+            + ' These are checked here rather than at the database because the invite route creates the'
+            + ' user row before it mints the token, so a late rejection leaves a seated user with no link.',
+        });
+      }
+
+      const body = buildInvitationBody(args);
+      const request = { method: 'POST', path: INVITE_PATH };
+
+      // The three-field gate, checked before `validateApiBridgeRequest` so the
+      // refusal can name ALL of what is missing. That helper throws on the
+      // first one it finds, which tells a caller to add a reason and then, one
+      // round trip later, to add an idempotency key. Same gate, said once.
+      if (isLiveWrite(args)) {
+        const missing = missingLiveWriteFields(args);
+        if (missing.length > 0) {
+          return ok({
+            ...liveWriteRefusal(args, request),
+            executed: false,
+            minted: false,
+          });
+        }
+      }
+
+      let validation;
+      try {
+        validation = validateApiBridgeRequest({
+          method: 'POST',
+          path: INVITE_PATH,
+          dryRun: args.dryRun,
+          approved: args.approved,
+          reason: args.reason,
+          idempotencyKey: args.idempotencyKey,
+          grantedScope: getGrantedScope(),
+        });
+      } catch (err) {
+        return ok({ error: true, executed: false, minted: false, message: err.message });
+      }
+
+      if (validation.dryRun) {
+        // A preview has minted nothing, so it has no URL and no token to leak.
+        // It names the launch and the accounts because those are the two things
+        // a reviewer is being asked to approve — an approval step that does not
+        // show what is being configured is decoration.
+        return ok({
+          dryRun: true,
+          executed: false,
+          minted: false,
+          action: `Seat ${body.email} as ${body.role} and mint one onboarding link`,
+          role: body.role,
+          // The seat's consequence, said in the language of what the person
+          // will and will not be able to do, at the moment somebody is being
+          // asked to approve it. An approval step that prints a role name and
+          // not its effect is asking for a rubber stamp.
+          roleNote:
+            body.role === WORKSPACE_SETUP_ROLE
+              ? `As ${WORKSPACE_SETUP_ROLE} they can set this workspace up and add their own team;`
+                + ' Adrata will offer them the team invite once their first loop closes.'
+              : `As ${body.role} they can use the workspace but cannot invite anybody, and Adrata will`
+                + ` never offer them the team invite. Seat them as ${WORKSPACE_SETUP_ROLE} instead if`
+                + ' this is the person standing the workspace up.',
+          launch: body.launch ?? null,
+          launchNote: body.launch
+            ? `They will land in the "${body.launch}" launch.`
+            : 'No launch named. They land in the default cold start rather than a configured loop.',
+          preparedAccountIds: body.preparedAccountIds ?? [],
+          preparedAccountCount: body.preparedAccountIds?.length ?? 0,
+          preparedNote: body.preparedNote ?? null,
+          adaptivePayloadDurable: false,
+          adaptivePayloadNote:
+            'INTEGRATION POINT: the deployed invite endpoint accepts email, role and managerId only, so'
+            + ' launch, preparedAccountIds, preparedNote and source are sent but not yet stored. The seat'
+            + ' and the link are real; the adaptive configuration becomes durable when the'
+            + ' workspace_invitation_records route change ships.',
+          preview: validation,
+          body,
+          note:
+            'Nothing was written and no token exists. Re-call with dryRun:false, approved:true, a reason,'
+            + ' and an idempotencyKey to mint the link.',
+        });
+      }
+
+      // ── Live write ──────────────────────────────────────────────────────
+      const workspaceId = getWorkspaceId();
+      const key = String(args.idempotencyKey).trim();
+      const fingerprint = fingerprintInvitation(body);
+      const previous = ledger.get(workspaceId, key);
+
+      if (previous) {
+        if (previous.fingerprint !== fingerprint) {
+          // The dangerous case, and the reason the ledger stores a fingerprint
+          // rather than only a URL. Returning the stored link would hand back
+          // an invitation for a DIFFERENT person or a different launch than
+          // the one just requested; minting would defeat the key's whole
+          // purpose. Refusing is the only answer that is not a lie.
+          return ok({
+            error: true,
+            refused: true,
+            executed: false,
+            minted: false,
+            message:
+              `idempotencyKey "${key}" was already used in this workspace for a DIFFERENT invitation.`
+              + ' Nothing was minted and the earlier link was not returned: replaying it would hand back'
+              + ' an invitation for different arguments, and minting would make the key meaningless.'
+              + ' Use a new idempotencyKey, or re-send the identical arguments to replay the first link.',
+          });
+        }
+        return ok({
+          dryRun: false,
+          executed: true,
+          minted: false,
+          replayed: true,
+          inviteUrl: previous.inviteUrl,
+          userId: previous.userId,
+          email: body.email,
+          message:
+            `Replayed the invitation already minted under idempotencyKey "${key}". No second invitation`
+            + ' was created and no second seat was taken.',
+        });
+      }
+
+      let data;
+      try {
+        data = await api('POST', INVITE_PATH, {
+          body,
+          headers: buildMutationHeaders(args),
+        });
+      } catch (err) {
+        // The error is surfaced verbatim EXCEPT that it is never allowed to
+        // carry a URL: a failure late in minting can echo the request back.
+        return ok({
+          error: true,
+          executed: false,
+          minted: false,
+          message: String(err?.message ?? err).replace(/https?:\/\/\S*token=\S*/gi, '[redacted invite url]'),
+        });
+      }
+
+      const payload = data?.data ?? data ?? {};
+      const inviteUrl = payload.inviteUrl ?? null;
+      const userId = payload.userId ?? null;
+
+      if (inviteUrl) ledger.remember(workspaceId, key, { fingerprint, inviteUrl, userId });
+
+      return ok({
+        dryRun: false,
+        executed: true,
+        minted: Boolean(inviteUrl),
+        replayed: false,
+        email: body.email,
+        role: body.role,
+        userId,
+        inviteUrl,
+        launch: body.launch ?? null,
+        preparedAccountIds: body.preparedAccountIds ?? [],
+        adaptivePayloadDurable: false,
+        adaptivePayloadNote:
+          'The seat and the link are live. launch/preparedAccountIds/preparedNote were sent but the'
+          + ' deployed endpoint does not yet store them — see the integration point in tools/provisioning.js.',
+        credentialWarning:
+          'inviteUrl is a credential: anyone holding it can seat themselves in this workspace. Deliver it'
+          + ' over a trusted channel and do not paste it into a log, a ticket, or a shared document.',
+        replaySafety:
+          `Retry with idempotencyKey "${key}" and identical arguments to get this same link back rather`
+          + ' than a second one. That guard is in-process: a restarted or second MCP server will not see it.',
+      });
+    },
+  );
+}
+
+export const PROVISIONING_TOOL_NAMES = ['list_workspace_seats', 'create_onboarding_link'];