@foris/ai-agent 1.0.8 → 1.1.1

package/dist/api/chatStream.types.d.ts

@@ -1,8 +1,3 @@
-/**
- * Raw event shapes as sent by the backend over the SSE stream.
- * Update this type when the backend contract changes, then adjust
- * chatStreamAdapter.ts accordingly — nothing else needs to change.
- */
 export type RawBackendEvent = {
     type: 'message_chunk';
     content: string;
@@ -20,4 +15,18 @@ export type RawBackendEvent = {
     tool_call_id?: string;
     display_name?: string;
     message?: string;
+} | {
+    type: 'render_not_front';
+    id: string;
+    display: unknown;
+} | {
+    type: 'stop';
+    chat_id?: string;
+    references: Record<string, unknown>;
+} | {
+    type: 'remove_not_front';
+    id: string;
+} | {
+    type: 'error';
+    error: 'resume_timeout' | (string & {});
 };

package/dist/api/chatStreamAdapter.d.ts

@@ -1,8 +1,18 @@
 import type { ChatMessage } from '../types/chat';
 import type { RawBackendEvent } from './chatStream.types';
 export type MessageListUpdater = (prev: ChatMessage[]) => ChatMessage[];
+/**
+ * Updater that removes the not-front payload with the given id from any
+ * assistant message. Shared by the `remove_not_front` SSE event and the
+ * pause-expiry path (which dismisses the stale card locally using the
+ * `render_id` carried in the `stop` references).
+ */
+export declare function removeNotFrontPayload(id: string): MessageListUpdater;
 /**
  * Maps a raw backend event to a pure state updater function.
  * Returns null for events that require no state change.
+ *
+ * `stop` is NOT handled here: it is a flow-control event resolved by
+ * `useSplitChunks` (like `[DONE]`), not a message-list update.
  */
 export declare function adaptBackendEvent(event: RawBackendEvent): MessageListUpdater | null;

package/dist/components/ai-elements/message-code-block.d.ts

@@ -1,7 +1,18 @@
 import React from 'react';
+import type { CodeBlockLanguage } from './code-block';
 export declare const PreWrapper: ({ children }: {
     children: React.ReactNode;
 }) => import("react/jsx-runtime").JSX.Element;
+export type ChatCodeBlockProps = {
+    code: string;
+    language: CodeBlockLanguage;
+    className?: string;
+    bodyClassName?: string;
+    showCopy?: boolean;
+    copyDisabled?: boolean;
+};
+/** Styled code block shared by markdown messages and tool trace panels. */
+export declare const ChatCodeBlock: React.MemoExoticComponent<({ code, language, className, bodyClassName, showCopy, copyDisabled, }: ChatCodeBlockProps) => import("react/jsx-runtime").JSX.Element>;
 /** Props from react-markdown for the code component */
 export type MessageCodeBlockProps = React.ComponentProps<'code'>;
 /**

package/dist/components/chat-panel/chat-panel/ChatPanel.d.ts

@@ -2,6 +2,7 @@ import type { FC } from 'react';
 import { type AiAgentTheme, type ResolveSyntaxAppearanceFn } from '@/context/AiAgentThemeContext';
 import type { SuggestionType } from '../../../types/chat';
 import type { DataSource } from '../../../types/dataSource';
+import type { RenderNotFront } from '../../../types/notFront';
 import type { ChatPanelTranslations } from './chatPanel.types';
 interface ChatPanelProps extends React.HTMLAttributes<HTMLDivElement> {
     dataSource: DataSource;
@@ -14,15 +15,16 @@ interface ChatPanelProps extends React.HTMLAttributes<HTMLDivElement> {
     theme?: AiAgentTheme;
     /** Optional mapper from theme id to syntax appearance (incl. CodeBlock Shiki light/dark). */
     resolveSyntaxAppearance?: ResolveSyntaxAppearanceFn;
-    /** Called when the user toggles the expand/collapse button. The host can use this to drive `isExpanded` on the containing Drawer. */
+    /** Fired when the user toggles expand/collapse. Use to drive `isExpanded` on a containing Drawer. */
     onExpandedChange?: (expanded: boolean) => void;
-    /**
-     * When `true`, constrains width to the same formula as Drawer `contentWidth="default"`:
-     * `max-width: min(30vw, 507px)` and `min-width: 448px` (desktop). Does not change Drawer; use for standalone previews or hosts that do not wrap the panel in Drawer.
-     *
-     * @default false
-     */
+    /** Constrains width to `min(30vw, 507px)` — same formula as Drawer default. For standalone use outside a Drawer. */
     viewportColumnWidth?: boolean;
+    /** Component that renders `render_not_front` SSE payloads. Import `renderNotFront` from `@foris/avocado-not-front`. */
+    renderNotFront?: RenderNotFront;
+    /** Stable session id sent with every stream POST. Omit to let the panel generate one internally. */
+    chatId?: string;
+    /** Called after the user clears the conversation; receives the new session id. */
+    onChatIdChange?: (nextChatId: string) => void;
 }
 export declare const ChatPanel: FC<ChatPanelProps>;
 export default ChatPanel;

package/dist/components/chat-panel/chat-panel/chatPanel.types.d.ts

@@ -1,5 +1,6 @@
 import type { ToolCall } from '../../../types/chat';
-export type ErrorMessageKind = 'connection' | 'response';
+import type { NotFrontPayload } from '../../../types/notFront';
+export type ErrorMessageKind = 'connection' | 'response' | 'expired';
 export interface ChatPanelTranslations {
     title?: string;
     welcomeTitle?: string;
@@ -8,7 +9,9 @@ export interface ChatPanelTranslations {
     placeholder?: string;
     placeholderProcessing?: string;
     placeholderDisconnected?: string;
+    placeholderWaiting?: string;
     processingTooltip?: string;
+    waitingTooltip?: string;
     sendMessageAriaLabel?: string;
     disclaimer?: string;
     clearChatTitle?: string;
@@ -29,6 +32,7 @@ export interface ChatPanelTranslations {
     errorConnectionInlineRetry?: string;
     errorResponseTitle?: string;
     errorResponseRetry?: string;
+    pauseExpiredMessage?: string;
     thinkingStep1?: string;
     thinkingStep2?: string;
     thinkingUsingTool?: string;
@@ -37,6 +41,7 @@ export interface ChatPanelTranslations {
     reasoningTracePlural?: string;
     reasoningTraceParameters?: string;
     reasoningTraceResult?: string;
+    notFrontErrorLabel?: string;
 }
 export interface UserMessage {
     key: string;
@@ -73,12 +78,14 @@ export interface AssistantMessage {
         duration: number;
     };
     tools?: ToolCall[];
+    notFront?: NotFrontPayload[];
 }
 export interface ErrorMessage {
     key: string;
     from: 'error';
     kind: ErrorMessageKind;
-    failedUserMessageKey: string;
+    /** Absent for `expired` notices — there is no message to retry. */
+    failedUserMessageKey?: string;
 }
 export type MessageType = UserMessage | AssistantMessage | ErrorMessage;
 export declare const isErrorMessage: (message: MessageType) => message is ErrorMessage;

package/dist/components/chat-panel/error-connection-inline/errorConnectionInline.type.d.ts

@@ -3,8 +3,11 @@ export interface ErrorConnectionInlineTranslations {
     retryLabel?: string;
 }
 export interface ErrorConnectionInlineProps {
-    failedUserMessageKey: string;
-    onRetry: (failedUserMessageKey: string) => Promise<void> | void;
+    /** Absent for non-retryable notices (e.g. pause expiry). */
+    failedUserMessageKey?: string;
+    onRetry?: (failedUserMessageKey?: string) => Promise<void> | void;
     translations?: ErrorConnectionInlineTranslations;
     className?: string;
+    /** Hides the retry action — for informational notices like pause expiry. */
+    hideRetry?: boolean;
 }

package/dist/components/chat-panel/footer/footer.type.d.ts

@@ -1,10 +1,17 @@
 /// <reference types="react" />
-export type FooterState = 'idle' | 'processing' | 'disconnected';
+/**
+ * `waiting`: the agent paused mid-turn (stop → resume) and is waiting for the
+ * user to interact with a card in the conversation — input locked like
+ * `processing`, with its own placeholder.
+ */
+export type FooterState = 'idle' | 'processing' | 'disconnected' | 'waiting';
 export interface FooterTranslations {
     placeholderIdle: string;
     placeholderProcessing: string;
     placeholderDisconnected: string;
+    placeholderWaiting?: string;
     processingTooltip: string;
+    waitingTooltip?: string;
     sendMessageAriaLabel: string;
 }
 export interface FooterProps {

package/dist/components/chat-panel/locale/en.json.d.ts

@@ -6,7 +6,9 @@ declare const _default: {
   "placeholder": "Ask or create something...",
   "placeholderProcessing": "Processing request...",
   "placeholderDisconnected": "Not available",
+  "placeholderWaiting": "Waiting for your confirmation...",
   "processingTooltip": "You have a request in progress",
+  "waitingTooltip": "Respond to the pending request to continue",
   "sendMessageAriaLabel": "Send message",
   "disclaimer": "Foris AI may make mistakes. Verify the responses.",
   "clearChatTitle": "Clear current conversation",
@@ -27,6 +29,7 @@ declare const _default: {
   "errorResponseRetry": "Retry",
   "errorConnectionInlineTitle": "We couldn't send your message. Check your connection and try again.",
   "errorConnectionInlineRetry": "Retry",
+  "pauseExpiredMessage": "The request expired. You can keep chatting.",
   "thinkingStep1": "Thinking...",
   "thinkingStep2": "Understanding your request...",
   "thinkingUsingTool": "Using: {tool}",
@@ -34,7 +37,8 @@ declare const _default: {
   "reasoningTraceSingular": "Reasoning · 1 tool used",
   "reasoningTracePlural": "Reasoning · {count} tools used",
   "reasoningTraceParameters": "Parameters",
-  "reasoningTraceResult": "Result"
+  "reasoningTraceResult": "Result",
+  "notFrontErrorLabel": "Unable to display this content."
 }
 ;
 

package/dist/components/chat-panel/locale/es.json.d.ts

@@ -6,7 +6,9 @@ declare const _default: {
   "placeholder": "Pregunta o crea algo...",
   "placeholderProcessing": "Procesando solicitud...",
   "placeholderDisconnected": "No disponible",
+  "placeholderWaiting": "Esperando tu confirmación...",
   "processingTooltip": "Tienes una solicitud en curso",
+  "waitingTooltip": "Responde la solicitud pendiente para continuar",
   "sendMessageAriaLabel": "Enviar mensaje",
   "disclaimer": "Foris AI puede cometer errores. Verifica sus respuestas.",
   "clearChatTitle": "Limpiar conversación actual",
@@ -27,6 +29,7 @@ declare const _default: {
   "errorResponseRetry": "Reintentar",
   "errorConnectionInlineTitle": "No pudimos enviar tu mensaje. Verifica tu conexión e intenta de nuevo.",
   "errorConnectionInlineRetry": "Reintentar",
+  "pauseExpiredMessage": "La solicitud expiró. Puedes seguir conversando.",
   "thinkingStep1": "Pensando...",
   "thinkingStep2": "Entendiendo tu solicitud...",
   "thinkingUsingTool": "Usando: {tool}",
@@ -34,7 +37,8 @@ declare const _default: {
   "reasoningTraceSingular": "Razonamiento · 1 herramienta utilizada",
   "reasoningTracePlural": "Razonamiento · {count} herramientas utilizadas",
   "reasoningTraceParameters": "Parámetros",
-  "reasoningTraceResult": "Resultado"
+  "reasoningTraceResult": "Resultado",
+  "notFrontErrorLabel": "No se pudo mostrar este contenido."
 }
 ;
 

package/dist/components/chat-panel/message-item/MessageItem.d.ts

@@ -1,5 +1,6 @@
 import type { FC } from 'react';
 import type { MessageType } from '../chat-panel/chatPanel.types';
+import type { RenderNotFront } from '../../../types/notFront';
 interface MessageItemProps {
     message: MessageType;
     locale?: 'en' | 'es';
@@ -10,10 +11,13 @@ interface MessageItemProps {
     errorConnectionInlineRetry?: string;
     errorResponseTitle?: string;
     errorResponseRetry?: string;
+    pauseExpiredMessage?: string;
     reasoningTraceSingular?: string;
     reasoningTracePlural?: string;
     reasoningTraceParameters?: string;
     reasoningTraceResult?: string;
+    renderNotFront?: RenderNotFront;
+    notFrontErrorLabel?: string;
 }
 declare const MessageItem: FC<MessageItemProps>;
 export default MessageItem;

package/dist/components/chat-panel/not-front-error-boundary/NotFrontErrorBoundary.d.ts

@@ -0,0 +1,16 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+export interface NotFrontErrorBoundaryProps {
+    payloadId: string;
+    children: ReactNode;
+    label?: string;
+}
+interface NotFrontErrorBoundaryState {
+    hasError: boolean;
+}
+export declare class NotFrontErrorBoundary extends Component<NotFrontErrorBoundaryProps, NotFrontErrorBoundaryState> {
+    state: NotFrontErrorBoundaryState;
+    static getDerivedStateFromError(): NotFrontErrorBoundaryState;
+    componentDidCatch(error: Error, _errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/dist/components/chat-panel/not-front-error-boundary/index.d.ts

@@ -0,0 +1,2 @@
+export { NotFrontErrorBoundary } from './NotFrontErrorBoundary';
+export type { NotFrontErrorBoundaryProps } from './NotFrontErrorBoundary';

package/dist/hooks/chat.constants.d.ts

@@ -1,2 +1,10 @@
-/** Default chat stream identifier shared by useChat and useConnectivityPing. */
+/**
+ * Default chat stream identifier.
+ *
+ * @deprecated Use {@link generateChatId} from `./chat.utils` (or import
+ * `generateChatId` from `@foris/ai-agent`) to mint a unique id per chat
+ * session. This constant remains exported for backwards compatibility with
+ * external consumers but is no longer used inside `useChat` or
+ * `useConnectivityPing`.
+ */
 export declare const DEFAULT_CHAT_STREAM_ID = "demo-123";

package/dist/hooks/chat.utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generates a unique chat session identifier.
+ *
+ * Format: `chat-{base36-timestamp}-{6-char-random-suffix}`
+ * Example: `chat-lqz8kx-a3f9b2`
+ *
+ * Not cryptographic — for UI identity only. Collision probability is
+ * sufficient for distinguishing concurrent chat sessions in the same
+ * browser; do NOT use as a security primitive.
+ */
+export declare const generateChatId: () => string;

package/dist/hooks/chat.utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useChat.d.ts

@@ -1,16 +1,32 @@
 import { ApiManager } from '@foris/mango-core';
 import type { ChatMessage } from '../types/chat';
 import { DEFAULT_CHAT_STREAM_ID } from './chat.constants';
+import { generateChatId } from './chat.utils';
 export interface OnSubmitProps {
     params?: Record<string, unknown>;
     input: string;
 }
 export { DEFAULT_CHAT_STREAM_ID };
-/** When apiManager is passed, streaming uses mango (fetch or axios depending on delegate). */
-export declare const useChat: (api: string, headers?: Record<string, string>, apiManager?: ApiManager) => {
+export { generateChatId };
+/**
+ * When apiManager is passed, streaming uses mango (fetch or axios depending on delegate).
+ *
+ * `chatId` identifies the chat session in the stream POST body and is shared
+ * with `useConnectivityPing` so the backend can correlate ping ↔ stream
+ * traffic. When omitted, an id is generated lazily once per hook instance.
+ *
+ * `resumeUrl` (typically `dataSource.resumeUrl` from the host's ChatPanel
+ * config) enables the pause/resume protocol: when a stream leg ends with
+ * a `stop` control event, a blocking SSE POST `{ chat_id, references }` is
+ * sent there and its continuation flows through the same pipeline. Without
+ * it, a `stop` degrades to an immediate pause expiry (notice + local card
+ * removal) so the conversation stays usable.
+ */
+export declare const useChat: (api: string, headers?: Record<string, string>, apiManager?: ApiManager, chatId?: string, resumeUrl?: string) => {
     onSubmit: ({ params, input }: OnSubmitProps) => Promise<void>;
     messages: ChatMessage[];
     isLoading: boolean;
+    isWaiting: boolean;
     retryLastMessage: (key?: string) => Promise<void>;
     clearMessages: () => void;
     initialLoadError: boolean;

package/dist/hooks/useChat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useConnectivityPing.d.ts

@@ -4,10 +4,11 @@
  */
 export declare const CONNECTIVITY_PROBE_MESSAGE = "[connectivity-probe]";
 /**
- * Same JSON shape as `useChat` / `postStream` (`chat_id` + `message`). When the
- * backend exposes a dedicated ping contract, switch the body / URL here.
+ * Build the JSON body for a connectivity probe with a specific `chat_id`.
+ * Matches the streaming chat payload shape (`chat_id` + `message`) so the
+ * backend can use the same endpoint contract.
  */
-export declare const CONNECTIVITY_PROBE_BODY: string;
+export declare const buildConnectivityProbeBody: (chatId: string) => string;
 /**
  * Stable string for cache keys so the same logical headers map to the same entry.
  * Exported for tests that reset or assert cache behaviour.
@@ -24,4 +25,4 @@ export interface UseConnectivityPingResult {
  * Body matches the streaming chat payload (`chat_id` + `message`) because many backends
  * reject `HEAD` (405). Replace with a dedicated ping payload when the API supports it.
  */
-export declare const useConnectivityPing: (pingUrl?: string, headers?: Record<string, string>) => UseConnectivityPingResult;
+export declare const useConnectivityPing: (pingUrl?: string, headers?: Record<string, string>, chatId?: string) => UseConnectivityPingResult;

package/dist/hooks/useConnectivityPing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useMessageProcessor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useSplitChunks.d.ts

@@ -1,12 +1,39 @@
 import type React from 'react';
 import type { StreamResponse } from '@foris/mango-core';
 import type { ChatMessage } from '../types/chat';
+/**
+ * Terminal state of a stream leg:
+ * - `done`: saw the explicit `[DONE]` sentinel.
+ * - `stopped`: saw a `stop` control event — the agent paused waiting for user
+ *   interaction; `references` must be forwarded to the resume endpoint.
+ * - `resume_timeout`: saw `{ type: "error", error: "resume_timeout" }` on a
+ *   resume leg — the pause expired waiting for user interaction.
+ * - `closed`: EOF without `[DONE]`, `stop`, or `resume_timeout`. Success on
+ *   the primary leg (some backends never send `[DONE]`); also success on a
+ *   resume leg that completed normally after user interaction.
+ */
 export type SplitChunksResult = {
     ok: true;
+    end: 'done' | 'closed';
+} | {
+    ok: true;
+    end: 'stopped';
+    references: Record<string, unknown>;
+} | {
+    ok: true;
+    end: 'resume_timeout';
 } | {
     ok: false;
     error: Error;
 };
+export type SplitChunksOptions = {
+    /**
+     * Fired once when the first event in this leg produces a message-list
+     * update (or plain-text fallback). Used by the resume leg to leave the
+     * user-interaction wait state before the turn finishes.
+     */
+    onContinuationStart?: () => void;
+};
 export declare const useSplitChunks: (setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>) => {
-    splitChunks: (res: StreamResponse) => Promise<SplitChunksResult>;
+    splitChunks: (res: StreamResponse, options?: SplitChunksOptions) => Promise<SplitChunksResult>;
 };

package/dist/hooks/useThinkingPhase.d.ts

@@ -2,6 +2,8 @@ import type { ToolCall } from '../types/chat';
 export type ThinkingPhase = 'idle' | 'thinking' | 'tool' | 'preparing' | 'done';
 interface UseThinkingPhaseOptions {
     isLoading: boolean;
+    /** True while the agent paused for user interaction on a not-front card. */
+    isWaiting?: boolean;
     streamingTools: ToolCall[];
     streamingContent: string;
     labels: {
@@ -15,5 +17,5 @@ interface UseThinkingPhaseResult {
     phase: ThinkingPhase;
     label: string;
 }
-export declare const useThinkingPhase: ({ isLoading, streamingTools, streamingContent, labels, }: UseThinkingPhaseOptions) => UseThinkingPhaseResult;
+export declare const useThinkingPhase: ({ isLoading, isWaiting, streamingTools, streamingContent, labels, }: UseThinkingPhaseOptions) => UseThinkingPhaseResult;
 export {};

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { ChatPanel, type ChatPanelTranslations, type SuggestionType, type AiAgentTheme, type SyntaxAppearance, type ResolveSyntaxAppearanceFn, } from './components/chat-panel';
+export type { NotFrontPayload, RenderNotFront, } from './types/notFront';
+export { generateChatId } from './hooks/chat.utils';
 export { ChatSessionProvider, useChatSession, useChatSessionOptional, type ChatSessionContextValue, type ChatSessionProviderProps, } from './context/ChatSessionContext';
 export { ChatPanelMenu } from './components/ui/ai-chat-panel-menu';
 export { SummaryCard, type SummaryCardProps, type SummaryCardTranslations, type SupportedLocale, } from './components/summary-card';