@personaai/react 0.8.1 → 0.10.0

package/dist/index.d.ts

@@ -197,6 +197,12 @@ interface PersonaMemoryList {
  * and `REASONING_END` rather than `REASONING_MESSAGE_END`).
  */
 type PersonaStreamingEvent = {
+    type: "RUN_STARTED";
+    threadId?: string;
+    runId?: string;
+} | {
+    type: "RUN_FINISHED";
+} | {
     type: "TEXT_MESSAGE_CHUNK";
     delta: string;
     messageId?: string;
@@ -272,6 +278,29 @@ type PersonaStreamingEvent = {
         resourceUri: string;
         mcpId: string;
     };
+} | {
+    type: "CUSTOM";
+    name: "workflow_node_started";
+    value: {
+        nodeId: string;
+        nodeType: string;
+        nodeLabel: string;
+        input?: unknown;
+    };
+} | {
+    type: "CUSTOM";
+    name: "workflow_node_completed";
+    value: {
+        nodeId: string;
+        output: unknown;
+    };
+} | {
+    type: "CUSTOM";
+    name: "workflow_node_failed";
+    value: {
+        nodeId: string;
+        error: string;
+    };
 } | {
     type: "CUSTOM";
     name: string & {};
@@ -314,6 +343,28 @@ interface UseChatOptions {
      */
     context?: Record<string, unknown> | (() => Record<string, unknown>);
 }
+interface UseArchitectChatOptions {
+    threadId?: string;
+    initialMessages?: PersonaMessage[];
+    onFinish?: (message: PersonaMessage) => void;
+    onError?: (error: Error) => void;
+    /** Hook for receiving every low-level AG-UI streaming event (tool calls, steps, subagents) */
+    onEvent?: (event: PersonaStreamingEvent) => void;
+    /** Called when a fake/ephemeral chat mints a real thread on first send. Use to sync sidebar state (e.g. setThreadId(id)). */
+    onThreadCreated?: (threadId: string) => void;
+    /** Called when the backend auto-generates a thread title (3-4 word LLM summary of first user message). */
+    onTitle?: (title: string) => void;
+}
+interface SendArchitectMessageOverride {
+    /**
+     * A plain id, or a promise/thunk for one still in flight (e.g. a thread
+     * being lazily created for the first message of a new conversation).
+     * Mirrors {@link SendMessageOverride.threadId}.
+     */
+    threadId?: string | Promise<string | undefined>;
+    /** Answers/approves a paused interrupt from a previous turn instead of starting a fresh one. */
+    resume?: PersonaResumeValue;
+}
 interface SendMessageOverride {
     agentId?: string;
     /**
@@ -426,6 +477,149 @@ interface UseVoiceResult {
      */
     updateContext: (context: Record<string, unknown>) => void;
 }
+type PersonaWorkflowNodeType = "trigger" | "agent" | "tool" | "condition" | "parallel" | "code" | "human_review" | (string & {});
+interface PersonaWorkflowNode {
+    id: string;
+    type: PersonaWorkflowNodeType;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: Record<string, unknown>;
+}
+interface PersonaWorkflowEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    label?: string;
+}
+interface PersonaWorkflowTrigger {
+    type: "manual" | "webhook" | "schedule" | "event" | (string & {});
+    config?: Record<string, unknown>;
+}
+interface PersonaWorkflowDraft {
+    nodes: PersonaWorkflowNode[];
+    edges: PersonaWorkflowEdge[];
+    triggers?: PersonaWorkflowTrigger[];
+    settings?: Record<string, unknown>;
+}
+interface PersonaWorkflowSummary {
+    _id: string;
+    name: string;
+    slug?: string;
+    description?: string;
+    status: "draft" | "published" | "archived";
+    visibility?: "private" | "public";
+    activeVersion?: number;
+    tags?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface PersonaWorkflow extends PersonaWorkflowSummary {
+    draft: PersonaWorkflowDraft;
+    triggers?: PersonaWorkflowTrigger[];
+    ownerId?: string;
+    projectId?: string;
+}
+interface PersonaWorkflowVersionSummary {
+    _id: string;
+    workflowId: string;
+    version: number;
+    summary?: string;
+    createdAt: string;
+}
+interface PersonaWorkflowRunSummary {
+    _id: string;
+    workflowId: string;
+    version: number;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled";
+    startedAt?: string;
+    finishedAt?: string;
+    durationMs?: number;
+    error?: string;
+    isDryRun?: boolean;
+    createdAt: string;
+}
+interface PersonaNodeRunState {
+    nodeId: string;
+    nodeType: string;
+    nodeLabel: string;
+    status: "idle" | "running" | "completed" | "failed";
+    startedAt?: string;
+    finishedAt?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+}
+interface CreateWorkflowInput {
+    name: string;
+    description?: string;
+    slug?: string;
+    draft?: PersonaWorkflowDraft;
+    triggers?: PersonaWorkflowTrigger[];
+    visibility?: "private" | "public";
+    tags?: string[];
+}
+type UpdateWorkflowInput = Partial<CreateWorkflowInput>;
+interface UseWorkflowsOptions {
+    autoFetch?: boolean;
+    search?: string;
+    status?: string;
+    page?: number;
+    limit?: number;
+}
+interface UseWorkflowOptions {
+    autoFetch?: boolean;
+}
+interface UseWorkflowStreamOptions {
+    workflowId?: string;
+    onNodeStarted?: (node: {
+        nodeId: string;
+        nodeType: string;
+        nodeLabel: string;
+        input?: unknown;
+    }) => void;
+    onNodeCompleted?: (node: {
+        nodeId: string;
+        output: unknown;
+    }) => void;
+    onNodeFailed?: (node: {
+        nodeId: string;
+        error: string;
+    }) => void;
+    onFinish?: (result: {
+        runId: string;
+        output: unknown;
+        text: string;
+    }) => void;
+    onError?: (error: Error) => void;
+    onEvent?: (event: PersonaStreamingEvent) => void;
+}
+interface UseWorkflowStreamResult {
+    runId: string | null;
+    status: "idle" | "running" | "completed" | "failed" | "cancelled";
+    isRunning: boolean;
+    activeNodeId: string | null;
+    nodeRuns: Record<string, PersonaNodeRunState>;
+    text: string;
+    output: unknown;
+    error: Error | null;
+    events: PersonaStreamingEvent[];
+    start: (input?: unknown, options?: {
+        dryRun?: boolean;
+        workflowId?: string;
+    }) => Promise<unknown>;
+    cancel: () => Promise<void>;
+    resume: (runId: string, sinceSeq?: number) => Promise<void>;
+    reset: () => void;
+}
+interface UseWorkflowRunsOptions {
+    autoFetch?: boolean;
+    page?: number;
+    limit?: number;
+}
 
 interface PersonaContextValue {
     baseUrl: string;
@@ -466,6 +660,61 @@ declare function useChat(options?: UseChatOptions): {
     loadThreadMessages: (id: string) => Promise<PersonaMessage[]>;
 };
 
+/**
+ * The Developer Platform Architect's own reserved Agent id
+ * (`DEVELOPER_ARCHITECT_AGENT_ID` in agent-backend/src/modules/agents/
+ * architectConstants.js) — it isn't a row in the Agent collection, but the
+ * backend's `POST /api/v1/developer/threads` special-cases exactly this id
+ * past its usual Agent-existence check (see developerThread.controller.js's
+ * `assertAgentAccessible`), so a named Architect Thread can be created the
+ * same way as for a real Agent. Kept in sync with that backend constant —
+ * update both together if it ever changes.
+ */
+declare const ARCHITECT_AGENT_ID = "000000000000000000000002";
+/**
+ * Runs the Agent Architect co-pilot — a conversational tool-calling agent
+ * that creates/edits the caller's own Agents (`manage_agent`, `manage_skill`,
+ * etc.), reached over the runtime's `POST /architect` route (see
+ * `@personaai/runtime`'s `routes/architect.ts`). Structurally a trimmed
+ * `useChat`: same streaming/interrupt/reload/thread-resume mechanics, but
+ * with no `agentId` to pass (the Architect is a single fixed target) and no
+ * `voice`/`sandboxCommands` (the Architect has no voice mode and no
+ * `execute` tool).
+ *
+ * `threadId` resume only has an effect when the underlying credential
+ * asserts an external user — a bare Project credential has no Subject for a
+ * Thread to belong to, so the backend silently keeps its single
+ * deterministic per-Project conversation either way (see
+ * `developerArchitect.controller.js`'s doc comment).
+ */
+declare function useArchitectChat(options?: UseArchitectChatOptions): {
+    messages: PersonaMessage[];
+    input: string;
+    setInput: react.Dispatch<react.SetStateAction<string>>;
+    handleInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    handleSubmit: (e?: React.FormEvent) => void;
+    sendMessage: (contentToSend?: string, overrideOptions?: SendArchitectMessageOverride) => Promise<boolean>;
+    isStreaming: boolean;
+    isLoading: boolean;
+    isLoadingHistory: boolean;
+    error: Error | null;
+    interrupt: PersonaInterrupt | null;
+    resumeInterrupt: (resume: PersonaResumeValue, displayContent: string) => Promise<boolean>;
+    files: Record<string, PersonaWorkspaceFile>;
+    todos: PersonaTodo[];
+    presentedFile: PersonaPresentedFile | null;
+    dismissPresentedFile: () => void;
+    openWorkspaceFile: (path: string) => void;
+    stop: () => void;
+    reload: () => Promise<boolean>;
+    clear: () => void;
+    startNewChat: () => void;
+    currentThreadId: string | undefined;
+    isEphemeral: boolean;
+    setMessages: react.Dispatch<react.SetStateAction<PersonaMessage[]>>;
+    loadThreadMessages: (id: string) => Promise<PersonaMessage[]>;
+};
+
 declare function useMemory(autoFetch?: boolean): {
     memory: PersonaMemoryList;
     isLoading: boolean;
@@ -633,6 +882,52 @@ declare function useMcp(options?: UseMcpOptions): {
     callTool: (name: string, args?: Record<string, unknown>, mcpId?: string) => Promise<any>;
 };
 
+interface WorkflowsPagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+declare function useWorkflows(options?: UseWorkflowsOptions | boolean): {
+    workflows: PersonaWorkflowSummary[];
+    pagination: WorkflowsPagination;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<PersonaWorkflowSummary[]>;
+    createWorkflow: (input: CreateWorkflowInput) => Promise<PersonaWorkflow>;
+};
+
+declare function useWorkflow(workflowId: string, options?: UseWorkflowOptions | boolean): {
+    workflow: PersonaWorkflow | null;
+    versions: PersonaWorkflowVersionSummary[];
+    mermaid: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<PersonaWorkflow | null>;
+    fetchVersions: () => Promise<PersonaWorkflowVersionSummary[]>;
+    fetchMermaid: () => Promise<any>;
+    saveDraft: (draft: PersonaWorkflowDraft) => Promise<PersonaWorkflow>;
+    publish: (summary?: string) => Promise<PersonaWorkflowVersionSummary>;
+    deleteWorkflow: () => Promise<void>;
+};
+
+declare function useWorkflowStream(workflowId?: string, options?: UseWorkflowStreamOptions): UseWorkflowStreamResult;
+
+declare function useWorkflowRuns(workflowId?: string, options?: UseWorkflowRunsOptions | boolean): {
+    runs: PersonaWorkflowRunSummary[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<PersonaWorkflowRunSummary[]>;
+    getRun: (runId: string) => Promise<PersonaWorkflowRunSummary>;
+    cancelRun: (runId: string) => Promise<void>;
+};
+
 /**
  * SSE transport for chat streams, with a React Native fallback.
  *
@@ -671,7 +966,8 @@ interface SSEStream {
 interface OpenSSEOptions {
     url: string;
     headers: Record<string, string>;
-    body: string;
+    body?: string;
+    method?: "GET" | "POST";
     signal?: AbortSignal;
 }
 /**
@@ -689,6 +985,6 @@ declare function supportsStreamingFetch(): boolean;
  */
 declare function openSSEStream(opts: OpenSSEOptions): Promise<SSEStream>;
 
-declare const VERSION = "0.8.1";
+declare const VERSION = "0.10.0";
 
-export { type OpenSSEOptions, type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaSandboxCommand, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendMessageOverride, type UseChatOptions, type UseMcpConnectionsOptions, type UseMcpOptions, type UseVoiceOptions, type UseVoiceResult, VERSION, openSSEStream, supportsStreamingFetch, useAgents, useChat, useConnection, useFiles, useMcp, useMcpConnections, useMemory, usePersonaContext, useThreads, useVoice };
+export { ARCHITECT_AGENT_ID, type CreateWorkflowInput, type OpenSSEOptions, type PersonaAgentSummary, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaNodeRunState, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaResumeValue, type PersonaRole, type PersonaSandboxCommand, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkflow, type PersonaWorkflowDraft, type PersonaWorkflowEdge, type PersonaWorkflowNode, type PersonaWorkflowNodeType, type PersonaWorkflowRunSummary, type PersonaWorkflowSummary, type PersonaWorkflowTrigger, type PersonaWorkflowVersionSummary, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendArchitectMessageOverride, type SendMessageOverride, type UpdateWorkflowInput, type UseArchitectChatOptions, type UseChatOptions, type UseMcpConnectionsOptions, type UseMcpOptions, type UseVoiceOptions, type UseVoiceResult, type UseWorkflowOptions, type UseWorkflowRunsOptions, type UseWorkflowStreamOptions, type UseWorkflowStreamResult, type UseWorkflowsOptions, VERSION, type WorkflowsPagination, openSSEStream, supportsStreamingFetch, useAgents, useArchitectChat, useChat, useConnection, useFiles, useMcp, useMcpConnections, useMemory, usePersonaContext, useThreads, useVoice, useWorkflow, useWorkflowRuns, useWorkflowStream, useWorkflows };