mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-08 20:28:29 +00:00
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)
This commit is contained in:
Onur Solmaz
@@ -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) {
|
||||
|
||||
Reference in New Issue
Block a user