Pont ACP

Vue d’ensemble

packages/acp-bridge/ gère la frontière entre la couche HTTP du démon et le processus enfant ACP. Il est consommé par packages/cli/src/serve/ (le démon qwen serve) et a été extrait dans #4175 F1 étape 3 afin que de futurs consommateurs (channels/base/AcpBridge.ts, le compagnon IDE VS Code) puissent utiliser le même cœur de pont sans dépendre du package CLI.

Le pont fournit une instance HttpAcpBridge, un AcpChannel vers l’enfant ACP, des sessions multiplexées sur ce canal, des EventBus par session, un MultiClientPermissionMediator, un adaptateur BridgeFileSystem, et des assistants orientés ACP (spawnOrAttach, loadSession, resumeSession, sendPrompt, cancelSession, respondToPermission, plus des RPC extMethod pour le statut de l’espace de travail et le redémarrage MCP).

Responsabilités

• Lancer ou attacher l’enfant ACP via une ChannelFactory enfichable. Fabrique par défaut : defaultSpawnChannelFactory (sous-processus qwen --acp). Les tests injectent inMemoryChannel.
• Maintenir aliveChannels (registre des canaux) et byId (registre des sessions).
• Multiplexer N sessions côté HTTP sur un seul enfant ACP via connection.newSession().
• Sérialiser les invites par session via promptQueue (ACP impose une invite active par session).
• FIFO par session pour les appels setSessionModel afin que les attachements concurrents avec différents modèles ne provoquent pas de course avec l’agent.
• EventBus par session qui pilote GET /session/:id/events (voir 10-event-bus.md).
• Flux d’autorisation : BridgeClient.requestPermission → MultiClientPermissionMediator.request → diffusion → collecte des votes → réponse ACP (voir 04-permission-mediation.md).
• E/S de fichiers : adaptateur BridgeFileSystem pour les appels ACP readTextFile / writeTextFile (voir 07-workspace-filesystem.md).
• RPC extMethod pour le statut au niveau de l’espace de travail (/workspace/mcp, /workspace/skills, /workspace/providers) et redémarrage MCP.
• Cycle de vie : shutdown() gracieux avec KILL_HARD_DEADLINE_MS (10s) par canal ; killAllSync() synchrone pour la sortie forcée au second signal.

Architecture

Point d’entrée public : createHttpAcpBridge(opts: BridgeOptions): HttpAcpBridge dans packages/acp-bridge/src/bridge.ts.

Types clés :

Invariant isDying : tout chemin de démontage doit positionner ChannelInfo.isDying = true de manière synchrone avant d’attendre channel.kill(). ensureChannel traite un canal en état de « dying » comme absent et en crée un nouveau. Sans ce flag, un spawnOrAttach concurrent arrivant pendant la fenêtre de grâce SIGTERM (jusqu’à 10s) s’attacherait à un transport sur le point de se fermer, et le sessionId de l’appelant répondrait en 404 à chaque requête suivante. Points d’affectation (doivent rester synchronisés) : ensureChannel (échec d’initialisation + re-vérification lors d’un arrêt tardif), doSpawn (échec de newSession sur canal vide), killSession (dernière session quittant), shutdown (en masse).

Invariant de rétention de channelInfo : ne pas effacer channelInfo lorsqu’on positionne isDying = true. killAllSync doit encore trouver le canal pendant la fenêtre de grâce SIGTERM pour envoyer SIGKILL sur process.exit(1). aliveChannels conserve l’entrée « dying » jusqu’à ce que channel.exited se déclenche.

Tamponnement limité du BridgeClient : Les trames ACP extNotification arrivant sur BridgeClient pour un sessionId pas encore présent dans byId (parce que la réponse de connection.newSession n’est pas encore revenue, mais la découverte MCP à l’intérieur de newSession a déjà émis des événements de budget) sont mises en file d’attente dans une queue d’événements précoces limitée par MAX_EARLY_EVENT_SESSIONS = 64 × MAX_EARLY_EVENTS_PER_SESSION = 32 × EARLY_EVENT_TTL_MS = 60_000. Le pire cas représente environ 400 Ko de tas. Sans tamponnement, le premier emplacement du ring SSE pour une nouvelle session manquerait les événements émis pendant sa création.

Workflow

spawnOrAttach (point d’entrée principal)

Points clés :

• sessionScope='single' avec un defaultEntry existant ne fait qu’incrémenter attachCount, enregistrer clientId, et retourner attached: true.
• Le chemin froid exécute ChannelFactory, effectue l’initialisation ACP (DEFAULT_INIT_TIMEOUT_MS=10s), appelle connection.newSession({cwd}), puis enregistre la nouvelle SessionEntry.
• SessionLimitExceededError est levée lorsque byId.size >= maxSessions.
• InvalidClientIdError est levée si X-Qwen-Client-Id n’est pas dans l’intervalle [A-Za-z0-9._:-]{1,128}.
• Le « disconnect-reaper » dans server.ts suit le propriétaire du spawn via attachCount/spawnOwnerWantedKill pour éviter de démonter une session dont le propriétaire du spawn s’est déconnecté mais où d’autres clients sont déjà attachés (revue #3889 BQ9tV).

Sérialisation des prompts

Les échecs en queue de file sont avalés afin que le rejet d’une requête précédente n’empoisonne pas les requêtes suivantes ; l’appelant original reçoit toujours le rejet sur sa propre promesse retournée. Le transportClosedReject mis en cache sur la session met en concurrence la promesse de la requête avec channel.exited de sorte qu’un enfant planté se manifeste immédiatement plutôt que de bloquer.

Flux de permissions (vue d’ensemble)

InvalidPermissionOptionError est levée avant le médiateur lorsqu’un vote filaire tente d’injecter CANCEL_VOTE_SENTINEL via le champ normal optionId — le sentinelle est la seule échappatoire du pont pour court-circuiter une requête en cancelled / agent_cancelled et ne doit pas être accessible depuis le filaire par accident. Voir 04-permission-mediation.md.

Arrêt

Channel factory

AcpChannel (channel.ts) est l’abstraction de transport du pont. En production, defaultSpawnChannelFactory dans spawnChannel.ts est utilisée, qui exécute qwen --acp comme un sous-processus avec une paire de pipes stdio. Les tests injectent inMemoryChannel pour exécuter l’agent en processus. Le pont ne connaît rien du mécanisme sous-jacent — il a seulement besoin de { stream, kill, killSync, exited }.

ChannelFactory accepte childEnvOverrides afin que chaque poignée de démon puisse passer ses propres variables d’environnement de budget MCP (QWEN_SERVE_MCP_CLIENT_BUDGET, QWEN_SERVE_MCP_BUDGET_MODE) sans modifier process.env (ce qui créerait une course lorsque deux démons embarqués s’exécutent dans le même processus Node).

État & Cycle de vie

• La construction du pont est synchrone ; le premier spawnOrAttach démarre à froid l’enfant ACP.
• defaultEntry vit pendant toute la durée de vie du pont sous sessionScope: 'single' ; le canal se rétracte lorsque sessionIds.size === 0 (après killSession) ET isDying passe à vrai.
• MAX_EVENT_RING_SIZE = 1_000_000 est une limite supérieure souple pour BridgeOptions.eventRingSize afin de détecter les fautes de frappe de l’opérateur avant un OOM d’environ 500 Mo par session.
• DEFAULT_PERMISSION_TIMEOUT_MS = 5 * 60 * 1000 empêche une demande d’autorisation bloquée de bloquer indéfiniment la promptQueue par session.
• DEFAULT_MAX_PENDING_PER_SESSION = 64 correspond à DEFAULT_MAX_SUBSCRIBERS ; les appels requestPermission en excès sont résolus comme annulés avec un avertissement sur stderr.

Dépendances

Configuration

BridgeOptions (bridgeOptions.ts) :

Méthodes supplémentaires du bridge

En plus des appels centraux spawnOrAttach, sendPrompt, cancelSession, respondToPermission, loadSession et resumeSession, l’interface HttpAcpBridge inclut désormais ces assistants orientés démon :

BridgeSpawnRequest.sessionScope a été renommé de 'per-client' à 'thread'. BridgeRestoredSession transporte désormais compactedReplay, liveJournal et lastEventId. BridgeClientRequestContext est le contexte de requête transmis à travers les appels du bridge ; il porte clientId, fromLoopback: boolean et promptId.

Limitations et mises en garde connues

• MCP_RESTART_TIMEOUT_MS = 300_000 (5 min) — le délai d’attente du bridge pour /workspace/mcp/:server/restart est intentionnellement grand car McpClientManager.MAX_DISCOVERY_TIMEOUT_MS peut atteindre 5 min pour les serveurs stdio. Une échéance plus courte produirait de faux délais d’attente pendant que le processus ACP enfant continue de se reconnecter en arrière-plan.
• BridgeOptions.eventRingSize > 1_000_000 lève une exception à la construction.
• connection.unstable_resumeSession est exposé via la capacité stable du démon session_resume ; unstable_session_resume reste annoncé comme un alias de compatibilité déprécié pour les anciens SDK. Les clients doivent détecter la présence de session_resume.
• Le paquet bridge est @qwen-code/acp-bridge et est consommé via des shims de ré-export dans serve/event-bus.ts, serve/status.ts, serve/httpAcpBridge.ts pour la rétrocompatibilité avec les chemins d’importation pré-F1. Le nouveau code doit importer directement.

Références

• packages/acp-bridge/src/bridge.ts (notamment createHttpAcpBridge à la ligne 350+)
• packages/acp-bridge/src/bridgeClient.ts
• packages/acp-bridge/src/bridgeTypes.ts
• packages/acp-bridge/src/bridgeOptions.ts
• packages/acp-bridge/src/channel.ts
• packages/acp-bridge/src/spawnChannel.ts
• packages/acp-bridge/src/bridgeErrors.ts
• Issues : #3803 , #4175 .