@llmnative/agentico 0.1.0

package/dist/types/domain/agentDefinition.d.ts

@@ -0,0 +1,83 @@
+import type { z } from 'zod';
+import type { AIAttachment } from '@llmnative/react';
+/** Rif mutabile, sempre aggiornato da useAgent.ts all'inizio di ogni turno (roundTrip 0) con
+ * gli allegati grezzi (base64) di QUESTO turno — mai un valore statico catturato una volta:
+ * un tool creato da getTools() (chiamato una sola volta per sessione) deve comunque vedere gli
+ * allegati dell'ULTIMO messaggio, non quelli del primo. Esiste per un solo motivo: un allegato
+ * testuale grande (es. un CSV da alcuni MB) non può essere incollato per intero nel messaggio
+ * al modello — supererebbe qualunque finestra di contesto — ma un tool (es.
+ * extract_csv_column) può leggerlo direttamente da qui, bypassando quel limite. `undefined` =
+ * nessun allegato in questo turno. */
+export interface LatestAttachmentsRef {
+    current: AIAttachment[] | undefined;
+}
+/** Tool che il modello può scegliere di invocare durante la conversazione — `execute` è
+ * l'implementazione VERA, mai inviata al provider (solo name/description/inputSchema lo sono,
+ * via useAgent, convertito in JSON Schema in quel punto — vedi mcpTool.ts). Tipicamente
+ * chiude su `params`/`context` dell'agente per rieseguire il controller con argomenti
+ * diversi suggeriti dall'utente in un messaggio di follow-up. */
+export interface AgentTool {
+    name: string;
+    description: string;
+    /** Zod, non JSON Schema — sorgente unica di validazione/tipi. Serializzato a JSON
+     * Schema solo al bordo del provider AI (useAgent.ts), mai qui. */
+    inputSchema: z.ZodType;
+    execute: (input: Record<string, unknown>) => Promise<unknown>;
+    /** Etichetta human-friendly per la UI mentre il tool gira (es. "Ricontrollo
+     * https://example.com/about…") — puramente deterministica/locale, MAI generata
+     * chiedendo al modello di narrare se stesso (inaffidabile, spreca token, e duplica
+     * un'informazione — name+input — già strutturata nella risposta del provider). Assente =
+     * la UI mostra un'etichetta generica col solo nome del tool. */
+    describeInvocation?: (input: Record<string, unknown>) => string;
+    /** Frase completa e discorsiva sullo scopo GENERALE del tool (es. "Sto ricontrollando il
+     * sito per aggiornare branding e stile…"), SENZA i parametri della singola chiamata —
+     * quelli li mostra già la riga della tool call sotto, via describeInvocation. Usata SOLO
+     * per il turno "sto pensando" che ha richiesto questo tool senza scrivere testo libero
+     * (vedi useAgent.ts/thinkingDisplayLabel): senza questo campo, quella riga ripeterebbe
+     * parola per parola l'etichetta della tool call subito sotto — la stessa informazione
+     * scritta due volte una sopra l'altra. Assente = ripiega su describeInvocation (meglio
+     * di niente, ma con la ripetizione). */
+    describeIntent?: string;
+}
+export interface AgentDefinition<TParams, TContext, TResult> {
+    /** Gira sempre, con o senza AI — estrazione/parsing deterministico dei dati grezzi. */
+    buildContext(params: TParams): Promise<TContext> | TContext;
+    /** Prompt finale da inviare al provider — già completamente renderizzato (nessuna
+     * sostituzione ulteriore lato hook). */
+    buildPrompt(params: TParams, context: TContext): string;
+    /** Incorpora un messaggio libero dell'utente in un turno di follow-up (conversazione già
+     * avviata da run(), vedi useAgent.sendMessage) — DEVE ripetere il contratto di output
+     * (schema atteso) di buildPrompt: il modello tende a rispondere in prosa libera dopo
+     * qualche turno se non gli si ricorda il formato, e un fallimento di parseResponse a
+     * quel punto farebbe silenziosamente perdere il risultato del turno all'utente. */
+    buildFollowUpPrompt(userText: string, params: TParams, context: TContext): string;
+    /** Valida/interpreta la risposta grezza dell'AI. `null` = risposta non valida → fallback. */
+    parseResponse(raw: string, params: TParams, context: TContext): TResult | null;
+    /** Risultato deterministico usato quando l'AI è disabilitata, non disponibile, o la sua
+     * risposta non è valida. */
+    fallback(params: TParams, context: TContext): TResult;
+    /** Frase da mostrare nel log di attività quando l'utente preme "Continua senza AI" (vedi
+     * useAgent.runFallback) — descrive COSA rappresenta il risultato appena prodotto per
+     * QUESTO agente specifico, perché runFallback (generico per costruzione, non conosce la
+     * forma di TResult) non può saperlo da solo. Per un agente il cui fallback produce un
+     * output azionabile (import HTML, tema, redirect) basta una conferma breve ("pronto per la
+     * revisione qui sotto"); per l'orchestratore è FONDAMENTALE: il suo fallback non è un vero
+     * handoff (non può indovinare l'intento dell'utente senza AI), è SOLO un messaggio da
+     * leggere — a differenza di un turno AI riuscito, il cui testo libero è già visibile di suo
+     * nel log "sto pensando", qui non esiste un turno equivalente che lo mostri, quindi senza
+     * questo hook il messaggio sparirebbe nel nulla (bug osservato: click su "Continua senza
+     * AI", nessun feedback, l'utente non sa se l'import è riuscito o no). Assente = etichetta
+     * generica ("Continuo senza AI — uso il risultato deterministico."). */
+    describeFallback?(result: TResult): string;
+    /** Tool disponibili al modello durante l'intera conversazione (primo turno e ogni
+     * messaggio di follow-up) — assente o [] = nessun tool per questo agente.
+     * `attachmentsRef` — vedi LatestAttachmentsRef: solo i tool che ne hanno davvero bisogno
+     * (oggi extract_csv_column) lo leggono, tutti gli altri lo ignorano tranquillamente
+     * (parametro opzionale, retrocompatibile con ogni getTools già scritto). */
+    getTools?(params: TParams, context: TContext, attachmentsRef?: LatestAttachmentsRef): AgentTool[];
+    /** Id di micro-prompt trasversali (vedi microPrompts.ts) da aggiungere in coda a
+     * buildPrompt/buildFollowUpPrompt — applicati centralmente da useAgent, non da questo
+     * agente: qui si dichiara solo QUALI si vogliono, mai il loro testo. Assente o [] =
+     * nessuno. */
+    microPromptIds?: string[];
+}

package/dist/types/domain/cli/renderManifestCli.d.ts

@@ -0,0 +1,7 @@
+import type { SubagentManifest } from '../subagentManifest';
+/** Help completo di UN subagent — tutte le sue command, la sua descrizione. */
+export declare function renderSubagentCli<TParams, TContext, TResult>(manifest: SubagentManifest<TParams, TContext, TResult>): string;
+/** Indice sintetico di TUTTI i subagent registrati — una riga per subagent, i suoi comandi
+ * elencati per nome. Questa è la vista che l'orchestratore Agentico usa come punto di partenza
+ * ("cosa esiste") prima di approfondire un singolo subagent con renderSubagentCli(). */
+export declare function renderRegistryCli(registry: ReadonlyArray<SubagentManifest<any, any, any>>): string;

package/dist/types/domain/crossAgentTools.d.ts

@@ -0,0 +1,13 @@
+import type { AgentTool, LatestAttachmentsRef } from './agentDefinition';
+export interface CrossAgentToolContext {
+    /** Raw attachments of the current turn — for tools that read files too big for the prompt. */
+    attachmentsRef: LatestAttachmentsRef | undefined;
+    /** Per-conversation scratchpad shared with the subagent manifests (see withCollected). */
+    collected: Record<string, unknown>;
+    /** CORS-safe fetch of the host app (the framework's proxyFetch). */
+    proxyFetch: typeof fetch;
+}
+export type CrossAgentToolFactory = (context: CrossAgentToolContext) => AgentTool[];
+/** Registers the host's cross-agent tools. Called once at startup; a later call replaces the set. */
+export declare function registerCrossAgentTools(...toolFactories: CrossAgentToolFactory[]): void;
+export declare function createCrossAgentTools(context: CrossAgentToolContext): AgentTool[];

package/dist/types/domain/defineSubagent.d.ts

@@ -0,0 +1,5 @@
+import type { AgentDefinition } from './agentDefinition';
+import type { SubagentManifest } from './subagentManifest';
+export declare function defineSubagent<TParams, TContext, TResult>(config: Omit<SubagentManifest<TParams, TContext, TResult>, 'definition'> & {
+    definition: AgentDefinition<TParams, TContext, TResult>;
+}): SubagentManifest<TParams, TContext, TResult>;

package/dist/types/domain/destinationRegistry.d.ts

@@ -0,0 +1,5 @@
+import type { ResultDestination } from './resultDestination';
+/** Chiamata dall'host UNA VOLTA, a livello di modulo — un secondo giro SOSTITUISCE il registro
+ * precedente, stesso principio di registerSubagents. */
+export declare function registerDestinations(destinations: Record<string, ResultDestination<any>>): void;
+export declare function getDestinationRegistry(): Record<string, ResultDestination<any>>;

package/dist/types/domain/entityChatStore.d.ts

@@ -0,0 +1,48 @@
+import type { AIConversationTurn } from '@llmnative/react';
+/** Stessa forma di AgentActivityEntry (agentico/presentation/useAgent.ts) — ridefinita qui invece
+ * di importata: il domain layer non dipende dal presentation layer, e questi campi sono
+ * semplici dati (mai funzioni), quindi TypeScript accetta un AgentActivityEntry[] ovunque sia
+ * richiesto questo tipo per compatibilità strutturale, senza bisogno di un cast esplicito. */
+export interface EntityChatActivityEntry {
+    id: string;
+    kind: 'user' | 'thinking' | 'tool';
+    label: string;
+    status: 'running' | 'done' | 'error' | 'stopped';
+    detail?: string;
+    toolNames?: string[];
+}
+export interface EntityChatSnapshot {
+    /** Host scope (tenant, company…) the chat belongs to — see AgenticoScope. */
+    scopeId: string;
+    subagentId: string;
+    entityId: string;
+    /** TParams grezzo (pre-manifest.toParams, es. `{ url }` per theme) con cui la sessione
+     * originale era stata avviata — necessario per ricostruire context/tools al resume (vedi
+     * useAgent.resume/SubagentRunner.resumeSeed): senza, `manifest.toParams` non avrebbe nulla
+     * da validare/convertire per riavviare la sessione. */
+    params: Record<string, unknown>;
+    history: AIConversationTurn[];
+    activity: EntityChatActivityEntry[];
+    savedAt: number;
+    /** Etichetta human-friendly dell'entità (es. il nome del tema) — usata dallo storico chat
+     * di Agentico (vedi Agentico.tsx) per mostrare "cosa" senza dover rileggere l'entità stessa
+     * dal suo DataProviderAdapter (che questo store, domain-side, non possiede). */
+    title: string;
+}
+/** Sets the localStorage key of the chat store — call once at startup, before any read. */
+export declare function configureEntityChatStore(options: {
+    storageKey: string;
+}): void;
+/** La chat attualmente associata a un'entità — `null` se non ne è mai stata salvata una (o è
+ * stata rimossa, vedi removeEntityChat). */
+export declare function getEntityChat(scopeId: string, subagentId: string, entityId: string): EntityChatSnapshot | null;
+/** Sovrascrive (o crea) la chat associata a questa entità — vedi il commento in testa al file
+ * per perché è sempre un overwrite, mai un accumulo. */
+export declare function saveEntityChat(snapshot: Omit<EntityChatSnapshot, 'savedAt'>): void;
+/** Rimuove la chat di un'entità — chiamata quando l'entità stessa viene eliminata, altrimenti
+ * resterebbe un'entry orfana senza nulla a cui riattaccarsi. */
+export declare function removeEntityChat(scopeId: string, subagentId: string, entityId: string): void;
+/** Tutte le chat salvate di uno scope, più recenti prima — per lo storico di Agentico
+ * (Agentico.tsx), che le mescola across subagent (theme, redirects, html-to-liquid) in un'unica
+ * lista ordinata per data. */
+export declare function listEntityChats(scopeId: string): EntityChatSnapshot[];

package/dist/types/domain/extractErrorMessage.d.ts

@@ -0,0 +1 @@
+export declare function extractErrorMessage(err: unknown): string;

package/dist/types/domain/extractJsonBlock.d.ts

@@ -0,0 +1 @@
+export declare function extractJsonBlock(raw: string): string;

package/dist/types/domain/jsonExportDestination.d.ts

@@ -0,0 +1,3 @@
+import type { ResultDestination } from './resultDestination';
+export declare const JSON_EXPORT_DESTINATION_ID = "json-export";
+export declare const jsonExportDestination: ResultDestination<unknown>;

package/dist/types/domain/mcpTool.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+export declare function toJsonSchema(schema: z.ZodType): Record<string, unknown>;
+export declare function toMcpTool(name: string, description: string, inputSchema: z.ZodType, outputSchema?: z.ZodType): McpTool;

package/dist/types/domain/microPrompts.d.ts

@@ -0,0 +1,20 @@
+export interface MicroPrompt {
+    id: string;
+    text: string;
+}
+/** Chiede al modello di chiudere SEMPRE la propria risposta testuale con un riepilogo
+ * conciso di cosa ha fatto — utile perché l'utente altrimenti vede solo il log delle tool
+ * call/turni "sto pensando" (già deterministico, mai narrato dal modello) ma nessuna sintesi
+ * finale in linguaggio naturale di cosa è stato effettivamente ottenuto.
+ *
+ * Il riepilogo va DOPO il blocco ```json — mai prima, mai a comporlo — cosi
+ * extractJsonBlock() lo trova comunque cercando il fence ovunque nel testo, e il riepilogo
+ * stesso resta visibile all'utente come testo libero accanto al JSON (vedi DetailContent in
+ * AgentActivityLog.tsx, che già sa render testo + blocco codice misti nello stesso turno). */
+export declare const SUMMARY_MICRO_PROMPT: MicroPrompt;
+/** Registro dei micro-prompt disponibili, per id. */
+export declare const MICRO_PROMPT_REGISTRY: Record<string, MicroPrompt>;
+/** Applica in coda al prompt verticale i micro-prompt richiesti per id — no-op se l'agente
+ * non ne richiede nessuno (o richiede un id sconosciuto, ignorato silenziosamente: un id
+ * scritto male non deve far fallire l'intero prompt). */
+export declare function applyMicroPrompts(prompt: string, ids: string[] | undefined): string;

package/dist/types/domain/orchestrator/agenticoOrchestratorAgent.d.ts

@@ -0,0 +1,34 @@
+import type { AgentDefinition } from '../agentDefinition';
+import { type OrchestratorHandoff, type OrchestratorResult } from './prompt';
+export interface OrchestratorAgentParams {
+    /** The opening message — the user's free request, or a goal pre-seeded from a subagent card. */
+    userGoal: string;
+    /** "Where the user is now" (see useAgenticoPageContext), captured once at run(). */
+    pageContext: string | null;
+    /** Subagent the starting page is pinned to, `null` for a generic chat. Restricts the
+     * cross-agent tools to the ones that subagent declares (SubagentManifest.crossAgentToolIds). */
+    scopedSubagentId: string | null;
+}
+export interface OrchestratorAgentContext {
+    cliCatalog: string;
+    /** Written by the execute() of the handoff tool invoked in this turn and read by parseResponse:
+     * the only way a tool call outcome reaches parseResponse, which only sees the final text.
+     * Reset every turn — a handoff is valid only for the turn that invoked it. */
+    handoff: {
+        current: OrchestratorHandoff | null;
+    };
+    /** Complete outputs of the cross-agent tools of this conversation (see crossAgentTools.ts). */
+    collected: Record<string, unknown>;
+}
+/** User-facing labels of the orchestrator (from the `agentico` i18n namespace). */
+export interface OrchestratorLabels {
+    /** Chat message used when the AI is not available. */
+    unavailable: string;
+    /** Log line of "continue without AI". */
+    continueWithoutAi: string;
+    /** Tool call label while a handoff is prepared — `{label}` = subagent label. */
+    preparing: string;
+    /** "Thinking" label of the turn that requested the handoff — `{label}` = subagent label. */
+    collecting: string;
+}
+export declare function createOrchestratorAgentDefinition(labels: OrchestratorLabels): AgentDefinition<OrchestratorAgentParams, OrchestratorAgentContext, OrchestratorResult>;

package/dist/types/domain/orchestrator/prompt.d.ts

@@ -0,0 +1,17 @@
+export interface OrchestratorHandoff {
+    subagentId: string;
+    command: string;
+    params: Record<string, unknown>;
+}
+export type OrchestratorResult = {
+    kind: 'chat';
+    message: string;
+} | ({
+    kind: 'handoff';
+} & OrchestratorHandoff);
+export declare function describeOrchestratorResponseContract(): string;
+export declare function buildOrchestratorPrompt(userGoal: string, cliCatalog: string, pageContext?: string | null): string;
+/** `handoff` arriva dal context della sessione (settato dall'execute() del tool invocato in
+ * questo turno, vedi agenticoOrchestratorAgent.ts) — se presente ha sempre priorità sul testo
+ * libero del modello, che a quel punto è solo un commento discorsivo sul tool appena invocato. */
+export declare function parseOrchestratorResponse(raw: string, handoff: OrchestratorHandoff | null): OrchestratorResult;

package/dist/types/domain/prompts.d.ts

@@ -0,0 +1,29 @@
+export interface AgenticoPrompts {
+    /** First paragraph of the orchestrator prompt: who the orchestrator is and what it does. */
+    orchestratorIntro: string;
+    /** Bullet rules of the orchestrator response contract (generic ones first, host ones after). */
+    responseRules: string[];
+    responseRulesHeading: string;
+    toolsHeading: string;
+    pageContextHeading: string;
+    pageContextIntro: string;
+    userRequestHeading: string;
+    /** CLI catalog shown when no subagent is registered. */
+    noToolsAvailable: string;
+    /** Sent to the model when it keeps calling tools past the round-trip limit. */
+    stopCallingTools: string;
+    /** Returned to the model by a handoff tool: the work is queued, not done. `{label}` = subagent. */
+    handoffQueued: string;
+    /** Closing-summary micro-prompt (see microPrompts.ts). */
+    closingSummary: string;
+    /** Page context preamble when several subagents are anchored on the same page. */
+    multipleCandidates: string;
+}
+export declare const agenticoPromptsEn: AgenticoPrompts;
+export declare const agenticoPromptsIt: AgenticoPrompts;
+/** Sets the model-facing pack once at startup — e.g. `configureAgenticoPrompts({ ...agenticoPromptsIt,
+ * responseRules: [...agenticoPromptsIt.responseRules, ...hostRules] })`. Fields left out keep their value. */
+export declare function configureAgenticoPrompts(prompts: Partial<AgenticoPrompts>): void;
+export declare function getAgenticoPrompts(): AgenticoPrompts;
+/** Restores the English defaults (tests). */
+export declare function resetAgenticoPrompts(): void;

package/dist/types/domain/resultDestination.d.ts

@@ -0,0 +1,24 @@
+import type { DataProviderAdapter, StorageProviderAdapter } from '@llmnative/react';
+export interface DestinationContext {
+    /** Id of the host scope the result is saved into (a tenant, a company…) — see AgenticoScope. */
+    scopeId: string;
+    dataProvider: DataProviderAdapter;
+    storageProvider: StorageProviderAdapter | null;
+    proxyFetch: typeof fetch;
+}
+/** Esito opzionale di un apply — `id` (usato da destinazioni tenant-wide come
+ * componentLibraryDestination per far sapere al chiamante l'id della risorsa creata/aggiornata,
+ * un'informazione che una destinazione generica non può conoscere da sola: vedi
+ * ResultDestinationPicker.commitEntityChat). `void` per le destinazioni che non hanno nulla da
+ * restituire — non un cambio breaking, tutte le destinazioni esistenti restano valide. */
+export type ResultDestinationOutcome = {
+    id?: string;
+} | void;
+export interface ResultDestination<TResult = unknown> {
+    id: string;
+    label: string;
+    /** `meta` è il TParams con cui il subagent è stato lanciato (es. `{ url }` per theme) —
+     * alcuni risultati non si bastano da soli (es. ThemeExtractResult non porta l'URL
+     * sorgente, servito solo per nominare il tema). */
+    apply(result: TResult, ctx: DestinationContext, meta: Record<string, unknown>): Promise<ResultDestinationOutcome>;
+}

package/dist/types/domain/subagentManifest.d.ts

@@ -0,0 +1,172 @@
+import type { z } from 'zod';
+import type { AgentDefinition } from './agentDefinition';
+/** Una singola capability offerta dal subagent (oggi quasi sempre una sola per manifest). */
+export interface SubagentCommand {
+    /** Nome del comando, snake_case, univoco nel subagent — es. "extract", "import". */
+    name: string;
+    /** Una riga — cosa fa questo comando. */
+    summary: string;
+    /** Zod, non JSON Schema — sorgente unica di validazione/tipi dei parametri del RUN
+     * primario (buildContext/buildPrompt), non di un tool di follow-up a metà conversazione
+     * (quelli sono AgentTool.inputSchema). Serializzato a JSON Schema solo ai bordi (render
+     * CLI, futuro MCP tool) via mcpTool.ts — mai qui. */
+    inputSchema: z.ZodType;
+    /** Zod dei dati che compongono il TResult — opzionale: oggi la forma del risultato è
+     * documentata solo in prosa da describeOutput(); questo schema serve a un futuro
+     * consumer machine-readable (es. la CLI) che debba validare/tipizzare l'output, non al
+     * prompt AI né al CLI help testuale. */
+    outputSchema?: z.ZodType;
+    /** Testo che descrive la forma della risposta — quasi sempre un riuso diretto della
+     * describe<Feature>ResponseContract() già scritta per il prompt AI (domain/prompts/<feature>.ts):
+     * nessuna duplicazione, la stessa stringa serve sia da contratto per il modello sia da
+     * sezione OUTPUT del CLI help. */
+    describeOutput(): string;
+    /** Un invocazione realistica, mostrata nella sezione EXAMPLE del CLI help. */
+    example?: string;
+    /** Riassunto in una riga per un UMANO che guarda la card di Agentico (SubagentUsageCardView,
+     * Agentico.tsx) — NON per il modello/CLI, quelli restano su `summary` (che può permettersi
+     * di essere tecnico/preciso perché è machine-facing). Assente = la card ripiega su `summary`
+     * (comportamento di oggi, invariato per i subagent che non ne hanno ancora bisogno). Due
+     * pubblici diversi per lo stesso comando: un LLM ha bisogno di casi limite ed enumerazioni
+     * per non sbagliare la chiamata, un umano ha bisogno di una frase che si legge in un
+     * secondo — mai lo stesso testo per entrambi. */
+    humanSummary?: string;
+    /** Come `humanSummary` ma per-campo (chiave = nome campo in `inputSchema`) — sostituisce SOLO
+     * nella card umana la `.describe()` Zod di quel campo (che resta la fonte tecnica per JSON
+     * Schema/prompt/CLI, invariata). Un campo assente da questa mappa mostra comunque la
+     * descrizione tecnica nella card — non è un obbligo compilare tutti i campi qui, solo quelli
+     * la cui descrizione tecnica è troppo densa per un umano di passaggio. Ignorato quando
+     * `humanSummaryOnly` è true (vedi sotto). */
+    humanFieldHints?: Record<string, string>;
+    /** Quando true, la card umana mostra SOLO `humanSummary` (che allora deve raccontare da solo,
+     * in prosa naturale, cosa serve e come recuperarlo) — niente elenco di campi con badge
+     * richiesto/opzionale, niente esempio in sintassi CLI. Serve per comandi il cui schema
+     * tecnico (N campi separati) non rispecchia come un umano pensa l'input — es. redirects:
+     * lo schema ha 4 campi (incomingPaths/destinationPaths/trafficByPath/siteHostname) ma un
+     * umano ragiona in termini di "cosa mando" (un CSV, l'accesso a Search Console, una sitemap),
+     * non di quei 4 nomi — un elenco a campi separati implicherebbe erroneamente che vadano
+     * forniti come input distinti, quando in realtà UNA fonte sola (es. un CSV con status code)
+     * può bastare da sola per riempirli entrambi. Assente/false = comportamento di oggi (elenco
+     * campi), corretto per un comando i cui campi SONO l'input diretto dell'utente (es. `url` di
+     * theme). */
+    humanSummaryOnly?: boolean;
+    /** Regola/i decisionale/i ad alta visibilità per l'ORCHESTRATORE Agentico — iniettata nel
+     * "Contesto pagina" (vedi useAgenticoPageContext/agentico-orchestrator.ts, che istruisce
+     * esplicitamente il modello a controllare quella sezione PRIMA di chiedere qualunque
+     * parametro), non nella `.describe()` Zod dei campi. Le due cose sembrano ridondanti ma non
+     * lo sono: la `.describe()` di un campo il modello la vede solo quando ha già deciso di
+     * ispezionare/chiamare quel tool specifico — un contesto profondo, letto in modo
+     * inconsistente (bug osservato: la stessa regola, "un URL/sitemap di un sito live è SEMPRE
+     * destinationPaths", a volte veniva dedotta correttamente e a volte no, nella stessa
+     * conversazione). Il Contesto pagina invece è la PRIMA cosa che il modello controlla per
+     * istruzione esplicita — la stessa regola lì è affidabile. Non duplicare qui la spiegazione
+     * completa dei campi (quella resta nella card/nello schema): solo le regole che altrimenti
+     * richiederebbero al modello di "scoprire" una logica che invece va data per scontata subito. */
+    orchestratorHint?: string;
+}
+/** Descrizione pubblica e discoverable via CLI (nessuna chiamata LLM) di un subagent —
+ * un modulo per cartella (es. domain/subagents/theme/manifest.ts), esportato
+ * dal barrel della cartella ed elencato in subagentRegistry.ts. */
+export interface SubagentManifest<TParams = any, TContext = any, TResult = any> {
+    /** Id stabile, usato come chiave del registry e prefisso dei tool generati dall'orchestratore
+     * Agentico (`${id}_${command.name}`) — mai esposto all'utente, solo a modello/codice. */
+    id: string;
+    /** Etichetta human-friendly, mostrata nella grid di /tools. */
+    label: string;
+    /** Nome icona del framework (@llmnative/react Icon), usato da grid e CLI header. */
+    icon: string;
+    /** Prosa più lunga — cosa fa e come, sezione DESCRIPTION del CLI help. */
+    description: string;
+    /** Le capability offerte — oggi tipicamente un solo comando primario per subagent. */
+    commands: SubagentCommand[];
+    /** Route dell'indice DUREVOLE di questo subagent — dove vivono le entità che ha prodotto/
+     * modificato. Contratto condiviso a livello di ROUTING, non di componente React: le entità
+     * di ogni subagent hanno esigenze reali diverse (redirects ha un indice leggero custom
+     * scritto per questo, theme/html-to-liquid riusano le pagine già esistenti e più ricche —
+     * ThemesPage/LibraryComponentsPage via Grid — invece di duplicarle in una lista povera solo
+     * per uniformità visiva). Ogni subagent DEVE dichiararlo: `ToolsPage` naviga sempre qui al
+     * click sulla card (non esiste un fallback generico allo storico-run — vedi menu.ts). */
+    indexPath: string;
+    /** Id dei ResultDestination (vedi destinationRegistry.ts) che accettano il TResult di
+     * questo subagent — 'json-export' è sempre valido per qualunque TResult e non va elencato
+     * qui esplicitamente (vedi ResultDestinationPicker). */
+    destinationIds: string[];
+    /** Sottoinsieme di `destinationIds` applicato AUTOMATICAMENTE (da SubagentRunner) a ogni
+     * risultato/aggiornamento — non richiede un click su ResultDestinationPicker. Per subagent
+     * dove il risultato stesso È il dato definitivo (oggi solo redirects: vedi
+     * redirectsSaveDestination/docs/30-redirects-system.md), non un export opzionale che
+     * l'utente sceglie se e quando applicare. Assente/vuoto = comportamento invariato (solo
+     * apply manuale via picker). */
+    autoApplyDestinationIds?: string[];
+    /** Sottoinsieme dei tool cross-agent condivisi (domain/services/tools/ — read_sitemap,
+     * scrape_page, list_csv_columns, extract_csv_column) che QUESTO subagent usa davvero, per
+     * nome (`AgentTool.name`). L'orchestratore Agentico (agenticoOrchestratorAgent.ts) li
+     * espone TUTTI quando la conversazione non è ancora scoped a un subagent specifico (chat
+     * generica — non si sa ancora quale servirà), ma li RESTRINGE a questo elenco quando la
+     * pagina di partenza è pinnata a un subagent (vedi useAgenticoPageContext + `usageCard`) —
+     * un subagent vede solo il proprio sottoinsieme, mai tutti gli strumenti disponibili
+     * nell'app. Assente/vuoto = nessun tool di raccolta dati condiviso (es. theme/
+     * html-to-liquid: i loro parametri arrivano già di mano dall'utente — url, markup — senza
+     * bisogno di leggere una sitemap o un CSV). */
+    crossAgentToolIds?: string[];
+    /** Merges what the cross-agent tools collected in this conversation (see crossAgentTools.ts,
+     * `collected`) into the command input right before the handoff — the collected values are
+     * complete, while the copy the model passed may be truncated. Absent = input used as is. */
+    withCollected?(input: Record<string, unknown>, collected: Record<string, unknown>): Record<string, unknown>;
+    /** Il vero esecutore — lo stesso AgentDefinition consumato da useAgent altrove nell'app. */
+    definition: AgentDefinition<TParams, TContext, TResult>;
+    /** Converte l'input validato di un comando (raccolto in conversazione dall'orchestratore, o
+     * passato da un futuro chiamante CLI) nei TParams che l'AgentDefinition si aspetta. */
+    toParams(input: Record<string, unknown>): TParams;
+    /** Percorso "senza AI" alternativo all'intera conversazione orchestratore — solo per un
+     * subagent il cui INTERO input primario è un unico blob di testo grezzo (oggi solo
+     * html-to-liquid: `markup`), mai per uno con più parametri distinti da raccogliere (theme
+     * ha bisogno di un `url`, redirects di due liste di path — un singolo testo non basta a
+     * riempirli, un form vero servirebbe, fuori scope per ora). Usato SOLO quando la
+     * conversazione è già scoped a QUESTO subagent (vedi AgenticoContext.startOrchestrator
+     * `scopedSubagentId`, un solo target possibile, niente da instradare) E l'orchestratore
+     * stesso non riesce a partire (AI giù) — l'utente incolla il testo direttamente, zero
+     * round-trip di rete, mai un tentativo AI (vedi ManualEntryRunner). `prompt` è il messaggio
+     * statico mostrato in chat al posto del solito hint; `fromRawText` converte quel testo nei
+     * TParams — può lanciare (es. testo vuoto), il chiamante lo mostra come errore. Assente =
+     * nessun percorso manuale (comportamento invariato: serve comunque l'orchestratore). */
+    manualEntry?: {
+        prompt: string;
+        fromRawText(rawText: string): TParams;
+    };
+    /** Titolo breve per l'header di Agentico/lo storico chat, derivato dai parametri RAW di
+     * QUESTO subagent (lo stesso `Record<string, unknown>` grezzo passato a `toParams`, non il
+     * TParams già convertito — SubagentRunner lo ha disponibile senza doverlo ri-convertire) —
+     * es. theme: hostname da `params.url`; redirects: `params.siteHostname`. Agentico
+     * (SubagentRunner) non conosce la forma dei parametri di nessun subagent specifico, quindi
+     * non può indovinare quale campo mostrare: il manifest lo dichiara esplicitamente. Assente =
+     * ripiega su `label` (comportamento corretto anche per subagent il cui unico campo (es.
+     * html-to-liquid: `markup`, il testo incollato dall'utente) non è mai un titolo leggibile). */
+    deriveHistoryTitle?(params: Record<string, unknown>): string | undefined;
+    /** Punti di ancoraggio semantico subagent↔componente — keyed per nome componente scelto
+     * liberamente dall'autore del subagent, ma per coerenza tra subagent (oggi solo `theme`,
+     * futuri: redirects/html-to-liquid) usare la convenzione: 'indexList' per il componente che
+     * elenca le entità (naviga verso un editor nuovo pre-compilato quando riceve un risultato) e
+     * 'editor' per il componente che ne modifica una aperta (si popola da solo). Un consumer
+     * indipendente che ascolta solo una fetta del risultato (es. SiteEditorPage per i soli campi
+     * di site-branding) usa una chiave propria, descrittiva del suo ruolo (es. 'siteBranding'),
+     * non una delle due sopra. Letto da
+     * useSubagentComponentContext (presentation/hooks), chiamato DAL componente React stesso al
+     * mount, mai dalla pagina che lo ospita: chi monta il componente ottiene il contesto
+     * Agentico corretto gratis, senza ricostruirlo pagina per pagina (vedi SubagentCommand.
+     * orchestratorHint/humanSummary* per il vecchio meccanismo a livello di pagina, ancora usato
+     * da redirects/html-to-liquid finché non vengono migrati). */
+    componentContexts?: Record<string, SubagentComponentContext>;
+}
+/** Coppia di messaggi per UN punto di ancoraggio componente↔subagent (vedi
+ * SubagentManifest.componentContexts) — due pubblici diversi per lo stesso aggancio, mai lo
+ * stesso testo per entrambi (stesso principio di SubagentCommand.humanSummary vs summary). */
+export interface SubagentComponentContext {
+    /** Per il prompt dell'orchestratore LLM — iniettato nel "Contesto pagina" quando questo
+     * componente è montato (vedi AgenticoContext.componentAnchors). */
+    agenticoHint: string;
+    /** Mostrato in chat all'utente quando Agentico si aggancia a questo componente — sostituisce
+     * la card a campi (SubagentUsageCardView) per gli anchor component-based: una frase, non un
+     * modulo da compilare. */
+    userMessage: string;
+}

package/dist/types/domain/subagentRegistry.d.ts

@@ -0,0 +1,11 @@
+import type { SubagentManifest } from './subagentManifest';
+/** Chiamata dall'host UNA VOLTA, a livello di modulo (non dentro un componente React) — un
+ * secondo giro SOSTITUISCE il registro precedente, non lo somma: niente doppie registrazioni
+ * accidentali (es. da un hot-reload) da dover deduplicare a valle. */
+export declare function registerSubagents(manifests: ReadonlyArray<SubagentManifest<any, any, any>>): void;
+/** Letto da codice che ha bisogno dell'INTERO elenco (es. la Grid di ToolsPage, il catalogo CLI
+ * dell'orchestratore) — mai per costruzione statica a import-time: se questo ritorna `[]` è
+ * quasi sempre perché `registerSubagents` non è ancora stato chiamato (o il modulo che lo chiama
+ * non è ancora stato importato) prima di questo punto, non un progetto senza subagent. */
+export declare function getSubagentRegistry(): ReadonlyArray<SubagentManifest<any, any, any>>;
+export declare function findSubagentManifest(id: string): SubagentManifest<any, any, any> | undefined;

package/dist/types/domain/subagentUsageCard.d.ts

@@ -0,0 +1,37 @@
+import type { SubagentCommand, SubagentManifest } from './subagentManifest';
+export interface SubagentUsageField {
+    key: string;
+    type: string;
+    required: boolean;
+    /** Tecnica, machine-facing — la `.describe()` Zod tale e quale, stessa fonte del JSON
+     * Schema/CLI help. Verbosa ed enumerativa per progettazione: un LLM sbaglia meno con casi
+     * limite espliciti, un umano di passaggio no. */
+    description: string;
+    /** Human-facing, per la card di Agentico — `command.humanFieldHints[key]` se presente,
+     * altrimenti ripiega su `description` (mai vuota, mai un secondo giro di scrittura
+     * obbligato per ogni subagent). */
+    humanDescription: string;
+}
+export interface SubagentUsageCard {
+    subagentId: string;
+    label: string;
+    commandName: string;
+    /** Tecnica, machine-facing — vedi SubagentCommand.summary. */
+    summary: string;
+    /** Human-facing — `command.humanSummary` se presente, altrimenti ripiega su `summary`. */
+    humanSummary: string;
+    fields: SubagentUsageField[];
+    example?: string;
+    /** Quando true, il consumer UI (SubagentUsageCardView) mostra SOLO `humanSummary` — niente
+     * `fields`/`example` (pensati per l'occhio tecnico) — vedi SubagentCommand.humanSummaryOnly
+     * per il perché. */
+    humanSummaryOnly: boolean;
+}
+/** Estrae la lista di campi (nome/tipo/obbligatorietà/descrizione) dallo z.ZodType di un
+ * comando — riusata sia qui sia da renderManifestCli.ts, che altrimenti duplicherebbe la stessa
+ * lettura di `properties`/`required` dal JSON Schema. */
+export declare function describeCommandFields(command: SubagentCommand): SubagentUsageField[];
+/** Il comando primario di un manifest (oggi quasi sempre l'unico, vedi SubagentManifest.commands)
+ * proiettato in una card — `null` solo se un manifest non ne dichiara nessuno (non dovrebbe
+ * succedere per un subagent registrato, ma il chiamante UI non deve crashare se succede). */
+export declare function buildSubagentUsageCard(manifest: SubagentManifest<any, any, any>): SubagentUsageCard | null;

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

@@ -0,0 +1,2 @@
+import type { AgenticoDict } from './types';
+export declare const agenticoDe: AgenticoDict;

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

@@ -0,0 +1,2 @@
+import type { AgenticoDict } from './types';
+export declare const agenticoEn: AgenticoDict;

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

@@ -0,0 +1,20 @@
+import { agenticoDe } from './de';
+import { agenticoEn } from './en';
+import { agenticoIt } from './it';
+import type { AgenticoDict } from './types';
+export type { AgenticoDict } from './types';
+export { agenticoDe, agenticoEn, agenticoIt };
+/** Merge into <App i18n={{ translations }}> — e.g. `it: { ...locales.it, ...agenticoTranslations.it, ...yourIt }`. */
+export declare const agenticoTranslations: {
+    en: {
+        agentico: AgenticoDict;
+    };
+    it: {
+        agentico: AgenticoDict;
+    };
+    de: {
+        agentico: AgenticoDict;
+    };
+};
+/** Agentico strings for the active locale: what the host registered, on top of English. */
+export declare function useAgenticoI18n(): AgenticoDict;

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

@@ -0,0 +1,2 @@
+import type { AgenticoDict } from './types';
+export declare const agenticoIt: AgenticoDict;