feat: ACP thread-bound agents (#23580)

* docs: add ACP thread-bound agents plan doc

* docs: expand ACP implementation specification

* feat(acp): route ACP sessions through core dispatch and lifecycle cleanup

* feat(acp): add /acp commands and Discord spawn gate

* ACP: add acpx runtime plugin backend

* fix(subagents): defer transient lifecycle errors before announce

* Agents: harden ACP sessions_spawn and tighten spawn guidance

* Agents: require explicit ACP target for runtime spawns

* docs: expand ACP control-plane implementation plan

* ACP: harden metadata seeding and spawn guidance

* ACP: centralize runtime control-plane manager and fail-closed dispatch

* ACP: harden runtime manager and unify spawn helpers

* Commands: route ACP sessions through ACP runtime in agent command

* ACP: require persisted metadata for runtime spawns

* Sessions: preserve ACP metadata when updating entries

* Plugins: harden ACP backend registry across loaders

* ACPX: make availability probe compatible with adapters

* E2E: add manual Discord ACP plain-language smoke script

* ACPX: preserve streamed spacing across Discord delivery

* Docs: add ACP Discord streaming strategy

* ACP: harden Discord stream buffering for thread replies

* ACP: reuse shared block reply pipeline for projector

* ACP: unify streaming config and adopt coalesceIdleMs

* Docs: add temporary ACP production hardening plan

* Docs: trim temporary ACP hardening plan goals

* Docs: gate ACP thread controls by backend capabilities

* ACP: add capability-gated runtime controls and /acp operator commands

* Docs: remove temporary ACP hardening plan

* ACP: fix spawn target validation and close cache cleanup

* ACP: harden runtime dispatch and recovery paths

* ACP: split ACP command/runtime internals and centralize policy

* ACP: harden runtime lifecycle, validation, and observability

* ACP: surface runtime and backend session IDs in thread bindings

* docs: add temp plan for binding-service migration

* ACP: migrate thread binding flows to SessionBindingService

* ACP: address review feedback and preserve prompt wording

* ACPX plugin: pin runtime dependency and prefer bundled CLI

* Discord: complete binding-service migration cleanup and restore ACP plan

* Docs: add standalone ACP agents guide

* ACP: route harness intents to thread-bound ACP sessions

* ACP: fix spawn thread routing and queue-owner stall

* ACP: harden startup reconciliation and command bypass handling

* ACP: fix dispatch bypass type narrowing

* ACP: align runtime metadata to agentSessionId

* ACP: normalize session identifier handling and labels

* ACP: mark thread banner session ids provisional until first reply

* ACP: stabilize session identity mapping and startup reconciliation

* ACP: add resolved session-id notices and cwd in thread intros

* Discord: prefix thread meta notices consistently

* Discord: unify ACP/thread meta notices with gear prefix

* Discord: split thread persona naming from meta formatting

* Extensions: bump acpx plugin dependency to 0.1.9

* Agents: gate ACP prompt guidance behind acp.enabled

* Docs: remove temp experiment plan docs

* Docs: scope streaming plan to holy grail refactor

* Docs: refactor ACP agents guide for human-first flow

* Docs/Skill: add ACP feature-flag guidance and direct acpx telephone-game flow

* Docs/Skill: add OpenCode and Pi to ACP harness lists

* Docs/Skill: align ACP harness list with current acpx registry

* Dev/Test: move ACP plain-language smoke script and mark as keep

* Docs/Skill: reorder ACP harness lists with Pi first

* ACP: split control-plane manager into core/types/utils modules

* Docs: refresh ACP thread-bound agents plan

* ACP: extract dispatch lane and split manager domains

* ACP: centralize binding context and remove reverse deps

* Infra: unify system message formatting

* ACP: centralize error boundaries and session id rendering

* ACP: enforce init concurrency cap and strict meta clear

* Tests: fix ACP dispatch binding mock typing

* Tests: fix Discord thread-binding mock drift and ACP request id

* ACP: gate slash bypass and persist cleared overrides

* ACPX: await pre-abort cancel before runTurn return

* Extension: pin acpx runtime dependency to 0.1.11

* Docs: add pinned acpx install strategy for ACP extension

* Extensions/acpx: enforce strict local pinned startup

* Extensions/acpx: tighten acp-router install guidance

* ACPX: retry runtime test temp-dir cleanup

* Extensions/acpx: require proactive ACPX repair for thread spawns

* Extensions/acpx: require restart offer after acpx reinstall

* extensions/acpx: remove workspace protocol devDependency

* extensions/acpx: bump pinned acpx to 0.1.13

* extensions/acpx: sync lockfile after dependency bump

* ACPX: make runtime spawn Windows-safe

* fix: align doctor-config-flow repair tests with default-account migration (#23580) (thanks @osolmaz)

src/infra/outbound/conversation-id.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { resolveConversationIdFromTargets } from "./conversation-id.js";
+
+describe("resolveConversationIdFromTargets", () => {
+  it("prefers explicit thread id when present", () => {
+    const resolved = resolveConversationIdFromTargets({
+      threadId: "123456789",
+      targets: ["channel:987654321"],
+    });
+    expect(resolved).toBe("123456789");
+  });
+
+  it("extracts channel ids from channel: targets", () => {
+    const resolved = resolveConversationIdFromTargets({
+      targets: ["channel:987654321"],
+    });
+    expect(resolved).toBe("987654321");
+  });
+
+  it("extracts ids from Discord channel mentions", () => {
+    const resolved = resolveConversationIdFromTargets({
+      targets: ["<#1475250310120214812>"],
+    });
+    expect(resolved).toBe("1475250310120214812");
+  });
+
+  it("accepts raw numeric ids", () => {
+    const resolved = resolveConversationIdFromTargets({
+      targets: ["1475250310120214812"],
+    });
+    expect(resolved).toBe("1475250310120214812");
+  });
+
+  it("returns undefined for non-channel targets", () => {
+    const resolved = resolveConversationIdFromTargets({
+      targets: ["user:alice", "general"],
+    });
+    expect(resolved).toBeUndefined();
+  });
+});

src/infra/outbound/conversation-id.ts

@@ -0,0 +1,41 @@
+function normalizeConversationId(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+export function resolveConversationIdFromTargets(params: {
+  threadId?: string | number;
+  targets: Array<string | undefined | null>;
+}): string | undefined {
+  const threadId =
+    params.threadId != null ? normalizeConversationId(String(params.threadId)) : undefined;
+  if (threadId) {
+    return threadId;
+  }
+
+  for (const rawTarget of params.targets) {
+    const target = normalizeConversationId(rawTarget);
+    if (!target) {
+      continue;
+    }
+    if (target.startsWith("channel:")) {
+      const channelId = normalizeConversationId(target.slice("channel:".length));
+      if (channelId) {
+        return channelId;
+      }
+      continue;
+    }
+    const mentionMatch = target.match(/^<#(\d+)>$/);
+    if (mentionMatch?.[1]) {
+      return mentionMatch[1];
+    }
+    if (/^\d{6,}$/.test(target)) {
+      return target;
+    }
+  }
+
+  return undefined;
+}

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

@@ -0,0 +1,201 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  __testing,
+  getSessionBindingService,
+  isSessionBindingError,
+  registerSessionBindingAdapter,
+  type SessionBindingBindInput,
+  type SessionBindingRecord,
+} from "./session-binding-service.js";
+
+function createRecord(input: SessionBindingBindInput): SessionBindingRecord {
+  const conversationId =
+    input.placement === "child"
+      ? "thread-created"
+      : input.conversation.conversationId.trim() || "thread-current";
+  return {
+    bindingId: `default:${conversationId}`,
+    targetSessionKey: input.targetSessionKey,
+    targetKind: input.targetKind,
+    conversation: {
+      channel: "discord",
+      accountId: "default",
+      conversationId,
+      parentConversationId: input.conversation.parentConversationId?.trim() || undefined,
+    },
+    status: "active",
+    boundAt: 1,
+  };
+}
+
+describe("session binding service", () => {
+  beforeEach(() => {
+    __testing.resetSessionBindingAdaptersForTests();
+  });
+
+  it("normalizes conversation refs and infers current placement", async () => {
+    const bind = vi.fn(async (input: SessionBindingBindInput) => createRecord(input));
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      bind,
+      listBySession: () => [],
+      resolveByConversation: () => null,
+    });
+
+    const result = await getSessionBindingService().bind({
+      targetSessionKey: "agent:main:subagent:child-1",
+      targetKind: "subagent",
+      conversation: {
+        channel: "Discord",
+        accountId: "DEFAULT",
+        conversationId: " thread-1 ",
+      },
+    });
+
+    expect(result.conversation.channel).toBe("discord");
+    expect(result.conversation.accountId).toBe("default");
+    expect(bind).toHaveBeenCalledWith(
+      expect.objectContaining({
+        placement: "current",
+        conversation: expect.objectContaining({
+          channel: "discord",
+          accountId: "default",
+          conversationId: "thread-1",
+        }),
+      }),
+    );
+  });
+
+  it("supports explicit child placement when adapter advertises it", async () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      capabilities: { placements: ["child"] },
+      bind: async (input) => createRecord(input),
+      listBySession: () => [],
+      resolveByConversation: () => null,
+    });
+
+    const result = await getSessionBindingService().bind({
+      targetSessionKey: "agent:codex:acp:1",
+      targetKind: "session",
+      conversation: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: "thread-1",
+      },
+      placement: "child",
+    });
+
+    expect(result.conversation.conversationId).toBe("thread-created");
+  });
+
+  it("returns structured errors when adapter is unavailable", async () => {
+    await expect(
+      getSessionBindingService().bind({
+        targetSessionKey: "agent:main:subagent:child-1",
+        targetKind: "subagent",
+        conversation: {
+          channel: "discord",
+          accountId: "default",
+          conversationId: "thread-1",
+        },
+      }),
+    ).rejects.toMatchObject({
+      code: "BINDING_ADAPTER_UNAVAILABLE",
+    });
+  });
+
+  it("returns structured errors for unsupported placement", async () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      capabilities: { placements: ["current"] },
+      bind: async (input) => createRecord(input),
+      listBySession: () => [],
+      resolveByConversation: () => null,
+    });
+
+    const rejected = await getSessionBindingService()
+      .bind({
+        targetSessionKey: "agent:codex:acp:1",
+        targetKind: "session",
+        conversation: {
+          channel: "discord",
+          accountId: "default",
+          conversationId: "thread-1",
+        },
+        placement: "child",
+      })
+      .catch((error) => error);
+
+    expect(isSessionBindingError(rejected)).toBe(true);
+    expect(rejected).toMatchObject({
+      code: "BINDING_CAPABILITY_UNSUPPORTED",
+      details: {
+        placement: "child",
+      },
+    });
+  });
+
+  it("returns structured errors when adapter bind fails", async () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      bind: async () => null,
+      listBySession: () => [],
+      resolveByConversation: () => null,
+    });
+
+    await expect(
+      getSessionBindingService().bind({
+        targetSessionKey: "agent:main:subagent:child-1",
+        targetKind: "subagent",
+        conversation: {
+          channel: "discord",
+          accountId: "default",
+          conversationId: "thread-1",
+        },
+      }),
+    ).rejects.toMatchObject({
+      code: "BINDING_CREATE_FAILED",
+    });
+  });
+
+  it("reports adapter capabilities for command preflight messaging", () => {
+    registerSessionBindingAdapter({
+      channel: "discord",
+      accountId: "default",
+      capabilities: {
+        placements: ["current", "child"],
+      },
+      bind: async (input) => createRecord(input),
+      listBySession: () => [],
+      resolveByConversation: () => null,
+      unbind: async () => [],
+    });
+
+    const known = getSessionBindingService().getCapabilities({
+      channel: "discord",
+      accountId: "default",
+    });
+    const unknown = getSessionBindingService().getCapabilities({
+      channel: "discord",
+      accountId: "other",
+    });
+
+    expect(known).toEqual({
+      adapterAvailable: true,
+      bindSupported: true,
+      unbindSupported: true,
+      placements: ["current", "child"],
+    });
+    expect(unknown).toEqual({
+      adapterAvailable: false,
+      bindSupported: false,
+      unbindSupported: false,
+      placements: [],
+    });
+  });
+});

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

@@ -2,6 +2,11 @@ import { normalizeAccountId } from "../../routing/session-key.js";
 
 export type BindingTargetKind = "subagent" | "session";
 export type BindingStatus = "active" | "ending" | "ended";
+export type SessionBindingPlacement = "current" | "child";
+export type SessionBindingErrorCode =
+  | "BINDING_ADAPTER_UNAVAILABLE"
+  | "BINDING_CAPABILITY_UNSUPPORTED"
+  | "BINDING_CREATE_FAILED";
 
 export type ConversationRef = {
   channel: string;
@@ -21,31 +26,66 @@ export type SessionBindingRecord = {
   metadata?: Record<string, unknown>;
 };
 
-type SessionBindingBindInput = {
+export type SessionBindingBindInput = {
   targetSessionKey: string;
   targetKind: BindingTargetKind;
   conversation: ConversationRef;
+  placement?: SessionBindingPlacement;
   metadata?: Record<string, unknown>;
   ttlMs?: number;
 };
 
-type SessionBindingUnbindInput = {
+export type SessionBindingUnbindInput = {
   bindingId?: string;
   targetSessionKey?: string;
   reason: string;
 };
 
+export type SessionBindingCapabilities = {
+  adapterAvailable: boolean;
+  bindSupported: boolean;
+  unbindSupported: boolean;
+  placements: SessionBindingPlacement[];
+};
+
+export class SessionBindingError extends Error {
+  constructor(
+    public readonly code: SessionBindingErrorCode,
+    message: string,
+    public readonly details?: {
+      channel?: string;
+      accountId?: string;
+      placement?: SessionBindingPlacement;
+    },
+  ) {
+    super(message);
+    this.name = "SessionBindingError";
+  }
+}
+
+export function isSessionBindingError(error: unknown): error is SessionBindingError {
+  return error instanceof SessionBindingError;
+}
+
 export type SessionBindingService = {
   bind: (input: SessionBindingBindInput) => Promise<SessionBindingRecord>;
+  getCapabilities: (params: { channel: string; accountId: string }) => SessionBindingCapabilities;
   listBySession: (targetSessionKey: string) => SessionBindingRecord[];
   resolveByConversation: (ref: ConversationRef) => SessionBindingRecord | null;
   touch: (bindingId: string, at?: number) => void;
   unbind: (input: SessionBindingUnbindInput) => Promise<SessionBindingRecord[]>;
 };
 
+export type SessionBindingAdapterCapabilities = {
+  placements?: SessionBindingPlacement[];
+  bindSupported?: boolean;
+  unbindSupported?: boolean;
+};
+
 export type SessionBindingAdapter = {
   channel: string;
   accountId: string;
+  capabilities?: SessionBindingAdapterCapabilities;
   bind?: (input: SessionBindingBindInput) => Promise<SessionBindingRecord | null>;
   listBySession: (targetSessionKey: string) => SessionBindingRecord[];
   resolveByConversation: (ref: ConversationRef) => SessionBindingRecord | null;
@@ -66,6 +106,45 @@ function toAdapterKey(params: { channel: string; accountId: string }): string {
   return `${params.channel.trim().toLowerCase()}:${normalizeAccountId(params.accountId)}`;
 }
 
+function normalizePlacement(raw: unknown): SessionBindingPlacement | undefined {
+  return raw === "current" || raw === "child" ? raw : undefined;
+}
+
+function inferDefaultPlacement(ref: ConversationRef): SessionBindingPlacement {
+  return ref.conversationId ? "current" : "child";
+}
+
+function resolveAdapterPlacements(adapter: SessionBindingAdapter): SessionBindingPlacement[] {
+  const configured = adapter.capabilities?.placements?.map((value) => normalizePlacement(value));
+  const placements = configured?.filter((value): value is SessionBindingPlacement =>
+    Boolean(value),
+  );
+  if (placements && placements.length > 0) {
+    return [...new Set(placements)];
+  }
+  return ["current", "child"];
+}
+
+function resolveAdapterCapabilities(
+  adapter: SessionBindingAdapter | null,
+): SessionBindingCapabilities {
+  if (!adapter) {
+    return {
+      adapterAvailable: false,
+      bindSupported: false,
+      unbindSupported: false,
+      placements: [],
+    };
+  }
+  const bindSupported = adapter.capabilities?.bindSupported ?? Boolean(adapter.bind);
+  return {
+    adapterAvailable: true,
+    bindSupported,
+    unbindSupported: adapter.capabilities?.unbindSupported ?? Boolean(adapter.unbind),
+    placements: bindSupported ? resolveAdapterPlacements(adapter) : [],
+  };
+}
+
 const ADAPTERS_BY_CHANNEL_ACCOUNT = new Map<string, SessionBindingAdapter>();
 
 export function registerSessionBindingAdapter(adapter: SessionBindingAdapter): void {
@@ -88,10 +167,19 @@ export function unregisterSessionBindingAdapter(params: {
 }
 
 function resolveAdapterForConversation(ref: ConversationRef): SessionBindingAdapter | null {
-  const normalized = normalizeConversationRef(ref);
+  return resolveAdapterForChannelAccount({
+    channel: ref.channel,
+    accountId: ref.accountId,
+  });
+}
+
+function resolveAdapterForChannelAccount(params: {
+  channel: string;
+  accountId: string;
+}): SessionBindingAdapter | null {
   const key = toAdapterKey({
-    channel: normalized.channel,
-    accountId: normalized.accountId,
+    channel: params.channel,
+    accountId: params.accountId,
   });
   return ADAPTERS_BY_CHANNEL_ACCOUNT.get(key) ?? null;
 }
@@ -112,20 +200,65 @@ function createDefaultSessionBindingService(): SessionBindingService {
     bind: async (input) => {
       const normalizedConversation = normalizeConversationRef(input.conversation);
       const adapter = resolveAdapterForConversation(normalizedConversation);
-      if (!adapter?.bind) {
-        throw new Error(
+      if (!adapter) {
+        throw new SessionBindingError(
+          "BINDING_ADAPTER_UNAVAILABLE",
           `Session binding adapter unavailable for ${normalizedConversation.channel}:${normalizedConversation.accountId}`,
+          {
+            channel: normalizedConversation.channel,
+            accountId: normalizedConversation.accountId,
+          },
+        );
+      }
+      if (!adapter.bind) {
+        throw new SessionBindingError(
+          "BINDING_CAPABILITY_UNSUPPORTED",
+          `Session binding adapter does not support binding for ${normalizedConversation.channel}:${normalizedConversation.accountId}`,
+          {
+            channel: normalizedConversation.channel,
+            accountId: normalizedConversation.accountId,
+          },
+        );
+      }
+      const placement =
+        normalizePlacement(input.placement) ?? inferDefaultPlacement(normalizedConversation);
+      const supportedPlacements = resolveAdapterPlacements(adapter);
+      if (!supportedPlacements.includes(placement)) {
+        throw new SessionBindingError(
+          "BINDING_CAPABILITY_UNSUPPORTED",
+          `Session binding placement "${placement}" is not supported for ${normalizedConversation.channel}:${normalizedConversation.accountId}`,
+          {
+            channel: normalizedConversation.channel,
+            accountId: normalizedConversation.accountId,
+            placement,
+          },
         );
       }
       const bound = await adapter.bind({
         ...input,
         conversation: normalizedConversation,
+        placement,
       });
       if (!bound) {
-        throw new Error("Session binding adapter failed to bind target conversation");
+        throw new SessionBindingError(
+          "BINDING_CREATE_FAILED",
+          "Session binding adapter failed to bind target conversation",
+          {
+            channel: normalizedConversation.channel,
+            accountId: normalizedConversation.accountId,
+            placement,
+          },
+        );
       }
       return bound;
     },
+    getCapabilities: (params) => {
+      const adapter = resolveAdapterForChannelAccount({
+        channel: params.channel,
+        accountId: params.accountId,
+      });
+      return resolveAdapterCapabilities(adapter);
+    },
     listBySession: (targetSessionKey) => {
       const key = targetSessionKey.trim();
       if (!key) {

src/infra/system-message.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { SYSTEM_MARK, hasSystemMark, prefixSystemMessage } from "./system-message.js";
+
+describe("system-message", () => {
+  it("prepends the system mark once", () => {
+    expect(prefixSystemMessage("thread notice")).toBe(`${SYSTEM_MARK} thread notice`);
+  });
+
+  it("does not double-prefix messages that already have the mark", () => {
+    expect(prefixSystemMessage(`${SYSTEM_MARK} already prefixed`)).toBe(
+      `${SYSTEM_MARK} already prefixed`,
+    );
+  });
+
+  it("detects marked system text after trim normalization", () => {
+    expect(hasSystemMark(`  ${SYSTEM_MARK} hello`)).toBe(true);
+    expect(hasSystemMark("hello")).toBe(false);
+  });
+});

src/infra/system-message.ts

@@ -0,0 +1,20 @@
+export const SYSTEM_MARK = "⚙️";
+
+function normalizeSystemText(value: string): string {
+  return value.trim();
+}
+
+export function hasSystemMark(text: string): boolean {
+  return normalizeSystemText(text).startsWith(SYSTEM_MARK);
+}
+
+export function prefixSystemMessage(text: string): string {
+  const normalized = normalizeSystemText(text);
+  if (!normalized) {
+    return normalized;
+  }
+  if (hasSystemMark(normalized)) {
+    return normalized;
+  }
+  return `${SYSTEM_MARK} ${normalized}`;
+}