@edugate/builder-core

Le utility condivise della tela del builder di Edugate: il contratto zod delle operazioni, la fabbrica di JSON-schema per il tool-calling, il rilevamento dei conflitti, la risoluzione delle @-menzioni — e l'esecutore puro che applica un'operazione a un'attività.

⚠️ Era @edugate/ai-agent, che resta su npm fermo alla 0.7.0 ed è deprecato. Le API non sono cambiate: cambia solo lo specificatore di import. Il vecchio nome descriveva ciò che il pacchetto non è più — l'orchestrazione multi-agente è uscita da qui tempo fa, e ciò che resta è la tela.

applyCanvasOp — l'operazione senza browser

import { applyCanvasOp } from "@edugate/builder-core";

const { activity, applied, skipped, reason } = applyCanvasOp(attività, {
  action: "addBlock",
  data: { /* … */ },
});

Finora esisteva un solo posto capace di eseguire un'operazione della tela: 345 righe legate allo store Zustand della web-app. Quindi senza un browser aperto l'operazione di un modello non poteva succedere — poteva solo essere validata. Questa funzione è pura: attività dentro, attività fuori, nessuno stato. È il pezzo che rende il builder usabile da un host MCP.

Diciotto operazioni si applicano (APPLIED_CANVAS_OPS); quattro sono dichiarate non applicabili qui (UNAPPLIED_CANVAS_OPS — setScript, addHandler, removeHandler, updateHandler). L'elenco è esplicito di proposito: un'operazione sconosciuta torna applied: false con un reason, e mai un silenzio che somiglia a un successo.

generateScriptReference — il vocabolario degli script, da mettere in un prompt

import { generateScriptReference } from "@edugate/builder-core";

const ref = generateScriptReference();                        // 22KB, con la prosa
const menu = generateScriptReference({ descriptions: false }); // 7KB, solo i nomi
const soloEffetti = generateScriptReference({
  categories: ["effect"],
  preamble: false,
});

generateBlockReference insegna i blocchi. Degli script diceva, alla lettera:

- `effects` (array<object | object | object | object | …>, optional)

perché zod-to-json-schema rende un'unione discriminata come una fila di oggetti anonimi — e in modalità contentOnly, quella che la sua stessa documentazione consiglia ai prompt, il campo scripts non c'è affatto: sta in BASE_BLOCK_FIELDS. Quindi un agente esterno che teneva questo pacchetto non poteva sapere che esistono rotate, forward, warp, flipVelocity, la trigonometria o la penna — e non solo quelli nuovi: non poteva sapere che esiste un qualsiasi kind di effetto.

Il catalogo leggibile a macchina (SCRIPT_KIND_CATALOG, o getScriptKindCatalog()) è sempre stato completo e sorvegliato da un test di deriva. Mancava qualcosa che lo rendesse iniettabile: un catalogo che nessuno rende non insegna a nessuno. Questa funzione lo rende, col preambolo che il catalogo non può dire — cos'è una busta handler, come si scrive un Value, che un target omesso significa «questo blocco».

Un test verifica che ogni kind e ogni campo del catalogo finiscano nel testo, quindi un kind aggiunto allo schema senza voce di catalogo fa cadere il test di deriva, e uno che questo renderer salta fa cadere l'altro.

Gira anche nel browser

Questo pacchetto è consumato dalla web-app, quindi non importa node:crypto né nient'altro che esista solo su Node: gli id nuovi passano da crypto.randomUUID quando c'è e da un ripiego quando non c'è.

Cosa NON fa

Non conosce Edugate. Non legge, non scrive, non autentica. Chi vuole aprire un'attività, applicare e risalvare con guardia ottimistica usa i tre tool builder_* di @edugate/authoring/builder, che montano queste funzioni sopra le porte dell'host.