@volter/supercode-orchestrator 0.4.4

package/adapters/chat-sdk.mjs

@@ -0,0 +1,475 @@
+// The Chat SDK sidecar (ORC-9): one adapter instance per (platform, account),
+// mounting `vercel/chat` behind the same three-method trait every adapter has
+// (`connect(emit)` / `send(target, content)` / `close()`).
+//
+// PIN. `chat@4.39.0` (npm package name is `chat`, repo `github.com/vercel/chat`;
+// the contracts quoted below were read at repo HEAD `043386b` by ORC-1 F4 and
+// re-verified against the installed 4.39.0 `.d.ts`). The platform packages
+// (`@chat-adapter/slack`, `@chat-adapter/telegram`, …) are NOT dependencies of
+// this package: each is imported lazily at `connect` from the profile's own
+// `platforms:` block, so a home that names none pulls none.
+//
+// WHY A SIDECAR AND NOT A TRANSPORT REWRITE (docs/ORCHESTRATOR-IR.md §7,
+// `docs/interop/research/orc1-fact-finders-2026-09-04.md` §F4). The SDK's
+// handler contract is `(thread, message)`: the SURFACE identity lives on the
+// `Thread` and the CONTENT on the `Message`. Everything the IR's `inbound`
+// event needs is therefore read off the `Thread` — never off the `Message` —
+// and nothing reaches the reducer by any other door (§3: "An adapter that
+// cannot express something as an `inbound` event does not get a private path
+// into the loop").
+//
+// THE MAPPING, field by field (left: IR §3 `inbound` / §2.1 `Attachment`;
+// right: the Chat SDK member quoted in F4):
+//
+//   key.platform     thread.adapter.name          (types.ts:438)
+//   key.chat_id      thread.channelId             (types.ts:1246)
+//   key.thread_id    thread.id                    (types.ts:1065, Postable.id)
+//   key.kind         thread.isDM -> "dm"          (types.ts:1067)
+//                    else thread.channelVisibility (types.ts:27-31) — see chatType()
+//   sender           message.author.userId        (types.ts:1648)
+//   sender_name      message.author.userName      (types.ts:1649)
+//   is_me            message.author.isMe          (types.ts:1644)
+//   is_bot           message.author.isBot         (types.ts:1643; "unknown" -> null)
+//   mention          message.isMention            (message.ts:40)
+//   message_id       message.id                   (message.ts:38)
+//   at               message.metadata.dateSent    (types.ts:1671)
+//   text             message.text                 (message.ts:51, formatting stripped)
+//   attachments[].*  message.attachments[].*      (types.ts:1833-1862)
+//   attachments[].ref  attachment.fetchMetadata   (the re-fetch instruction, verbatim)
+//
+// OUTBOUND. `send` is `thread.post(text)` (types.ts:1083-1086), `thread.reply`
+// when the obligation names a `reply_to` (types.ts:1646), and
+// `adapter.postChannelMessage(channelId, …)` (types.ts:941) for a target with
+// no thread. It returns `{ message_id }` — the platform's handle for what was
+// posted — which `loop.mjs`'s `deliver` records as `Obligation.posted`
+// (§2.6, F4 finding 3).
+//
+// KNOWN GAP, not papered over: `loop.mjs`'s `deliver` projects the obligation
+// down to `{ text, at }` before calling `send`, so `OutboundContent.reply_to`
+// and `attachments` are never populated by the loop today even though §2.1
+// declares them and this adapter honours both when a caller supplies them.
+// Closing it is a `deliver` change, out of ORC-9's one-line budget.
+//
+// CONCURRENCY. The SDK has its own per-thread queue with five strategies
+// (`ConcurrencyStrategy`, types.ts:905-910) and the IR has its own (§4.1 step
+// 5 / §2.8 `queues`). Two queues on one surface is F4 finding 11, so the
+// sidecar defaults the SDK's to `"concurrent"` — no SDK-side locking — and
+// leaves the IR's queue as the single one. `extra.concurrency` overrides it.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseDotenv } from '../orchestration.mjs';
+import { TOKEN_SCOPES, acquireTokenLock, releaseTokenLock } from '../hermes-locks.mjs';
+import { chunks } from './chunks.mjs';
+
+/** The Chat SDK version this adapter was written against and pinned to. */
+export const CHAT_SDK_VERSION = '4.39.0';
+
+/**
+ * A Hermes-shaped `platforms:` block (no `credentials:` refs) for the three chat
+ * platforms Hermes serves: the factory options each takes, read from the
+ * profile's own `.env` under Hermes's variable names (`gateway/config.py`),
+ * and the resident ingress Hermes itself uses — Slack Socket Mode (Hermes
+ * requires `SLACK_APP_TOKEN`), Telegram long polling, the Discord gateway.
+ * Option names are the platform packages' own (their READMEs, read
+ * 2026-09-23). Unverified end to end on this box: the platform packages are
+ * not installed here and no platform tokens exist.
+ */
+export const HERMES_PLATFORMS = Object.freeze({
+  slack: { env: { botToken: 'SLACK_BOT_TOKEN', appToken: 'SLACK_APP_TOKEN', signingSecret: 'SLACK_SIGNING_SECRET' }, options: { mode: 'socket' } },
+  telegram: { env: { botToken: 'TELEGRAM_BOT_TOKEN', userName: 'TELEGRAM_BOT_USERNAME' }, options: { mode: 'polling' } },
+  discord: { env: { botToken: 'DISCORD_BOT_TOKEN', publicKey: 'DISCORD_PUBLIC_KEY', applicationId: 'DISCORD_APPLICATION_ID' }, options: {}, gateway: true },
+});
+
+/** The most characters a platform takes in one message (Discord's API refuses more; Telegram's Bot API caps 4096). */
+const MESSAGE_LIMIT = Object.freeze({ discord: 2000, telegram: 4096 });
+
+/** How long one Discord gateway listen runs before the adapter starts the next. */
+export const GATEWAY_SLICE_MS = 10 * 60_000;
+
+/** The npm package names this adapter imports lazily, never at module load. */
+export const CHAT_SDK_PACKAGE = 'chat';
+export const CHAT_SDK_STATE_PACKAGE = '@chat-adapter/state-memory';
+
+/**
+ * `kind` (§2.3's four-value enum) from the SDK's three-way surface split.
+ *
+ * F4 finding 4 records that `isDM` / `channelVisibility` / the
+ * Thread-vs-Channel structure "does not project onto the IR enum without a
+ * rule the IR would have to invent", and names `"external"` (Slack Connect) as
+ * having no IR value. This IS that rule, decided here and nowhere else:
+ *
+ *   isDM                      -> "dm"
+ *   channelVisibility private -> "group"    (a closed room with named members)
+ *   workspace|external|unknown-> "channel"  (an open room; external is a
+ *                                            channel shared with another org,
+ *                                            not a different kind of surface)
+ *
+ * `thread` is deliberately not produced: a thread is carried by the key's own
+ * `thread_id`, which is always set (`Postable.id`), so using it as a kind
+ * as well would double-encode one fact.
+ */
+export function chatType(thread) {
+  if (thread?.isDM) return 'dm';
+  return thread?.channelVisibility === 'private' ? 'group' : 'channel';
+}
+
+/** One SDK `Attachment` (types.ts:1833-1862) -> the IR's (§2.1). */
+export function toAttachment(a) {
+  const out = { kind: a.type };
+  if (a.name) out.name = a.name;
+  if (a.mimeType) out.mime = a.mimeType;
+  if (typeof a.size === 'number') out.size = a.size;
+  if (a.url) out.url = a.url;
+  // §2.1: "`ref` = adapter data to re-fetch (Chat SDK fetchMetadata …)"
+  if (a.fetchMetadata) out.ref = { ...a.fetchMetadata };
+  return out;
+}
+
+/**
+ * `(thread, message)` -> the `inbound` payload the loop's `emit` takes.
+ * Pure, and exported so a test can assert the mapping without a Chat instance.
+ */
+export function toInbound({ profile, thread, message }) {
+  const isBot = message.author?.isBot;
+  return {
+    profile,
+    key: {
+      platform: thread.adapter.name,
+      kind: chatType(thread),
+      chat_id: String(thread.channelId ?? thread.id),
+      thread_id: String(thread.id),
+    },
+    sender: String(message.author?.userId ?? ''),
+    sender_name: message.author?.userName ?? null,
+    text: message.text ?? '',
+    attachments: (message.attachments ?? []).map(toAttachment),
+    at: new Date(message.metadata?.dateSent ?? Date.now()).toISOString(),
+    message_id: String(message.id),
+    is_me: Boolean(message.author?.isMe),
+    // `isBot: boolean | "unknown"` — "unknown" is not false, so it is null here
+    is_bot: isBot === 'unknown' || isBot === undefined ? null : Boolean(isBot),
+    mention: Boolean(message.isMention),
+  };
+}
+
+export class ChatSdkAdapter {
+  /**
+   * @param {object} o
+   * @param {string} o.platform   the `platforms.<name>` block's name; also the SDK adapter slug unless `extra.slug` says otherwise
+   * @param {string} o.profile    the profile that owns this (platform, account)
+   * @param {object} [o.channel]  the loaded `ChannelConfig` (§2.4): credentials by ref, `extra` verbatim
+   * @param {Map<string,string>} [o.vault]  resolves `${NAME}` references at connect, never before
+   * @param {object} [o.sdkAdapter]  an already-built SDK `Adapter` (tests inject one; production builds it from `channel`)
+   * @param {object} [o.chat]        an already-built `Chat` (tests may inject one instead of an adapter)
+   * @param {object} [o.state]       an SDK `StateAdapter`; defaults to `@chat-adapter/state-memory`
+   * @param {(level: string, message: string) => void} [o.log]
+   */
+  constructor({ platform, profile = 'default', profileDir = null, channel = null, vault = new Map(), sdkAdapter = null, chat = null, state = null, log = () => {} }) {
+    this.platform = platform;
+    this.profile = profile;
+    /** The owning profile's folder: a Hermes-shaped block reads its own `.env` there, never another profile's. */
+    this.profileDir = profileDir;
+    this.channel = channel;
+    this.vault = vault;
+    this.sdkAdapter = sdkAdapter;
+    this.chat = chat;
+    this.state = state;
+    this.log = log;
+    this.emit = null;
+    /** thread_id -> the live `Thread`, so `send` posts through the SDK's own door. */
+    this.threads = new Map();
+  }
+
+  /** The block's `extra:` map, whose keys the loader prefixes with `extra.` (the world codec's channel decoder). */
+  extra(name, fallback = undefined) {
+    const e = this.channel?.extra ?? {};
+    return e[`extra.${name}`] ?? e[name] ?? fallback;
+  }
+
+  /**
+   * The factory options for the platform package: the credential KEY NAMES in
+   * the profile block are the SDK factory's own option names, resolved from
+   * the vault here and never earlier (§2.4: the model holds refs, not values).
+   * supercode renames nothing.
+   */
+  async credentials() {
+    const slug = String(this.extra('slug', this.platform));
+    const hermes = HERMES_PLATFORMS[slug];
+    if (hermes && !Object.keys(this.channel?.credentials ?? {}).length) {
+      // Hermes's own variables, from the owning profile's own .env only (a
+      // named profile's token never serves the root's block, Hermes #59739)
+      const file = this.profileDir ? join(this.profileDir, '.env') : null;
+      const env = file && existsSync(file) ? parseDotenv(readFileSync(file, 'utf8')) : new Map();
+      const out = { ...hermes.options };
+      for (const [option, name] of Object.entries(hermes.env)) {
+        const value = env.get(name);
+        if (value !== undefined && value !== '') out[option] = value;
+      }
+      if (!out.botToken) throw new Error(`platforms.${this.platform}: ${hermes.env.botToken} is not in ${file ?? "the profile's .env"}`);
+      // Hermes connects Slack only over Socket Mode, and requires the app token for it
+      if (slug === 'slack' && !out.appToken) throw new Error(`platforms.${this.platform}: SLACK_APP_TOKEN is not in ${file}; Socket Mode needs it, as Hermes does`);
+      // The Discord package needs the application id and public key, which
+      // Hermes never asks for: Discord's own application record gives both
+      if (slug === 'discord' && (!out.applicationId || !out.publicKey)) {
+        let app;
+        try {
+          const res = await fetch('https://discord.com/api/v10/applications/@me', { headers: { authorization: `Bot ${out.botToken}` }, signal: AbortSignal.timeout(15_000) });
+          if (res.status === 401 || res.status === 403) throw new Error(`Discord refused DISCORD_BOT_TOKEN (${res.status})`);
+          if (!res.ok) throw Object.assign(new Error(`Discord answered ${res.status} for the application record`), { transient: true });
+          app = await res.json();
+        } catch (error) {
+          if (error.name === 'TimeoutError' || error.name === 'TypeError') throw Object.assign(new Error(`Discord unreachable: ${error.message}`), { transient: true });
+          throw error;
+        }
+        out.applicationId ??= app.id;
+        out.publicKey ??= app.verify_key;
+      }
+      return out;
+    }
+    const out = {};
+    for (const [key, ref] of Object.entries(this.channel?.credentials ?? {})) {
+      const name = ref.dotenv ?? ref.env;
+      const value = this.vault.get(name) ?? process.env[name];
+      if (value === undefined) throw new Error(`platforms.${this.platform}.${key}: \${${name}} is in neither the home's .env nor the environment`);
+      // `extra.foo` in the block is the factory option `foo`
+      out[key.startsWith('extra.') ? key.slice(6) : key] = value;
+    }
+    return out;
+  }
+
+  /**
+   * Build the SDK platform adapter named by this block. `extra.slug` picks the
+   * registry entry when the block's name is an account label rather than a
+   * platform ("slack-eng" -> `extra.slug: slack`); otherwise the block's name
+   * IS the slug, which is why one block is one (platform, account).
+   */
+  async buildSdkAdapter() {
+    const slug = String(this.extra('slug', this.platform));
+    const { getAdapter } = await import(/* @vite-ignore */ `${CHAT_SDK_PACKAGE}/adapters`);
+    const entry = getAdapter(slug);
+    if (!entry || entry.type !== 'platform') throw new Error(`chat-sdk: \`${slug}\` is not a Chat SDK platform adapter`);
+    let mod;
+    try {
+      mod = await import(/* @vite-ignore */ entry.packageName);
+    } catch (error) {
+      throw new Error(`chat-sdk: ${entry.packageName} is not installed (${error.message})`);
+    }
+    const factory = mod[entry.factoryExport];
+    if (typeof factory !== 'function') throw new Error(`chat-sdk: ${entry.packageName} exports no ${entry.factoryExport}`);
+    const options = await this.credentials();
+    this.lockToken(slug, options);
+    return factory(options);
+  }
+
+  /**
+   * One gateway per bot token on this machine, as Hermes's adapters hold it: the token's scoped lock in
+   * Hermes's own lock directory and record, so a Hermes gateway on any home refuses the token while this
+   * adapter serves it, and this adapter refuses a token a live Hermes gateway serves.
+   */
+  lockToken(slug, options) {
+    const lock = TOKEN_SCOPES[slug];
+    const identity = lock && options[lock.option];
+    if (!identity) return;
+    const got = acquireTokenLock({ scope: lock.scope, identity, home: this.profileDir ?? process.cwd(), platform: slug });
+    if (!got.ok) {
+      const who = got.holder?.pid ? `pid ${got.holder.pid}${got.holder.hermes_home ? ` serving ${got.holder.hermes_home}` : ''}` : 'another gateway';
+      throw new Error(`${slug}'s token is served by ${who}; one gateway serves a token at a time`);
+    }
+    this.tokenLock = { scope: lock.scope, identity };
+  }
+
+  async buildState() {
+    if (this.state) return this.state;
+    const { createMemoryState } = await import(/* @vite-ignore */ CHAT_SDK_STATE_PACKAGE);
+    return createMemoryState();
+  }
+
+  /**
+   * Mount the sidecar. Every handler door the SDK offers for an inbound human
+   * message is registered onto the SAME mapping, so a DM, a fresh @-mention
+   * and a follow-up in a subscribed thread all become one `inbound`.
+   */
+  async connect(emit) {
+    this.emit = emit;
+    if (!this.chat) {
+      try {
+        const { Chat } = await import(/* @vite-ignore */ CHAT_SDK_PACKAGE);
+        const sdkAdapter = this.sdkAdapter ?? (await this.buildSdkAdapter());
+        this.sdkAdapter = sdkAdapter;
+        this.chat = new Chat({
+          adapters: { [sdkAdapter.name]: sdkAdapter },
+          state: await this.buildState(),
+          // F4 finding 11: the IR owns the queue, so the SDK's is off by default
+          concurrency: this.extra('concurrency', 'concurrent'),
+          logger: this.extra('logger', 'silent'),
+        });
+        this.builtChat = true;
+      } catch (error) {
+        this.emit = null;
+        // a transient failure (a platform unreachable) is retried by the loop
+        if (error.transient) throw error;
+        // A missing platform package or credential is this ADAPTER not set
+        // up, not the daemon failing to start: reported down and not
+        // configured (§3), so the surface stays visibly unconnected, no retry
+        // is spent on it, and Hermes's preflight does not count it connected.
+        this.log('error', `chat-sdk ${this.platform}: ${error.message}`);
+        return { state: 'down', error: error.message, configured: false };
+      }
+    }
+    if (!this.handlersOn) {
+      // registered once: a retried connect must not answer each message twice
+      const handle = (thread, message) => this.handle(thread, message);
+      this.chat.onDirectMessage(handle);
+      this.chat.onNewMention(handle);
+      this.chat.onSubscribedMessage(handle);
+      // Hermes's free-response channels answer without a mention; only they admit an unmentioned message
+      if (this.discordRules()?.free.size) this.chat.onNewMessage(/[\s\S]*/, (thread, message) => this.handle(thread, message, { unmentioned: true }));
+      this.handlersOn = true;
+    }
+    try {
+      await this.chat.initialize();
+    } catch (error) {
+      // the SDK keeps a rejected initialize; a Chat this adapter built is
+      // rebuilt on the loop's retry
+      if (this.builtChat) { this.chat = null; this.handlersOn = false; }
+      throw error;
+    }
+    if (HERMES_PLATFORMS[String(this.extra('slug', this.platform))]?.gateway) this.listenGateway();
+    return { state: 'up' };
+  }
+
+  /**
+   * Discord's messages arrive only over its gateway websocket, which the
+   * package runs for a bounded duration per call (built for serverless crons);
+   * a resident daemon, as Hermes is, starts the next slice when one ends,
+   * until close.
+   */
+  listenGateway() {
+    if (this.gateway) return;
+    const abort = new AbortController();
+    this.gateway = abort;
+    const run = async () => {
+      let backoff = 0;
+      while (!abort.signal.aborted && typeof this.sdkAdapter?.startGatewayListener === 'function') {
+        const tasks = [];
+        const began = Date.now();
+        let why = null;
+        try {
+          const res = await this.sdkAdapter.startGatewayListener({ waitUntil: (task) => { tasks.push(task); } }, GATEWAY_SLICE_MS, abort.signal);
+          if (res && typeof res.status === 'number' && res.status >= 400) why = `the listener answered ${res.status}`;
+          await Promise.allSettled(tasks);
+        } catch (error) {
+          why = error.message;
+        }
+        if (abort.signal.aborted) break;
+        // a slice that ended well before its time (a refused login, a
+        // dropped socket) is retried with backoff, never in a tight loop
+        if (why || Date.now() - began < GATEWAY_SLICE_MS * 0.9) {
+          backoff = Math.min(backoff ? backoff * 2 : 5_000, 300_000);
+          this.log('warn', `chat-sdk ${this.platform}: gateway listener ended early (${why ?? 'before its slice'}); retrying in ${backoff / 1000}s`);
+          await new Promise((r) => {
+            const stop = () => { clearTimeout(t); r(); };
+            const t = setTimeout(() => { abort.signal.removeEventListener('abort', stop); r(); }, backoff);
+            t.unref?.();
+            abort.signal.addEventListener('abort', stop, { once: true });
+          });
+        } else backoff = 0;
+      }
+    };
+    void run().catch((error) => this.log('error', `chat-sdk ${this.platform}: gateway: ${error.message}`));
+  }
+
+  /**
+   * The one door from the SDK into the loop. Exported behaviour, not private:
+   * it builds an `inbound` payload and hands it to the loop's `emit`, which is
+   * the same callback `LoopbackAdapter` gets.
+   */
+  handle(thread, message, { unmentioned = false } = {}) {
+    if (!this.emit) throw new Error('chat-sdk adapter is not connected');
+    const inbound = toInbound({ profile: this.profile, thread, message });
+    // one message reaches several handlers (a mention in a free channel): it is one turn
+    const seen = (this.seen ??= new Set());
+    if (seen.has(inbound.message_id)) return undefined;
+    if (!this.admitDiscord(inbound, unmentioned)) return undefined;
+    seen.add(inbound.message_id);
+    if (seen.size > 512) seen.delete(seen.values().next().value);
+    this.threads.set(String(thread.id), thread);
+    return this.emit(inbound);
+  }
+
+  /**
+   * Hermes's Discord channel rules, from the profile's own `.env`: `DISCORD_ALLOWED_CHANNELS`,
+   * `DISCORD_IGNORED_CHANNELS`, `DISCORD_FREE_RESPONSE_CHANNELS` (comma lists, `*` for every channel).
+   * Null for any other platform.
+   */
+  discordRules() {
+    if (this.rules !== undefined) return this.rules;
+    if (String(this.extra('slug', this.platform)) !== 'discord') return (this.rules = null);
+    const file = this.profileDir ? join(this.profileDir, '.env') : null;
+    const env = file && existsSync(file) ? parseDotenv(readFileSync(file, 'utf8')) : new Map();
+    const list = (name) => new Set(String(env.get(name) ?? process.env[name] ?? '').split(',').map((v) => v.trim()).filter(Boolean));
+    return (this.rules = { allowed: list('DISCORD_ALLOWED_CHANNELS'), ignored: list('DISCORD_IGNORED_CHANNELS'), free: list('DISCORD_FREE_RESPONSE_CHANNELS') });
+  }
+
+  /** Whether Hermes's Discord adapter would take this message: DMs always; else not ignored, allowed, and mentioned unless free. */
+  admitDiscord(inbound, unmentioned) {
+    const rules = this.discordRules();
+    if (!rules || inbound.key.kind === 'dm') return true;
+    const ids = new Set([inbound.key.chat_id, inbound.key.thread_id].filter(Boolean).map(String));
+    const hit = (set) => set.has('*') || [...ids].some((id) => set.has(id) || [...set].some((c) => id.endsWith(`:${c}`)));
+    if (rules.ignored.size && hit(rules.ignored)) return false;
+    if (rules.allowed.size && !hit(rules.allowed)) return false;
+    if (unmentioned && !hit(rules.free)) return false;
+    return true;
+  }
+
+  /**
+   * `Deliver(obligation)` (§5). Returns the platform's handle so the loop can
+   * record `Obligation.posted.message_id` (§2.6) — the thing §4.2's
+   * edit-in-place would edit.
+   */
+  async send(target, content) {
+    const threadId = target.thread_id ? String(target.thread_id) : null;
+    const thread = threadId ? this.threads.get(threadId) : null;
+    if (!thread && !threadId && typeof this.sdkAdapter?.postChannelMessage !== 'function') {
+      throw new Error(`chat-sdk: ${this.platform} cannot post to a channel without a thread`);
+    }
+    // A platform that caps a message's length gets the text in parts, in order, as Hermes's own adapters send it
+    // (Discord refuses past 2000 characters, and a fire's report was cut off there). The first part is the handle.
+    const limit = MESSAGE_LIMIT[this.platform];
+    let first;
+    for (const [index, text] of (limit ? chunks(content.text ?? '', limit) : [content.text ?? '']).entries()) {
+      let sent;
+      if (thread) {
+        sent = content.reply_to && index === 0 ? await thread.reply(String(content.reply_to), text) : await thread.post(text);
+      } else if (threadId) {
+        sent = await this.sdkAdapter.postMessage(threadId, text);
+      } else {
+        sent = await this.sdkAdapter.postChannelMessage(this.channelId(String(target.chat_id)), text);
+      }
+      first ??= sent;
+    }
+    return first?.id ? { ok: true, message_id: String(first.id) } : { ok: true };
+  }
+
+  /**
+   * A chat as the Chat SDK names it. Hermes keeps a Discord channel as its bare id (`DISCORD_HOME_CHANNEL`,
+   * `/sethome`), and the Discord package posts only to its own `discord:<guild>:<channel>` form, which it
+   * builds with `encodeThreadId` and `@me` for an unknown guild (it posts by the channel part alone).
+   */
+  channelId(chat) {
+    const slug = String(this.extra('slug', this.platform));
+    if (slug !== 'discord' || chat.includes(':') || typeof this.sdkAdapter?.encodeThreadId !== 'function') return chat;
+    return this.sdkAdapter.encodeThreadId({ guildId: '@me', channelId: chat });
+  }
+
+  async close() {
+    this.gateway?.abort();
+    this.gateway = null;
+    this.emit = null;
+    this.threads.clear();
+    try { await this.chat?.shutdown(); } catch (error) { this.log('warn', `chat-sdk shutdown: ${error.message}`); }
+    if (this.tokenLock) { releaseTokenLock(this.tokenLock); this.tokenLock = null; }
+  }
+}

package/adapters/chunks.mjs

@@ -0,0 +1,14 @@
+// A message cut into parts a platform will take: at most `max` characters each, ending where a paragraph, else a
+// line, else a word ends. Shared by every adapter whose platform caps a message's length.
+export function chunks(text, max) {
+  const parts = [];
+  let rest = text;
+  while (rest.length > max) {
+    const window = rest.slice(0, max);
+    const at = [window.lastIndexOf('\n\n'), window.lastIndexOf('\n'), window.lastIndexOf(' ')].find((i) => i > max / 2) ?? max;
+    parts.push(rest.slice(0, at).trimEnd());
+    rest = rest.slice(at).trimStart();
+  }
+  parts.push(rest);
+  return parts;
+}

package/adapters/loopback.mjs

@@ -0,0 +1,37 @@
+// The loopback adapter: an in-memory channel for tests and for the week
+// comparison (docs/ORCHESTRATOR-IR.md §7). Inbound is injected by the test;
+// outbound lands in an outbox the test reads. Same trait as every adapter:
+//   connect(emit) / send(target, content) / close()
+
+export class LoopbackAdapter {
+  constructor({ platform = 'loopback', profile = 'default', failSends = 0 } = {}) {
+    this.platform = platform;
+    this.profile = profile;
+    this.outbox = [];
+    this.failSends = failSends;
+    this.emit = null;
+  }
+
+  async connect(emit) {
+    this.emit = emit;
+    return { state: 'up' };
+  }
+
+  /** Inject an inbound message as the platform would deliver it. */
+  inject({ kind = 'dm', chat_id = '1', thread_id, sender = 'u1', sender_name = null, text, at, guild_id = null }) {
+    if (!this.emit) throw new Error('loopback not connected');
+    const key = { platform: this.platform, kind, chat_id: String(chat_id) };
+    if (thread_id) key.thread_id = String(thread_id);
+    return this.emit({ profile: this.profile, key, sender, sender_name, text, at, guild_id });
+  }
+
+  async send(target, content) {
+    if (this.failSends > 0) { this.failSends -= 1; throw new Error('loopback send failed (injected)'); }
+    this.outbox.push({ target: { ...target }, text: content.text, at: content.at ?? null });
+    return { ok: true };
+  }
+
+  async close() {
+    this.emit = null;
+  }
+}