@nextclaw/agent-chat 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,430 @@
+import { Subscribable, BehaviorSubject, Observable, Subject } from 'rxjs';
+import { JSONSchema7 } from 'json-schema';
+
+declare enum EventType {
+    TEXT_START = "TEXT_START",
+    TEXT_DELTA = "TEXT_DELTA",
+    TEXT_END = "TEXT_END",
+    TOOL_CALL_START = "TOOL_CALL_START",
+    TOOL_CALL_ARGS = "TOOL_CALL_ARGS",
+    TOOL_CALL_ARGS_DELTA = "TOOL_CALL_ARGS_DELTA",
+    TOOL_CALL_END = "TOOL_CALL_END",
+    TOOL_CALL_RESULT = "TOOL_CALL_RESULT",
+    RUN_STARTED = "RUN_STARTED",
+    RUN_FINISHED = "RUN_FINISHED",
+    RUN_ERROR = "RUN_ERROR",
+    RUN_METADATA = "RUN_METADATA",
+    REASONING_START = "REASONING_START",
+    REASONING_DELTA = "REASONING_DELTA",
+    REASONING_END = "REASONING_END"
+}
+interface BaseAgentEvent {
+    type: EventType;
+}
+interface TextStartEvent extends BaseAgentEvent {
+    type: EventType.TEXT_START;
+    messageId: string;
+}
+interface TextDeltaEvent extends BaseAgentEvent {
+    type: EventType.TEXT_DELTA;
+    messageId: string;
+    delta: string;
+}
+interface TextEndEvent extends BaseAgentEvent {
+    type: EventType.TEXT_END;
+    messageId: string;
+}
+interface ReasoningStartEvent extends BaseAgentEvent {
+    type: EventType.REASONING_START;
+    messageId: string;
+}
+interface ReasoningDeltaEvent extends BaseAgentEvent {
+    type: EventType.REASONING_DELTA;
+    messageId: string;
+    delta: string;
+}
+interface ReasoningEndEvent extends BaseAgentEvent {
+    type: EventType.REASONING_END;
+    messageId: string;
+}
+interface ToolCallStartEvent extends BaseAgentEvent {
+    type: EventType.TOOL_CALL_START;
+    messageId?: string;
+    toolCallId: string;
+    toolName: string;
+}
+interface ToolCallArgsEvent extends BaseAgentEvent {
+    type: EventType.TOOL_CALL_ARGS;
+    toolCallId: string;
+    args: string;
+}
+interface ToolCallArgsDeltaEvent extends BaseAgentEvent {
+    type: EventType.TOOL_CALL_ARGS_DELTA;
+    toolCallId: string;
+    argsDelta: string;
+}
+interface ToolCallEndEvent extends BaseAgentEvent {
+    type: EventType.TOOL_CALL_END;
+    toolCallId: string;
+}
+interface ToolCallResultEvent extends BaseAgentEvent {
+    type: EventType.TOOL_CALL_RESULT;
+    toolCallId: string;
+    content: unknown;
+}
+interface RunStartedEvent extends BaseAgentEvent {
+    type: EventType.RUN_STARTED;
+    threadId?: string;
+    runId?: string;
+}
+interface RunFinishedEvent extends BaseAgentEvent {
+    type: EventType.RUN_FINISHED;
+    threadId?: string;
+    runId?: string;
+}
+interface RunErrorEvent extends BaseAgentEvent {
+    type: EventType.RUN_ERROR;
+    error?: string;
+    threadId?: string;
+    runId?: string;
+}
+interface RunMetadataEvent extends BaseAgentEvent {
+    type: EventType.RUN_METADATA;
+    runId?: string;
+    metadata: Record<string, unknown>;
+}
+type AgentEvent = TextStartEvent | TextDeltaEvent | TextEndEvent | ReasoningStartEvent | ReasoningDeltaEvent | ReasoningEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallArgsDeltaEvent | ToolCallEndEvent | ToolCallResultEvent | RunStartedEvent | RunFinishedEvent | RunErrorEvent | RunMetadataEvent;
+
+type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
+type JSONObject = {
+    [key: string]: JSONValue;
+};
+type JSONArray = JSONValue[];
+type LanguageModelV1ProviderMetadata = Record<string, Record<string, JSONValue>>;
+type LanguageModelV1Source = {
+    sourceType: 'url';
+    id: string;
+    url: string;
+    title?: string;
+    providerMetadata?: LanguageModelV1ProviderMetadata;
+};
+interface ToolInvocation<ARGS = unknown, RESULT = unknown> {
+    status: ToolInvocationStatus;
+    toolCallId: string;
+    toolName: string;
+    args: string;
+    parsedArgs?: ARGS;
+    result?: RESULT;
+    error?: string;
+    cancelled?: boolean;
+}
+interface UIMessage {
+    id: string;
+    role: 'system' | 'user' | 'assistant' | 'data' | 'tool';
+    parts: Array<TextUIPart | ReasoningUIPart | ToolInvocationUIPart | SourceUIPart | FileUIPart | StepStartUIPart>;
+    meta?: UiMessageMeta;
+}
+type TextUIPart = {
+    type: 'text';
+    text: string;
+};
+type ReasoningUIPart = {
+    type: 'reasoning';
+    reasoning: string;
+    details: Array<{
+        type: 'text';
+        text: string;
+        signature?: string;
+    } | {
+        type: 'redacted';
+        data: string;
+    }>;
+};
+type ToolInvocationUIPart = {
+    type: 'tool-invocation';
+    toolInvocation: ToolInvocation;
+};
+type SourceUIPart = {
+    type: 'source';
+    source: LanguageModelV1Source;
+};
+type FileUIPart = {
+    type: 'file';
+    mimeType: string;
+    data: string;
+};
+type StepStartUIPart = {
+    type: 'step-start';
+};
+type UiMessageRole = UIMessage['role'];
+type UiMessage = UIMessage;
+type UiMessagePart = UIMessage['parts'][number];
+type UiMessageTextPart = TextUIPart;
+type UiMessageReasoningPart = ReasoningUIPart;
+type UiMessageToolInvocationPart = ToolInvocationUIPart;
+type UiMessageSourcePart = SourceUIPart;
+type UiMessageFilePart = FileUIPart;
+type UiMessageStepStartPart = StepStartUIPart;
+type UiMessageSource = 'history' | 'stream' | 'optimistic' | 'local';
+type UiMessageStatus = 'pending' | 'streaming' | 'final' | 'error';
+type UiMessageMeta = {
+    seq?: number;
+    status?: UiMessageStatus;
+    source?: UiMessageSource;
+    runId?: string;
+    sessionKey?: string;
+    timestamp?: string;
+    isDraft?: boolean;
+};
+
+declare enum ToolInvocationStatus {
+    CALL = "call",
+    RESULT = "result",
+    PARTIAL_CALL = "partial-call",
+    ERROR = "error",
+    CANCELLED = "cancelled"
+}
+interface ToolCall {
+    id: string;
+    type: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ToolResult<RESULT = ToolExecutionResult> {
+    toolCallId: string;
+    result?: RESULT;
+    status: ToolInvocationStatus;
+    error?: string;
+    cancelled?: boolean;
+}
+type ToolExecutionResult = unknown;
+type ToolExecutor<ARGS = unknown, RESULT = ToolExecutionResult> = (toolCallArgs: ARGS, context?: Record<string, unknown>) => RESULT | Promise<RESULT>;
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: JSONSchema7;
+}
+interface ToolRenderer<ARGS = unknown, RESULT = ToolExecutionResult> {
+    render: ToolRenderFn<ARGS, RESULT>;
+    definition: ToolDefinition;
+}
+type ToolRenderFn<ARGS = unknown, RESULT = ToolExecutionResult> = (tool: ToolInvocation<ARGS, RESULT>, onResult: (result: ToolResult<RESULT>) => void) => unknown;
+interface Tool<ARGS = unknown, RESULT = ToolExecutionResult> extends ToolDefinition {
+    execute?: ToolExecutor<ARGS, RESULT>;
+    render?: ToolRenderFn<ARGS, RESULT>;
+}
+interface Context {
+    description: string;
+    value: string;
+}
+interface RunAgentInput {
+    threadId?: string;
+    runId?: string;
+    messages: UIMessage[];
+    tools?: Tool[];
+    context?: Context[];
+    metadata?: Record<string, unknown>;
+}
+interface IAgent {
+    run: (input: RunAgentInput) => Subscribable<AgentEvent>;
+    abortRun?: () => void;
+}
+
+interface ActiveRunContext {
+    localRunId: number;
+    sessionId?: string;
+    agentId?: string;
+    remoteRunId?: string;
+    remoteStopCapable: boolean;
+    remoteStopReason?: string;
+    sourceMessage?: string;
+    restoreDraftOnError?: boolean;
+}
+declare function getStopDisabledReason(run: ActiveRunContext | null): string | null;
+interface RunReadyInfo {
+    remoteRunId?: string;
+    sessionId?: string;
+    stopCapable?: boolean;
+    stopReason?: string;
+}
+interface RunFinalInfo {
+    sessionId?: string;
+    hasOutput?: boolean;
+}
+interface RunLifecycleCallbacks {
+    onRunSettled?: (info: {
+        sourceSessionId?: string;
+        resultSessionId?: string;
+    }) => void | Promise<void>;
+    onRunError?: (info: {
+        error: string;
+        sourceMessage?: string;
+        restoreDraft?: boolean;
+    }) => void;
+    onSessionChanged?: (sessionId: string) => void;
+}
+interface RunMetadataParsers {
+    parseReady: (metadata: Record<string, unknown>) => RunReadyInfo | null;
+    parseFinal: (metadata: Record<string, unknown>) => RunFinalInfo | null;
+}
+interface SendRunOptions {
+    message: string;
+    sessionId?: string;
+    agentId?: string;
+    metadata?: Record<string, unknown>;
+    restoreDraftOnError?: boolean;
+    stopCapable?: boolean;
+    stopReason?: string;
+}
+interface ResumeRunOptions {
+    remoteRunId: string;
+    sessionId?: string;
+    agentId?: string;
+    metadata?: Record<string, unknown>;
+    stopCapable?: boolean;
+    stopReason?: string;
+}
+
+interface IAgentProvider {
+    agent: IAgent;
+    getToolDefs: () => ToolDefinition[];
+    getContexts: () => Context[];
+    getToolExecutor: (name: string) => ToolExecutor | undefined;
+}
+interface AgentChatControllerOptions {
+    initialMessages?: UIMessage[];
+    metadataParsers?: RunMetadataParsers;
+    callbacks?: RunLifecycleCallbacks;
+}
+type RunAgentOptions = {
+    threadId?: string;
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    agentId?: string;
+    stopCapable?: boolean;
+    stopReason?: string;
+    sourceMessage?: string;
+    restoreDraftOnError?: boolean;
+};
+declare class Disposable {
+    private disposables;
+    addDisposable: (disposable: () => void) => void;
+    dispose: () => void;
+}
+declare class AgentChatController extends Disposable {
+    private readonly agentProvider;
+    _messages$: BehaviorSubject<UIMessage[]>;
+    messages$: Observable<UIMessage[]>;
+    threadId$: BehaviorSubject<string | null>;
+    isAgentResponding$: BehaviorSubject<boolean>;
+    activeRun$: BehaviorSubject<ActiveRunContext | null>;
+    lastError$: BehaviorSubject<string | null>;
+    isAwaitingResponse$: BehaviorSubject<boolean>;
+    runCompleted$: Subject<{
+        runId: string;
+    }>;
+    runError$: Subject<{
+        runId: string;
+        error: unknown;
+        isAbort: boolean;
+    }>;
+    runMetadata$: Subject<{
+        runId: string;
+        metadata: Record<string, unknown>;
+    }>;
+    private activeSubscription;
+    addMessagesEvent$: Subject<{
+        messages: UIMessage[];
+    }>;
+    updateMessageEvent$: Subject<{
+        message: UIMessage;
+    }>;
+    setMessagesEvent$: Subject<{
+        messages: UIMessage[];
+    }>;
+    toolCall$: Subject<{
+        toolCall: ToolCall;
+    }>;
+    private eventHandler;
+    private runIdCounter;
+    private metadataParsers;
+    private callbacks;
+    constructor(agentProvider?: IAgentProvider | null, options?: AgentChatControllerOptions);
+    getMessages: () => UIMessage[];
+    setMessages: (messages: UIMessage[]) => void;
+    handleEvent: (event: AgentEvent) => void;
+    setCallbacks: (callbacks: RunLifecycleCallbacks) => void;
+    reset: () => void;
+    addMessages: (messages: UIMessage[]) => void;
+    removeMessages: (messageIds: string[]) => void;
+    updateMessage: (message: UIMessage) => void;
+    addToolResult: (result: ToolResult, _options?: {
+        triggerAgent?: boolean;
+    }) => void;
+    send: (options: SendRunOptions) => Promise<void>;
+    resume: (options: ResumeRunOptions) => Promise<void>;
+    stop: () => Promise<void>;
+    handleAgentResponse: (response: Observable<AgentEvent>) => void;
+    abortAgentRun: () => void;
+    runAgent: (options?: RunAgentOptions) => Promise<void>;
+    private processRunMetadata;
+    private applyReadyMetadata;
+    private applyFinalMetadata;
+    private isMatchingRun;
+    private connectToolExecutor;
+}
+
+declare class AgentEventHandler {
+    private readonly sessionManager;
+    private currentMessageId?;
+    private currentReasoningMessageId?;
+    private currentReasoningContent;
+    private currentToolCallId?;
+    private currentToolCallMessageId?;
+    private currentToolCallName?;
+    private currentToolCallArgs;
+    private emittedToolCallIds;
+    constructor(sessionManager: AgentChatController);
+    private findAssistantMessageById;
+    private findAssistantMessageByToolCallId;
+    private findAssistantMessageForCurrentTool;
+    reset(): void;
+    private emitToolCallEvents;
+    handleEvent(event: AgentEvent): void;
+    private handleTextStart;
+    private appendTextDelta;
+    private handleTextContent;
+    private handleTextEnd;
+    private updateReasoningPart;
+    private handleReasoningStart;
+    private handleReasoningContent;
+    private handleReasoningEnd;
+    private handleToolCallStart;
+    private handleToolCallArgsDelta;
+    private handleToolCallArgs;
+    private handleToolCallEnd;
+    private handleToolCallResult;
+}
+
+declare const toolCallToToolInvocation: (toolCall: ToolCall) => ToolInvocation;
+declare function finalizePendingToolInvocations(messages: UIMessage[], options?: {
+    stubResult?: unknown;
+}): UIMessage[];
+
+declare function extractTextFromMessage(message: UIMessage): string;
+declare function hasCopyableText(message: UIMessage): boolean;
+declare function getMessagePreview(message: UIMessage, maxLength?: number): string;
+
+declare const getToolDefFromTool: (tool: Tool) => ToolDefinition;
+declare const toolInvocationToToolCall: (toolInvocation: ToolInvocation) => ToolCall;
+
+declare function isAbortLikeError(error: unknown): boolean;
+declare function formatSendError(error: unknown): string;
+declare function buildLocalAssistantMessage(text: string, options?: {
+    sessionKey?: string;
+    status?: UiMessageStatus;
+}): UIMessage;
+
+export { type ActiveRunContext, AgentChatController, type AgentChatControllerOptions, type AgentEvent, AgentEventHandler, type BaseAgentEvent, type Context, Disposable, EventType, type FileUIPart, type IAgent, type IAgentProvider, type ReasoningDeltaEvent, type ReasoningEndEvent, type ReasoningStartEvent, type ReasoningUIPart, type ResumeRunOptions, type RunAgentInput, type RunErrorEvent, type RunFinalInfo, type RunFinishedEvent, type RunLifecycleCallbacks, type RunMetadataEvent, type RunMetadataParsers, type RunReadyInfo, type RunStartedEvent, type SendRunOptions, type SourceUIPart, type StepStartUIPart, type TextDeltaEvent, type TextEndEvent, type TextStartEvent, type TextUIPart, type Tool, type ToolCall, type ToolCallArgsDeltaEvent, type ToolCallArgsEvent, type ToolCallEndEvent, type ToolCallResultEvent, type ToolCallStartEvent, type ToolDefinition, type ToolExecutionResult, type ToolExecutor, type ToolInvocation, ToolInvocationStatus, type ToolInvocationUIPart, type ToolRenderFn, type ToolRenderer, type ToolResult, type UIMessage, type UiMessage, type UiMessageFilePart, type UiMessageMeta, type UiMessagePart, type UiMessageReasoningPart, type UiMessageRole, type UiMessageSource, type UiMessageSourcePart, type UiMessageStatus, type UiMessageStepStartPart, type UiMessageTextPart, type UiMessageToolInvocationPart, buildLocalAssistantMessage, extractTextFromMessage, finalizePendingToolInvocations, formatSendError, getMessagePreview, getStopDisabledReason, getToolDefFromTool, hasCopyableText, isAbortLikeError, toolCallToToolInvocation, toolInvocationToToolCall };