@personaai/react 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -2,12 +2,22 @@ import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 
 type PersonaRole = 'user' | 'assistant' | 'system';
+/** One live update on a running `task` (subagent) tool call's timeline. */
+interface PersonaSubagentActivityEntry {
+    kind: 'text' | 'tool_start' | 'tool_result';
+    toolName?: string;
+    args?: string;
+    result?: string;
+    delta?: string;
+}
 interface PersonaToolCall {
     toolCallId: string;
     toolName: string;
     args?: string;
     result?: string;
     isError?: boolean;
+    /** Nested activity timeline — only present on `task` (subagent) tool calls. */
+    subagentActivity?: PersonaSubagentActivityEntry[];
 }
 interface PersonaMessage {
     id: string;
@@ -16,7 +26,40 @@ interface PersonaMessage {
     createdAt: Date;
     isStreaming?: boolean;
     toolCalls?: PersonaToolCall[];
+    /** Model reasoning/thinking text streamed ahead of the final answer, when the provider exposes it. */
+    reasoning?: string;
+    isReasoning?: boolean;
+}
+interface PersonaHitlActionRequest {
+    name: string;
+    args?: unknown;
+}
+interface PersonaClarificationQuestion {
+    id: string;
+    text: string;
+    options: string[];
+    required: boolean;
+    allowCustom: boolean;
 }
+/** A paused human-in-the-loop tool approval, or a paused clarification question. */
+type PersonaInterrupt = {
+    kind: 'hitl';
+    actionRequests: PersonaHitlActionRequest[];
+    reviewConfigs: unknown[];
+} | {
+    kind: 'clarification';
+    questions: PersonaClarificationQuestion[];
+};
+/** What to send back in `sendMessage(content, { resume })` to unpause a paused run. */
+type PersonaResumeValue = {
+    decisions: Array<{
+        type: 'approve' | 'reject';
+        message?: string;
+    }>;
+} | {
+    answers: unknown[];
+    text?: string;
+};
 interface PersonaProviderProps {
     /** Base URL where the Persona runtime / adapter is mounted, e.g. "http://localhost:4000/api/persona" */
     baseUrl: string;
@@ -28,73 +71,130 @@ interface PersonaProviderProps {
 }
 interface PersonaThread {
     _id: string;
-    agentId: string;
+    /** A bare id string on create()/get(); populated as an object on list(). */
+    agentId: string | {
+        _id: string;
+        name: string;
+        avatar?: string;
+        slug: string;
+    };
     title?: string;
     isArchived?: boolean;
     createdAt: string;
     updatedAt: string;
 }
+/** Mirrors the wire shape of `GET/POST /files` — `id`, not `_id`. */
+interface PersonaFileItem {
+    id: string;
+    originalName: string;
+    mimeType: string;
+    /** Bytes. */
+    size: number;
+    agentId: string | null;
+    threadId: string | null;
+    createdAt: string;
+}
 interface PersonaMemoryFile {
+    scope?: 'user' | 'agent';
+    agentId?: string;
     path: string;
     content: string;
+    mimeType?: string;
+    createdAt?: string;
     updatedAt?: string;
 }
+/** One agent's group of agent-scoped memory files, as returned by `GET /memory`. */
+interface PersonaMemoryAgentGroup {
+    agentId: string;
+    /** `null` if the agent no longer exists. */
+    agentName: string | null;
+    files: PersonaMemoryFile[];
+}
 interface PersonaMemoryList {
-    user: Array<{
-        path: string;
-        size?: number;
-        updatedAt?: string;
-    }>;
-    agents: Record<string, Array<{
-        path: string;
-        size?: number;
-        updatedAt?: string;
-    }>>;
+    userFiles: PersonaMemoryFile[];
+    agentMemories: PersonaMemoryAgentGroup[];
 }
-/** AG-UI Streaming Protocol Event types emitted during streaming */
+/**
+ * AG-UI protocol events emitted during streaming — mirrors exactly what
+ * `aguiTranslator.js` produces server-side (verified against that file, not
+ * guessed from the AG-UI spec: this backend only emits a subset, and uses
+ * `TOOL_CALL_CHUNK` rather than separate START/ARGS events for tool calls,
+ * and `REASONING_END` rather than `REASONING_MESSAGE_END`).
+ */
 type PersonaStreamingEvent = {
     type: 'TEXT_MESSAGE_CHUNK';
     delta: string;
     messageId?: string;
+    role?: 'assistant';
 } | {
-    type: 'TOOL_CALL_START';
-    toolCallId: string;
-    toolName: string;
+    type: 'TOOL_CALL_CHUNK';
+    toolCallId?: string;
+    toolCallName?: string;
+    delta?: string;
     parentMessageId?: string;
-} | {
-    type: 'TOOL_CALL_ARGS';
-    toolCallId: string;
-    delta: string;
 } | {
     type: 'TOOL_CALL_RESULT';
     toolCallId: string;
-    result: string;
-    isError?: boolean;
+    content: string;
+    messageId?: string;
+    role?: 'tool';
+    structuredContent?: unknown;
 } | {
-    type: 'RUN_STARTED';
-    runId: string;
-    threadId?: string;
+    type: 'REASONING_MESSAGE_START';
+    messageId: string;
+} | {
+    type: 'REASONING_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'REASONING_END';
 } | {
-    type: 'RUN_FINISHED';
-    runId: string;
-    tokenUsage?: {
-        promptTokens?: number;
-        completionTokens?: number;
+    type: 'STATE_SNAPSHOT';
+    snapshot: {
+        files: Record<string, unknown>;
+        todos: Array<{
+            content: string;
+            status: string;
+        }>;
     };
 } | {
     type: 'RUN_ERROR';
     code: string;
     message: string;
+    retryable?: boolean;
+    providerName?: string;
 } | {
-    type: 'STEP_STARTED';
-    stepName: string;
+    type: 'CUSTOM';
+    name: 'hitl_request';
+    value: {
+        actionRequests: PersonaHitlActionRequest[];
+        reviewConfigs: unknown[];
+    };
 } | {
-    type: 'STEP_FINISHED';
-    stepName: string;
+    type: 'CUSTOM';
+    name: 'clarification_request';
+    value: {
+        questions: PersonaClarificationQuestion[];
+        currentIndex: number;
+    };
 } | {
     type: 'CUSTOM';
-    name: string;
-    payload: unknown;
+    name: 'subagent_activity';
+    value: {
+        toolCallId: string;
+    } & PersonaSubagentActivityEntry;
+} | {
+    type: 'CUSTOM';
+    name: 'mcp_app';
+    value: {
+        toolCallId: string;
+        resourceUri: string;
+        mcpId: string;
+    };
+} | {
+    type: 'CUSTOM';
+    name: string & {};
+    value: unknown;
 };
 interface UseChatOptions {
     agentId?: string;
@@ -105,6 +205,12 @@ interface UseChatOptions {
     /** Hook for receiving every low-level AG-UI streaming event (tool calls, steps, subagents) */
     onEvent?: (event: PersonaStreamingEvent) => void;
 }
+interface SendMessageOverride {
+    agentId?: string;
+    threadId?: string;
+    /** Answers/approves a paused interrupt from a previous turn instead of starting a fresh one. */
+    resume?: PersonaResumeValue;
+}
 
 interface PersonaContextValue {
     baseUrl: string;
@@ -121,17 +227,18 @@ declare function useChat(options?: UseChatOptions): {
     setInput: react.Dispatch<react.SetStateAction<string>>;
     handleInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
     handleSubmit: (e?: React.FormEvent) => void;
-    sendMessage: (contentToSend?: string, overrideOptions?: {
-        agentId?: string;
-        threadId?: string;
-    }) => Promise<void>;
+    sendMessage: (contentToSend?: string, overrideOptions?: SendMessageOverride) => Promise<void>;
     isStreaming: boolean;
     isLoading: boolean;
+    isLoadingHistory: boolean;
     error: Error | null;
+    interrupt: PersonaInterrupt | null;
+    resumeInterrupt: (resume: PersonaResumeValue, displayContent: string) => Promise<void>;
     stop: () => void;
     reload: () => void;
     clear: () => void;
     setMessages: react.Dispatch<react.SetStateAction<PersonaMessage[]>>;
+    loadThreadMessages: (id: string) => Promise<PersonaMessage[]>;
 };
 
 declare function useMemory(autoFetch?: boolean): {
@@ -161,44 +268,60 @@ declare function useThreads(autoFetch?: boolean): {
     threads: PersonaThread[];
     isLoading: boolean;
     error: Error | null;
-    refetch: () => Promise<any>;
+    refetch: () => Promise<PersonaThread[]>;
     createThread: (agentId?: string) => Promise<PersonaThread>;
     deleteThread: (threadId: string) => Promise<void>;
+    bulkDeleteThreads: (threadIds: string[]) => Promise<{
+        deleted: string[];
+        failed: Array<{
+            id: string;
+            reason: string;
+        }>;
+    }>;
+    deleteAllThreads: () => Promise<void>;
+    updateThread: (threadId: string, input: {
+        title?: string;
+        isArchived?: boolean;
+    }) => Promise<PersonaThread>;
+    renameThread: (threadId: string, title: string) => Promise<PersonaThread>;
+    getThread: (threadId: string) => Promise<PersonaThread>;
 };
 
-interface PersonaFileItem {
-    _id: string;
-    filename: string;
-    contentType?: string;
-    sizeBytes?: number;
-    createdAt: string;
-}
 declare function useFiles(autoFetch?: boolean): {
     files: PersonaFileItem[];
     isLoading: boolean;
     isUploading: boolean;
     error: Error | null;
-    refetch: () => Promise<any>;
+    refetch: () => Promise<PersonaFileItem[]>;
     uploadFile: (fileOrFormData: FormData | {
         name: string;
         uri: string;
         type?: string;
     }) => Promise<PersonaFileItem>;
     deleteFile: (fileId: string) => Promise<void>;
+    bulkDeleteFiles: (fileIds: string[]) => Promise<{
+        deleted: string[];
+        failed: Array<{
+            id: string;
+            reason: string;
+        }>;
+    }>;
     getDownloadUrl: (fileId: string) => string;
 };
 
 interface PersonaAgentSummary {
     _id: string;
     name: string;
+    slug: string;
     description?: string;
-    avatarUrl?: string;
+    tagline?: string;
+    avatar?: string;
 }
 declare function useAgents(autoFetch?: boolean): {
     agents: PersonaAgentSummary[];
     isLoading: boolean;
     error: Error | null;
-    refetch: () => Promise<any>;
+    refetch: () => Promise<PersonaAgentSummary[]>;
 };
 
 interface PersonaHealthInfo {
@@ -213,6 +336,6 @@ declare function useConnection(autoCheck?: boolean): {
     checkHealth: () => Promise<PersonaHealthInfo | null>;
 };
 
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.2.0";
 
-export { type PersonaAgentSummary, type PersonaFileItem, type PersonaHealthInfo, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, PersonaProvider, type PersonaProviderProps, type PersonaRole, type PersonaStreamingEvent, type PersonaThread, type PersonaToolCall, type UseChatOptions, VERSION, useAgents, useChat, useConnection, useFiles, useMemory, usePersonaContext, useThreads };
+export { type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaToolCall, type SendMessageOverride, type UseChatOptions, VERSION, useAgents, useChat, useConnection, useFiles, useMemory, usePersonaContext, useThreads };

package/dist/index.d.ts

@@ -2,12 +2,22 @@ import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 
 type PersonaRole = 'user' | 'assistant' | 'system';
+/** One live update on a running `task` (subagent) tool call's timeline. */
+interface PersonaSubagentActivityEntry {
+    kind: 'text' | 'tool_start' | 'tool_result';
+    toolName?: string;
+    args?: string;
+    result?: string;
+    delta?: string;
+}
 interface PersonaToolCall {
     toolCallId: string;
     toolName: string;
     args?: string;
     result?: string;
     isError?: boolean;
+    /** Nested activity timeline — only present on `task` (subagent) tool calls. */
+    subagentActivity?: PersonaSubagentActivityEntry[];
 }
 interface PersonaMessage {
     id: string;
@@ -16,7 +26,40 @@ interface PersonaMessage {
     createdAt: Date;
     isStreaming?: boolean;
     toolCalls?: PersonaToolCall[];
+    /** Model reasoning/thinking text streamed ahead of the final answer, when the provider exposes it. */
+    reasoning?: string;
+    isReasoning?: boolean;
+}
+interface PersonaHitlActionRequest {
+    name: string;
+    args?: unknown;
+}
+interface PersonaClarificationQuestion {
+    id: string;
+    text: string;
+    options: string[];
+    required: boolean;
+    allowCustom: boolean;
 }
+/** A paused human-in-the-loop tool approval, or a paused clarification question. */
+type PersonaInterrupt = {
+    kind: 'hitl';
+    actionRequests: PersonaHitlActionRequest[];
+    reviewConfigs: unknown[];
+} | {
+    kind: 'clarification';
+    questions: PersonaClarificationQuestion[];
+};
+/** What to send back in `sendMessage(content, { resume })` to unpause a paused run. */
+type PersonaResumeValue = {
+    decisions: Array<{
+        type: 'approve' | 'reject';
+        message?: string;
+    }>;
+} | {
+    answers: unknown[];
+    text?: string;
+};
 interface PersonaProviderProps {
     /** Base URL where the Persona runtime / adapter is mounted, e.g. "http://localhost:4000/api/persona" */
     baseUrl: string;
@@ -28,73 +71,130 @@ interface PersonaProviderProps {
 }
 interface PersonaThread {
     _id: string;
-    agentId: string;
+    /** A bare id string on create()/get(); populated as an object on list(). */
+    agentId: string | {
+        _id: string;
+        name: string;
+        avatar?: string;
+        slug: string;
+    };
     title?: string;
     isArchived?: boolean;
     createdAt: string;
     updatedAt: string;
 }
+/** Mirrors the wire shape of `GET/POST /files` — `id`, not `_id`. */
+interface PersonaFileItem {
+    id: string;
+    originalName: string;
+    mimeType: string;
+    /** Bytes. */
+    size: number;
+    agentId: string | null;
+    threadId: string | null;
+    createdAt: string;
+}
 interface PersonaMemoryFile {
+    scope?: 'user' | 'agent';
+    agentId?: string;
     path: string;
     content: string;
+    mimeType?: string;
+    createdAt?: string;
     updatedAt?: string;
 }
+/** One agent's group of agent-scoped memory files, as returned by `GET /memory`. */
+interface PersonaMemoryAgentGroup {
+    agentId: string;
+    /** `null` if the agent no longer exists. */
+    agentName: string | null;
+    files: PersonaMemoryFile[];
+}
 interface PersonaMemoryList {
-    user: Array<{
-        path: string;
-        size?: number;
-        updatedAt?: string;
-    }>;
-    agents: Record<string, Array<{
-        path: string;
-        size?: number;
-        updatedAt?: string;
-    }>>;
+    userFiles: PersonaMemoryFile[];
+    agentMemories: PersonaMemoryAgentGroup[];
 }
-/** AG-UI Streaming Protocol Event types emitted during streaming */
+/**
+ * AG-UI protocol events emitted during streaming — mirrors exactly what
+ * `aguiTranslator.js` produces server-side (verified against that file, not
+ * guessed from the AG-UI spec: this backend only emits a subset, and uses
+ * `TOOL_CALL_CHUNK` rather than separate START/ARGS events for tool calls,
+ * and `REASONING_END` rather than `REASONING_MESSAGE_END`).
+ */
 type PersonaStreamingEvent = {
     type: 'TEXT_MESSAGE_CHUNK';
     delta: string;
     messageId?: string;
+    role?: 'assistant';
 } | {
-    type: 'TOOL_CALL_START';
-    toolCallId: string;
-    toolName: string;
+    type: 'TOOL_CALL_CHUNK';
+    toolCallId?: string;
+    toolCallName?: string;
+    delta?: string;
     parentMessageId?: string;
-} | {
-    type: 'TOOL_CALL_ARGS';
-    toolCallId: string;
-    delta: string;
 } | {
     type: 'TOOL_CALL_RESULT';
     toolCallId: string;
-    result: string;
-    isError?: boolean;
+    content: string;
+    messageId?: string;
+    role?: 'tool';
+    structuredContent?: unknown;
 } | {
-    type: 'RUN_STARTED';
-    runId: string;
-    threadId?: string;
+    type: 'REASONING_MESSAGE_START';
+    messageId: string;
+} | {
+    type: 'REASONING_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+} | {
+    type: 'REASONING_END';
 } | {
-    type: 'RUN_FINISHED';
-    runId: string;
-    tokenUsage?: {
-        promptTokens?: number;
-        completionTokens?: number;
+    type: 'STATE_SNAPSHOT';
+    snapshot: {
+        files: Record<string, unknown>;
+        todos: Array<{
+            content: string;
+            status: string;
+        }>;
     };
 } | {
     type: 'RUN_ERROR';
     code: string;
     message: string;
+    retryable?: boolean;
+    providerName?: string;
 } | {
-    type: 'STEP_STARTED';
-    stepName: string;
+    type: 'CUSTOM';
+    name: 'hitl_request';
+    value: {
+        actionRequests: PersonaHitlActionRequest[];
+        reviewConfigs: unknown[];
+    };
 } | {
-    type: 'STEP_FINISHED';
-    stepName: string;
+    type: 'CUSTOM';
+    name: 'clarification_request';
+    value: {
+        questions: PersonaClarificationQuestion[];
+        currentIndex: number;
+    };
 } | {
     type: 'CUSTOM';
-    name: string;
-    payload: unknown;
+    name: 'subagent_activity';
+    value: {
+        toolCallId: string;
+    } & PersonaSubagentActivityEntry;
+} | {
+    type: 'CUSTOM';
+    name: 'mcp_app';
+    value: {
+        toolCallId: string;
+        resourceUri: string;
+        mcpId: string;
+    };
+} | {
+    type: 'CUSTOM';
+    name: string & {};
+    value: unknown;
 };
 interface UseChatOptions {
     agentId?: string;
@@ -105,6 +205,12 @@ interface UseChatOptions {
     /** Hook for receiving every low-level AG-UI streaming event (tool calls, steps, subagents) */
     onEvent?: (event: PersonaStreamingEvent) => void;
 }
+interface SendMessageOverride {
+    agentId?: string;
+    threadId?: string;
+    /** Answers/approves a paused interrupt from a previous turn instead of starting a fresh one. */
+    resume?: PersonaResumeValue;
+}
 
 interface PersonaContextValue {
     baseUrl: string;
@@ -121,17 +227,18 @@ declare function useChat(options?: UseChatOptions): {
     setInput: react.Dispatch<react.SetStateAction<string>>;
     handleInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
     handleSubmit: (e?: React.FormEvent) => void;
-    sendMessage: (contentToSend?: string, overrideOptions?: {
-        agentId?: string;
-        threadId?: string;
-    }) => Promise<void>;
+    sendMessage: (contentToSend?: string, overrideOptions?: SendMessageOverride) => Promise<void>;
     isStreaming: boolean;
     isLoading: boolean;
+    isLoadingHistory: boolean;
     error: Error | null;
+    interrupt: PersonaInterrupt | null;
+    resumeInterrupt: (resume: PersonaResumeValue, displayContent: string) => Promise<void>;
     stop: () => void;
     reload: () => void;
     clear: () => void;
     setMessages: react.Dispatch<react.SetStateAction<PersonaMessage[]>>;
+    loadThreadMessages: (id: string) => Promise<PersonaMessage[]>;
 };
 
 declare function useMemory(autoFetch?: boolean): {
@@ -161,44 +268,60 @@ declare function useThreads(autoFetch?: boolean): {
     threads: PersonaThread[];
     isLoading: boolean;
     error: Error | null;
-    refetch: () => Promise<any>;
+    refetch: () => Promise<PersonaThread[]>;
     createThread: (agentId?: string) => Promise<PersonaThread>;
     deleteThread: (threadId: string) => Promise<void>;
+    bulkDeleteThreads: (threadIds: string[]) => Promise<{
+        deleted: string[];
+        failed: Array<{
+            id: string;
+            reason: string;
+        }>;
+    }>;
+    deleteAllThreads: () => Promise<void>;
+    updateThread: (threadId: string, input: {
+        title?: string;
+        isArchived?: boolean;
+    }) => Promise<PersonaThread>;
+    renameThread: (threadId: string, title: string) => Promise<PersonaThread>;
+    getThread: (threadId: string) => Promise<PersonaThread>;
 };
 
-interface PersonaFileItem {
-    _id: string;
-    filename: string;
-    contentType?: string;
-    sizeBytes?: number;
-    createdAt: string;
-}
 declare function useFiles(autoFetch?: boolean): {
     files: PersonaFileItem[];
     isLoading: boolean;
     isUploading: boolean;
     error: Error | null;
-    refetch: () => Promise<any>;
+    refetch: () => Promise<PersonaFileItem[]>;
     uploadFile: (fileOrFormData: FormData | {
         name: string;
         uri: string;
         type?: string;
     }) => Promise<PersonaFileItem>;
     deleteFile: (fileId: string) => Promise<void>;
+    bulkDeleteFiles: (fileIds: string[]) => Promise<{
+        deleted: string[];
+        failed: Array<{
+            id: string;
+            reason: string;
+        }>;
+    }>;
     getDownloadUrl: (fileId: string) => string;
 };
 
 interface PersonaAgentSummary {
     _id: string;
     name: string;
+    slug: string;
     description?: string;
-    avatarUrl?: string;
+    tagline?: string;
+    avatar?: string;
 }
 declare function useAgents(autoFetch?: boolean): {
     agents: PersonaAgentSummary[];
     isLoading: boolean;
     error: Error | null;
-    refetch: () => Promise<any>;
+    refetch: () => Promise<PersonaAgentSummary[]>;
 };
 
 interface PersonaHealthInfo {
@@ -213,6 +336,6 @@ declare function useConnection(autoCheck?: boolean): {
     checkHealth: () => Promise<PersonaHealthInfo | null>;
 };
 
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.2.0";
 
-export { type PersonaAgentSummary, type PersonaFileItem, type PersonaHealthInfo, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, PersonaProvider, type PersonaProviderProps, type PersonaRole, type PersonaStreamingEvent, type PersonaThread, type PersonaToolCall, type UseChatOptions, VERSION, useAgents, useChat, useConnection, useFiles, useMemory, usePersonaContext, useThreads };
+export { type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaToolCall, type SendMessageOverride, type UseChatOptions, VERSION, useAgents, useChat, useConnection, useFiles, useMemory, usePersonaContext, useThreads };