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)
2026-05-05 16:50:23 +00:00 · 2026-02-26 11:00:09 +01:00
parent a9d9a968ed
commit a7d56e3554
151 changed files with 19005 additions and 324 deletions
--- a/src/channels/thread-bindings-messages.ts
+++ b/src/channels/thread-bindings-messages.ts
@@ -0,0 +1,84 @@
+import { prefixSystemMessage } from "../infra/system-message.js";
+
+const DEFAULT_THREAD_BINDING_FAREWELL_TEXT =
+  "Session ended. Messages here will no longer be routed.";
+
+function normalizeThreadBindingMessageTtlMs(raw: unknown): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return 0;
+  }
+  const ttlMs = Math.floor(raw);
+  if (ttlMs < 0) {
+    return 0;
+  }
+  return ttlMs;
+}
+
+export function formatThreadBindingTtlLabel(ttlMs: number): string {
+  if (ttlMs <= 0) {
+    return "disabled";
+  }
+  if (ttlMs < 60_000) {
+    return "<1m";
+  }
+  const totalMinutes = Math.floor(ttlMs / 60_000);
+  if (totalMinutes % 60 === 0) {
+    return `${Math.floor(totalMinutes / 60)}h`;
+  }
+  return `${totalMinutes}m`;
+}
+
+export function resolveThreadBindingThreadName(params: {
+  agentId?: string;
+  label?: string;
+}): string {
+  const label = params.label?.trim();
+  const base = label || params.agentId?.trim() || "agent";
+  const raw = `🤖 ${base}`.replace(/\s+/g, " ").trim();
+  return raw.slice(0, 100);
+}
+
+export function resolveThreadBindingIntroText(params: {
+  agentId?: string;
+  label?: string;
+  sessionTtlMs?: number;
+  sessionCwd?: string;
+  sessionDetails?: string[];
+}): string {
+  const label = params.label?.trim();
+  const base = label || params.agentId?.trim() || "agent";
+  const normalized = base.replace(/\s+/g, " ").trim().slice(0, 100) || "agent";
+  const ttlMs = normalizeThreadBindingMessageTtlMs(params.sessionTtlMs);
+  const cwd = params.sessionCwd?.trim();
+  const details = (params.sessionDetails ?? [])
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  if (cwd) {
+    details.unshift(`cwd: ${cwd}`);
+  }
+  const intro =
+    ttlMs > 0
+      ? `${normalized} session active (auto-unfocus in ${formatThreadBindingTtlLabel(ttlMs)}). Messages here go directly to this session.`
+      : `${normalized} session active. Messages here go directly to this session.`;
+  if (details.length === 0) {
+    return prefixSystemMessage(intro);
+  }
+  return prefixSystemMessage(`${intro}\n${details.join("\n")}`);
+}
+
+export function resolveThreadBindingFarewellText(params: {
+  reason?: string;
+  farewellText?: string;
+  sessionTtlMs: number;
+}): string {
+  const custom = params.farewellText?.trim();
+  if (custom) {
+    return prefixSystemMessage(custom);
+  }
+  if (params.reason === "ttl-expired") {
+    return prefixSystemMessage(
+      `Session ended automatically after ${formatThreadBindingTtlLabel(params.sessionTtlMs)}. Messages here will no longer be routed.`,
+    );
+  }
+  return prefixSystemMessage(DEFAULT_THREAD_BINDING_FAREWELL_TEXT);
+}
--- a/src/channels/thread-bindings-policy.ts
+++ b/src/channels/thread-bindings-policy.ts
@@ -0,0 +1,168 @@
+import type { OpenClawConfig } from "../config/config.js";
+import { normalizeAccountId } from "../routing/session-key.js";
+
+export const DISCORD_THREAD_BINDING_CHANNEL = "discord";
+const DEFAULT_THREAD_BINDING_TTL_HOURS = 24;
+
+type SessionThreadBindingsConfigShape = {
+  enabled?: unknown;
+  ttlHours?: unknown;
+  spawnSubagentSessions?: unknown;
+  spawnAcpSessions?: unknown;
+};
+
+type ChannelThreadBindingsContainerShape = {
+  threadBindings?: SessionThreadBindingsConfigShape;
+  accounts?: Record<string, { threadBindings?: SessionThreadBindingsConfigShape } | undefined>;
+};
+
+export type ThreadBindingSpawnKind = "subagent" | "acp";
+
+export type ThreadBindingSpawnPolicy = {
+  channel: string;
+  accountId: string;
+  enabled: boolean;
+  spawnEnabled: boolean;
+};
+
+function normalizeChannelId(value: string | undefined | null): string {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase();
+}
+
+function normalizeBoolean(value: unknown): boolean | undefined {
+  if (typeof value !== "boolean") {
+    return undefined;
+  }
+  return value;
+}
+
+function normalizeThreadBindingTtlHours(raw: unknown): number | undefined {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return undefined;
+  }
+  if (raw < 0) {
+    return undefined;
+  }
+  return raw;
+}
+
+export function resolveThreadBindingSessionTtlMs(params: {
+  channelTtlHoursRaw: unknown;
+  sessionTtlHoursRaw: unknown;
+}): number {
+  const ttlHours =
+    normalizeThreadBindingTtlHours(params.channelTtlHoursRaw) ??
+    normalizeThreadBindingTtlHours(params.sessionTtlHoursRaw) ??
+    DEFAULT_THREAD_BINDING_TTL_HOURS;
+  return Math.floor(ttlHours * 60 * 60 * 1000);
+}
+
+export function resolveThreadBindingsEnabled(params: {
+  channelEnabledRaw: unknown;
+  sessionEnabledRaw: unknown;
+}): boolean {
+  return (
+    normalizeBoolean(params.channelEnabledRaw) ?? normalizeBoolean(params.sessionEnabledRaw) ?? true
+  );
+}
+
+function resolveChannelThreadBindings(params: {
+  cfg: OpenClawConfig;
+  channel: string;
+  accountId: string;
+}): {
+  root?: SessionThreadBindingsConfigShape;
+  account?: SessionThreadBindingsConfigShape;
+} {
+  const channels = params.cfg.channels as Record<string, unknown> | undefined;
+  const channelConfig = channels?.[params.channel] as
+    | ChannelThreadBindingsContainerShape
+    | undefined;
+  const accountConfig = channelConfig?.accounts?.[params.accountId];
+  return {
+    root: channelConfig?.threadBindings,
+    account: accountConfig?.threadBindings,
+  };
+}
+
+function resolveSpawnFlagKey(
+  kind: ThreadBindingSpawnKind,
+): "spawnSubagentSessions" | "spawnAcpSessions" {
+  return kind === "subagent" ? "spawnSubagentSessions" : "spawnAcpSessions";
+}
+
+export function resolveThreadBindingSpawnPolicy(params: {
+  cfg: OpenClawConfig;
+  channel: string;
+  accountId?: string;
+  kind: ThreadBindingSpawnKind;
+}): ThreadBindingSpawnPolicy {
+  const channel = normalizeChannelId(params.channel);
+  const accountId = normalizeAccountId(params.accountId);
+  const { root, account } = resolveChannelThreadBindings({
+    cfg: params.cfg,
+    channel,
+    accountId,
+  });
+  const enabled =
+    normalizeBoolean(account?.enabled) ??
+    normalizeBoolean(root?.enabled) ??
+    normalizeBoolean(params.cfg.session?.threadBindings?.enabled) ??
+    true;
+  const spawnFlagKey = resolveSpawnFlagKey(params.kind);
+  const spawnEnabledRaw =
+    normalizeBoolean(account?.[spawnFlagKey]) ?? normalizeBoolean(root?.[spawnFlagKey]);
+  // Non-Discord channels currently have no dedicated spawn gate config keys.
+  const spawnEnabled = spawnEnabledRaw ?? channel !== DISCORD_THREAD_BINDING_CHANNEL;
+  return {
+    channel,
+    accountId,
+    enabled,
+    spawnEnabled,
+  };
+}
+
+export function resolveThreadBindingSessionTtlMsForChannel(params: {
+  cfg: OpenClawConfig;
+  channel: string;
+  accountId?: string;
+}): number {
+  const channel = normalizeChannelId(params.channel);
+  const accountId = normalizeAccountId(params.accountId);
+  const { root, account } = resolveChannelThreadBindings({
+    cfg: params.cfg,
+    channel,
+    accountId,
+  });
+  return resolveThreadBindingSessionTtlMs({
+    channelTtlHoursRaw: account?.ttlHours ?? root?.ttlHours,
+    sessionTtlHoursRaw: params.cfg.session?.threadBindings?.ttlHours,
+  });
+}
+
+export function formatThreadBindingDisabledError(params: {
+  channel: string;
+  accountId: string;
+  kind: ThreadBindingSpawnKind;
+}): string {
+  if (params.channel === DISCORD_THREAD_BINDING_CHANNEL) {
+    return "Discord thread bindings are disabled (set channels.discord.threadBindings.enabled=true to override for this account, or session.threadBindings.enabled=true globally).";
+  }
+  return `Thread bindings are disabled for ${params.channel} (set session.threadBindings.enabled=true to enable).`;
+}
+
+export function formatThreadBindingSpawnDisabledError(params: {
+  channel: string;
+  accountId: string;
+  kind: ThreadBindingSpawnKind;
+}): string {
+  if (params.channel === DISCORD_THREAD_BINDING_CHANNEL && params.kind === "acp") {
+    return "Discord thread-bound ACP spawns are disabled for this account (set channels.discord.threadBindings.spawnAcpSessions=true to enable).";
+  }
+  if (params.channel === DISCORD_THREAD_BINDING_CHANNEL && params.kind === "subagent") {
+    return "Discord thread-bound subagent spawns are disabled for this account (set channels.discord.threadBindings.spawnSubagentSessions=true to enable).";
+  }
+  return `Thread-bound ${params.kind} spawns are disabled for ${params.channel}.`;
+}