@tylertech/forge-ai 0.4.0 → 0.5.0

package/dist/ai-chatbot/ag-ui-adapter.mjs

@@ -0,0 +1,331 @@
+import { HttpAgentWithCredentials } from "./http-agent-with-credentials.mjs";
+import { AgentAdapter } from "./agent-adapter.mjs";
+import { generateId } from "./utils.mjs";
+class AgUiAdapter extends AgentAdapter {
+  #config;
+  #agent;
+  #toolCalls = /* @__PURE__ */ new Map();
+  #threadId;
+  #textBuffers = /* @__PURE__ */ new Map();
+  constructor(config, threadId) {
+    super();
+    this.#config = config;
+    this.#threadId = threadId ?? generateId("thread");
+    this.#agent = new HttpAgentWithCredentials({
+      url: config.url,
+      headers: config.headers
+    });
+    this.#agent.threadId = this.#threadId;
+    if (config.tools) {
+      this.setTools(config.tools);
+    }
+    this.#setupSubscriber();
+  }
+  get threadId() {
+    return this.#threadId;
+  }
+  set threadId(value) {
+    this.#threadId = value;
+    this.#agent.threadId = value;
+  }
+  static async create(config) {
+    const { threadId, ...adapterConfig } = config;
+    const adapter = new AgUiAdapter(adapterConfig, threadId ?? generateId("thread"));
+    await adapter.connect();
+    return adapter;
+  }
+  async connect() {
+    if (this._state.isConnecting || this._state.isConnected) {
+      return;
+    }
+    this._updateState({ isConnecting: true, isConnected: true });
+    await Promise.resolve();
+    this._updateState({ isConnecting: false });
+  }
+  async disconnect() {
+    this.abort();
+    this._updateState({ isConnected: false });
+  }
+  sendMessage(messages) {
+    if (!this._state.isConnected) {
+      throw new Error("Adapter not connected. Call connect() first.");
+    }
+    const transformedMessages = this.#transformMessages(messages);
+    const context = this.#config.context ? this.#transformContext(this.#config.context) : void 0;
+    this.#agent.setMessages(transformedMessages);
+    const tools = this.#transformTools(this._tools);
+    this.#agent.runAgent({ tools, context });
+  }
+  sendToolResult(toolCallId, result, messages) {
+    const toolMessage = {
+      id: generateId("tool"),
+      role: "tool",
+      content: JSON.stringify(result),
+      timestamp: Date.now(),
+      status: "complete",
+      toolCallId
+    };
+    messages = messages ? [...messages, toolMessage] : [toolMessage];
+    this.sendMessage(messages);
+    this._emitToolResult({ toolCallId, result, message: toolMessage });
+  }
+  abort() {
+    if (this._state.isRunning) {
+      try {
+        this.#agent.abortRun();
+      } catch {
+      }
+    }
+    this.#clearRunState();
+  }
+  #setupSubscriber() {
+    const subscriber = {
+      onRunInitialized: this.#handleRunInitialized.bind(this),
+      onTextMessageStartEvent: this.#handleTextMessageStart.bind(this),
+      onTextMessageContentEvent: this.#handleTextMessageContent.bind(this),
+      onTextMessageEndEvent: this.#handleTextMessageEnd.bind(this),
+      onToolCallStartEvent: this.#handleToolCallStart.bind(this),
+      onToolCallArgsEvent: this.#handleToolCallArgs.bind(this),
+      onToolCallEndEvent: this.#handleToolCallEnd.bind(this),
+      onToolCallResultEvent: this.#handleToolCallResult.bind(this),
+      onRunFinishedEvent: this.#handleRunFinished.bind(this),
+      onRunErrorEvent: this.#handleRunError.bind(this),
+      onRunFailed: this.#handleRunFailed.bind(this)
+    };
+    this.#agent.subscribe(subscriber);
+  }
+  #handleRunInitialized() {
+    this._updateState({ isRunning: true });
+    this._emitRunStarted();
+  }
+  #handleTextMessageStart({ event }) {
+    this._emitMessageStart(event.messageId);
+  }
+  #handleTextMessageContent({
+    textMessageBuffer,
+    event
+  }) {
+    this.#processTextDelta(event.messageId, textMessageBuffer, false);
+  }
+  #handleTextMessageEnd({
+    textMessageBuffer,
+    event
+  }) {
+    this.#processTextDelta(event.messageId, textMessageBuffer, true);
+    this._emitMessageEnd(event.messageId);
+  }
+  #handleToolCallStart({
+    event
+  }) {
+    const toolCallState = {
+      messageId: event.parentMessageId || "",
+      name: event.toolCallName,
+      argsBuffer: ""
+    };
+    this.#toolCalls.set(event.toolCallId, toolCallState);
+    this._emitToolCallStart({
+      id: event.toolCallId,
+      messageId: toolCallState.messageId,
+      name: toolCallState.name
+    });
+  }
+  #handleToolCallArgs({
+    event,
+    partialToolCallArgs,
+    toolCallBuffer
+  }) {
+    const toolCall = this.#getToolCallOrWarn(event.toolCallId);
+    if (!toolCall) {
+      return;
+    }
+    if (partialToolCallArgs && Object.keys(partialToolCallArgs).length) {
+      toolCall.argsBuffer = JSON.stringify(partialToolCallArgs);
+    } else {
+      toolCall.argsBuffer = toolCallBuffer;
+    }
+    this._emitToolCallArgs({
+      id: event.toolCallId,
+      messageId: toolCall.messageId,
+      name: toolCall.name,
+      argsBuffer: toolCall.argsBuffer,
+      partialArgs: partialToolCallArgs
+    });
+  }
+  #handleToolCallEnd({
+    event,
+    toolCallArgs
+  }) {
+    const toolCall = this.#getToolCallOrWarn(event.toolCallId);
+    if (!toolCall) {
+      return;
+    }
+    const args = toolCallArgs || {};
+    const toolDef = this.#findToolDefinition(toolCall.name);
+    if (toolDef) {
+      const validationError = this.#validateToolArgs(toolCall.name, args, toolDef);
+      if (validationError) {
+        this._emitError(validationError);
+        this.#toolCalls.delete(event.toolCallId);
+        return;
+      }
+    }
+    const toolCallEvent = {
+      id: event.toolCallId,
+      messageId: toolCall.messageId,
+      name: toolCall.name,
+      args
+    };
+    this._emitToolCallEnd(toolCallEvent);
+    this._emitToolCall(toolCallEvent);
+    this.#toolCalls.delete(event.toolCallId);
+  }
+  #handleToolCallResult({ event }) {
+    const result = JSON.parse(event.content);
+    const toolMessage = {
+      id: generateId("tool"),
+      role: "tool",
+      content: event.content,
+      timestamp: Date.now(),
+      status: "complete",
+      toolCallId: event.toolCallId
+    };
+    this._emitToolResult({
+      toolCallId: event.toolCallId,
+      result,
+      message: toolMessage
+    });
+  }
+  #handleRunFinished() {
+    this.#clearRunState();
+    this._emitRunFinished();
+  }
+  #handleRunError({ event }) {
+    if (event.rawEvent?.name === "AbortError") {
+      this.#clearRunState();
+      this._emitRunAborted();
+      return;
+    }
+    this._emitError(event.message || "Unknown error");
+    this._updateState({ isRunning: false });
+  }
+  #handleRunFailed() {
+    this.#clearRunState();
+    this._emitError("An unexpected error occurred. Please try again.");
+  }
+  #processTextDelta(messageId, buffer, isFinal) {
+    const previousBuffer = this.#textBuffers.get(messageId) ?? "";
+    const delta = buffer.slice(previousBuffer.length);
+    if (delta.length) {
+      this._emitMessageDelta(messageId, delta);
+    }
+    if (isFinal) {
+      this.#textBuffers.delete(messageId);
+    } else {
+      this.#textBuffers.set(messageId, buffer);
+    }
+  }
+  #getToolCallOrWarn(toolCallId) {
+    const toolCall = this.#toolCalls.get(toolCallId);
+    if (!toolCall) {
+      console.warn(`Tool call ${toolCallId} not found in state`);
+    }
+    return toolCall ?? null;
+  }
+  #findToolDefinition(name) {
+    return this._tools?.find((t) => t.name === name);
+  }
+  #clearRunState() {
+    this.#toolCalls.clear();
+    this.#textBuffers.clear();
+    this._updateState({ isRunning: false });
+  }
+  #transformTools(tools) {
+    if (!tools || tools.length === 0) {
+      return void 0;
+    }
+    return tools.map((tool) => {
+      const agUiTool = {
+        name: tool.name,
+        description: tool.description ?? "",
+        parameters: tool.parameters
+      };
+      return agUiTool;
+    });
+  }
+  #transformContext(context) {
+    return Object.entries(context).map(([key, value]) => ({
+      description: `Client context: ${key}`,
+      value: typeof value === "string" ? value : JSON.stringify(value)
+    }));
+  }
+  #transformMessages(messages) {
+    return messages.filter((msg) => msg.role === "user" || msg.role === "assistant" || msg.role === "system" || msg.role === "tool").filter((msg) => {
+      if (msg.role === "assistant") {
+        return msg.content.trim().length > 0 || msg.toolCalls && msg.toolCalls.length > 0;
+      }
+      return true;
+    }).map((msg) => {
+      switch (msg.role) {
+        case "user": {
+          const userMsg = {
+            id: msg.id,
+            role: "user",
+            content: msg.content
+          };
+          return userMsg;
+        }
+        case "assistant": {
+          const assistantMsg = {
+            id: msg.id,
+            role: "assistant",
+            content: msg.content || ""
+          };
+          if (msg.toolCalls && msg.toolCalls.length) {
+            assistantMsg.toolCalls = msg.toolCalls.map((tc) => ({
+              id: tc.id,
+              type: "function",
+              function: {
+                name: tc.name,
+                arguments: JSON.stringify(tc.args)
+              }
+            }));
+          }
+          return assistantMsg;
+        }
+        case "system": {
+          const systemMsg = {
+            id: msg.id,
+            role: "system",
+            content: msg.content
+          };
+          return systemMsg;
+        }
+        case "tool": {
+          const toolMsg = {
+            id: msg.id,
+            role: "tool",
+            toolCallId: msg.toolCallId || "",
+            content: msg.content
+          };
+          return toolMsg;
+        }
+      }
+    });
+  }
+  #validateToolArgs(toolName, args, toolDef) {
+    const { parameters } = toolDef;
+    if (!parameters || parameters.type !== "object") {
+      return null;
+    }
+    const required = parameters.required || [];
+    for (const field of required) {
+      if (!(field in args)) {
+        return `Tool ${toolName} missing required parameter: ${field}`;
+      }
+    }
+    return null;
+  }
+}
+export {
+  AgUiAdapter
+};

package/dist/ai-chatbot/agent-adapter.d.ts

@@ -0,0 +1,125 @@
+import { ChatMessage, FileUploadCallbacks, ToolDefinition } from './types.js';
+import { EventEmitter, Subscription } from './event-emitter.js';
+export interface MessageStartEvent {
+    messageId: string;
+}
+export interface MessageDeltaEvent {
+    messageId: string;
+    delta: string;
+}
+export interface MessageEndEvent {
+    messageId: string;
+}
+export interface ToolCallEvent {
+    id: string;
+    messageId: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ToolCallStartEvent {
+    id: string;
+    messageId: string;
+    name: string;
+}
+export interface ToolCallArgsEvent {
+    id: string;
+    messageId: string;
+    name: string;
+    argsBuffer: string;
+    partialArgs?: Record<string, unknown>;
+}
+export interface ToolCallEndEvent {
+    id: string;
+    messageId: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ToolResultEvent {
+    toolCallId: string;
+    result: unknown;
+    message: ChatMessage;
+}
+export interface AdapterState {
+    isConnected: boolean;
+    isConnecting: boolean;
+    isRunning: boolean;
+}
+export interface FileUploadEvent extends FileUploadCallbacks {
+    file: File;
+}
+export interface FileRemoveEvent {
+    fileId: string;
+    onSuccess: () => void;
+    onError: (error: string) => void;
+}
+export interface ErrorEvent {
+    message: string;
+}
+export declare abstract class AgentAdapter {
+    protected _state: AdapterState;
+    protected _tools: ToolDefinition[];
+    protected _events: {
+        runStarted: EventEmitter<void>;
+        runFinished: EventEmitter<void>;
+        runAborted: EventEmitter<void>;
+        messageStart: EventEmitter<MessageStartEvent>;
+        messageDelta: EventEmitter<MessageDeltaEvent>;
+        messageEnd: EventEmitter<MessageEndEvent>;
+        toolCall: EventEmitter<ToolCallEvent>;
+        toolCallStart: EventEmitter<ToolCallStartEvent>;
+        toolCallArgs: EventEmitter<ToolCallArgsEvent>;
+        toolCallEnd: EventEmitter<ToolCallEndEvent>;
+        toolResult: EventEmitter<ToolResultEvent>;
+        fileUpload: EventEmitter<FileUploadEvent>;
+        fileRemove: EventEmitter<FileRemoveEvent>;
+        error: EventEmitter<ErrorEvent>;
+        stateChange: EventEmitter<AdapterState>;
+    };
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract sendMessage(messages: ChatMessage[]): void;
+    abstract sendToolResult(toolCallId: string, result: unknown, messages: ChatMessage[]): void;
+    abstract abort(): void;
+    abstract get threadId(): string;
+    abstract set threadId(value: string);
+    clearMemory?(): Promise<void>;
+    setTools(tools: ToolDefinition[]): void;
+    getTools(): ToolDefinition[];
+    getState(): AdapterState;
+    get isConnected(): boolean;
+    get isConnecting(): boolean;
+    get isRunning(): boolean;
+    onRunStarted(callback: () => void): Subscription;
+    onRunFinished(callback: () => void): Subscription;
+    onRunAborted(callback: () => void): Subscription;
+    onMessageStart(callback: (event: MessageStartEvent) => void): Subscription;
+    onMessageDelta(callback: (event: MessageDeltaEvent) => void): Subscription;
+    onMessageEnd(callback: (event: MessageEndEvent) => void): Subscription;
+    onToolCall(callback: (event: ToolCallEvent) => void): Subscription;
+    onToolCallStart(callback: (event: ToolCallStartEvent) => void): Subscription;
+    onToolCallArgs(callback: (event: ToolCallArgsEvent) => void): Subscription;
+    onToolCallEnd(callback: (event: ToolCallEndEvent) => void): Subscription;
+    onToolCallResult(callback: (event: ToolResultEvent) => void): Subscription;
+    onFileUpload(callback: (event: FileUploadEvent) => void): Subscription;
+    onFileRemove(callback: (event: FileRemoveEvent) => void): Subscription;
+    onError(callback: (event: ErrorEvent) => void): Subscription;
+    onStateChange(callback: (state: AdapterState) => void): Subscription;
+    protected _emitRunStarted(): void;
+    protected _emitRunFinished(): void;
+    protected _emitRunAborted(): void;
+    protected _emitMessageStart(messageId: string): void;
+    protected _emitMessageDelta(messageId: string, delta: string): void;
+    protected _emitMessageEnd(messageId: string): void;
+    protected _emitToolCall(event: ToolCallEvent): void;
+    protected _emitToolCallStart(event: ToolCallStartEvent): void;
+    protected _emitToolCallArgs(event: ToolCallArgsEvent): void;
+    protected _emitToolCallEnd(event: ToolCallEndEvent): void;
+    protected _emitToolResult(event: ToolResultEvent): void;
+    emitFileUpload(file: File, callbacks: FileUploadCallbacks): void;
+    emitFileRemove(fileId: string, callbacks: {
+        onSuccess: () => void;
+        onError: (error: string) => void;
+    }): void;
+    protected _emitError(message: string): void;
+    protected _updateState(updates: Partial<AdapterState>): void;
+}

package/dist/ai-chatbot/agent-adapter.mjs

@@ -0,0 +1,136 @@
+import { EventEmitter } from "./event-emitter.mjs";
+class AgentAdapter {
+  constructor() {
+    this._state = { isConnected: false, isConnecting: false, isRunning: false };
+    this._tools = [];
+    this._events = {
+      runStarted: new EventEmitter(),
+      runFinished: new EventEmitter(),
+      runAborted: new EventEmitter(),
+      messageStart: new EventEmitter(),
+      messageDelta: new EventEmitter(),
+      messageEnd: new EventEmitter(),
+      toolCall: new EventEmitter(),
+      toolCallStart: new EventEmitter(),
+      toolCallArgs: new EventEmitter(),
+      toolCallEnd: new EventEmitter(),
+      toolResult: new EventEmitter(),
+      fileUpload: new EventEmitter(),
+      fileRemove: new EventEmitter(),
+      error: new EventEmitter(),
+      stateChange: new EventEmitter()
+    };
+  }
+  setTools(tools) {
+    this._tools = tools;
+  }
+  getTools() {
+    return [...this._tools];
+  }
+  getState() {
+    return { ...this._state };
+  }
+  get isConnected() {
+    return this._state.isConnected;
+  }
+  get isConnecting() {
+    return this._state.isConnecting;
+  }
+  get isRunning() {
+    return this._state.isRunning;
+  }
+  onRunStarted(callback) {
+    return this._events.runStarted.subscribe(callback);
+  }
+  onRunFinished(callback) {
+    return this._events.runFinished.subscribe(callback);
+  }
+  onRunAborted(callback) {
+    return this._events.runAborted.subscribe(callback);
+  }
+  onMessageStart(callback) {
+    return this._events.messageStart.subscribe(callback);
+  }
+  onMessageDelta(callback) {
+    return this._events.messageDelta.subscribe(callback);
+  }
+  onMessageEnd(callback) {
+    return this._events.messageEnd.subscribe(callback);
+  }
+  onToolCall(callback) {
+    return this._events.toolCall.subscribe(callback);
+  }
+  onToolCallStart(callback) {
+    return this._events.toolCallStart.subscribe(callback);
+  }
+  onToolCallArgs(callback) {
+    return this._events.toolCallArgs.subscribe(callback);
+  }
+  onToolCallEnd(callback) {
+    return this._events.toolCallEnd.subscribe(callback);
+  }
+  onToolCallResult(callback) {
+    return this._events.toolResult.subscribe(callback);
+  }
+  onFileUpload(callback) {
+    return this._events.fileUpload.subscribe(callback);
+  }
+  onFileRemove(callback) {
+    return this._events.fileRemove.subscribe(callback);
+  }
+  onError(callback) {
+    return this._events.error.subscribe(callback);
+  }
+  onStateChange(callback) {
+    return this._events.stateChange.subscribe(callback);
+  }
+  _emitRunStarted() {
+    this._events.runStarted.emit();
+  }
+  _emitRunFinished() {
+    this._events.runFinished.emit();
+  }
+  _emitRunAborted() {
+    this._events.runAborted.emit();
+  }
+  _emitMessageStart(messageId) {
+    this._events.messageStart.emit({ messageId });
+  }
+  _emitMessageDelta(messageId, delta) {
+    this._events.messageDelta.emit({ messageId, delta });
+  }
+  _emitMessageEnd(messageId) {
+    this._events.messageEnd.emit({ messageId });
+  }
+  _emitToolCall(event) {
+    this._events.toolCall.emit(event);
+  }
+  _emitToolCallStart(event) {
+    this._events.toolCallStart.emit(event);
+  }
+  _emitToolCallArgs(event) {
+    this._events.toolCallArgs.emit(event);
+  }
+  _emitToolCallEnd(event) {
+    this._events.toolCallEnd.emit(event);
+  }
+  _emitToolResult(event) {
+    this._events.toolResult.emit(event);
+  }
+  emitFileUpload(file, callbacks) {
+    this._events.fileUpload.emit({ file, ...callbacks });
+  }
+  emitFileRemove(fileId, callbacks) {
+    this._events.fileRemove.emit({ fileId, ...callbacks });
+  }
+  _emitError(message) {
+    this._events.error.emit({ message });
+  }
+  _updateState(updates) {
+    this._state = { ...this._state, ...updates };
+    this._events.stateChange.emit(this.getState());
+  }
+}
+export {
+  AgentAdapter
+};

package/dist/ai-chatbot/agent-runner.d.ts

@@ -0,0 +1,41 @@
+import { AgentAdapter } from './agent-adapter.js';
+import { ChatMessage, ToolCall, ToolDefinition } from './types.js';
+export interface AgentRunnerConfig {
+    /** The adapter instance that handles communication with the AI model */
+    adapter: AgentAdapter;
+    /** The user prompt to send to the agent */
+    prompt: string;
+    /** Optional tools the agent can call during execution */
+    tools?: ToolDefinition[];
+    /** Execution mode: 'one-shot' stops after first response, 'multi-turn' allows tool usage loops. @default 'one-shot' */
+    mode?: 'one-shot' | 'multi-turn';
+    /** Maximum conversation turns in multi-turn mode to prevent infinite loops. @default 20 */
+    maxTurns?: number;
+    /** Callback fired when agent starts generating a new message */
+    onStart?: (messageId: string) => void;
+    /** Callback fired for each text chunk as it streams in */
+    onDelta?: (delta: string) => void;
+    /** Callback fired when agent requests a tool call */
+    onToolCall?: (toolCall: ToolCall) => void;
+    /** Callback fired when execution completes with final result */
+    onComplete?: (result: AgentRunnerResult) => void;
+}
+export interface AgentRunnerResult {
+    /** Complete message history including user, assistant, and tool messages */
+    messages: ChatMessage[];
+    /** The final assistant message returned by the agent */
+    finalMessage: ChatMessage;
+    /** All tool calls executed during the conversation */
+    toolCalls: ToolCall[];
+    /** Number of conversation turns completed */
+    turns: number;
+    /** Whether execution completed successfully without errors */
+    success: boolean;
+    /** Reason execution stopped: 'text-response' (natural completion), 'max-turns' (hit turn limit), 'error' (failed), or 'one-shot-complete' (single turn mode) */
+    stoppedReason: 'text-response' | 'max-turns' | 'error' | 'one-shot-complete';
+}
+export declare class AgentRunner {
+    #private;
+    private constructor();
+    static run(config: AgentRunnerConfig): Promise<AgentRunnerResult>;
+}