Function onTurn

packages/bot/src/create-bot.ts:375–450

(turn: IncomingTurn)

  function makeSink(adapter: PlatformAdapter): IngressSink {
    return {
      async onTurn(turn: IncomingTurn) {
        const lockKey = `turn:${turn.conversationKey}`;
        const acquired = await backend.lock.acquire(lockKey, {
          ttlMs: cfg.lockTtl ?? 60_000,
        });

        if (!acquired) {
          const decision =
            typeof cfg.onLockConflict === "function"
              ? await cfg.onLockConflict(
                  turn.conversationKey,
                  msgFromTurn(turn),
                )
              : (cfg.onLockConflict ?? "drop");
          if (decision === "drop") return; // discard overlapping turn
          // "force": proceed WITHOUT a lock token. Does NOT cancel the
          // in-flight handler — cooperative cancellation is a future extension.
        }

        try {
          // Dedup AFTER acquiring the lock: a turn dropped on lock-conflict must NOT burn its
          // eventId, so Slack's retry can still be processed once the lock frees. (A handler
          // that throws still leaves its event marked seen — dedup drops duplicate DELIVERIES,
          // it is not retry-of-failed-turns.)
          if (turn.eventId) {
            const dupKey = `evt:${adapter.platform}:${turn.eventId}`;
            try {
              if (await backend.dedup.seen(dupKey, cfg.dedupTtl ?? 300_000))
                return;
            } catch (err) {
              console.warn(
                `[bot] dedup check failed for ${adapter.platform}; processing without dedup`,
                err,
              );
            }
          }

          // Resolve cross-platform identity key (if configured) and stamp it on
          // the message so handlers and transcript storage can use it. Done
          // BEFORE makeThread so the thread carries the userKey + message for
          // the transcript auto-bridge (runAgent({ transcript: true })).
          let userKey: string | undefined;
          if (cfg.identity) {
            try {
              const resolved = await cfg.identity({
                adapter: adapter.platform,
                author: turn.user ?? { id: "" },
                message: msgFromTurn(turn),
              });
              userKey = resolved ?? undefined;
            } catch (err) {
              console.warn(
                `[bot] identity resolution failed for ${adapter.platform}; continuing without userKey`,
                err,
              );
            }
          }
          const message: IncomingMessage = { ...msgFromTurn(turn), userKey };