@llmnative/agentico 0.3.0 → 0.4.0

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

@@ -55,6 +55,14 @@ export interface AgenticoDict {
     resumeWithAi: string;
     openPanel: string;
     closePanel: string;
+    /** Accessible name of the edge that resizes the panel. */
+    resizePanel: string;
+    /** Tooltip of that edge. */
+    resizePanelHint: string;
+    /** Accessible name of the questions docked at the bottom of the panel. */
+    pendingQuestions: string;
+    /** Stops the turn while its questions are docked (the composer, with its stop button, is hidden). */
+    stop: string;
 }
 declare module '@llmnative/react' {
     interface I18nDict {

package/dist/types/index.d.ts

@@ -17,7 +17,8 @@ export { jsonExportDestination, JSON_EXPORT_DESTINATION_ID } from './domain/json
 export { registerDestinations, getDestinationRegistry } from './domain/destinationRegistry';
 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 { Agentico, AGENTICO_WIDTH, type AgenticoProps } from './presentation/Agentico';
+export { AGENTICO_MIN_WIDTH, AGENTICO_MAX_WIDTH, AGENTICO_WIDTH_STORAGE_KEY, type AgenticoPanelSize } from './presentation/panelWidth';
 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';

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

@@ -1,5 +1,5 @@
 import type { AgentActivityEntry } from './useAgent';
-import type { AgentQuestionAnswer } from '../domain/messageParts';
+import type { AgentQuestionAnswer, AgentQuestionsPart } 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. */
@@ -7,6 +7,25 @@ export interface AgentActivityLogQuestions {
     canAnswer: (entryId: string) => boolean;
     onAnswer: (entryId: string, partId: string, answers: AgentQuestionAnswer[]) => Promise<unknown>;
 }
+/** The questions part shown docked at the bottom of the panel instead of in the thread (CR-005). */
+export interface DockedQuestions {
+    entry: AgentActivityEntry;
+    part: AgentQuestionsPart;
+}
+/** The questions waiting for an answer in the latest message of the agent (CR-005): the last
+ * questions part without answers of the last entry, when that entry is a message in parts of a turn
+ * that did not stop or fail, and the person can answer it. Otherwise nothing is docked and the
+ * questions stay in the thread (read-only once answered). */
+export declare function findDockedQuestions(activity: readonly AgentActivityEntry[], canAnswer: (entryId: string) => boolean): DockedQuestions | null;
+/** A questions part of the agent with `ChatQuestions`: answerable while the entry is live and it has
+ * no answers, read-only with its answers, disabled otherwise. */
+export declare function QuestionsPart({ entry, part, questions, autoFocus, className }: {
+    entry: AgentActivityEntry;
+    part: AgentQuestionsPart;
+    questions?: AgentActivityLogQuestions;
+    autoFocus?: boolean;
+    className?: string;
+}): import("react").JSX.Element;
 /** 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
@@ -15,7 +34,12 @@ export interface AgentActivityLogQuestions {
  * 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 }: {
+export declare function AgentActivityLog({ activity, questions, docked, pinUserMessages }: {
     activity: AgentActivityEntry[];
     questions?: AgentActivityLogQuestions;
+    /** Questions docked at the bottom of the panel (CR-005): left out of the thread. */
+    docked?: DockedQuestions | null;
+    /** The message of the person sticks at the top while its turn scrolls (default). Off while
+     * questions are docked, so the thread has more room. */
+    pinUserMessages?: boolean;
 }): import("react").JSX.Element | null;

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

@@ -1,7 +1,17 @@
 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;
+import { AGENTICO_WIDTH, type AgenticoPanelSize } from './panelWidth';
+export { AGENTICO_WIDTH };
+/** Props of the panel (CR-005): its width, which the person changes by dragging its inner edge. */
+export interface AgenticoProps {
+    /** Width when nothing is stored, and after a double click on the edge. Default `AGENTICO_WIDTH` (420 px). */
+    defaultWidth?: number;
+    /** Narrowest width, in px. Default 320. */
+    minWidth?: number;
+    /** Widest width: px, or a share of the viewport (`'60vw'`, the default). */
+    maxWidth?: AgenticoPanelSize;
+    /** The current width, whenever it changes (e.g. for the `rightInset` of a Modal beside the panel). */
+    onWidthChange?: (width: number) => void;
+}
 /** 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
@@ -20,4 +30,4 @@ export declare const AGENTICO_WIDTH = 420;
  * (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;
+export declare function Agentico({ defaultWidth, minWidth, maxWidth, onWidthChange }?: AgenticoProps): React.JSX.Element;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+/** The inner edge of the Agentico column (CR-005), the one facing the page: dragged with the
+ * pointer it resizes the panel; focused, the arrow keys do (Shift for bigger steps, Home/End for
+ * the minimum/maximum); a double click goes back to the default width. The framework has no
+ * splitter primitive, so this one is drawn with theme tokens only: a thin line in the primary
+ * colour on hover, focus and while dragging. The panel sits on the right, so moving the edge to
+ * the left makes it wider. */
+export declare function AgenticoResizeHandle({ width, min, max, onResize, onCommit, onReset }: {
+    width: number;
+    min: number;
+    max: number;
+    /** A new width while it changes (clamped by the caller). */
+    onResize: (width: number) => void;
+    /** The width the person settled on: stored. */
+    onCommit: (width: number) => void;
+    onReset: () => void;
+}): React.JSX.Element;

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

@@ -0,0 +1,32 @@
+/** Default width of the panel, in px. Also the `rightInset` a host can give a Modal that must leave it room. */
+export declare const AGENTICO_WIDTH = 420;
+/** Default minimum width of the panel, in px. */
+export declare const AGENTICO_MIN_WIDTH = 320;
+/** Default maximum width of the panel: a share of the viewport. */
+export declare const AGENTICO_MAX_WIDTH = "60vw";
+/** Where the width chosen by the person is kept, per browser. */
+export declare const AGENTICO_WIDTH_STORAGE_KEY = "agentico:panel-width";
+/** One arrow key press, in px (with Shift: four times as much). */
+export declare const AGENTICO_WIDTH_STEP = 16;
+/** A width in px, or a share of the viewport (`'60vw'`). */
+export type AgenticoPanelSize = number | `${number}vw`;
+/** A size in px: a number as it is, `'<n>vw'` as that share of `viewportWidth`. */
+export declare function resolvePanelSize(size: AgenticoPanelSize, viewportWidth: number): number;
+/** `width` kept between `min` and `max` (a max below the min gives way to the min). */
+export declare function clampPanelWidth(width: number, min: number, max: number): number;
+export interface PanelWidthOptions {
+    defaultWidth?: number;
+    minWidth?: number;
+    maxWidth?: AgenticoPanelSize;
+    onWidthChange?: (width: number) => void;
+}
+/** The width of the panel: the stored one or the default, clamped to the current viewport. `set`
+ * changes it (clamped), `commit` stores it, `reset` goes back to the default and forgets it. */
+export declare function usePanelWidth({ defaultWidth, minWidth, maxWidth, onWidthChange }: PanelWidthOptions): {
+    width: number;
+    min: number;
+    max: number;
+    set: (next: number) => void;
+    commit: (next: number) => void;
+    reset: () => void;
+};

package/llms.txt

@@ -1,41 +1,43 @@
-# @llmnative/agentico
-
-> Agentic chat orchestrator for @llmnative/react apps. A persistent panel: the orchestrator
-> collects parameters in conversation and hands the work to host-registered subagents. Every
-> subagent has a deterministic fallback. Agentico knows nothing concrete about the host.
-
-## 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, 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 })`.
-- i18n: merge `agenticoTranslations.<locale>` into `<App i18n={{ translations }}>`; override any `agentico.*` key.
-
-## Mount
-
-```tsx
-<AgenticoProvider scope={{ id, dataProvider, storageProvider } | null}>
-  <AgenticoToggle />
-  <Agentico />
-</AgenticoProvider>
-```
-
-## Hooks
-
-- `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? · 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)`.
+# @llmnative/agentico
+
+> Agentic chat orchestrator for @llmnative/react apps. A persistent panel: the orchestrator
+> collects parameters in conversation and hands the work to host-registered subagents. Every
+> subagent has a deterministic fallback. Agentico knows nothing concrete about the host.
+
+## 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, 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 })`.
+- i18n: merge `agenticoTranslations.<locale>` into `<App i18n={{ translations }}>`; override any `agentico.*` key.
+
+## Mount
+
+```tsx
+<AgenticoProvider scope={{ id, dataProvider, storageProvider } | null}>
+  <AgenticoToggle />
+  <Agentico />
+</AgenticoProvider>
+```
+
+`<Agentico defaultWidth? minWidth? maxWidth? onWidthChange? />` (0.4.0): the column is resized by dragging its inner edge (a `role="separator"`: arrows by 16 px, Shift ×4, Home/End, double click = default), clamped to `minWidth` (320) … `maxWidth` (px or `'<n>vw'`, default `'60vw'`), stored per browser under `agentico:panel-width`. Defaults `AGENTICO_WIDTH` (420), `AGENTICO_MIN_WIDTH`, `AGENTICO_MAX_WIDTH`. Unanswered questions of the latest agent message (turn not stopped/failed) are docked at the bottom in place of the composer (scroll inside, Stop while the turn runs), the person's message is not pinned meanwhile; once answered they are back in the thread, read-only. Questions of a reloaded chat are answerable (docked) too.
+
+## Hooks
+
+- `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? · 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.3.0",
+  "version": "0.4.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",