@llmnative/agentico 0.1.0 → 0.3.0

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

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 import type { AIAttachment } from '@llmnative/react';
+import type { AgentQuestion, AgentQuestionAnswer, AgentQuestionsAnswers } from './messageParts';
 /** 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
@@ -80,4 +81,82 @@ export interface AgentDefinition<TParams, TContext, TResult> {
      * agente: qui si dichiara solo QUALI si vogliono, mai il loro testo. Assente o [] =
      * nessuno. */
     microPromptIds?: string[];
+    /** Present = the turns of this agent are answered by the host, not by the AI provider of
+     * Agentico (CR-003): a remote agent with its own memory, for example an opencode session on
+     * a server. `useAgent` then builds no prompt, needs no model and never falls back: it gives
+     * the executor the text of the person and shows what it reports. `buildPrompt`,
+     * `buildFollowUpPrompt`, `parseResponse` and `fallback` stay required by the type but are not
+     * called. */
+    executor?: AgentExecutor<TParams, TContext, TResult>;
+}
+/** One step of a remote agent, shown as a line of the activity log and updated by `id`
+ * (e.g. "wrote GLOSSARY.md"). */
+export interface AgentExecutorStep {
+    id: string;
+    label: string;
+    status: 'running' | 'done' | 'error';
+}
+/** One turn given to an `AgentExecutor`. */
+export interface AgentExecutorTurn<TParams, TContext> {
+    params: TParams;
+    context: TContext;
+    /** What the person wrote: the opening message on the first turn (possibly empty), then
+     * each follow-up, as typed — never a prompt built by Agentico. */
+    text: string;
+    /** true on the turn of `run()`, false on every follow-up. */
+    first: boolean;
+    /** Aborted when the person stops the turn. */
+    signal: AbortSignal;
+    /** The model the person picked among `AgentExecutor.models`, if the executor offers any. */
+    model?: string;
+    /** Present when the person answered questions of an earlier turn (CR-004): the turn carries
+     * them, structured, with `text` empty. The executor decides how to forward them (e.g. to the
+     * `question` tool of its session). Questions answered while their own turn is still running
+     * resolve the promise of `onQuestions` instead. */
+    answers?: AgentQuestionsAnswers;
+    /** The reply so far, whole (not a delta): shown as it grows, as Markdown. Without `part.id` it
+     * is the one reply of the turn (CR-003), kept below the steps and the reasoning; with an id it is
+     * a text part of its own, in the order it first arrived (CR-004). `part.done` ends its streaming. */
+    onText(text: string, part?: AgentExecutorPartOptions): void;
+    /** The reasoning of the model so far, whole (not a delta), as Markdown: shown closed behind
+     * "Reasoned for 12 s" (CR-004). Without `part.id` it is one reasoning part per turn. It ends with
+     * `part.done`, when another kind of part arrives, or with the turn; `part.duration` (seconds)
+     * replaces the time Agentico measures. */
+    onReasoning(text: string, part?: AgentExecutorPartOptions & {
+        duration?: number;
+    }): void;
+    /** A step of the agent: added the first time its id is seen, updated after. Consecutive steps
+     * are shown as one collapsible group. */
+    onStep(step: AgentExecutorStep): void;
+    /** Questions to the person, answered with a click (CR-004). The promise resolves with the
+     * answers if they come while this turn is still running (e.g. the session waits for them);
+     * once the turn has ended (or the chat was reloaded), the answers arrive as a new turn with
+     * `answers` instead. It rejects when the person stops the turn. `part.id` names the set
+     * (default: made up by Agentico) and is the `answers.id` of that later turn. */
+    onQuestions(questions: AgentQuestion[], part?: {
+        id?: string;
+    }): Promise<AgentQuestionAnswer[]>;
+}
+/** Which part an `onText`/`onReasoning` call updates, and whether it is complete. */
+export interface AgentExecutorPartOptions {
+    /** The part to update: created the first time it is seen. */
+    id?: string;
+    /** The part is complete: no longer streaming. */
+    done?: boolean;
+}
+/** The host side of a remote agent: one call per turn, resolved when its reply is complete. */
+export interface AgentExecutor<TParams, TContext, TResult> {
+    turn(turn: AgentExecutorTurn<TParams, TContext>): Promise<{
+        text: string;
+        result?: TResult;
+    }>;
+    /** The models the person can pick in the composer, at any time: what one means is the host's
+     * (e.g. the model of the remote session from the next message). Absent = no picker. */
+    models?(params: TParams): Array<{
+        label: string;
+        value: string;
+        group?: string;
+    }>;
+    /** The model picked at first, e.g. the one the remote session runs with. */
+    defaultModel?(params: TParams): string | undefined;
 }

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

@@ -1,4 +1,5 @@
 import type { AIConversationTurn } from '@llmnative/react';
+import type { AgentMessagePart } from './messageParts';
 /** 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
@@ -10,6 +11,10 @@ export interface EntityChatActivityEntry {
     status: 'running' | 'done' | 'error' | 'stopped';
     detail?: string;
     toolNames?: string[];
+    attachmentNames?: string[];
+    /** The message in parts (CR-004): saved and reloaded as they are. Absent in chats saved before
+     * 0.3.0, which show `detail` as before. */
+    parts?: AgentMessagePart[];
 }
 export interface EntityChatSnapshot {
     /** Host scope (tenant, company…) the chat belongs to — see AgenticoScope. */
@@ -46,3 +51,7 @@ export declare function removeEntityChat(scopeId: string, subagentId: string, en
  * (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[];
+/** The id of the Agentico task of the chat of an entity: the same when the chat is resumed from
+ * the history and when a page starts it again (AgenticoContext.startSubagent), so it stays one
+ * task (CR-003). */
+export declare const entityChatTaskId: (subagentId: string, entityId: string) => string;

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

@@ -0,0 +1,79 @@
+/** A choice of a question (the shape of the `question` tool of opencode and of MCP elicitation). */
+export interface AgentQuestionOption {
+    /** What the answer says: it is the value returned when chosen. */
+    label: string;
+    /** A line under the label. */
+    description?: string;
+}
+/** A question of the agent to the person. */
+export interface AgentQuestion {
+    /** Returned with the answer, to match it to the question. */
+    id?: string;
+    /** Short title: the label of its tab. */
+    header?: string;
+    question: string;
+    /** The choices. Without them the question takes a free-text answer. */
+    options?: AgentQuestionOption[];
+    /** More than one choice. */
+    multiple?: boolean;
+    /** The choice the agent recommends: its index (from 0) or its label. */
+    recommended?: number | string;
+    /** Offers "Other" with a free-text answer (default: yes). */
+    custom?: boolean;
+}
+/** The answer to one question: the chosen labels and/or the free text, in the order of the questions. */
+export interface AgentQuestionAnswer {
+    id?: string;
+    header?: string;
+    values: string[];
+}
+/** The answers to a set of questions, as a turn gives them to the executor. `id` is the id of the
+ * questions part (the one given to `onQuestions`, or the one Agentico made up). */
+export interface AgentQuestionsAnswers {
+    id: string;
+    answers: AgentQuestionAnswer[];
+}
+/** Text of the reply, as Markdown. `streaming` while it is still arriving. */
+export interface AgentTextPart {
+    type: 'text';
+    id: string;
+    text: string;
+    streaming?: boolean;
+}
+/** The reasoning of the model, as Markdown, shown closed behind "Reasoned for 12 s". */
+export interface AgentReasoningPart {
+    type: 'reasoning';
+    id: string;
+    text: string;
+    streaming?: boolean;
+    /** Seconds the model reasoned: given by the executor, or measured by Agentico. */
+    duration?: number;
+}
+/** A step of the agent (a tool it ran, a file it wrote). Consecutive steps are shown as one group. */
+export interface AgentToolPart {
+    type: 'tool';
+    id: string;
+    label: string;
+    status: 'running' | 'done' | 'error' | 'stopped';
+}
+/** Questions to the person, answered with a click. `answers` once answered (shown read-only). */
+export interface AgentQuestionsPart {
+    type: 'questions';
+    id: string;
+    questions: AgentQuestion[];
+    answers?: AgentQuestionAnswer[];
+}
+export type AgentMessagePart = AgentTextPart | AgentReasoningPart | AgentToolPart | AgentQuestionsPart;
+/** The id of the text part of an executor that calls `onText` without an id (the reply of CR-003). */
+export declare const DEFAULT_TEXT_PART_ID = "text";
+/** The id of the reasoning part of an executor that calls `onReasoning` without an id. */
+export declare const DEFAULT_REASONING_PART_ID = "reasoning";
+/** Adds `part`, or replaces the part of the same type and id. A new step or reasoning goes above the
+ * default text part, so the reply (as in CR-003) stays below the work that led to it; anything else
+ * is appended. `closeReasoning` closes the reasoning still streaming when a part of another type
+ * arrives (the model moved on), with its duration. */
+export declare function upsertMessagePart(parts: AgentMessagePart[], part: AgentMessagePart, closeReasoning?: (part: AgentReasoningPart) => AgentReasoningPart): AgentMessagePart[];
+/** The text of a message: its text parts, one paragraph each (what `AgentActivityEntry.detail` holds). */
+export declare function messagePartsText(parts: readonly AgentMessagePart[]): string;
+/** The answers as one line per question ("Database: Postgres"), for the history of the chat. */
+export declare function formatQuestionAnswers(questions: readonly AgentQuestion[], answers: readonly AgentQuestionAnswer[]): string;

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

@@ -157,6 +157,20 @@ export interface SubagentManifest<TParams = any, TContext = any, TResult = any>
      * 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>;
+    /** The entity a chat of this subagent belongs to, from its raw params (e.g. the project it
+     * designs): when set, SubagentRunner saves the chat after every turn under it (see
+     * entityChatStore), so it is in the history and can be resumed on that entity (CR-003).
+     * Absent = saved only when the host commits it (commitEntityChat), as before. */
+    chatEntityId?(params: Record<string, unknown>): string | undefined;
+    /** true = the orchestrator offers this subagent only when the conversation is scoped to it,
+     * i.e. a component anchored to it is on the page (CR-003): a subagent that makes sense on
+     * one page only (e.g. the design of the project open there). Absent = offered everywhere. */
+    onlyWhenAnchored?: boolean;
+    /** Archiving a chat of this subagent from the history (CR-003): what the host does besides
+     * taking it off the history, e.g. close the remote session. A rejection keeps the chat. */
+    onArchive?(entityId: string, params: Record<string, unknown>): Promise<void> | void;
+    /** The question asked before archiving, if any (e.g. "close it without a pull request?"). */
+    confirmArchive?(entityId: string, params: Record<string, unknown>): Promise<string | undefined> | string | undefined;
 }
 /** Coppia di messaggi per UN punto di ancoraggio componente↔subagent (vedi
  * SubagentManifest.componentContexts) — due pubblici diversi per lo stesso aggancio, mai lo

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

@@ -31,6 +31,12 @@ export interface AgenticoDict {
     tooManyToolTurns: string;
     aiDisabledFallback: string;
     continueWithoutAiFallback: string;
+    /** The group of the steps of the agent, when it holds one step. */
+    oneStep: string;
+    /** The group of the steps of the agent. `{count}` = number of steps */
+    steps: string;
+    /** Accessible name of the group of the steps. */
+    stepsLabel: string;
     /** `{label}` = subagent label */
     newInstance: string;
     chatHistory: string;
@@ -39,6 +45,8 @@ export interface AgenticoDict {
     messagePlaceholder: string;
     unsavedConversationConfirm: string;
     noSavedChats: string;
+    /** Archives a chat of the history (CR-003). */
+    archiveChat: string;
     noResults: string;
     retry: string;
     /** User message sent to the model by the retry button */

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 import './i18n/types';
-export type { AgentDefinition, AgentTool, LatestAttachmentsRef } from './domain/agentDefinition';
+export type { AgentDefinition, AgentTool, LatestAttachmentsRef, AgentExecutor, AgentExecutorTurn, AgentExecutorStep, AgentExecutorPartOptions } from './domain/agentDefinition';
+export { DEFAULT_TEXT_PART_ID, DEFAULT_REASONING_PART_ID, upsertMessagePart, messagePartsText, formatQuestionAnswers, type AgentMessagePart, type AgentTextPart, type AgentReasoningPart, type AgentToolPart, type AgentQuestionsPart, type AgentQuestion, type AgentQuestionOption, type AgentQuestionAnswer, type AgentQuestionsAnswers, } from './domain/messageParts';
 export type { SubagentCommand, SubagentManifest, SubagentComponentContext } from './domain/subagentManifest';
 export { defineSubagent } from './domain/defineSubagent';
 export { registerSubagents, getSubagentRegistry, findSubagentManifest } from './domain/subagentRegistry';
@@ -14,7 +15,7 @@ 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 { configureEntityChatStore, saveEntityChat, getEntityChat, listEntityChats, removeEntityChat, entityChatTaskId, 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';
@@ -23,3 +24,4 @@ export { useAgent, type AgentActivityEntry, type AgentConversation, type UseAgen
 export { useAgenticoPageContext } from './presentation/useAgenticoPageContext';
 export { useSubagentComponentContext } from './presentation/useSubagentComponentContext';
 export { registerSubagentReports, getSubagentReport, type EditableReportModule, type SubagentReportModule, type SubagentSelection, } from './presentation/reports/subagentReportRegistry';
+export { registerSubagentControls, getSubagentControls, type SubagentControls, type SubagentControlsProps, type UseSubagentControls } from './presentation/subagentControls';

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

@@ -1,9 +1,21 @@
-import React from 'react';
 import type { AgentActivityEntry } from './useAgent';
+import type { AgentQuestionAnswer } from '../domain/messageParts';
+/** What the log needs to let the person answer questions (CR-004): the entries of the live
+ * conversation (`canAnswer`) and where the answers go. Without it, unanswered questions are shown
+ * disabled. */
+export interface AgentActivityLogQuestions {
+    canAnswer: (entryId: string) => boolean;
+    onAnswer: (entryId: string, partId: string, answers: AgentQuestionAnswer[]) => Promise<unknown>;
+}
 /** 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 }: {
+ * per l'icon-system e la logica "sto pensando" transitorio/collassabile.
+ *
+ * One `<li>` per turn (CR-004): the message of the person, sticky at the top while its turn
+ * scrolls, then what the agent did and said. Entries before the first message of the person
+ * (an opening without text) form a turn of their own, without a bubble. */
+export declare function AgentActivityLog({ activity, questions }: {
     activity: AgentActivityEntry[];
-}): React.JSX.Element | null;
+    questions?: AgentActivityLogQuestions;
+}): import("react").JSX.Element | null;

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { AIModelDescriptor, DataProviderAdapter, StorageProviderAdapter } from '@llmnative/react';
+import type { AIModelDescriptor, ChatbotAction, DataProviderAdapter, StorageProviderAdapter } from '@llmnative/react';
 import type { AgentActivityEntry, AgentConversation } from './useAgent';
 import type { ResultDestination } from '../domain/resultDestination';
 import type { SubagentUsageCard } from '../domain/subagentUsageCard';
@@ -94,6 +94,11 @@ export interface AgenticoTask<TResult = unknown> {
      * top=vecchio/bottom=nuovo (bug segnalato). Assente = comportamento invariato, sempre in
      * fondo (equivalente a passare la lunghezza corrente del log). */
     panelExtraAnchorIndex?: number;
+    /** What the host shows at the bottom of the panel, above the composer, while the task is open
+     * (see registerSubagentControls, CR-003). */
+    panelActions?: React.ReactNode;
+    /** Buttons of the host in the composer (see registerSubagentControls, CR-003). */
+    composerActions?: ChatbotAction[];
     /** 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
@@ -296,6 +301,22 @@ interface AgenticoContextValue {
      * indietro", niente eccezione per un task ancora in corso (deliberatamente semplice,
      * raffinabile in seguito). No-op se non c'è alcun task. */
     dismissForeignTask: () => void;
+    /** Starts a subagent from a page, without the orchestrator (CR-003): it replaces the current
+     * task. `taskId` keeps one task per entity (start it again = the same task); `openingMessage`
+     * is shown as the first message of the person and given to the first turn. */
+    startSubagent: (subagentId: string, params: Record<string, unknown>, options?: {
+        taskId?: string;
+        openingMessage?: string;
+    }) => void;
+    /** Present = a startSubagent() is pending, read by Agentico.tsx to mount its SubagentRunner. */
+    pendingStart: {
+        subagentId: string;
+        params: Record<string, unknown>;
+        taskId?: string;
+        openingMessage?: string;
+    } | null;
+    /** Changes at every startSubagent() — React `key` of that SubagentRunner. */
+    startRunId: string | null;
 }
 export declare function AgenticoProvider({ children, scope }: {
     children: React.ReactNode;

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

@@ -2,20 +2,7 @@ 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, }: {
+export declare function SubagentRunner({ manifest, params, extraDestinations, precedingActivity, taskId: taskIdProp, resumeSeed, model, openingMessage, }: {
     manifest: SubagentManifest<any, any, any>;
     params: Record<string, unknown>;
     /** Destinazioni scoped alla pagina che ha avviato questo run (es. "Applica a questo Site
@@ -45,4 +32,7 @@ export declare function SubagentRunner({ manifest, params, extraDestinations, pr
      * 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;
+    /** The first message of the person, when a page starts the subagent directly
+     * (AgenticoContext.startSubagent, CR-003): shown in the log and given to the first turn. */
+    openingMessage?: string;
 }): null;

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

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import type { ChatbotAction } from '@llmnative/react';
+/** What the controls of a subagent receive (CR-003). */
+export interface SubagentControlsProps {
+    /** The raw params the subagent was started with. */
+    params: Record<string, unknown>;
+    /** The id of the task in the Agentico panel. */
+    taskId: string;
+    /** A turn is running: actions that would interrupt it should wait. */
+    running: boolean;
+    /** Ends the task (stops a running turn and closes it). */
+    close: () => void;
+}
+/** The controls of a task: actions of the prompt, and what the host shows above it (a modal, a message). */
+export interface SubagentControls {
+    /** Buttons of the composer, next to the attachments (`ChatbotAction` with `onClick`). */
+    actions?: ChatbotAction[];
+    /** Shown above the composer while the task is open. */
+    content?: ReactNode;
+}
+/**
+ * A React hook of the host: called by the runner of each task of its subagent, on every render.
+ * Its `actions` and `content` must keep their identity while nothing changes (`useMemo`): a new
+ * one registers the task again, and a new one at every render would never stop.
+ */
+export type UseSubagentControls = (props: SubagentControlsProps) => SubagentControls;
+export declare function registerSubagentControls(controls: Record<string, UseSubagentControls>): void;
+export declare function getSubagentControls(subagentId: string): UseSubagentControls | undefined;

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

@@ -1,5 +1,6 @@
 import type { AIConversationTurn, AIModelDescriptor } from '@llmnative/react';
 import type { AgentDefinition } from '../domain/agentDefinition';
+import { type AgentMessagePart, type AgentQuestionAnswer } from '../domain/messageParts';
 /** Una voce del log di attività — o un messaggio dell'utente (il testo di sendMessage(),
  * mostrato subito com'è, mai "sto pensando" perché non è il modello a scriverlo), o una tool
  * call (etichetta SEMPRE deterministica/locale, vedi AgentTool.describeInvocation: mai testo
@@ -36,6 +37,10 @@ export interface AgentActivityEntry {
      * doveva fidarsi a memoria (bug osservato: un allegato sembrava "sparito" perché non
      * c'era traccia visiva che fosse mai arrivato). */
     attachmentNames?: string[];
+    /** On the turns of a remote agent (CR-004): the message in parts (text, reasoning, steps,
+     * questions), in the order they arrived. `detail` still holds its text. Absent on the turns of
+     * the AI provider and on chats saved before 0.3.0, shown from `detail` as before. */
+    parts?: AgentMessagePart[];
 }
 /** Stato di gating/selezione — non generico, condiviso dal componente <AgentControls />
  * (che non ha bisogno di conoscere TParams/TResult, solo di disegnare switch + select). */
@@ -54,6 +59,15 @@ export interface UseAgentResult<TParams, TResult> extends AgentControlState {
     /** true dopo che run() ha eseguito almeno un turno con AI abilitata — solo allora la
      * conversazione ha una history su cui sendMessage() può continuare. */
     canContinue: boolean;
+    /** true when the turns go to `AgentDefinition.executor` (CR-003): no attachments, no
+     * deterministic fallback; the models are the executor's (`remoteModels`), not the catalog. */
+    remote: boolean;
+    /** The models a remote executor offers (`AgentExecutor.models`); `selectedModel` is one of them. */
+    remoteModels: Array<{
+        label: string;
+        value: string;
+        group?: string;
+    }>;
     /** Log delle tool call della sessione corrente, più recenti in fondo — azzerato a ogni
      * run(), accumulato attraverso i sendMessage() successivi. */
     activity: AgentActivityEntry[];
@@ -130,11 +144,17 @@ export interface UseAgentResult<TParams, TResult> extends AgentControlState {
         history: AIConversationTurn[];
         activity: AgentActivityEntry[];
     } | null;
+    /** Answers the questions part `partId` of the entry `entryId` (CR-004). If the turn that asked
+     * is still waiting, its `onQuestions` promise resolves; otherwise a new turn of the executor
+     * carries them (`AgentExecutorTurn.answers`, with empty `text`). Either way the part keeps the
+     * answers and shows them read-only. Resolves with the result of that new turn, if any; rejects
+     * (leaving the form open) when another turn is running or the entry is not of this conversation. */
+    answerQuestions: (entryId: string, partId: string, answers: AgentQuestionAnswer[]) => Promise<TResult | null>;
 }
 /** Solo la fetta di UseAgentResult che serve a un consumer del pannello globale (Agentico.tsx)
  * per continuare una conversazione già avviata da run() — TParams non compare in nessuno dei
  * membri qui sotto, quindi `never` è innocuo. */
-export type AgentConversation<TResult> = Pick<UseAgentResult<never, TResult>, 'canContinue' | 'running' | 'error' | 'activity' | 'sendMessage' | 'stop' | 'runFallback' | 'snapshot'>;
+export type AgentConversation<TResult> = Pick<UseAgentResult<never, TResult>, 'canContinue' | 'remote' | 'remoteModels' | 'running' | 'error' | 'activity' | 'sendMessage' | 'stop' | 'runFallback' | 'snapshot' | 'answerQuestions'>;
 export declare function useAgent<TParams, TContext, TResult>(definition: AgentDefinition<TParams, TContext, TResult>, options?: {
     defaultEnabled?: boolean;
 }): UseAgentResult<TParams, TResult>;

package/llms.txt

@@ -6,9 +6,11 @@
 
 ## Host responsibilities (startup)
 
-- `registerSubagents(manifests)` — SubagentManifest: id, label, icon, description, indexPath, commands (name, summary, Zod inputSchema, describeOutput), definition (AgentDefinition), toParams, destinationIds, optional crossAgentToolIds, withCollected, manualEntry, componentContexts.
+- `registerSubagents(manifests)` — SubagentManifest: id, label, icon, description, indexPath, commands (name, summary, Zod inputSchema, describeOutput), definition (AgentDefinition), toParams, destinationIds, optional crossAgentToolIds, withCollected, manualEntry, componentContexts, chatEntityId (chat saved at every turn under that entity), onlyWhenAnchored (offered by the orchestrator only when scoped to it).
 - `registerDestinations({ id: ResultDestination })` — apply(result, { scopeId, dataProvider, storageProvider, proxyFetch }, meta).
 - `registerSubagentReports({ subagentId: SubagentReportModule })`.
+- `registerSubagentControls({ subagentId: useControls })` — a hook of the host per task (props: params, taskId, running, close) returning `{ actions?: ChatbotAction[] (with onClick), content?: ReactNode }`, memoized: actions in the prompt, content above it.
+- `SubagentManifest.onArchive(entityId, params)` / `confirmArchive(entityId, params)` — archiving a chat from the history (hover icon).
 - `registerCrossAgentTools((ctx) => AgentTool[])` — ctx: attachmentsRef, collected (per-conversation scratchpad), proxyFetch.
 - `configureAgenticoPrompts(partial)` — model-facing pack; `agenticoPromptsEn` (default) / `agenticoPromptsIt`.
 - `configureEntityChatStore({ storageKey })`.
@@ -25,11 +27,15 @@
 
 ## Hooks
 
-- `useAgentico()` — panel state, `startOrchestrator(goal, opts)`, `commitEntityChat(subagentId, entityId, taskId, scopeId, params, title)`, `scope`.
+- `useAgentico()` — panel state, `startOrchestrator(goal, opts)`, `startSubagent(subagentId, params, { taskId?, openingMessage? })` (use `entityChatTaskId(subagentId, entityId)` as taskId), `resumeEntityChat`, `commitEntityChat(subagentId, entityId, taskId, scopeId, params, title)`, `scope`.
 - `useAgenticoPageContext(text, card?)` — what the user is looking at.
 - `useSubagentComponentContext(subagentId, componentKey)` — anchor a component to a subagent.
 - `useAgent(definition)` — run an AgentDefinition directly.
 
 ## AgentDefinition
 
-buildContext (always runs) · buildPrompt · buildFollowUpPrompt · parseResponse (null → fallback) · fallback (required) · describeFallback? · getTools? · microPromptIds?
+buildContext (always runs) · buildPrompt · buildFollowUpPrompt · parseResponse (null → fallback) · fallback (required) · describeFallback? · getTools? · microPromptIds? · executor?
+
+`executor.turn({ params, context, text, first, signal, model?, onText(whole reply so far), onStep({ id, label, status }) }) → { text, result? }`; `executor.models(params)` / `defaultModel(params)` put the models of the executor in the composer: the turns go to the host instead of the AI provider; `text` is what the person typed (opening message on the first turn). The conversation is `remote: true`: no attachments, no fallback; the picker shows `remoteModels`.
+
+Message parts (0.3.0): the turn also has `onText(text, { id?, done? })` (without id: the one reply, kept below steps and reasoning; with id: a text part of its own), `onReasoning(text, { id?, done?, duration? })` (whole text so far; shown closed, "Reasoned for N s", duration measured if not given), `onQuestions(questions, { id? }) → Promise<answers>` (questions `{ id?, header?, question, options?: [{ label, description? }], multiple?, recommended?, custom? }`; answers `[{ id?, header?, values: string[] }]`). Answers given while the turn runs resolve that promise; given later (or after a reload) they start a new turn with `text: ''` and `answers: { id, answers }` (id = the questions part id, default `questions-N`). Parts are kept in `AgentActivityEntry.parts` (`text` | `reasoning` | `tool` | `questions`, `detail` = the text) and saved with the chat; old chats without parts show `detail`. Rendered with `ChatMarkdown`, `ChatReasoning`, steps grouped in a `Tree`, `ChatQuestions` (needs `@llmnative/react` 1.34). `useAgent().answerQuestions(entryId, partId, answers)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmnative/agentico",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agentic chat orchestrator for @llmnative/react apps: a persistent panel that talks with the user and hands the work to host-registered subagents.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "packageManager": "npm@11.11.0",
   "peerDependencies": {
-    "@llmnative/react": "^1.20.0",
+    "@llmnative/react": "^1.34.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "zod": "^3.24.1"
@@ -57,7 +57,7 @@
     "zod-to-json-schema": "^3.24.1"
   },
   "devDependencies": {
-    "@llmnative/react": "^1.20.0",
+    "@llmnative/react": "^1.34.0",
     "@phosphor-icons/react": "^2.1.10",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",