Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

34.3 KB
Raw Blame
const crypto = require("crypto");
const { describeError } = require("./errorSummary");
const { policyRefusal } = require("./connectorPolicy");
const { normalizeQueryResult, queryFailed } = require("./queryResult");

const CANCEL_REASONS = new Set(["cancelled_by_user", "conversation_ended", "expired"]);

// A connector is third-party code (or a stub in tests), so none of its result
// fields are trusted: each state keeps only the fields it defines, with their
// types checked. Anything else could leak to the renderer, or make the receipt
// write throw and leave the row stuck at "committing".
function stringFields(fields) {
  return Object.fromEntries(
    Object.entries(fields).filter(([, value]) => typeof value === "string")
  );
}

function booleanFields(fields) {
  return Object.fromEntries(
    Object.entries(fields).filter(([, value]) => typeof value === "boolean")
  );
}

function stringOr(value, fallback) {
  return typeof value === "string" ? value : fallback;
}

const FAILED_MESSAGE = "That action didn't go through.";

function failedResult(result) {
  return {
    state: "failed",
    errorCode: stringOr(result.errorCode, "action_failed"),
    message: stringOr(result.message, FAILED_MESSAGE),
  };
}

// Anything other than a recognized outcome may still have reached the
// provider, so it is "unknown", never "failed".
//
// destinationLabel is optional: only a connector whose commit can change
// who the receipt names (Gmail's edited To/Cc) returns one, for "sent" and
// "unknown" only. When it's absent the receipt keeps the label prepare
// wrote (Slack: the destination is fixed once prepared).
function normalizeCommitResult(result) {
  switch (result?.state) {
    case "sent":
      return {
        state: "sent",
        // resultLabel names what the send created ("ENG-124"), for the card
        // and the model; only a created item has one.
        ...stringFields({
          url: result.url,
          destinationLabel: result.destinationLabel,
          resultLabel: result.resultLabel,
        }),
      };
    case "failed":
      return failedResult(result);
    case "unknown":
      return {
        state: "unknown",
        ...stringFields({
          checkUrl: result.checkUrl,
          errorCode: result.errorCode,
          destinationLabel: result.destinationLabel,
        }),
      };
    default:
      return { state: "unknown" };
  }
}

// A direct action that threw or answered malformed may already have acted
// (a compose window opened before a later step failed); calling it "failed"
// would invite a duplicate retry.
function uncertainDirectResult(errorCode) {
  return {
    state: "unknown",
    errorCode,
    message: "That action may have gone through. Ask the user to check before trying again.",
  };
}

// "not_sent" is the connector saying it stopped before acting (a cancel that
// landed in time).
function normalizeDirectResult(result) {
  const destination = stringFields({ destinationLabel: result?.destinationLabel });
  switch (result?.state) {
    case "sent":
      return {
        state: "sent",
        destinationLabel: "",
        ...destination,
        ...booleanFields({
          bodyCopied: result.bodyCopied,
          subjectCopied: result.subjectCopied,
          copyFailed: result.copyFailed,
        }),
      };
    case "failed":
      return { ...failedResult(result), ...destination };
    case "not_sent":
      return { state: "not_sent", reason: stringOr(result.reason, "cancelled") };
    default:
      return uncertainDirectResult("invalid_result");
  }
}

const INVALID_PREPARE_RESULT = {
  status: "failed",
  errorCode: "invalid_result",
  message: "Couldn't prepare that action.",
};

const RECEIPT_UNAVAILABLE_PREPARE_RESULT = {
  status: "failed",
  errorCode: "receipt_unavailable",
  message: "Couldn't record this action, so nothing was prepared.",
};

// Connecting writes a login for the account, so it needs one.
function actionRefusal(policyState, accountId) {
  return policyRefusal(policyState) ?? (accountId ? null : "signed_out");
}

function isString(value) {
  return typeof value === "string";
}

function normalizePreviewNote(note) {
  if (!note || typeof note.key !== "string") return null;
  return note.values && typeof note.values === "object"
    ? { key: note.key, values: stringFields(note.values) }
    : { key: note.key };
}

// A card layout's fields (an email's to, cc, subject and body). Every field
// the card can edit must be one the action declares editable, holding a value
// of the declared type: an undeclared one (a typo in the declaration, say)
// would let the user change it only for Send to drop it, and a mistyped one
// would fail only at Send. Null when there are none; false when malformed.
function normalizePreviewFields(fields, editable) {
  if (fields === undefined || fields === null) return null;
  if (!fields || typeof fields !== "object" || Array.isArray(fields)) return false;
  const entries = Object.entries(fields);
  const valid = entries.every(
    ([name, value]) => Object.hasOwn(editable, name) && EDIT_TYPES[editable[name]](value)
  );
  if (!valid) return false;
  return entries.length > 0 ? Object.fromEntries(entries) : null;
}

// The fields an issue or comment card lays out. Fields without them would
// drop the card to its plain layout, whose edits Send never commits.
const LAYOUT_FIELDS = { issue: ["title", "body"], comment: ["body"] };

function hasLayoutFields(verbKey, fields) {
  const required = Object.hasOwn(LAYOUT_FIELDS, verbKey) ? LAYOUT_FIELDS[verbKey] : [];
  return required.every((name) => isString(fields[name]));
}

// The card renders exactly this, so a preview missing a field it needs is
// malformed rather than shown half empty.
function normalizePreview(preview, editable) {
  if (!preview || typeof preview !== "object") return null;
  const { verbKey, destinationLabel, accountLabel, body } = preview;
  if (![verbKey, destinationLabel, accountLabel, body].every(isString)) return null;
  const fields = normalizePreviewFields(preview.fields, editable);
  if (fields === false || (fields && !hasLayoutFields(verbKey, fields))) return null;
  return {
    verbKey,
    destinationLabel,
    accountLabel,
    body,
    ...stringFields({ workspaceLabel: preview.workspaceLabel, title: preview.title }),
    ...(Array.isArray(preview.notes)
      ? { notes: preview.notes.map(normalizePreviewNote).filter(Boolean) }
      : {}),
    ...(fields ? { fields } : {}),
  };
}

// A connector's prepare result decides whether a card appears and what it
// shows, so anything malformed fails closed, with no card and no receipt. The
// payload stays in main; only the fields each status defines reach the
// renderer, so a connector can't leak anything else (such as message text)
// through an odd result.
function normalizePrepareResult(result, editable) {
  switch (result?.status) {
    case "ready": {
      const preview = normalizePreview(result.preview, editable);
      return preview && result.payload !== undefined
        ? { status: "ready", payload: result.payload, preview }
        : INVALID_PREPARE_RESULT;
    }
    case "needs_clarification":
      return isString(result.message)
        ? {
            status: "needs_clarification",
            message: result.message,
            candidates: Array.isArray(result.candidates) ? result.candidates.filter(isString) : [],
          }
        : INVALID_PREPARE_RESULT;
    case "failed":
      return {
        status: "failed",
        errorCode: stringOr(result.errorCode, "prepare_failed"),
        message: stringOr(result.message, INVALID_PREPARE_RESULT.message),
      };
    default:
      return INVALID_PREPARE_RESULT;
  }
}

function normalizeStatus(status) {
  const value = status && typeof status === "object" ? status : {};
  return {
    connected: value.connected === true,
    // Only a connector that says so is unconfigured (Gmail without a Google
    // OAuth client); its Settings row is hidden.
    configured: value.configured !== false,
    accountLabel: isString(value.accountLabel) ? value.accountLabel : null,
    workspaceLabel: isString(value.workspaceLabel) ? value.workspaceLabel : null,
    needsReconnect: value.needsReconnect === true,
    // GitHub: where the user chooses the repositories its App is installed
    // on. Settings opens it in the browser, so only a github.com page passes.
    ...(isString(value.manageUrl) && value.manageUrl.startsWith("https://github.com/")
      ? { manageUrl: value.manageUrl }
      : {}),
    // GitHub: its repository count hasn't been read yet for this login.
    ...(value.workspaceLabelPending === true ? { workspaceLabelPending: true } : {}),
  };
}

// A binding that can't be compared counts as no connection.
function normalizeBinding(binding) {
  if (!binding || typeof binding !== "object") return null;
  if (!isString(binding.accountId) || !Number.isInteger(binding.generation)) return null;
  return binding;
}

// What each declared editable type accepts. A "line" goes into a header
// (an email's subject), so CR or LF would let it add headers such as Bcc.
const EDIT_TYPES = {
  addresses: (value) => Array.isArray(value) && value.every(isString),
  line: (value) => isString(value) && !/[\r\n]/.test(value),
  text: isString,
};

// Every approval action says which of its card's fields the user may edit.
// A missing declaration, or one naming a type that doesn't exist, would drop
// edits; it is a build fault, caught when the manager is created.
function assertEditableTypes(connectors) {
  for (const connector of connectors) {
    for (const [action, spec] of Object.entries(connector.actions ?? {})) {
      if (spec?.kind !== "approval") continue;
      if (!spec.editable || typeof spec.editable !== "object") {
        throw new Error(`${connector.id}.${action}: an approval action must declare editable`);
      }
      for (const [field, type] of Object.entries(spec.editable)) {
        if (!Object.hasOwn(EDIT_TYPES, type)) {
          throw new Error(`${connector.id}.${action}.${field}: unknown editable type "${type}"`);
        }
      }
    }
  }
}

// The card's edits reach the connector only as the action declares them:
// exactly the declared fields. A declared field of the wrong type returns
// null, so Send refuses instead of sending the prepared value in its place.
function sanitizeEdits(edits, editable) {
  const source = edits && typeof edits === "object" ? edits : {};
  const clean = {};
  for (const [field, type] of Object.entries(editable)) {
    if (!Object.hasOwn(source, field) || source[field] === undefined) continue;
    if (!EDIT_TYPES[type](source[field])) return null;
    clean[field] = source[field];
  }
  return clean;
}

const REVOKE_TIMEOUT_MS = 5000;
const CONNECT_ERROR_CODES = new Set([
  "not_configured",
  "oauth_denied",
  "oauth_timeout",
  "oauth_state_mismatch",
  "ports_busy",
  "token_exchange_failed",
  // Gmail: the user unticked "send email" at Google's consent screen, or
  // Google says the account's address isn't verified.
  "permission_not_granted",
  "email_not_verified",
  // Gmail: a Workspace admin blocked the app, or it's restricted to another org.
  "domain_policy",
  // GitHub: the device code ran out (15 minutes), or the App has Device Flow off.
  "code_expired",
  "device_flow_disabled",
  // GitHub: no device code could be asked for, offline or throttled, so the
  // user never saw one to enter.
  "network",
  "rate_limited",
]);

// A revoke is best effort: nothing may hang on an unreachable provider. The
// promise's value, or null when the deadline came first.
async function withinDeadline(promise, ms) {
  let timer;
  try {
    return await Promise.race([
      promise,
      new Promise((resolve) => (timer = setTimeout(() => resolve(null), ms))),
    ]);
  } finally {
    clearTimeout(timer);
  }
}

// Every action call carries `auth`: the org policy verdict and the signed-in
// account it was resolved for. The account owns the receipt, so an action
// with none (signed out, or mid sign-in or account switch) is refused before
// anything is written or done. Connecting and disconnecting a login use
// getAccountId(), the account whose login slot they write.
function createConnectorManager({
  connectors,
  pendingActions,
  actionLog,
  logger,
  getAccountId,
  credentials = null,
  onStatusChanged = () => {},
  randomId = () => crypto.randomBytes(16).toString("hex"),
}) {
  assertEditableTypes(connectors);
  const byId = new Map(connectors.map((connector) => [connector.id, connector]));

  // Writes before a side effect gate it: without a durable row, a crash
  // mid-send could hide a message that was actually sent.
  function writeRequired(step, write) {
    try {
      return write() !== false;
    } catch (error) {
      logger.error(
        "connector receipt write failed",
        { step, ...describeError(error) },
        "connectors"
      );
      return false;
    }
  }

  // Writes after the outcome is known are best effort: a failure leaves the
  // row in its last durable state, which reconciliation treats conservatively.
  function record(write) {
    try {
      write();
    } catch (error) {
      logger.warn("connector receipt update failed", { ...describeError(error) }, "connectors");
    }
  }

  record(() => {
    const reconciled = actionLog.reconcileInterrupted();
    if (reconciled.unknown || reconciled.cancelled || reconciled.orphaned) {
      logger.info("reconciled interrupted connector actions", reconciled, "connectors");
    }
  });

  function resolveAction(connectorId, action, kind) {
    const connector = byId.get(connectorId);
    if (!connector) return { error: "unknown_connector" };
    if (connector.actions[action]?.kind !== kind) return { error: "unknown_action" };
    return { connector };
  }

  // Cards the renderer never answered are expired here too, so their payload
  // (message text) doesn't linger and Recent never shows them as waiting.
  // Their receipts say so rather than a later "app_quit".
  function sweepExpired() {
    for (const actionId of pendingActions.sweepExpired()) {
      record(() =>
        actionLog.update(actionId, { state: "expired", errorCode: "expired" }, "pending")
      );
    }
  }

  async function statusOf(connector) {
    try {
      return { id: connector.id, ...normalizeStatus(await connector.getStatus()) };
    } catch (error) {
      logger.warn(
        "connector status failed",
        { connectorId: connector.id, ...describeError(error) },
        "connectors"
      );
      return { id: connector.id, ...normalizeStatus(null) };
    }
  }

  async function currentBinding(connector) {
    try {
      return normalizeBinding(await connector.getBinding());
    } catch (error) {
      logger.warn(
        "connector binding failed",
        { connectorId: connector.id, ...describeError(error) },
        "connectors"
      );
      return null;
    }
  }

  async function status() {
    sweepExpired();
    return Promise.all([...byId.values()].map(statusOf));
  }

  // One connector's status, or null for an unknown id.
  async function connectorStatus(connectorId) {
    const connector = byId.get(connectorId);
    return connector ? statusOf(connector) : null;
  }

  // The sign-in in flight per account and connector. A new Connect replaces
  // it: a user who closed the browser tab would otherwise wait out the flow.
  const connecting = new Map();
  let statusSequence = 0;

  async function notifyStatusChanged() {
    const sequence = ++statusSequence;
    try {
      const statuses = await status();
      // A later change is already being announced; this snapshot is older.
      if (sequence === statusSequence) onStatusChanged(statuses);
    } catch (error) {
      logger.warn("connector status broadcast failed", describeError(error), "connectors");
    }
  }

  // The connector's answer (Gmail: { kept: true } for a grant it left in
  // place), or null when the revoke failed or ran out of time.
  async function revokeQuietly(connector, credential, options) {
    try {
      return await withinDeadline(connector.revoke(credential, options), REVOKE_TIMEOUT_MS);
    } catch (error) {
      logger.warn(
        "connector revoke failed",
        { connectorId: connector.id, ...describeError(error) },
        "connectors"
      );
      return null;
    }
  }

  async function connect(connectorId, policyState) {
    const accountId = getAccountId();
    const refusal = actionRefusal(policyState, accountId);
    if (refusal) return { status: "unavailable", reason: refusal };
    const connector = byId.get(connectorId);
    if (!connector?.authorize || !credentials) {
      return { status: "unavailable", reason: "unknown_connector" };
    }
    const flowKey = `${accountId}:${connectorId}`;
    connecting.get(flowKey)?.abort();
    const controller = new AbortController();
    connecting.set(flowKey, controller);
    // The OAuth round trip can take minutes. What it returns belongs to the
    // account and slot generation that started it, or to no one.
    const startGeneration = credentials.generation(accountId, connectorId);
    try {
      let credential;
      let replaced = null;
      try {
        credential = await connector.authorize({ signal: controller.signal });
      } catch (error) {
        // Replaced by a newer Connect before the provider answered: nothing
        // was issued, so nothing is saved or revoked.
        if (controller.signal.aborted) return { status: "failed", errorCode: "oauth_cancelled" };
        const summary = describeError(error);
        logger.warn("connector connect failed", { connectorId, ...summary }, "connectors");
        return {
          status: "failed",
          errorCode: CONNECT_ERROR_CODES.has(summary.errorCode)
            ? summary.errorCode
            : "connect_failed",
        };
      }
      // Replaced after the provider answered: the newer attempt is the one
      // the user wants, and nobody will use this login.
      if (controller.signal.aborted) {
        await revokeQuietly(connector, credential);
        return { status: "failed", errorCode: "oauth_cancelled" };
      }
      try {
        if (getAccountId() !== accountId) {
          throw Object.assign(new Error("account changed"), { code: "connection_changed" });
        }
        // A new login: approvals prepared under the old one must not send.
        replaced = credentials.read(accountId, connectorId)?.credential ?? null;
        credentials.replace(accountId, connectorId, credential, startGeneration);
        // Saved: from here a Cancel has nothing left to stop.
        if (connecting.get(flowKey) === controller) connecting.delete(flowKey);
      } catch (error) {
        // Nobody will use this login, so it is revoked rather than left live.
        await revokeQuietly(connector, credential);
        if (error.code === "connection_changed" || error.code === "signed_out") {
          return { status: "failed", errorCode: "connection_changed" };
        }
        // A real write failure (disk, permission, encryption), not a race.
        logger.warn(
          "connector login save failed",
          { connectorId, ...describeError(error) },
          "connectors"
        );
        return { status: "failed", errorCode: "credential_save_failed" };
      }
      invalidate(connectorId);
      await notifyStatusChanged();
      // A login for another account is left with nothing using it, so it is
      // revoked rather than left live. The same account's is kept: Google's
      // revoke would end the new login's grant too. Not awaited: the new
      // login is already saved, and Settings shouldn't wait on the old one.
      if (replaced && connector.loginKey?.(replaced) !== connector.loginKey?.(credential)) {
        void revokeQuietly(connector, replaced);
      }
      const current = await statusOf(connector);
      return {
        status: "connected",
        accountLabel: current.accountLabel,
        workspaceLabel: current.workspaceLabel,
      };
    } finally {
      if (connecting.get(flowKey) === controller) connecting.delete(flowKey);
    }
  }

  // Aborts the connects in progress that `matches(accountId, connectorId)`;
  // each then ends as oauth_cancelled, and a login that arrives anyway is
  // never saved and is revoked where the connector does so (not GitHub, see
  // githubConnector's revoke), as when a newer Connect replaces it. True when
  // any was running.
  function abortConnects(matches) {
    let aborted = false;
    for (const [flowKey, controller] of connecting) {
      const split = flowKey.lastIndexOf(":");
      if (matches(flowKey.slice(0, split), flowKey.slice(split + 1))) {
        controller.abort();
        aborted = true;
      }
    }
    return aborted;
  }

  // The row's Cancel, or the user leaving Settings while GitHub's device code
  // is showing. A connect started before an account switch or sign-out is
  // stopped too: it can't be saved, and nothing else would end its polling.
  // Stopping is always allowed.
  function cancelConnect(connectorId) {
    return abortConnects((_accountId, id) => id === connectorId)
      ? { status: "cancelled" }
      : { status: "idle" };
  }

  // The signed-in account changed: a connect started under another one can
  // only be refused when it finishes, so it stops now.
  function accountChanged() {
    const accountId = getAccountId();
    abortConnects((flowAccountId) => flowAccountId !== String(accountId));
  }

  // Removing access is always allowed: no policy or plan check.
  // `erasingDevice` (Delete account with device erase) revokes a grant the
  // connector would otherwise keep because another login shares it.
  // `removingAll` (account deletion, Reset app data) tells a connector that
  // every login is going, not just this one.
  async function disconnect(connectorId, { erasingDevice = false, removingAll = false } = {}) {
    const connector = byId.get(connectorId);
    if (!connector?.revoke || !credentials) {
      return { status: "unavailable", reason: "unknown_connector" };
    }
    const accountId = getAccountId();
    if (!accountId) return { status: "unavailable", reason: "signed_out" };
    const entry = credentials.read(accountId, connectorId);
    let grantKept = false;
    if (entry) {
      const revoked = await revokeQuietly(connector, entry.credential, {
        erasingDevice,
        removingAll,
      });
      grantKept = revoked?.kept === true;
      try {
        credentials.clear(accountId, connectorId, entry.generation);
      } catch (error) {
        if (error.code === "connection_changed" || error.code === "signed_out") {
          // A reconnect landed while revoking: that newer login stays.
          return { status: "failed", errorCode: "connection_changed" };
        }
        // A real write failure (disk, permission): the revoke above already
        // happened, so the login is dead even though the local slot wasn't
        // cleared. Never claim "disconnected" for a slot that's still there.
        logger.warn(
          "connector login clear failed",
          { connectorId, ...describeError(error) },
          "connectors"
        );
        return { status: "failed", errorCode: "disconnect_failed" };
      }
    }
    invalidate(connectorId);
    await notifyStatusChanged();
    // Google still lists the app for that account until the other login
    // (the calendar) is disconnected too; Settings says so.
    return grantKept ? { status: "disconnected", grantKept: true } : { status: "disconnected" };
  }

  // In parallel, so an offline account deletion waits one revoke deadline.
  async function disconnectAll(options) {
    await Promise.all(
      [...byId.values()]
        .filter((connector) => connector.revoke)
        .map((connector) => disconnect(connector.id, { ...options, removingAll: true }))
    );
  }

  // Reset app data: every login stored on this device is revoked at its
  // provider, whichever account it belongs to and whether anyone is still
  // signed in (the renderer signs out before the reset runs). The files are
  // deleted right after, so nothing is cleared here. In parallel, so an
  // offline reset waits one revoke deadline, not one per login.
  async function revokeAllStored() {
    if (!credentials) return;
    const revokes = [];
    for (const connector of byId.values()) {
      if (!connector.revoke) continue;
      for (const credential of credentials.readAllAccounts(connector.id)) {
        revokes.push(
          revokeQuietly(connector, credential, { erasingDevice: true, removingAll: true })
        );
      }
      invalidate(connector.id);
    }
    await Promise.all(revokes);
  }

  async function prepare(connectorId, action, args, { policyState, accountId }) {
    sweepExpired();
    const refusal = policyRefusal(policyState);
    if (refusal) return { status: "unavailable", reason: refusal };
    const resolved = resolveAction(connectorId, action, "approval");
    if (resolved.error) return { status: "unavailable", reason: resolved.error };
    if (!accountId) return RECEIPT_UNAVAILABLE_PREPARE_RESULT;
    const { connector } = resolved;

    const binding = await currentBinding(connector);
    if (!binding) return { status: "unavailable", reason: "not_connected" };

    let prepared;
    try {
      prepared = normalizePrepareResult(
        await connector.prepare(action, args || {}, { binding }),
        connector.actions?.[action]?.editable
      );
    } catch (error) {
      logger.warn(
        "connector prepare threw",
        { connectorId, action, ...describeError(error) },
        "connectors"
      );
      return { ...INVALID_PREPARE_RESULT, errorCode: "prepare_failed" };
    }
    if (prepared.errorCode === "reconnect_needed") void notifyStatusChanged();
    if (prepared.status !== "ready") return prepared;

    const actionId = pendingActions.create({
      connectorId,
      action,
      binding,
      accountId,
      payload: prepared.payload,
      preview: prepared.preview,
    });
    const recorded = writeRequired("pending", () => {
      actionLog.insert({
        id: actionId,
        accountId,
        connector: connectorId,
        action,
        kind: "approval",
        destinationLabel: prepared.preview.destinationLabel,
        state: "pending",
      });
    });
    if (!recorded) {
      pendingActions.cancel(actionId);
      return RECEIPT_UNAVAILABLE_PREPARE_RESULT;
    }
    return { status: "ready", actionId, preview: prepared.preview };
  }

  // Withdrawn rather than left pending: a refused card is settled in the
  // renderer, so nothing may commit it later.
  function withdrawPending(actionId, reason) {
    pendingActions.cancel(actionId);
    record(() => actionLog.update(actionId, { state: "cancelled", errorCode: reason }, "pending"));
    return { state: "not_sent", reason };
  }

  async function commit(actionId, edits, { policyState, accountId }) {
    sweepExpired();
    const entry = pendingActions.get(actionId);
    if (!entry) return { state: "not_sent", reason: "not_found" };
    // A second click while the first is sending must neither send nor
    // overwrite the in-flight row.
    if (entry.state !== "pending") return { state: "not_sent", reason: "not_pending" };

    const connector = byId.get(entry.connectorId);
    const cleanEdits = sanitizeEdits(edits, connector.actions[entry.action]?.editable);
    if (!cleanEdits) return withdrawPending(actionId, "invalid_edit");

    const refusal = policyRefusal(policyState);
    // A policy lookup that timed out or went offline says nothing about this
    // action: leave it pending so the user can press Send again.
    if (refusal === "policy_unavailable") {
      return { state: "not_sent", reason: refusal, retryable: true };
    }
    if (refusal) return withdrawPending(actionId, refusal);
    // Another account (or none) must not send what this one prepared.
    if (entry.accountId !== accountId) return withdrawPending(actionId, "account_changed");

    const begun = pendingActions.beginCommit(actionId, await currentBinding(connector));
    if (!begun.ok) {
      if (begun.reason === "expired" || begun.reason === "connection_changed") {
        const state = begun.reason === "expired" ? "expired" : "cancelled";
        record(() => actionLog.update(actionId, { state, errorCode: begun.reason }, "pending"));
      }
      return { state: "not_sent", reason: begun.reason };
    }

    const recorded = writeRequired(
      "committing",
      () => actionLog.update(actionId, { state: "committing" }, "pending") === 1
    );
    if (!recorded) {
      pendingActions.finish(actionId);
      record(() =>
        actionLog.update(
          actionId,
          { state: "cancelled", errorCode: "receipt_unavailable" },
          "pending"
        )
      );
      return { state: "not_sent", reason: "receipt_unavailable" };
    }

    let result;
    try {
      result = normalizeCommitResult(
        await connector.commit(entry.action, entry.payload, cleanEdits, { binding: entry.binding })
      );
    } catch (error) {
      logger.warn(
        "connector commit threw",
        { connectorId: entry.connectorId, action: entry.action, ...describeError(error) },
        "connectors"
      );
      result = { state: "unknown" };
    }
    if (result.errorCode === "reconnect_needed") void notifyStatusChanged();

    pendingActions.finish(actionId);
    record(() =>
      actionLog.update(actionId, {
        state: result.state,
        resultUrl: result.url || result.checkUrl || null,
        errorCode: result.errorCode || null,
        // Only when the connector's commit named one (Gmail, edited
        // recipients): the row otherwise keeps the label prepare wrote.
        ...(typeof result.destinationLabel === "string"
          ? { destinationLabel: result.destinationLabel }
          : {}),
      })
    );
    logger.info(
      "connector action finished",
      {
        connectorId: entry.connectorId,
        action: entry.action,
        state: result.state,
        errorCode: result.errorCode || null,
      },
      "connectors"
    );
    return result;
  }

  function cancel(actionId, reason) {
    sweepExpired();
    const safeReason = CANCEL_REASONS.has(reason) ? reason : "cancelled_by_user";
    const cancelled = pendingActions.cancel(actionId);
    if (cancelled) {
      const state = safeReason === "expired" ? "expired" : "cancelled";
      record(() => actionLog.update(actionId, { state, errorCode: safeReason }));
    }
    return { cancelled };
  }

  // runtime may carry a `signal`: a cancel that lands before the side effect
  // must stop it (the connector checks it right before acting).
  async function runDirect(connectorId, action, args, { policyState, accountId }, runtime) {
    const refusal = policyRefusal(policyState);
    if (refusal) return { state: "unavailable", reason: refusal };
    const resolved = resolveAction(connectorId, action, "direct");
    if (resolved.error) return { state: "unavailable", reason: resolved.error };
    if (!accountId) return { state: "unavailable", reason: "receipt_unavailable" };

    const id = randomId();
    const recorded = writeRequired("direct", () => {
      actionLog.insert({
        id,
        accountId,
        connector: connectorId,
        action,
        kind: "direct",
        state: "committing",
      });
    });
    if (!recorded) return { state: "unavailable", reason: "receipt_unavailable" };

    let result;
    try {
      result = normalizeDirectResult(
        await resolved.connector.runDirect(action, args || {}, runtime || {})
      );
    } catch (error) {
      logger.warn(
        "connector direct action threw",
        { connectorId, action, ...describeError(error) },
        "connectors"
      );
      result = uncertainDirectResult("direct_failed");
    }
    const outcome =
      result.state === "not_sent"
        ? { state: "cancelled", errorCode: result.reason }
        : { state: result.state, errorCode: result.errorCode || null };
    record(() =>
      actionLog.update(id, { ...outcome, destinationLabel: result.destinationLabel || null })
    );
    return result;
  }

  // A read for the model (an issue search). It changes nothing anywhere, so
  // there is no pending action and no receipt; it still needs the policy, an
  // account and the bound login, since what it returns leaves the device
  // with the model's request.
  async function query(connectorId, action, args, { policyState, accountId }) {
    const refusal = policyRefusal(policyState);
    if (refusal) return { status: "unavailable", reason: refusal };
    const resolved = resolveAction(connectorId, action, "query");
    if (resolved.error) return { status: "unavailable", reason: resolved.error };
    if (!accountId) return { status: "unavailable", reason: "signed_out" };
    const { connector } = resolved;

    const binding = await currentBinding(connector);
    if (!binding) return { status: "unavailable", reason: "not_connected" };
    // A login filed under another account must not answer for this one.
    if (isString(binding.ownerAccountId) && binding.ownerAccountId !== accountId) {
      return { status: "unavailable", reason: "account_changed" };
    }

    let result;
    try {
      result = normalizeQueryResult(await connector.query(action, args || {}, { binding }));
    } catch (error) {
      logger.warn(
        "connector query threw",
        { connectorId, action, ...describeError(error) },
        "connectors"
      );
      result = queryFailed();
    }
    if (result.errorCode === "reconnect_needed") void notifyStatusChanged();
    logger.info(
      "connector query finished",
      {
        connectorId,
        action,
        status: result.status,
        itemCount: result.status === "ok" ? result.items.length : 0,
        truncated: result.status === "ok" && result.truncated,
        errorCode: result.errorCode || null,
      },
      "connectors"
    );
    return result;
  }

  function invalidate(connectorId) {
    const removed = pendingActions.invalidateConnector(connectorId);
    for (const actionId of removed) {
      record(() =>
        actionLog.update(actionId, { state: "cancelled", errorCode: "connection_changed" })
      );
    }
    return removed;
  }

  // Receipts name the people a user wrote to: only the account that took the
  // action sees them.
  function recentActions(connectorId, limit, accountId) {
    sweepExpired();
    if (!accountId) return [];
    const safeLimit = Number.isInteger(limit) && limit > 0 ? Math.min(limit, 50) : 10;
    return actionLog.listRecent(connectorId, safeLimit, accountId);
  }

  return {
    status,
    connectorStatus,
    prepare,
    commit,
    cancel,
    runDirect,
    query,
    invalidate,
    recentActions,
    sweepExpired,
    connect,
    cancelConnect,
    accountChanged,
    disconnect,
    disconnectAll,
    revokeAllStored,
    notifyStatusChanged,
  };
}

module.exports = { createConnectorManager };