feat: thread-bound subagents on Discord (#21805)

* docs: thread-bound subagents plan

* docs: add exact thread-bound subagent implementation touchpoints

* Docs: prioritize auto thread-bound subagent flow

* Docs: add ACP harness thread-binding extensions

* Discord: add thread-bound session routing and auto-bind spawn flow

* Subagents: add focus commands and ACP/session binding lifecycle hooks

* Tests: cover thread bindings, focus commands, and ACP unbind hooks

* Docs: add plugin-hook appendix for thread-bound subagents

* Plugins: add subagent lifecycle hook events

* Core: emit subagent lifecycle hooks and decouple Discord bindings

* Discord: handle subagent bind lifecycle via plugin hooks

* Subagents: unify completion finalizer and split registry modules

* Add subagent lifecycle events module

* Hooks: fix subagent ended context key

* Discord: share thread bindings across ESM and Jiti

* Subagents: add persistent sessions_spawn mode for thread-bound sessions

* Subagents: clarify thread intro and persistent completion copy

* test(subagents): stabilize sessions_spawn lifecycle cleanup assertions

* Discord: add thread-bound session TTL with auto-unfocus

* Subagents: fail session spawns when thread bind fails

* Subagents: cover thread session failure cleanup paths

* Session: add thread binding TTL config and /session ttl controls

* Tests: align discord reaction expectations

* Agent: persist sessionFile for keyed subagent sessions

* Discord: normalize imports after conflict resolution

* Sessions: centralize sessionFile resolve/persist helper

* Discord: harden thread-bound subagent session routing

* Rebase: resolve upstream/main conflicts

* Subagents: move thread binding into hooks and split bindings modules

* Docs: add channel-agnostic subagent routing hook plan

* Agents: decouple subagent routing from Discord

* Discord: refactor thread-bound subagent flows

* Subagents: prevent duplicate end hooks and orphaned failed sessions

* Refactor: split subagent command and provider phases

* Subagents: honor hook delivery target overrides

* Discord: add thread binding kill switches and refresh plan doc

* Discord: fix thread bind channel resolution

* Routing: centralize account id normalization

* Discord: clean up thread bindings on startup failures

* Discord: add startup cleanup regression tests

* Docs: add long-term thread-bound subagent architecture

* Docs: split session binding plan and dedupe thread-bound doc

* Subagents: add channel-agnostic session binding routing

* Subagents: stabilize announce completion routing tests

* Subagents: cover multi-bound completion routing

* Subagents: suppress lifecycle hooks on failed thread bind

* tests: fix discord provider mock typing regressions

* docs/protocol: sync slash command aliases and delete param models

* fix: add changelog entry for Discord thread-bound subagents (#21805) (thanks @onutc)

---------

Co-authored-by: Shadow <hi@shadowing.dev>

src/infra/outbound/bound-delivery-router.test.ts

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { createBoundDeliveryRouter } from "./bound-delivery-router.js";
+import { __testing, registerSessionBindingAdapter } from "./session-binding-service.js";
+
+describe("bound delivery router", () => {
+  beforeEach(() => {
+    __testing.resetSessionBindingAdaptersForTests();
+  });
+
+  it("resolves to a bound destination when a single active binding exists", () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "runtime",
+      listBySession: (targetSessionKey) =>
+        targetSessionKey === "agent:main:subagent:child"
+          ? [
+              {
+                bindingId: "runtime:thread-1",
+                targetSessionKey,
+                targetKind: "subagent",
+                conversation: {
+                  channel: "discord",
+                  accountId: "runtime",
+                  conversationId: "thread-1",
+                  parentConversationId: "parent-1",
+                },
+                status: "active",
+                boundAt: 1,
+              },
+            ]
+          : [],
+      resolveByConversation: () => null,
+    });
+
+    const route = createBoundDeliveryRouter().resolveDestination({
+      eventKind: "task_completion",
+      targetSessionKey: "agent:main:subagent:child",
+      requester: {
+        channel: "discord",
+        accountId: "runtime",
+        conversationId: "parent-1",
+      },
+      failClosed: false,
+    });
+
+    expect(route.mode).toBe("bound");
+    expect(route.binding?.conversation.conversationId).toBe("thread-1");
+  });
+
+  it("falls back when no active binding exists", () => {
+    const route = createBoundDeliveryRouter().resolveDestination({
+      eventKind: "task_completion",
+      targetSessionKey: "agent:main:subagent:missing",
+      requester: {
+        channel: "discord",
+        accountId: "runtime",
+        conversationId: "parent-1",
+      },
+      failClosed: false,
+    });
+
+    expect(route).toEqual({
+      binding: null,
+      mode: "fallback",
+      reason: "no-active-binding",
+    });
+  });
+
+  it("fails closed when multiple bindings exist without requester signal", () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "runtime",
+      listBySession: (targetSessionKey) =>
+        targetSessionKey === "agent:main:subagent:child"
+          ? [
+              {
+                bindingId: "runtime:thread-1",
+                targetSessionKey,
+                targetKind: "subagent",
+                conversation: {
+                  channel: "discord",
+                  accountId: "runtime",
+                  conversationId: "thread-1",
+                },
+                status: "active",
+                boundAt: 1,
+              },
+              {
+                bindingId: "runtime:thread-2",
+                targetSessionKey,
+                targetKind: "subagent",
+                conversation: {
+                  channel: "discord",
+                  accountId: "runtime",
+                  conversationId: "thread-2",
+                },
+                status: "active",
+                boundAt: 2,
+              },
+            ]
+          : [],
+      resolveByConversation: () => null,
+    });
+
+    const route = createBoundDeliveryRouter().resolveDestination({
+      eventKind: "task_completion",
+      targetSessionKey: "agent:main:subagent:child",
+      failClosed: true,
+    });
+
+    expect(route).toEqual({
+      binding: null,
+      mode: "fallback",
+      reason: "ambiguous-without-requester",
+    });
+  });
+});

src/infra/outbound/bound-delivery-router.ts

@@ -0,0 +1,131 @@
+import {
+  getSessionBindingService,
+  type ConversationRef,
+  type SessionBindingRecord,
+  type SessionBindingService,
+} from "./session-binding-service.js";
+
+export type BoundDeliveryRouterInput = {
+  eventKind: "task_completion";
+  targetSessionKey: string;
+  requester?: ConversationRef;
+  failClosed: boolean;
+};
+
+export type BoundDeliveryRouterResult = {
+  binding: SessionBindingRecord | null;
+  mode: "bound" | "fallback";
+  reason: string;
+};
+
+export type BoundDeliveryRouter = {
+  resolveDestination: (input: BoundDeliveryRouterInput) => BoundDeliveryRouterResult;
+};
+
+function isActiveBinding(record: SessionBindingRecord): boolean {
+  return record.status === "active";
+}
+
+function resolveBindingForRequester(
+  requester: ConversationRef,
+  bindings: SessionBindingRecord[],
+): SessionBindingRecord | null {
+  const matchingChannelAccount = bindings.filter(
+    (entry) =>
+      entry.conversation.channel === requester.channel &&
+      entry.conversation.accountId === requester.accountId,
+  );
+  if (matchingChannelAccount.length === 0) {
+    return null;
+  }
+
+  const exactConversation = matchingChannelAccount.find(
+    (entry) => entry.conversation.conversationId === requester.conversationId,
+  );
+  if (exactConversation) {
+    return exactConversation;
+  }
+
+  if (matchingChannelAccount.length === 1) {
+    return matchingChannelAccount[0] ?? null;
+  }
+  return null;
+}
+
+export function createBoundDeliveryRouter(
+  service: SessionBindingService = getSessionBindingService(),
+): BoundDeliveryRouter {
+  return {
+    resolveDestination: (input) => {
+      const targetSessionKey = input.targetSessionKey.trim();
+      if (!targetSessionKey) {
+        return {
+          binding: null,
+          mode: "fallback",
+          reason: "missing-target-session",
+        };
+      }
+
+      const activeBindings = service.listBySession(targetSessionKey).filter(isActiveBinding);
+      if (activeBindings.length === 0) {
+        return {
+          binding: null,
+          mode: "fallback",
+          reason: "no-active-binding",
+        };
+      }
+
+      if (!input.requester) {
+        if (activeBindings.length === 1) {
+          return {
+            binding: activeBindings[0] ?? null,
+            mode: "bound",
+            reason: "single-active-binding",
+          };
+        }
+        return {
+          binding: null,
+          mode: "fallback",
+          reason: "ambiguous-without-requester",
+        };
+      }
+
+      const requester: ConversationRef = {
+        channel: input.requester.channel.trim().toLowerCase(),
+        accountId: input.requester.accountId.trim(),
+        conversationId: input.requester.conversationId.trim(),
+        parentConversationId: input.requester.parentConversationId?.trim() || undefined,
+      };
+      if (!requester.channel || !requester.conversationId) {
+        return {
+          binding: null,
+          mode: "fallback",
+          reason: "invalid-requester",
+        };
+      }
+
+      const fromRequester = resolveBindingForRequester(requester, activeBindings);
+      if (fromRequester) {
+        return {
+          binding: fromRequester,
+          mode: "bound",
+          reason: "requester-match",
+        };
+      }
+
+      if (activeBindings.length === 1 && !input.failClosed) {
+        return {
+          binding: activeBindings[0] ?? null,
+          mode: "bound",
+          reason: "single-active-binding-fallback",
+        };
+      }
+
+      return {
+        binding: null,
+        mode: "fallback",
+        reason: "no-requester-match",
+      };
+    },
+  };
+}

src/infra/outbound/session-binding-service.ts

@@ -0,0 +1,192 @@
+import { normalizeAccountId } from "../../routing/session-key.js";
+
+export type BindingTargetKind = "subagent" | "session";
+export type BindingStatus = "active" | "ending" | "ended";
+
+export type ConversationRef = {
+  channel: string;
+  accountId: string;
+  conversationId: string;
+  parentConversationId?: string;
+};
+
+export type SessionBindingRecord = {
+  bindingId: string;
+  targetSessionKey: string;
+  targetKind: BindingTargetKind;
+  conversation: ConversationRef;
+  status: BindingStatus;
+  boundAt: number;
+  expiresAt?: number;
+  metadata?: Record<string, unknown>;
+};
+
+type SessionBindingBindInput = {
+  targetSessionKey: string;
+  targetKind: BindingTargetKind;
+  conversation: ConversationRef;
+  metadata?: Record<string, unknown>;
+  ttlMs?: number;
+};
+
+type SessionBindingUnbindInput = {
+  bindingId?: string;
+  targetSessionKey?: string;
+  reason: string;
+};
+
+export type SessionBindingService = {
+  bind: (input: SessionBindingBindInput) => Promise<SessionBindingRecord>;
+  listBySession: (targetSessionKey: string) => SessionBindingRecord[];
+  resolveByConversation: (ref: ConversationRef) => SessionBindingRecord | null;
+  touch: (bindingId: string, at?: number) => void;
+  unbind: (input: SessionBindingUnbindInput) => Promise<SessionBindingRecord[]>;
+};
+
+export type SessionBindingAdapter = {
+  channel: string;
+  accountId: string;
+  bind?: (input: SessionBindingBindInput) => Promise<SessionBindingRecord | null>;
+  listBySession: (targetSessionKey: string) => SessionBindingRecord[];
+  resolveByConversation: (ref: ConversationRef) => SessionBindingRecord | null;
+  touch?: (bindingId: string, at?: number) => void;
+  unbind?: (input: SessionBindingUnbindInput) => Promise<SessionBindingRecord[]>;
+};
+
+function normalizeConversationRef(ref: ConversationRef): ConversationRef {
+  return {
+    channel: ref.channel.trim().toLowerCase(),
+    accountId: normalizeAccountId(ref.accountId),
+    conversationId: ref.conversationId.trim(),
+    parentConversationId: ref.parentConversationId?.trim() || undefined,
+  };
+}
+
+function toAdapterKey(params: { channel: string; accountId: string }): string {
+  return `${params.channel.trim().toLowerCase()}:${normalizeAccountId(params.accountId)}`;
+}
+
+const ADAPTERS_BY_CHANNEL_ACCOUNT = new Map<string, SessionBindingAdapter>();
+
+export function registerSessionBindingAdapter(adapter: SessionBindingAdapter): void {
+  const key = toAdapterKey({
+    channel: adapter.channel,
+    accountId: adapter.accountId,
+  });
+  ADAPTERS_BY_CHANNEL_ACCOUNT.set(key, {
+    ...adapter,
+    channel: adapter.channel.trim().toLowerCase(),
+    accountId: normalizeAccountId(adapter.accountId),
+  });
+}
+
+export function unregisterSessionBindingAdapter(params: {
+  channel: string;
+  accountId: string;
+}): void {
+  ADAPTERS_BY_CHANNEL_ACCOUNT.delete(toAdapterKey(params));
+}
+
+function resolveAdapterForConversation(ref: ConversationRef): SessionBindingAdapter | null {
+  const normalized = normalizeConversationRef(ref);
+  const key = toAdapterKey({
+    channel: normalized.channel,
+    accountId: normalized.accountId,
+  });
+  return ADAPTERS_BY_CHANNEL_ACCOUNT.get(key) ?? null;
+}
+
+function dedupeBindings(records: SessionBindingRecord[]): SessionBindingRecord[] {
+  const byId = new Map<string, SessionBindingRecord>();
+  for (const record of records) {
+    if (!record?.bindingId) {
+      continue;
+    }
+    byId.set(record.bindingId, record);
+  }
+  return [...byId.values()];
+}
+
+function createDefaultSessionBindingService(): SessionBindingService {
+  return {
+    bind: async (input) => {
+      const normalizedConversation = normalizeConversationRef(input.conversation);
+      const adapter = resolveAdapterForConversation(normalizedConversation);
+      if (!adapter?.bind) {
+        throw new Error(
+          `Session binding adapter unavailable for ${normalizedConversation.channel}:${normalizedConversation.accountId}`,
+        );
+      }
+      const bound = await adapter.bind({
+        ...input,
+        conversation: normalizedConversation,
+      });
+      if (!bound) {
+        throw new Error("Session binding adapter failed to bind target conversation");
+      }
+      return bound;
+    },
+    listBySession: (targetSessionKey) => {
+      const key = targetSessionKey.trim();
+      if (!key) {
+        return [];
+      }
+      const results: SessionBindingRecord[] = [];
+      for (const adapter of ADAPTERS_BY_CHANNEL_ACCOUNT.values()) {
+        const entries = adapter.listBySession(key);
+        if (entries.length > 0) {
+          results.push(...entries);
+        }
+      }
+      return dedupeBindings(results);
+    },
+    resolveByConversation: (ref) => {
+      const normalized = normalizeConversationRef(ref);
+      if (!normalized.channel || !normalized.conversationId) {
+        return null;
+      }
+      const adapter = resolveAdapterForConversation(normalized);
+      if (!adapter) {
+        return null;
+      }
+      return adapter.resolveByConversation(normalized);
+    },
+    touch: (bindingId, at) => {
+      const normalizedBindingId = bindingId.trim();
+      if (!normalizedBindingId) {
+        return;
+      }
+      for (const adapter of ADAPTERS_BY_CHANNEL_ACCOUNT.values()) {
+        adapter.touch?.(normalizedBindingId, at);
+      }
+    },
+    unbind: async (input) => {
+      const removed: SessionBindingRecord[] = [];
+      for (const adapter of ADAPTERS_BY_CHANNEL_ACCOUNT.values()) {
+        if (!adapter.unbind) {
+          continue;
+        }
+        const entries = await adapter.unbind(input);
+        if (entries.length > 0) {
+          removed.push(...entries);
+        }
+      }
+      return dedupeBindings(removed);
+    },
+  };
+}
+
+const DEFAULT_SESSION_BINDING_SERVICE = createDefaultSessionBindingService();
+
+export function getSessionBindingService(): SessionBindingService {
+  return DEFAULT_SESSION_BINDING_SERVICE;
+}
+
+export const __testing = {
+  resetSessionBindingAdaptersForTests() {
+    ADAPTERS_BY_CHANNEL_ACCOUNT.clear();
+  },
+  getRegisteredAdapterKeys() {
+    return [...ADAPTERS_BY_CHANNEL_ACCOUNT.keys()];
+  },
+};