@scoutqa/ag-ui-client 0.0.42-fork.1

package/README.md

@@ -0,0 +1,78 @@
+# @ag-ui/client
+
+Client SDK for connecting to **Agent-User Interaction (AG-UI) Protocol** servers.
+
+`@ag-ui/client` provides agent implementations that handle the full lifecycle of AG-UI communication: connecting to servers, processing streaming events, managing state mutations, and providing reactive subscriber hooks.
+
+## Installation
+
+```bash
+npm install @ag-ui/client
+pnpm add @ag-ui/client
+yarn add @ag-ui/client
+```
+
+## Features
+
+- 🔗 **HTTP connectivity** – `HttpAgent` for direct server connections with SSE/protobuf support
+- 🏗️ **Custom agents** – `AbstractAgent` base class for building your own transport layer
+- 📡 **Event streaming** – Full AG-UI event processing with validation and transformation
+- 🔄 **State management** – Automatic message/state tracking with reactive updates
+- 🪝 **Subscriber system** – Middleware-style hooks for logging, persistence, and custom logic
+- 🎯 **Middleware support** – Transform and filter events with function or class-based middleware
+
+## Quick example
+
+```ts
+import { HttpAgent } from "@ag-ui/client";
+
+const agent = new HttpAgent({
+  url: "https://api.example.com/agent",
+  headers: { Authorization: "Bearer token" },
+});
+
+const result = await agent.runAgent({
+  messages: [{ role: "user", content: "Hello!" }],
+});
+
+console.log(result.newMessages);
+```
+
+## Using Middleware
+
+```ts
+import { HttpAgent, FilterToolCallsMiddleware } from "@ag-ui/client";
+
+const agent = new HttpAgent({
+  url: "https://api.example.com/agent",
+});
+
+// Add middleware to transform or filter events
+agent.use(
+  // Function middleware for logging
+  (input, next) => {
+    console.log("Starting run:", input.runId);
+    return next.run(input);
+  },
+
+  // Class middleware for filtering tool calls
+  new FilterToolCallsMiddleware({
+    allowedToolCalls: ["search", "calculate"]
+  })
+);
+
+await agent.runAgent();
+```
+
+## Documentation
+
+- Concepts & architecture: [`docs/concepts`](https://docs.ag-ui.com/concepts/architecture)
+- Full API reference: [`docs/sdk/js/client`](https://docs.ag-ui.com/sdk/js/client/overview)
+
+## Contributing
+
+Bug reports and pull requests are welcome! Please read our [contributing guide](https://docs.ag-ui.com/development/contributing) first.
+
+## License
+
+MIT © 2025 AG-UI Protocol Contributors

package/dist/index.d.mts

@@ -0,0 +1,446 @@
+import { Message, State, RunAgentInput, BaseEvent, RunStartedEvent, RunFinishedEvent, RunErrorEvent, StepStartedEvent, StepFinishedEvent, TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent, ToolCallStartEvent, ToolCallArgsEvent, ToolCallEndEvent, ToolCallResultEvent, StateSnapshotEvent, StateDeltaEvent, MessagesSnapshotEvent, ActivitySnapshotEvent, ActivityMessage, ActivityDeltaEvent, RawEvent, CustomEvent, ToolCall } from '@ag-ui/core';
+export * from '@ag-ui/core';
+import { Observable } from 'rxjs';
+import { z } from 'zod';
+
+interface AgentConfig {
+    agentId?: string;
+    description?: string;
+    threadId?: string;
+    initialMessages?: Message[];
+    initialState?: State;
+    debug?: boolean;
+}
+interface HttpAgentConfig extends AgentConfig {
+    url: string;
+    headers?: Record<string, string>;
+}
+type RunAgentParameters = Partial<Pick<RunAgentInput, "runId" | "tools" | "context" | "forwardedProps">>;
+
+declare const LegacyRuntimeProtocolEvent: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"TextMessageStart">;
+    messageId: z.ZodString;
+    parentMessageId: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "TextMessageStart";
+    messageId: string;
+    role?: string | undefined;
+    parentMessageId?: string | undefined;
+}, {
+    type: "TextMessageStart";
+    messageId: string;
+    role?: string | undefined;
+    parentMessageId?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"TextMessageContent">;
+    messageId: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "TextMessageContent";
+    messageId: string;
+    content: string;
+}, {
+    type: "TextMessageContent";
+    messageId: string;
+    content: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"TextMessageEnd">;
+    messageId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "TextMessageEnd";
+    messageId: string;
+}, {
+    type: "TextMessageEnd";
+    messageId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ActionExecutionStart">;
+    actionExecutionId: z.ZodString;
+    actionName: z.ZodString;
+    parentMessageId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "ActionExecutionStart";
+    actionExecutionId: string;
+    actionName: string;
+    parentMessageId?: string | undefined;
+}, {
+    type: "ActionExecutionStart";
+    actionExecutionId: string;
+    actionName: string;
+    parentMessageId?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ActionExecutionArgs">;
+    actionExecutionId: z.ZodString;
+    args: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ActionExecutionArgs";
+    actionExecutionId: string;
+    args: string;
+}, {
+    type: "ActionExecutionArgs";
+    actionExecutionId: string;
+    args: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ActionExecutionEnd">;
+    actionExecutionId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ActionExecutionEnd";
+    actionExecutionId: string;
+}, {
+    type: "ActionExecutionEnd";
+    actionExecutionId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"ActionExecutionResult">;
+    actionName: z.ZodString;
+    actionExecutionId: z.ZodString;
+    result: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "ActionExecutionResult";
+    actionExecutionId: string;
+    actionName: string;
+    result: string;
+}, {
+    type: "ActionExecutionResult";
+    actionExecutionId: string;
+    actionName: string;
+    result: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"AgentStateMessage">;
+    threadId: z.ZodString;
+    agentName: z.ZodString;
+    nodeName: z.ZodString;
+    runId: z.ZodString;
+    active: z.ZodBoolean;
+    role: z.ZodString;
+    state: z.ZodString;
+    running: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    runId: string;
+    threadId: string;
+    state: string;
+    type: "AgentStateMessage";
+    agentName: string;
+    nodeName: string;
+    active: boolean;
+    running: boolean;
+}, {
+    role: string;
+    runId: string;
+    threadId: string;
+    state: string;
+    type: "AgentStateMessage";
+    agentName: string;
+    nodeName: string;
+    active: boolean;
+    running: boolean;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"MetaEvent">;
+    name: z.ZodEnum<["LangGraphInterruptEvent", "PredictState", "Exit"]>;
+    value: z.ZodAny;
+}, "strip", z.ZodTypeAny, {
+    type: "MetaEvent";
+    name: "LangGraphInterruptEvent" | "PredictState" | "Exit";
+    value?: any;
+}, {
+    type: "MetaEvent";
+    name: "LangGraphInterruptEvent" | "PredictState" | "Exit";
+    value?: any;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"RunError">;
+    message: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "RunError";
+    message: string;
+    code?: string | undefined;
+}, {
+    type: "RunError";
+    message: string;
+    code?: string | undefined;
+}>]>;
+type LegacyRuntimeProtocolEvent = z.infer<typeof LegacyRuntimeProtocolEvent>;
+
+interface RunHttpAgentConfig extends RunAgentParameters {
+    abortController?: AbortController;
+}
+declare class HttpAgent extends AbstractAgent {
+    url: string;
+    headers: Record<string, string>;
+    abortController: AbortController;
+    /**
+     * Returns the fetch config for the http request.
+     * Override this to customize the request.
+     *
+     * @returns The fetch config for the http request.
+     */
+    protected requestInit(input: RunAgentInput): RequestInit;
+    runAgent(parameters?: RunHttpAgentConfig, subscriber?: AgentSubscriber): Promise<RunAgentResult>;
+    abortRun(): void;
+    constructor(config: HttpAgentConfig);
+    run(input: RunAgentInput): Observable<BaseEvent>;
+    clone(): HttpAgent;
+}
+
+type MiddlewareFunction = (input: RunAgentInput, next: AbstractAgent) => Observable<BaseEvent>;
+interface EventWithState {
+    event: BaseEvent;
+    messages: Message[];
+    state: any;
+}
+declare abstract class Middleware {
+    abstract run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;
+    /**
+     * Runs the next agent in the chain with automatic chunk transformation.
+     */
+    protected runNext(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;
+    /**
+     * Runs the next agent and tracks state, providing current messages and state with each event.
+     * The messages and state represent the state AFTER the event has been applied.
+     */
+    protected runNextWithState(input: RunAgentInput, next: AbstractAgent): Observable<EventWithState>;
+}
+declare class FunctionMiddleware extends Middleware {
+    private fn;
+    constructor(fn: MiddlewareFunction);
+    run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;
+}
+
+type FilterToolCallsConfig = {
+    allowedToolCalls: string[];
+    disallowedToolCalls?: never;
+} | {
+    disallowedToolCalls: string[];
+    allowedToolCalls?: never;
+};
+declare class FilterToolCallsMiddleware extends Middleware {
+    private blockedToolCallIds;
+    private readonly allowedTools?;
+    private readonly disallowedTools?;
+    constructor(config: FilterToolCallsConfig);
+    run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;
+    private shouldFilterTool;
+}
+
+/**
+ * Middleware placeholder that maintains compatibility with AG-UI 0.0.39 flows.
+ * Currently it simply forwards all events to the next middleware/agent.
+ */
+declare class BackwardCompatibility_0_0_39 extends Middleware {
+    run(input: RunAgentInput, next: AbstractAgent): Observable<BaseEvent>;
+}
+
+interface RunAgentResult {
+    result: any;
+    newMessages: Message[];
+}
+declare abstract class AbstractAgent {
+    agentId?: string;
+    description: string;
+    threadId: string;
+    messages: Message[];
+    state: State;
+    debug: boolean;
+    subscribers: AgentSubscriber[];
+    isRunning: boolean;
+    private middlewares;
+    private activeRunDetach$?;
+    private activeRunCompletionPromise?;
+    get maxVersion(): string;
+    constructor({ agentId, description, threadId, initialMessages, initialState, debug, }?: AgentConfig);
+    subscribe(subscriber: AgentSubscriber): {
+        unsubscribe: () => void;
+    };
+    abstract run(input: RunAgentInput): Observable<BaseEvent>;
+    use(...middlewares: (Middleware | MiddlewareFunction)[]): this;
+    runAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>;
+    protected connect(input: RunAgentInput): Observable<BaseEvent>;
+    connectAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>;
+    abortRun(): void;
+    detachActiveRun(): Promise<void>;
+    protected apply(input: RunAgentInput, events$: Observable<BaseEvent>, subscribers: AgentSubscriber[]): Observable<AgentStateMutation>;
+    protected processApplyEvents(input: RunAgentInput, events$: Observable<AgentStateMutation>, subscribers: AgentSubscriber[]): Observable<AgentStateMutation>;
+    protected prepareRunAgentInput(parameters?: RunAgentParameters): RunAgentInput;
+    protected onInitialize(input: RunAgentInput, subscribers: AgentSubscriber[]): Promise<void>;
+    protected onError(input: RunAgentInput, error: Error, subscribers: AgentSubscriber[]): Observable<AgentStateMutation>;
+    protected onFinalize(input: RunAgentInput, subscribers: AgentSubscriber[]): Promise<void>;
+    clone(): any;
+    addMessage(message: Message): void;
+    addMessages(messages: Message[]): void;
+    setMessages(messages: Message[]): void;
+    setState(state: State): void;
+    legacy_to_be_removed_runAgentBridged(config?: RunAgentParameters): Observable<LegacyRuntimeProtocolEvent>;
+}
+
+interface AgentStateMutation {
+    messages?: Message[];
+    state?: State;
+    stopPropagation?: boolean;
+}
+interface AgentSubscriberParams {
+    messages: Message[];
+    state: State;
+    agent: AbstractAgent;
+    input: RunAgentInput;
+}
+type MaybePromise<T> = T | Promise<T>;
+interface AgentSubscriber {
+    onRunInitialized?(params: AgentSubscriberParams): MaybePromise<Omit<AgentStateMutation, "stopPropagation"> | void>;
+    onRunFailed?(params: {
+        error: Error;
+    } & AgentSubscriberParams): MaybePromise<Omit<AgentStateMutation, "stopPropagation"> | void>;
+    onRunFinalized?(params: AgentSubscriberParams): MaybePromise<Omit<AgentStateMutation, "stopPropagation"> | void>;
+    onEvent?(params: {
+        event: BaseEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onRunStartedEvent?(params: {
+        event: RunStartedEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onRunFinishedEvent?(params: {
+        event: RunFinishedEvent;
+        result?: any;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onRunErrorEvent?(params: {
+        event: RunErrorEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onStepStartedEvent?(params: {
+        event: StepStartedEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onStepFinishedEvent?(params: {
+        event: StepFinishedEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onTextMessageStartEvent?(params: {
+        event: TextMessageStartEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onTextMessageContentEvent?(params: {
+        event: TextMessageContentEvent;
+        textMessageBuffer: string;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onTextMessageEndEvent?(params: {
+        event: TextMessageEndEvent;
+        textMessageBuffer: string;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onToolCallStartEvent?(params: {
+        event: ToolCallStartEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onToolCallArgsEvent?(params: {
+        event: ToolCallArgsEvent;
+        toolCallBuffer: string;
+        toolCallName: string;
+        partialToolCallArgs: Record<string, any>;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onToolCallEndEvent?(params: {
+        event: ToolCallEndEvent;
+        toolCallName: string;
+        toolCallArgs: Record<string, any>;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onToolCallResultEvent?(params: {
+        event: ToolCallResultEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onStateSnapshotEvent?(params: {
+        event: StateSnapshotEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onStateDeltaEvent?(params: {
+        event: StateDeltaEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onMessagesSnapshotEvent?(params: {
+        event: MessagesSnapshotEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onActivitySnapshotEvent?(params: {
+        event: ActivitySnapshotEvent;
+        activityMessage?: ActivityMessage;
+        existingMessage?: Message;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onActivityDeltaEvent?(params: {
+        event: ActivityDeltaEvent;
+        activityMessage?: ActivityMessage;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onRawEvent?(params: {
+        event: RawEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onCustomEvent?(params: {
+        event: CustomEvent;
+    } & AgentSubscriberParams): MaybePromise<AgentStateMutation | void>;
+    onMessagesChanged?(params: Omit<AgentSubscriberParams, "input"> & {
+        input?: RunAgentInput;
+    }): MaybePromise<void>;
+    onStateChanged?(params: Omit<AgentSubscriberParams, "input"> & {
+        input?: RunAgentInput;
+    }): MaybePromise<void>;
+    onNewMessage?(params: {
+        message: Message;
+    } & Omit<AgentSubscriberParams, "input"> & {
+        input?: RunAgentInput;
+    }): MaybePromise<void>;
+    onNewToolCall?(params: {
+        toolCall: ToolCall;
+    } & Omit<AgentSubscriberParams, "input"> & {
+        input?: RunAgentInput;
+    }): MaybePromise<void>;
+}
+
+declare const defaultApplyEvents: (input: RunAgentInput, events$: Observable<BaseEvent>, agent: AbstractAgent, subscribers: AgentSubscriber[]) => Observable<AgentStateMutation>;
+
+declare const verifyEvents: (debug: boolean) => (source$: Observable<BaseEvent>) => Observable<BaseEvent>;
+
+declare enum HttpEventType {
+    HEADERS = "headers",
+    DATA = "data"
+}
+interface HttpDataEvent {
+    type: HttpEventType.DATA;
+    data?: Uint8Array;
+}
+interface HttpHeadersEvent {
+    type: HttpEventType.HEADERS;
+    status: number;
+    headers: Headers;
+}
+type HttpEvent = HttpDataEvent | HttpHeadersEvent;
+declare const runHttpRequest: (url: string, requestInit: RequestInit) => Observable<HttpEvent>;
+
+/**
+ * Transforms HTTP events into BaseEvents using the appropriate format parser based on content type.
+ */
+declare const transformHttpEventStream: (source$: Observable<HttpEvent>) => Observable<BaseEvent>;
+
+/**
+ * Parses a stream of HTTP events into a stream of JSON objects using Server-Sent Events (SSE) format.
+ * Strictly follows the SSE standard where:
+ * - Events are separated by double newlines ('\n\n')
+ * - Only 'data:' prefixed lines are processed
+ * - Multi-line data events are supported and joined
+ * - Non-data fields (event, id, retry) are ignored
+ */
+declare const parseSSEStream: (source$: Observable<HttpEvent>) => Observable<any>;
+
+/**
+ * Parses a stream of HTTP events into a stream of BaseEvent objects using Protocol Buffer format.
+ * Each message is prefixed with a 4-byte length header (uint32 in big-endian format)
+ * followed by the protocol buffer encoded message.
+ */
+declare const parseProtoStream: (source$: Observable<HttpEvent>) => Observable<BaseEvent>;
+
+declare const convertToLegacyEvents: (threadId: string, runId: string, agentName: string) => (events$: Observable<BaseEvent>) => Observable<LegacyRuntimeProtocolEvent>;
+
+declare const structuredClone_: <T>(obj: T) => T;
+/**
+ * Generate a random UUID v4
+ * Cross-platform compatible (Node.js, browsers, React Native)
+ */
+declare function randomUUID(): string;
+
+/**
+ * Compacts streaming events by consolidating multiple deltas into single events.
+ * For text messages: multiple content deltas become one concatenated delta.
+ * For tool calls: multiple args deltas become one concatenated delta.
+ * Events between related streaming events are reordered to keep streaming events together.
+ *
+ * @param events - Array of events to compact
+ * @returns Compacted array of events
+ */
+declare function compactEvents(events: BaseEvent[]): BaseEvent[];
+
+declare const transformChunks: (debug: boolean) => (events$: Observable<BaseEvent>) => Observable<BaseEvent>;
+
+export { AbstractAgent, type AgentConfig, type AgentStateMutation, type AgentSubscriber, type AgentSubscriberParams, BackwardCompatibility_0_0_39, FilterToolCallsMiddleware, FunctionMiddleware, HttpAgent, type HttpAgentConfig, Middleware, type MiddlewareFunction, type RunAgentParameters, type RunAgentResult, compactEvents, convertToLegacyEvents, defaultApplyEvents, parseProtoStream, parseSSEStream, randomUUID, runHttpRequest, structuredClone_, transformChunks, transformHttpEventStream, verifyEvents };