@llmnative/agentico 0.1.0

package/dist/types/i18n/types.d.ts

@@ -0,0 +1,55 @@
+export interface AgenticoDict {
+    modelLabel: string;
+    modelsLoading: string;
+    noModelsAvailable: string;
+    noProviderConnected: string;
+    selectModelPlaceholder: string;
+    orchestratorStarterHint: string;
+    orchestratorStarterPlaceholder: string;
+    destinationPickerTitle: string;
+    destinationApplying: string;
+    destinationNoScope: string;
+    exportJson: string;
+    /** `{id}` = destination id */
+    unknownDestination: string;
+    orchestratorUnavailable: string;
+    orchestratorContinueWithoutAi: string;
+    /** `{label}` = subagent label */
+    orchestratorPreparing: string;
+    /** `{label}` = subagent label */
+    orchestratorCollecting: string;
+    thinking: string;
+    stopped: string;
+    toolRequest: string;
+    modelRequestError: string;
+    noProviderResponse: string;
+    noActiveSession: string;
+    requestInProgress: string;
+    invalidResponse: string;
+    responseReceived: string;
+    noProviderAvailable: string;
+    tooManyToolTurns: string;
+    aiDisabledFallback: string;
+    continueWithoutAiFallback: string;
+    /** `{label}` = subagent label */
+    newInstance: string;
+    chatHistory: string;
+    newChat: string;
+    searchChats: string;
+    messagePlaceholder: string;
+    unsavedConversationConfirm: string;
+    noSavedChats: string;
+    noResults: string;
+    retry: string;
+    /** User message sent to the model by the retry button */
+    retryMessage: string;
+    continueWithoutAi: string;
+    resumeWithAi: string;
+    openPanel: string;
+    closePanel: string;
+}
+declare module '@llmnative/react' {
+    interface I18nDict {
+        agentico: AgenticoDict;
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,25 @@
+import './i18n/types';
+export type { AgentDefinition, AgentTool, LatestAttachmentsRef } from './domain/agentDefinition';
+export type { SubagentCommand, SubagentManifest, SubagentComponentContext } from './domain/subagentManifest';
+export { defineSubagent } from './domain/defineSubagent';
+export { registerSubagents, getSubagentRegistry, findSubagentManifest } from './domain/subagentRegistry';
+export { registerCrossAgentTools, createCrossAgentTools, type CrossAgentToolContext, type CrossAgentToolFactory } from './domain/crossAgentTools';
+export { toJsonSchema, toMcpTool, type McpTool } from './domain/mcpTool';
+export { renderSubagentCli, renderRegistryCli } from './domain/cli/renderManifestCli';
+export { applyMicroPrompts, MICRO_PROMPT_REGISTRY, SUMMARY_MICRO_PROMPT } from './domain/microPrompts';
+export type { MicroPrompt } from './domain/microPrompts';
+export { configureAgenticoPrompts, getAgenticoPrompts, resetAgenticoPrompts, agenticoPromptsEn, agenticoPromptsIt, type AgenticoPrompts, } from './domain/prompts';
+export { extractErrorMessage } from './domain/extractErrorMessage';
+export { extractJsonBlock } from './domain/extractJsonBlock';
+export type { ResultDestination, DestinationContext, ResultDestinationOutcome } from './domain/resultDestination';
+export { jsonExportDestination, JSON_EXPORT_DESTINATION_ID } from './domain/jsonExportDestination';
+export { registerDestinations, getDestinationRegistry } from './domain/destinationRegistry';
+export { configureEntityChatStore, saveEntityChat, getEntityChat, listEntityChats, removeEntityChat, type EntityChatSnapshot, } from './domain/entityChatStore';
+export { agenticoTranslations, agenticoEn, agenticoIt, agenticoDe, useAgenticoI18n, type AgenticoDict } from './i18n';
+export { Agentico, AGENTICO_WIDTH } from './presentation/Agentico';
+export { AgenticoToggle } from './presentation/AgenticoToggle';
+export { AgenticoProvider, useAgentico, ORCHESTRATOR_TASK_ID, type AgenticoScope, type AgenticoTask, type ComponentAnchor, } from './presentation/AgenticoContext';
+export { useAgent, type AgentActivityEntry, type AgentConversation, type UseAgentResult } from './presentation/useAgent';
+export { useAgenticoPageContext } from './presentation/useAgenticoPageContext';
+export { useSubagentComponentContext } from './presentation/useSubagentComponentContext';
+export { registerSubagentReports, getSubagentReport, type EditableReportModule, type SubagentReportModule, type SubagentSelection, } from './presentation/reports/subagentReportRegistry';

package/dist/types/presentation/AgentActivityLog.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import type { AgentActivityEntry } from './useAgent';
+/** Il log di attività di un agente, usato dal pannello globale (Agentico) — ogni agente ora
+ * ci passa attraverso, il pannello embedded legacy (AgentFollowUp) è stato ritirato una volta
+ * migrato anche l'ultimo consumer (import HTML/JSX, vedi ComponentEditPage.tsx). Un solo posto
+ * per l'icon-system e la logica "sto pensando" transitorio/collassabile. */
+export declare function AgentActivityLog({ activity }: {
+    activity: AgentActivityEntry[];
+}): React.JSX.Element | null;

package/dist/types/presentation/AgentControls.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import type { AgentControlState } from './useAgent';
+/** Switch + select modello per un agente useAgent — nato per evitare una duplicazione identica
+ * tra due modali di import legacy (tema in SiteEditorPage, HTML/JSX in ComponentEditPage),
+ * entrambe da allora ritirate in favore del flusso chat-only via Agentico (SubagentRunner,
+ * sempre AI-on, nessuno switch pre-run) — vedi il piano di unificazione. Nessun chiamante
+ * attuale nel CMS, tenuto come primitiva riusabile se un futuro flusso avesse di nuovo bisogno
+ * di uno switch AI on/off + selezione modello prima di eseguire. Accetta `AgentControlState`
+ * (non `UseAgentResult<T>` intero): non ha
+ * bisogno di conoscere il tipo di risposta del chiamante, solo lo stato di gating/selezione —
+ * TypeScript accetta struttalmente un `UseAgentResult<T>` qui senza cast.
+ *
+ * Switch a sinistra (non a destra come una prima versione, che schiacciava label/hint in una
+ * colonna stretta quando il testo "nessun provider" — non troncabile per `shrink-0` — occupava
+ * quasi tutta la larghezza): `min-w-0`+`truncate` qui tengono il testo su una riga sola, con
+ * `title` per il testo completo al passaggio del mouse se troncato. */
+export declare function AgentControls({ agent, label, hint, disabledHint, forceSwitchDisabled, }: {
+    agent: AgentControlState;
+    label: string;
+    hint?: string;
+    disabledHint?: string;
+    /** Blocca lo switch acceso senza possibilità di spegnerlo (es. JSX che richiede AI
+     * obbligatoriamente) — il chiamante resta comunque responsabile di forzare
+     * `agent.setEnabled(true)`, questo prop riguarda solo l'interazione dello switch. */
+    forceSwitchDisabled?: boolean;
+}): React.JSX.Element;

package/dist/types/presentation/Agentico.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+/** Larghezza fissa del pannello — passata anche come `rightInset` alle Modal che devono
+ * lasciargli spazio invece di sovrapporlo (vedi Modal.rightInset nel framework). */
+export declare const AGENTICO_WIDTH = 420;
+/** Agentico — il pannello globale, persistente e non-overlay per le sessioni agente — affianca
+ * il CMS (che si stringe) invece di coprirlo, cosi la modale che ha avviato l'agente resta
+ * aperta e utilizzabile accanto. Header: titolo dell'UNICO task attivo (mai una tab bar — "una
+ * chat unica", decisione esplicita: avviarne uno nuovo sostituisce quello in corso, vedi
+ * AgenticoContext.openTask) — NESSUNA ×: si apre/chiude solo con AgenticoToggle (nell'Header del
+ * CMS, o come `closeSlot` di una Modal right), la stessa icona ovunque, mai una propria qui.
+ * Body: lo stesso log di attività del pannello embedded (AgentActivityLog), o un placeholder
+ * neutro se non c'è ancora nessun task — il pannello può restare aperto vuoto, non sparisce da
+ * solo quando il task finisce. Footer: il composer di follow-up (vedi AgenticoComposer sopra),
+ * nascosto quando non c'è un task attivo.
+ *
+ * Solo la sessione aperta in questa sessione browser (registry in memoria via AgenticoContext)
+ * — nessuna persistenza cross-sessione (Fase 3, deferita).
+ *
+ * Nota sul naming: "Agentico" è il nome dell'orchestratore — questo pannello, il suo contesto
+ * (AgenticoContext), il suo toggle (AgenticoToggle) — non degli agenti verticali che esegue
+ * (theme-import, html-to-liquid, ...), che restano nel proprio dominio senza questo
+ * prefisso: sono contenuto che Agentico orchestra, non parte della sua identità. */
+export declare function Agentico(): React.JSX.Element;

package/dist/types/presentation/AgenticoContext.d.ts

@@ -0,0 +1,305 @@
+import React from 'react';
+import type { AIModelDescriptor, DataProviderAdapter, StorageProviderAdapter } from '@llmnative/react';
+import type { AgentActivityEntry, AgentConversation } from './useAgent';
+import type { ResultDestination } from '../domain/resultDestination';
+import type { SubagentUsageCard } from '../domain/subagentUsageCard';
+import { type EntityChatSnapshot } from '../domain/entityChatStore';
+/** Where results are saved and chats are kept: the host's current tenant, company, workspace…
+ * `null` while the host has none selected — destinations then refuse to save. */
+export interface AgenticoScope {
+    id: string;
+    dataProvider: DataProviderAdapter;
+    storageProvider: StorageProviderAdapter | null;
+}
+/** Cattura la conversazione di un task subagent già esistente da "continuare" invece di forkare
+ * — vedi startOrchestrator sotto. `taskId` viene riusato dal nuovo SubagentRunner (invece di un
+ * uuid fresco) cosi il task esistente si aggiorna in place; `activity` (precedingActivity +
+ * agent.activity del vecchio task, già concatenati) viene prepesa al transcript del nuovo giro —
+ * l'utente legge tutto come UNA chat continua, mai due sessioni scollegate per lo stesso
+ * subagent. */
+export interface PendingCarryOver {
+    taskId: string;
+    activity: AgentActivityEntry[];
+}
+/** Id fisso del task dell'orchestratore Agentico — al massimo UNA conversazione orchestratore
+ * per volta, come per qualunque altro task (vedi AgenticoTask sotto: un solo task alla volta in
+ * tutta l'app, mai una tab bar da switchare). Un id fisso permette a startOrchestrator() di
+ * riconoscere "ce n'è già uno aperto" senza dover tenere un riferimento separato. */
+export declare const ORCHESTRATOR_TASK_ID = "agentico-orchestrator";
+/** Una sessione agente aperta nel pannello globale — riferimento vivo all'oggetto restituito
+ * da useAgent() nel componente che l'ha avviata (NON una copia: quel componente deve restare
+ * montato perché questo riferimento resti valido, vedi Agentico.tsx). Solo le sessioni aperte in
+ * questa sessione browser — nessuna persistenza su Firestore (Fase 3, deferita).
+ *
+ * Al massimo UN task alla volta in tutta l'app (decisione esplicita: "una chat unica", niente
+ * tab multiple per run paralleli) — avviarne uno nuovo mentre un altro è in corso lo sostituisce
+ * (vedi openTask sotto), mai lo affianca. */
+export interface AgenticoTask<TResult = unknown> {
+    id: string;
+    /** Titolo mostrato nell'header del pannello — es. l'URL importato, il nome del componente. */
+    title: string;
+    /** Nome icona (@llmnative/react Icon) mostrata nell'header — 'bot' per l'orchestratore
+     * (OrchestratorRunner, stessa identità di AgenticoToggle), manifest.icon per un subagent
+     * (SubagentRunner). */
+    icon: string;
+    /** SOLO sul task dell'orchestratore — id del subagent verso cui la pagina/componente che ha
+     * avviato questa conversazione era scoped (catturato da OrchestratorRunner al mount, da
+     * sidebar.scopedSubagentId). Permette a un indice come redirects/IndexList.tsx di mostrare
+     * "in corso" per QUESTO subagent anche prima dell'handoff (mentre l'orchestratore sta ancora
+     * raccogliendo parametri/chiamando tool di raccolta dati). Assente sui task dei subagent
+     * stessi (quelli sono già inequivocabilmente scoped dal proprio id
+     * `subagent-${subagentId}-...`). */
+    scopedSubagentId?: string;
+    /** Presente SOLO dopo un commitEntityChat riuscito su questo task — questa conversazione è
+     * genuinamente su disco (vedi entityChatStore), non solo in memoria. Usato dal bottone
+     * "nuova chat" (vedi Agentico.tsx) per decidere se avvertire l'utente prima di scartarla:
+     * senza salvataggio andrebbe persa per sempre (nessun "torna indietro", scelta esplicita). */
+    savedToDisk?: boolean;
+    agent: AgentConversation<TResult> & {
+        hasProviders: boolean;
+        selectedModel: string;
+        setSelectedModel: (id: string) => void;
+        modelsByProvider: Record<string, AIModelDescriptor[]>;
+    };
+    onApplied: (result: TResult) => void;
+    /** Transcript di UNA conversazione precedente da mostrare "prima" di `agent.activity` nello
+     * stesso log, senza soluzione di continuità — usato dal task del subagent per prependere la
+     * conversazione dell'orchestratore che lo ha invocato (vedi OrchestratorRunner/SubagentRunner):
+     * l'utente deve vivere Agentico come UNA chat discorsiva unica, mai accorgersi che ci sono
+     * due "attori" distinti dietro le quinte. */
+    precedingActivity?: AgentActivityEntry[];
+    /** Contenuto extra renderizzato nel body del pannello, sotto il log di attività (es.
+     * ResultDestinationPicker una volta che un subagent ha prodotto un risultato senza un
+     * componente vivo ad ascoltarlo — vedi SubagentRunner). Deve restare dentro il pannello
+     * Agentico, non un elemento reso altrove nell'albero: chi possiede il task
+     * (SubagentRunner/OrchestratorRunner) è montato come sibling PRIMA del pannello visibile in
+     * Agentico.tsx (per sopravvivere al toggle di isOpen), quindi il proprio JSX di ritorno
+     * finirebbe fuori dal pannello se non passato tramite questo slot esplicito. */
+    panelExtra?: React.ReactNode;
+    /** Presente SOLO sul task di un ManualEntryRunner — quando impostato, AgenticoComposer
+     * (Agentico.tsx) instrada il testo digitato QUI invece che ad `agent.sendMessage`: niente
+     * chiamata AI, `onSubmit` costruisce i TParams dal testo grezzo e avvia il subagent con
+     * l'AI disabilitata (vedi SubagentManifest.manualEntry). `prompt` è il messaggio statico
+     * mostrato quando non c'è ancora nessuna attività (invece del solito pageContext/hint). */
+    manualEntry?: {
+        prompt: string;
+        onSubmit: (rawText: string) => void;
+    };
+    /** Quante voci di `precedingActivity + agent.activity` (in ordine, vedi Agentico.tsx)
+     * precedono `panelExtra` nella timeline — cioè QUANTE erano già maturate quando il
+     * risultato mostrato in panelExtra è stato prodotto. Senza questo indice, panelExtra veniva
+     * sempre reso dopo l'INTERO log corrente, quindi ogni messaggio di follow-up successivo
+     * (es. un retry finito in errore) appariva SOPRA un risultato che in realtà era arrivato
+     * PRIMA — invertendo la cronologia di una chat che l'utente si aspetta scorra
+     * top=vecchio/bottom=nuovo (bug segnalato). Assente = comportamento invariato, sempre in
+     * fondo (equivalente a passare la lunghezza corrente del log). */
+    panelExtraAnchorIndex?: number;
+    /** Chiamato quando questo task viene sostituito da uno nuovo (vedi openTask) o quando
+     * l'utente lo interrompe — SEMPRE definito da chi possiede il task
+     * (OrchestratorRunner/SubagentRunner), mai un fallback generico su closeTask: quel
+     * componente resta montato anche a task chiuso, quindi il proprio effect che ri-registra il
+     * task a ogni cambiamento di agent.activity/running lo RIAPRIREBBE da solo (es.
+     * l'aggiornamento "Interrotto dall'utente" dopo uno stop()) se non gli si dice
+     * esplicitamente di smettere — vedi il ref `dismissedRef` in entrambi i chiamanti. */
+    onDismiss: () => void;
+}
+/** Un punto di ancoraggio semantico subagent↔componente attivo in questo momento — vedi
+ * useSubagentComponentContext (presentation/hooks) per come si registra, e
+ * SubagentManifest.componentContexts per dove vivono i testi (agenticoHint/userMessage). */
+export interface ComponentAnchor {
+    subagentId: string;
+    componentKey: string;
+    /** Chiamato da SubagentRunner quando arriva un risultato per `subagentId` mentre questo
+     * anchor è montato — il componente/pagina popola se stesso, mai un salvataggio automatico.
+     * `meta` è il TParams con cui il subagent è stato lanciato (es. `{ url }` per theme).
+     * `taskId` è l'id del task Agentico che ha prodotto questo risultato — un componente che
+     * vuole poter persistere la chat al proprio salvataggio (vedi commitEntityChat sotto) lo
+     * tiene da parte, altrimenti può ignorarlo. */
+    onResult?: (result: unknown, meta: Record<string, unknown>, taskId: string) => void;
+    /** Fatti live su QUESTA istanza dell'entità aperta (es. "Il tema aperto si chiama
+     * ducatimilano.it"), aggiunti in coda all'`agenticoHint` statico del manifest (vedi
+     * anchorTexts) — l'`agenticoHint` è prosa fissa scritta una volta nel manifest, non può
+     * sapere quale entità specifica è aperta ORA. Assente = comportamento invariato (solo il
+     * testo statico). Vedi useSubagentComponentContext per come un componente lo valorizza. */
+    contextInfo?: string;
+    /** Id dell'entità a cui QUESTA istanza è vincolata (es. l'hostId di RedirectsEditor) — a
+     * differenza di `contextInfo` (prosa, solo per il prompt), è un valore STRUTTURATO che
+     * SubagentRunner inoltra a `ResultDestination.apply()` (vedi `meta.pinnedEntityId`) perché una
+     * destinazione con logica di identità propria (es. redirectsSaveDestination, che calcola
+     * l'hostId di destinazione dal risultato) possa rifiutare un salvataggio il cui hostId
+     * risolto NON combacia — un backstop deterministico, non affidato solo all'istruzione nel
+     * prompt (che può comunque essere ignorata dal modello). Assente = nessun controllo
+     * aggiuntivo, comportamento invariato (es. RedirectsIndexList, che non è vincolato a un solo
+     * host). */
+    pinnedEntityId?: string;
+}
+interface AgenticoContextValue {
+    /** The host scope passed to <AgenticoProvider scope>. */
+    scope: AgenticoScope | null;
+    task: AgenticoTask | null;
+    /** Visibilità del pannello — completamente indipendente dal task (vedi AgenticoToggle:
+     * icona persistente stile "estensione del browser"). Nessuna chiamata a `openTask` la forza
+     * mai a true: un fetch/run() NON apre da solo il pannello (solo l'icona anima per segnalare
+     * che l'agente sta lavorando) — solo l'utente, cliccando il toggle, decide di vederlo. */
+    isOpen: boolean;
+    /** Crea o sostituisce il task attivo (upsert idempotente se stesso id, altrimenti sostituisce:
+     * un task con un id DIVERSO da quello corrente ne causa la chiusura esplicita via
+     * `onDismiss()` prima di installare il nuovo — mai due conversazioni vive insieme, vedi
+     * AgenticoTask). Richiamalo a ogni render, l'oggetto `agent` è nuovo a ogni render dell'hook
+     * useAgent. */
+    openTask: <TResult>(task: AgenticoTask<TResult>) => void;
+    closeTask: (id: string) => void;
+    /** Mostra/nasconde il pannello — l'unica azione che tocca `isOpen` insieme a `openPanel`
+     * (vedi commento su `isOpen`). Usato da AgenticoToggle. */
+    toggleOpen: () => void;
+    /** Goal in attesa che un OrchestratorRunner catturi al mount e lanci — settato SOLO se non
+     * esiste già un task orchestratore (vedi startOrchestrator). `null` quando non c'è nessun
+     * avvio in sospeso. */
+    pendingGoal: string | null;
+    /** Cambia a ogni conversazione orchestratore avviata per davvero — usato solo come React
+     * `key` sull'elemento <OrchestratorRunner>, mai letto per altro. */
+    orchestratorRunId: string | null;
+    /** Chiamato da ToolsPage ("Usa agent" su una card), dall'input vuoto del pannello Agentico, o
+     * da una pagina che vuole avviare una conversazione già scoped (es. SiteEditorPage) — apre il
+     * pannello e, se non c'è già una conversazione orchestratore in corso, la avvia con questo
+     * goal. Se ce n'è già una, la porta semplicemente a fuoco: NON inietta il nuovo goal in
+     * quella conversazione (limite noto, accettato per l'MVP).
+     * `options.scopedSubagentId` — presente quando il chiamante sa GIÀ, senza bisogno di AI,
+     * quale subagent servirà (es. il bottone "Importa HTML/JSX", sempre `html-to-liquid`) — a
+     * differenza dello scoping derivato da un componentAnchor (vedi `scopedSubagentId` sotto,
+     * che richiede un ancoraggio live), questo vale per un click one-shot che non monta alcun
+     * anchor. Usato SOLO per abilitare il percorso "Continua senza AI" → manuale (vedi
+     * startManualEntry/ManualEntryRunner) quando l'orchestratore stesso non riesce a partire:
+     * senza sapere il target, quel bottone non potrebbe offrire altro che il messaggio generico
+     * di fallback dell'orchestratore (non un vero handoff, non può indovinare l'intento). */
+    startOrchestrator: (goal: string, options?: {
+        extraDestinations?: ResultDestination[];
+        attachments?: File[];
+        model?: string;
+        scopedSubagentId?: string;
+    }) => void;
+    /** Destinazioni scoped alla pagina che ha avviato l'ultimo startOrchestrator() con
+     * `options.extraDestinations` — catturate da OrchestratorRunner al momento dell'handoff e
+     * inoltrate al SubagentRunner che monta, insieme a `pendingGoal`. `undefined` per i
+     * chiamanti che non ne passano. */
+    pendingExtraDestinations: ResultDestination[] | undefined;
+    /** File allegati al messaggio che ha avviato l'ultima conversazione orchestratore — catturati
+     * da OrchestratorRunner al mount, insieme a `pendingGoal`. */
+    pendingAttachments: File[] | undefined;
+    /** Modello scelto dall'utente nel composer "starter", prima ancora che esista una sessione
+     * useAgent — catturato da OrchestratorRunner al mount, insieme a `pendingGoal`. */
+    pendingModel: string | undefined;
+    /** Vedi PendingCarryOver — catturato da OrchestratorRunner al mount insieme a pendingGoal,
+     * `null` quando startOrchestrator() non ha trovato nessun task da continuare. */
+    pendingCarryOver: PendingCarryOver | null;
+    /** Vedi `options.scopedSubagentId` di startOrchestrator sopra — catturato da OrchestratorRunner
+     * al mount, insieme agli altri pending*. `undefined` = nessun target esplicito (comportamento
+     * invariato, l'orchestratore deriva lo scope SOLO da un componentAnchor live, se presente). */
+    pendingScopedSubagentId: string | undefined;
+    /** Testo "dove si trova l'utente adesso" per contestualizzare l'orchestratore — se ci sono
+     * ancoraggi componente↔subagent attivi (vedi componentAnchors sotto) deriva da quelli
+     * (agenticoHint, combinato se ne sono attivi più di uno di subagent diversi), altrimenti
+     * ripiega sul vecchio meccanismo a stack per-pagina (useAgenticoPageContext, ancora usato da
+     * pagine non migrate a componentContexts). Letto una sola volta da OrchestratorRunner al
+     * momento di run(). */
+    pageContext: string | null;
+    /** Card strutturata (campi richiesti/opzionali) — SOLO dal vecchio meccanismo a stack
+     * per-pagina (mai per un anchor component-based, che usa invece `anchoredUserMessages` sotto,
+     * un semplice messaggio invece di un modulo a campi). `null` quando non applicabile. */
+    pageContextCard: SubagentUsageCard | null;
+    /** Registra/rimuove (text === null) il contesto di UNA pagina/pannello identificata da `id`
+     * — usare tramite l'hook useAgenticoPageContext, non direttamente. Vedi pageContext sopra per
+     * come si combina con componentAnchors. */
+    setPageContext: (id: string, text: string | null, card?: SubagentUsageCard | null) => void;
+    /** Id del subagent a cui l'orchestratore deve restare scoped — deriva da componentAnchors
+     * quando esattamente UN subagent è ancorato, altrimenti (0 o >1 subagent distinti) ripiega
+     * sul vecchio pageContextCard/`null`. Sostituisce il vecchio `pageContextCard?.subagentId`
+     * come UNICA fonte per OrchestratorRunner/startOrchestrator. */
+    scopedSubagentId: string | null;
+    /** Ancoraggi componente↔subagent attualmente montati, deduplicati per subagentId (l'ultimo
+     * registrato per uno stesso subagent vince) — usato da SubagentRunner per instradare un
+     * risultato al componente vivo invece di mostrare sempre ResultDestinationPicker. */
+    componentAnchors: ComponentAnchor[];
+    /** Messaggi utente (SubagentComponentContext.userMessage) per gli anchor attivi — mostrati
+     * da Agentico.tsx al posto della vecchia card a campi quando ci sono anchor component-based.
+     * Vuoto se nessun anchor attivo, o se un anchor non ha un componentContexts corrispondente
+     * (es. SiteEditorPage, che ascolta un risultato senza fornire un proprio messaggio). */
+    anchoredUserMessages: string[];
+    /** Registra/rimuove (anchor === null) un ancoraggio componente↔subagent identificato da `id`
+     * — usare tramite l'hook useSubagentComponentContext, non direttamente. */
+    registerComponentAnchor: (id: string, anchor: ComponentAnchor | null) => void;
+    /** Apre il pannello incondizionatamente — a differenza di toggleOpen(), non dipende dal
+     * valore corrente di isOpen. */
+    openPanel: () => void;
+    /** Persiste (sovrascrivendo un'eventuale chat già salvata per la STESSA entità, vedi
+     * entityChatStore) la conversazione del task `taskId`, keyed su `${scopeId}:${subagentId}:
+     * ${entityId}` — chiamato da un componente (es. ThemeEditor) subito dopo un salvataggio
+     * riuscito. No-op se `taskId` è assente (nessuna estrazione coinvolta in questo salvataggio,
+     * es. edit manuale — un'eventuale chat già salvata in precedenza per questa entità resta
+     * intatta) o se il task `taskId` non è più quello corrente (l'utente ha aperto un'altra
+     * conversazione nel frattempo — niente si salva, per non attaccare a un'entità la chat
+     * sbagliata). */
+    commitEntityChat: (subagentId: string, entityId: string, taskId: string | null | undefined, scopeId: string | undefined, params: Record<string, unknown>, title: string) => void;
+    /** Riprende una chat salvata (vedi entityChatStore) — apre il pannello e monta un
+     * SubagentRunner con `resumeSeed` valorizzato invece di un run/handoff dall'orchestratore
+     * (vedi Agentico.tsx). Sostituisce (mai affianca) qualunque task corrente, stesso principio
+     * di startOrchestrator/openTask — una chat unica alla volta in tutta l'app. */
+    resumeEntityChat: (subagentId: string, entityId: string, snapshot: EntityChatSnapshot) => void;
+    /** Presente = un resumeEntityChat() è in sospeso, letto da Agentico.tsx per montare il
+     * SubagentRunner col resumeSeed giusto — analogo a pendingGoal per l'orchestratore. */
+    pendingResume: {
+        subagentId: string;
+        entityId: string;
+        snapshot: EntityChatSnapshot;
+    } | null;
+    /** Cambia a ogni resumeEntityChat() — usato solo come React `key` sul SubagentRunner di
+     * resume (vedi Agentico.tsx), stesso principio di orchestratorRunId. */
+    resumeRunId: string | null;
+    /** Presente = un startManualEntry() è in sospeso, letto da Agentico.tsx per montare un
+     * ManualEntryRunner per QUESTO subagent — percorso "senza AI" per quando l'orchestratore
+     * stesso non riesce a partire ma il target è già noto (vedi
+     * SubagentManifest.manualEntry/pendingScopedSubagentId). Analogo a pendingGoal/pendingResume. */
+    pendingManualEntry: {
+        subagentId: string;
+        extraDestinations?: ResultDestination[];
+    } | null;
+    /** Cambia a ogni startManualEntry() — React `key` sul ManualEntryRunner, stesso principio di
+     * orchestratorRunId/resumeRunId. */
+    manualEntryRunId: string | null;
+    /** Avvia il percorso "senza AI" per un subagent già noto — chiamato dal bottone "Continua
+     * senza AI" quando la conversazione orchestratore è scoped e non può proseguire (vedi
+     * Agentico.tsx). Congeda subito il task orchestratore corrente, stesso principio di un vero
+     * handoff AI-driven (OrchestratorRunner.handleResult). */
+    startManualEntry: (subagentId: string, extraDestinations?: ResultDestination[]) => void;
+    /** Presente = un resumeWithAI() è in sospeso, letto da Agentico.tsx per montare un vero
+     * SubagentRunner (AI abilitata) per QUESTO subagent con QUESTI parametri — il "contrario" di
+     * startManualEntry: dopo aver lavorato nel percorso senza AI, l'utente può far raffinare
+     * dall'AI lo stesso input, invece di restare bloccato lì per sempre. */
+    pendingResumeWithAI: {
+        subagentId: string;
+        params: Record<string, unknown>;
+        extraDestinations?: ResultDestination[];
+    } | null;
+    /** Cambia a ogni resumeWithAI() — React `key` sul SubagentRunner risultante, stesso principio
+     * di manualEntryRunId. */
+    resumeWithAIRunId: string | null;
+    /** Passa da un task ManualEntryRunner (senza AI) a un vero SubagentRunner (AI abilitata) per
+     * lo STESSO subagent, riusando `params` (gli ultimi usati con successo nel percorso senza
+     * AI) come punto di partenza — mai una conversazione persa, solo il canale che cambia.
+     * Generico per costruzione: nessuna conoscenza di QUALE subagent, funziona per ogni
+     * manifest con `manualEntry` dichiarato, non solo html-to-liquid. */
+    resumeWithAI: (subagentId: string, params: Record<string, unknown>, extraDestinations?: ResultDestination[]) => void;
+    /** Congeda il task corrente — usato da un componente che ha già stabilito (in base al
+     * proprio subagentId/entità) che il task visibile non è il suo (vedi ThemeEditor/
+     * ThemeIndexList). Regola unica, nessuna eccezione: quale chat si vede dipende SOLO dal
+     * componente/entità a cui si è agganciati in questo momento — niente puntatori "torna
+     * indietro", niente eccezione per un task ancora in corso (deliberatamente semplice,
+     * raffinabile in seguito). No-op se non c'è alcun task. */
+    dismissForeignTask: () => void;
+}
+export declare function AgenticoProvider({ children, scope }: {
+    children: React.ReactNode;
+    scope?: AgenticoScope | null;
+}): React.JSX.Element;
+export declare function useAgentico(): AgenticoContextValue;
+export {};

package/dist/types/presentation/AgenticoToggle.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+/** L'unica icona che apre/chiude il pannello agente globale, Agentico (Agentico.tsx) — stile
+ * icona-estensione-del-browser: sempre nello stesso angolo, sempre lo stesso significato, sia
+ * che tu stia guardando il CMS a schermo pieno (nell'Header) sia che ci sia una modale right
+ * aperta sopra (come `closeSlot` di quella Modal, al posto della sua ×). Un'unica istanza di
+ * questo componente — mai una ricreata ad hoc — cosi il comportamento resta identico ovunque
+ * compaia. `ActionButton` del framework (non un <button> a mano) per ereditare `cursor-pointer`
+ * e lo stato hover/focus-visible già standard su ogni bottone del CMS dalla classe condivisa
+ * `.btn` — solo sfondo/dimensione sono nostri via className, nessuna variante colore predefinita
+ * si adatta a un'icona-toggle isolata come questa.
+ *
+ * Animata (icona pulsante) quando l'unico task attivo ha l'agente al lavoro — anche se il
+ * pannello è chiuso, cosi si vede che sta succedendo qualcosa senza doverlo aprire apposta
+ * (l'agente NON apre più da solo il pannello durante un run(), vedi AgenticoContext). */
+export declare function AgenticoToggle({ className }: {
+    className?: string;
+}): React.JSX.Element;

package/dist/types/presentation/ManualEntryRunner.d.ts

@@ -0,0 +1,22 @@
+import type { SubagentManifest } from '../domain/subagentManifest';
+import type { ResultDestination } from '../domain/resultDestination';
+/** Percorso "senza AI" per un subagent già scoped (un solo target possibile, niente da
+ * instradare — vedi SubagentManifest.manualEntry e AgenticoContext.startManualEntry), montato
+ * quando l'orchestratore stesso non riesce a partire (AI giù) ma il chiamante sa già a priori
+ * quale subagent servirà. Mostra il prompt statico del manifest; sul primo testo inviato
+ * dall'utente costruisce i TParams DIRETTAMENTE dal testo grezzo (`manualEntry.fromRawText`) e
+ * chiama `agent.run()` con l'AI disabilitata a priori — `buildContext` (sempre deterministico)
+ * gira comunque, ma la chiamata AI viene saltata del tutto (vedi useAgent.run, ramo
+ * `!enabled`), zero round-trip di rete, zero possibilità di fallire per un provider giù.
+ *
+ * Il risultato è mostrato in anteprima (report del subagent se registrato, altrimenti
+ * `GenericResultPreview`) più `ResultDestinationPicker` — STESSO identico schema di
+ * SubagentRunner, mai un apply automatico appena arriva il risultato (bug segnalato: prima
+ * consegnava subito a un anchor live o alla prima extraDestination, senza che l'utente vedesse
+ * nulla prima). Un componentAnchor live (es. ThemeEditor per theme) è trattato come una
+ * destinazione in più tra quelle proposte (vedi liveAnchorDestination.ts), non un canale a
+ * parte. */
+export declare function ManualEntryRunner({ manifest, extraDestinations, }: {
+    manifest: SubagentManifest<any, any, any>;
+    extraDestinations?: ResultDestination[];
+}): null;

package/dist/types/presentation/OrchestratorRunner.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+/** Monta la conversazione dell'orchestratore Agentico — il "meta-agente" che legge il catalogo
+ * CLI dei subagent (deterministico, nessuna chiamata LLM, vedi createOrchestratorAgentDefinition
+ * buildContext) e conversa con l'utente finché non ha raccolto abbastanza parametri per invocare
+ * un subagent reale. Quando arriva un risultato `{ kind: 'handoff' }` monta un SubagentRunner per
+ * quel subagent, gli passa il transcript dell'orchestratore com'era in quel momento
+ * (`precedingActivity`) e chiude subito il proprio task — l'utente vede UNA chat continua che
+ * scivola dalla raccolta parametri all'esecuzione del subagent, mai due task da switchare a
+ * mano (decisione esplicita, vedi piano). */
+export declare function OrchestratorRunner({ userGoal }: {
+    userGoal: string;
+}): React.JSX.Element | null;

package/dist/types/presentation/ResultDestinationPicker.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { SubagentManifest } from '../domain/subagentManifest';
+import type { ResultDestination } from '../domain/resultDestination';
+/** Mostrata da SubagentRunner una volta che il subagent ha prodotto un risultato — un bottone
+ * per destinazione dichiarata dal manifest (`destinationIds`) più "Esporta come JSON", sempre
+ * disponibile per qualunque risultato (vedi jsonExportDestination). Le destinazioni tenant-scoped
+ * (theme, component-library) scrivono SOLO nel tenant attualmente attivo — vedi
+ * DestinationContext, nessuna scelta di un tenant diverso qui (decisione esplicita, vedi piano). */
+export declare function ResultDestinationPicker({ manifest, result, meta, taskId, initiallyApplied, onApplied, extraDestinations, }: {
+    manifest: SubagentManifest<any, any, any>;
+    result: unknown;
+    meta: Record<string, unknown>;
+    /** Id del task Agentico che ha prodotto questo risultato — passato a `commitEntityChat`
+     * quando un apply esplicito (click qui) restituisce un `id` (vedi sotto). Assente = nessuna
+     * persistenza dello storico per questo click (nessun task noto da cui pescare uno snapshot),
+     * comportamento invariato per un eventuale chiamante futuro senza un task Agentico dietro. */
+    taskId?: string;
+    /** Destinazioni già applicate in precedenza (es. riaprendo un'esecuzione dallo storico) —
+     * mostrate subito come spuntate invece di far credere che vadano riapplicate da zero. */
+    initiallyApplied?: string[];
+    /** Chiamato dopo un apply riuscito — usato da SubagentRunner per aggiornare la voce di
+     * storico (appliedDestinationIds), assente quando il chiamante non ne ha bisogno (es. una
+     * destinazione già storicizzata che si vuole solo ri-esportare). */
+    onApplied?: (destinationId: string) => void;
+    /** Destinazioni scoped alla pagina/istanza corrente (es. "Applica a questo Site aperto"),
+     * mai registrate nel destinationRegistry condiviso perché chiudono su stato React di UNA
+     * pagina specifica — mostrate accanto a quelle del registry, non al loro posto. */
+    extraDestinations?: ResultDestination[];
+}): React.JSX.Element;

package/dist/types/presentation/SubagentRunner.d.ts

@@ -0,0 +1,48 @@
+import type { AIConversationTurn } from '@llmnative/react';
+import { type AgentActivityEntry } from './useAgent';
+import type { SubagentManifest } from '../domain/subagentManifest';
+import type { ResultDestination } from '../domain/resultDestination';
+/** Monta il vero subagent (useAgent(manifest.definition)) e lo esegue una volta al mount con i
+ * parametri già raccolti dall'orchestratore Agentico — nessun passo utente aggiuntivo, la
+ * conversazione di raccolta parametri è già avvenuta a monte (vedi Agentico.tsx). Si registra
+ * nel pannello Agentico con id stabile via useRef + cleanup closeTask allo smontaggio, con il
+ * transcript dell'orchestratore (`precedingActivity`) prepeso al proprio log — l'utente vede
+ * UNA chat continua, mai due task distinti da switchare (vedi OrchestratorRunner).
+ *
+ * Con `resumeSeed` valorizzato, il primo giro chiama `agent.resume(...)` invece di
+ * `agent.run(...)` — riprende una chat già salvata (vedi entityChatStore/
+ * AgenticoContext.resumeEntityChat) invece di avviarne una nuova. Tutto il resto (consegna del
+ * risultato ai componentAnchors, ResultDestinationPicker di riserva, registrazione del task) è
+ * IDENTICO a un run normale — un follow-up dopo un resume produce un risultato esattamente come
+ * un follow-up dopo un run, nessuna duplicazione di logica per il caso "ripreso". */
+export declare function SubagentRunner({ manifest, params, extraDestinations, precedingActivity, taskId: taskIdProp, resumeSeed, model, }: {
+    manifest: SubagentManifest<any, any, any>;
+    params: Record<string, unknown>;
+    /** Destinazioni scoped alla pagina che ha avviato questo run (es. "Applica a questo Site
+     * aperto") — inoltrate tale e quali a ResultDestinationPicker, vedi quel file. */
+    extraDestinations?: ResultDestination[];
+    /** Transcript dell'orchestratore all'handoff — vedi AgenticoTask.precedingActivity. Non ha
+     * senso insieme a `resumeSeed` (una chat ripresa non ha un orchestratore a monte in questo
+     * giro) — semplicemente non passato dal chiamante in quel caso. */
+    precedingActivity?: AgentActivityEntry[];
+    /** Id di tab da RIUSARE invece di generarne uno fresco — vedi PendingCarryOver
+     * (AgenticoContext.tsx)/OrchestratorRunner.tsx: quando presente, questo run "continua" una
+     * tab già esistente (stessa posizione, stesso id) invece di aprirne una seconda per lo
+     * stesso subagent. Assente = comportamento invariato, id fresco per ogni run. */
+    taskId?: string;
+    /** Presente = riprendi una chat già salvata invece di avviarne una nuova (vedi
+     * AgenticoContext.resumeEntityChat) — `params` deve comunque essere la stessa forma raccolta
+     * originariamente (manifest.toParams(params) viene chiamato in entrambi i casi). */
+    resumeSeed?: {
+        history: AIConversationTurn[];
+        activity: AgentActivityEntry[];
+    };
+    /** Modello scelto nel composer "starter" a monte (OrchestratorRunner.tsx's modelRef) — questo
+     * componente monta la sua PROPRIA istanza di useAgent/useAIModelCatalog, indipendente da
+     * quella dell'orchestratore che ha appena fatto l'handoff, quindi senza propagarlo qui
+     * esplicitamente `agent.selectedModel` si auto-inizializzerebbe al default del provider
+     * invece di continuare con la scelta dell'utente (stesso bug, stessa causa, di
+     * OrchestratorRunner — vedi il commento lì). Non passato per un `resumeSeed` — lì non c'è una
+     * scelta "di questo giro" da propagare, si continua semplicemente la chat salvata così com'era. */
+    model?: string;
+}): null;

package/dist/types/presentation/deriveHistoryTitle.d.ts

@@ -0,0 +1,10 @@
+import type { SubagentManifest } from '../domain/subagentManifest';
+/** Etichetta breve mostrata nell'header di Agentico/nello storico chat per un task — Agentico
+ * stesso non conosce la forma di TParams di nessun subagent specifico (nessun `params.url`/
+ * `params.siteHostname` hard-codato qui): ogni manifest dichiara il proprio
+ * `deriveHistoryTitle` se ha un campo sensato da mostrare (vedi
+ * SubagentManifest.deriveHistoryTitle), altrimenti si ripiega sul nome generico del subagent
+ * (`manifest.label`) — mai un tentativo di indovinare quale campo di `params` sia "il titolo".
+ * File a sé (non dentro SubagentRunner.tsx/ResultDestinationPicker.tsx) perché entrambi lo
+ * consumano — tenerlo in uno dei due avrebbe creato un import circolare tra loro. */
+export declare function deriveHistoryTitle(manifest: SubagentManifest<any, any, any>, params: Record<string, unknown>): string;

package/dist/types/presentation/liveAnchorDestination.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentAnchor } from './AgenticoContext';
+import type { ResultDestination } from '../domain/resultDestination';
+/** Consegna a un componentAnchor live (es. ThemeEditor per theme) trattata come UNA destinazione
+ * qualunque tra quelle proposte da ResultDestinationPicker — non più un canale a parte con
+ * consegna automatica silenziosa (bug segnalato: il risultato finiva nel componente PRIMA che
+ * l'utente vedesse alcuna anteprima o cliccasse alcunché). Stesso schema per ogni subagent, con
+ * o senza AI: risultato → anteprima in chat → click esplicito → applica. Nessun `id` restituito
+ * (l'entità non è ancora persistita finché l'utente non salva lui stesso nel componente aperto —
+ * `commitEntityChat` si occupa di quel momento separatamente, dal Save del componente stesso). */
+export declare function buildLiveAnchorDestination(matching: ComponentAnchor[], meta: Record<string, unknown>, taskId: string): ResultDestination | null;

package/dist/types/presentation/reports/GenericResultPreview.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+/** Anteprima di riserva per un subagent SENZA un report registrato (oggi: theme, redirects) —
+ * mostrata nella stessa identica posizione/momento di un vero `SubagentReportModule.Report`
+ * (prima del bottone "Applica"), cosi ogni subagent, con o senza report dedicato, con o senza
+ * AI, passa dallo STESSO schema "vedi il risultato → poi applica", mai un apply automatico
+ * silenzioso. Un JSON grezzo non è bello quanto uno swatch di colori o una griglia editabile,
+ * ma è sempre meglio di applicare alla cieca — un report dedicato resta la via preferita quando
+ * ne vale la pena scriverne uno (vedi subagentReportRegistry.tsx). */
+export declare function GenericResultPreview({ result }: {
+    result: unknown;
+}): React.JSX.Element;