# Refactoring del Plugin Canvas

Canvas è poco usato e sperimentale. Trattalo come un Plugin in bundle, non come una funzionalità core. Il core può mantenere l’impianto generico di Gateway, Node, HTTP, auth, config e client nativo, ma il comportamento specifico di Canvas dovrebbe vivere sotto extensions/canvas.

# Obiettivo

Spostare la proprietà di Canvas in extensions/canvas preservando l’attuale comportamento del nodo abbinato:

• lo strumento canvas rivolto all’agente è registrato dal Plugin Canvas
• i comandi del nodo Canvas sono consentiti solo quando il Plugin Canvas li registra
• i file host/source A2UI vivono sotto il Plugin Canvas
• la materializzazione dei documenti Canvas vive sotto il Plugin Canvas
• l’implementazione del comando CLI vive sotto il Plugin Canvas, oppure delega tramite un barrel runtime di proprietà del Plugin
• la documentazione e l’inventario dei Plugin descrivono Canvas come sperimentale e supportato da Plugin

# Non obiettivi

• Non riprogettare l’interfaccia utente Canvas dell’app nativa in questo refactoring.
• Non rimuovere il supporto protocollo/client Canvas da iOS, Android o macOS a meno che una decisione di prodotto separata dica che Canvas deve essere eliminato.
• Non costruire un ampio framework di servizi Plugin solo per Canvas, a meno che almeno un altro Plugin in bundle non abbia bisogno della stessa cucitura.

# Stato attuale del branch

Fatto:

• Aggiunto il pacchetto Plugin in bundle in extensions/canvas.
• Aggiunto extensions/canvas/openclaw.plugin.json.
• Spostato lo strumento agente canvas da src/agents/tools/canvas-tool.ts a extensions/canvas/src/tool.ts.
• Rimossa la registrazione core di createCanvasTool da src/agents/openclaw-tools.ts.
• Spostata l’implementazione dell’host Canvas da src/canvas-host a extensions/canvas/src/host.
• Mantenuto extensions/canvas/runtime-api.ts come barrel di compatibilità di proprietà del Plugin per test, packaging e helper Canvas pubblici esterni.
• Spostata la materializzazione dei documenti Canvas da src/gateway/canvas-documents.ts a extensions/canvas/src/documents.ts.
• Spostata l’implementazione CLI Canvas e gli helper JSONL A2UI in extensions/canvas/src/cli.ts.
• Spostati l’URL host Canvas e gli helper di capability con ambito in extensions/canvas/src.
• Spostati i default dei comandi nodo Canvas fuori dagli elenchi core hardcoded e dentro nodeInvokePolicies del Plugin.
• Aggiunta la configurazione host Canvas di proprietà del Plugin in plugins.entries.canvas.config.host.
• Spostato il serving HTTP di Canvas e A2UI dietro la registrazione delle route HTTP del Plugin Canvas.
• Aggiunto dispatch generico dell’upgrade WebSocket dei Plugin per route HTTP di proprietà dei Plugin.
• Sostituiti l’URL host Gateway specifico di Canvas e l’autorizzazione capability del nodo con una superficie Plugin ospitata generica e helper capability del nodo.
• Aggiunti resolver dei media ospitati di proprietà del Plugin, così gli URL dei documenti Canvas si risolvono tramite il Plugin Canvas invece che tramite import core degli internals dei documenti Canvas.
• Aggiunto api.registerNodeCliFeature(...) così Canvas può dichiarare openclaw nodes canvas come funzionalità nodo di proprietà del Plugin senza scrivere manualmente il percorso del comando padre.
• Rimossi gli import di produzione src/** di extensions/canvas/runtime-api.js.
• Spostato il sorgente del bundle A2UI da apps/shared/OpenClawKit/Tools/CanvasA2UI a extensions/canvas/src/host/a2ui-app.
• Spostata l’implementazione build/copy A2UI sotto extensions/canvas/scripts e sostituito il wiring di build root con hook asset generici dei Plugin in bundle.
• Rimosso l’alias runtime legacy di configurazione top-level canvasHost.
• Mantenuta la migrazione doctor di Canvas così openclaw doctor --fix riscrive le vecchie configurazioni canvasHost in plugins.entries.canvas.config.host.
• Rimossa la compatibilità del protocollo Canvas per vecchi agenti dietro Gateway protocol v4. I client nativi e i Gateway ora usano solo pluginSurfaceUrls.canvas più node.pluginSurface.refresh; il percorso deprecato canvasHostUrl, canvasCapability e node.canvas.capability.refresh è intenzionalmente non supportato in questo refactoring sperimentale.
• Aggiornato l’inventario dei Plugin generato per includere Canvas.
• Aggiunta la documentazione di riferimento del Plugin in docs/plugins/reference/canvas.md.

Superfici Canvas note che restano di proprietà core:

• gli handler Canvas dell’app nativa sotto apps/ consumano ancora intenzionalmente la superficie del Plugin Canvas
• gli handler protocollo/client Canvas dell’app nativa sotto apps/
• l’output degli artefatti pubblicati usa ancora dist/canvas-host/a2ui per lookup runtime compatibile all’indietro, ma lo step di copia ora è di proprietà del Plugin

# Forma target

extensions/canvas dovrebbe possedere:

• manifest del Plugin e metadati del pacchetto
• registrazione dello strumento agente
• policy dei comandi invoke del nodo
• host Canvas e runtime A2UI
• sorgente del bundle Canvas A2UI e script di build/copy degli asset
• creazione dei documenti Canvas e risoluzione degli asset
• implementazione CLI Canvas
• pagina docs Canvas e voce dell’inventario Plugin

Il core dovrebbe possedere solo cuciture generiche:

• scoperta e registrazione dei Plugin
• registro generico degli strumenti agente
• registro generico delle policy invoke del nodo
• dispatch generico di HTTP/auth e upgrade WebSocket del Gateway
• risoluzione generica degli URL delle superfici Plugin ospitate
• registrazione generica dei resolver dei media ospitati
• trasporto generico delle capability del nodo
• impianto generico di configurazione
• scoperta generica degli hook asset dei Plugin in bundle

Le app native possono mantenere gli handler dei comandi Canvas come client del protocollo. Non sono proprietarie del runtime del Plugin.

# Passaggi di migrazione

1. Tratta plugins.entries.canvas.config.host come superficie di configurazione di proprietà del Plugin.
2. Aggiorna la documentazione così Canvas è descritto come Plugin sperimentale in bundle.
3. Esegui test Canvas mirati, controlli dell’inventario Plugin, controlli API del Plugin SDK e gate di build/tipi influenzati dai confini runtime.

# Checklist di audit

Prima di considerare completo il refactoring:

• rg "src/canvas-host|../canvas-host" non restituisce import sorgente live.
• rg "canvas-tool|createCanvasTool" src non trova implementazioni dello strumento Canvas di proprietà core.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway non trova default allowlist hardcoded fuori dai test generici delle policy Plugin.
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' è vuoto.
• rg "canvas-documents" src è vuoto.
• rg "registerNodesCanvasCommands|nodes-canvas" src è vuoto; il Plugin Canvas registra openclaw nodes canvas tramite metadati CLI Plugin annidati.
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway non restituisce proprietà runtime del Gateway.
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json trova solo wrapper di compatibilità o percorsi di proprietà del Plugin.
• pnpm plugins:inventory:check passa.
• pnpm plugin-sdk:api:check passa, oppure le baseline API generate sono aggiornate e revisionate intenzionalmente.
• I test Canvas mirati passano.
• I test delle changed-lanes passano per i percorsi host/A2UI Canvas.
• Il corpo della PR dice esplicitamente che Canvas è sperimentale e supportato da Plugin.

# Comandi di verifica

Usa controlli locali mirati durante l’iterazione:

pnpm test extensions/canvas/src/host/server.test.ts extensions/canvas/src/host/server.state-dir.test.ts extensions/canvas/src/host/file-resolver.test.ts
pnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.ts
pnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.ts
pnpm test test/scripts/changed-lanes.test.ts test/scripts/build-all.test.ts extensions/canvas/scripts/bundle-a2ui.test.ts test/scripts/bundled-plugin-assets.test.ts extensions/canvas/scripts/copy-a2ui.test.ts src/infra/run-node.test.ts
pnpm tsgo:extensions
pnpm plugins:inventory:check
pnpm plugin-sdk:api:check

Esegui pnpm build prima del push se cambiano il barrel runtime, import lazy, packaging o superfici Plugin pubblicate.