@better-agent/client 0.1.0-canary.0

package/dist/index.d.mts

@@ -0,0 +1,266 @@
+import { A as getEventErrorMessage, B as SubmitToolApprovalRequest, C as ToolCallPart, D as UIMessagePart, E as UIMessage, F as InferClient, G as AgentContext, H as ToolCallContext, I as OnToolCall, J as AgentsFromApp, K as AgentNameFromApp, L as ReplayInput, M as BetterAgentClient, N as ClientConfig, O as VideoPart, P as ClientEvent, Q as TextInputShorthandForAgent, R as RequestOptions, S as TextPart, T as TranscriptPart, U as ToolCallRequest, V as SubmitToolResultRequest, W as ToolHandlers, X as NormalizeClientApp, Y as ModalitiesForAgent, Z as RunInputForAgent, _ as EmbeddingPart, a as ControllerRunInput, b as PendingToolApproval, c as ResumeOption, d as SendMessageOptions, f as SendResult, g as AudioPart, h as UIMessageInput, i as ApproveToolCallParams, j as toAgentClientError, k as AgentClientError, l as RetryResult, m as SubmitInput, n as AgentChatSnapshot, o as OnFinishParams, p as SetMessagesInput, q as AgentRunInput, r as AgentStatus, s as PrepareMessages, t as AgentChatControllerOptions, v as FilePart, w as ToolResultPart, x as ReasoningPart, y as ImagePart, z as StreamRequestOptions } from "./controller-CJ79_cSR.mjs";
+import { pruneInputByCapabilities } from "@better-agent/core";
+import { ConversationItem, GenerativeModelInputItem } from "@better-agent/core/providers";
+
+//#region src/core/client/index.d.ts
+/**
+ * Creates a Better Agent client.
+ *
+ * @param config Client configuration.
+ * @returns A typed client.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from "@better-agent/client";
+ *
+ * const client = createClient({
+ *   baseURL: "http://localhost:3000/api",
+ *   secret: "dev_secret",
+ * });
+ *
+ * const result = await client.run("helloAgent", {
+ *   input: "Write one short sentence about TypeScript.",
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * import type ba from "./better-agent/server";
+ * import { createClient } from "@better-agent/client";
+ *
+ * const client = createClient<typeof ba>({
+ *   baseURL: "http://localhost:3000/api",
+ *   secret: "dev_secret",
+ *   toolHandlers: {
+ *     getClientTime: () => ({ now: new Date().toISOString() }),
+ *   },
+ * });
+ *
+ * for await (const event of client.stream("helloAgent", {
+ *   input: "Use tools if needed.",
+ * })) {
+ *   console.log(event.type);
+ * }
+ * ```
+ */
+declare const createClient: <TApp = unknown>(config: ClientConfig<TApp>) => BetterAgentClient<NormalizeClientApp<TApp>>;
+//#endregion
+//#region src/core/controller.d.ts
+/**
+ * Framework-agnostic controller for one agent conversation.
+ */
+declare class AgentChatController<TApp = unknown, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>> {
+  private client;
+  private readonly id;
+  private state;
+  private status;
+  private error;
+  private lastStreamId;
+  private lastRunId;
+  private lastResponse;
+  private lastStructured;
+  private lastAppliedSeq;
+  private lastAppliedSeqByStream;
+  private initialMessages;
+  private listeners;
+  private destroyed;
+  private initialized;
+  private warnedHistoryCombo;
+  private options;
+  private activeAbortController;
+  constructor(client: BetterAgentClient<TApp>, options: AgentChatControllerOptions<TApp, TAgentName>);
+  /** Returns the current messages. */
+  getMessages(): UIMessage[];
+  /** Returns the current status. */
+  getStatus(): AgentStatus;
+  /** Returns the latest client error. */
+  getError(): AgentClientError | undefined;
+  /** Returns the latest stream id. */
+  getStreamId(): string | undefined;
+  /** Returns the latest run id. */
+  getRunId(): string | undefined;
+  /** True while a request is active. */
+  get isLoading(): boolean;
+  /** True while stream events are being consumed. */
+  get isStreaming(): boolean;
+  /** Returns pending tool approvals. */
+  getPendingToolApprovals(): PendingToolApproval[];
+  /** Returns an immutable snapshot. */
+  getSnapshot(): AgentChatSnapshot;
+  /** Stops the active run or stream. */
+  stop(): void;
+  /** Replaces the transport client. */
+  updateClient(client: BetterAgentClient<TApp>): void;
+  /**
+   * Subscribes to state updates.
+   */
+  subscribe(listener: () => void): () => void;
+  /** Calls each subscribed listener after controller state changes. */
+  private notify;
+  /** Stores run and stream ids from response headers. */
+  private updateResponseIds;
+  /** Starts hydration or resume behavior. */
+  init(): void;
+  /** Starts resume behavior, even with messages when allowed. */
+  private initResume;
+  /** Hydrates from server history before resuming. */
+  private hydrateFromServer;
+  /** Sends one message. */
+  sendMessage(input: ControllerRunInput, options?: SendMessageOptions): Promise<SendResult>;
+  /** Retries a user message by local id. */
+  retryMessage(localId: string): Promise<RetryResult>;
+  /** Resumes an existing stream. */
+  resumeStream(options: {
+    streamId: string;
+    afterSeq?: number;
+  }): Promise<void>;
+  /** Resumes the active stream for the current conversation. */
+  resumeConversation(options?: {
+    afterSeq?: number;
+  }): Promise<void>;
+  /** Submits a tool approval decision. */
+  approveToolCall(params: ApproveToolCallParams): Promise<void>;
+  /** Clears the current error. */
+  clearError(): void;
+  /** Resets local state to the initial snapshot. */
+  reset(): void;
+  /** Replaces local messages. */
+  setMessages(value: SetMessagesInput): void;
+  /** Merges new options into the controller configuration. */
+  updateOptions(partial: Partial<AgentChatControllerOptions<TApp, TAgentName>>): void;
+  /** Destroys the controller. */
+  destroy(): void;
+  /** Applies one streamed event to local state. */
+  private applyEvent;
+  /** Reads streamed events until the stream finishes or a terminal event appears. */
+  private consumeStreamUntilTerminal;
+  /** Reads terminal state from one streamed event. */
+  private getTerminalStateFromEvent;
+  /** Sends one request through final or stream delivery. */
+  private submitWithInternalOptions;
+  /** Builds the mutable context for one submission. */
+  private createSubmissionContext;
+  /** Warns when client history will replace stored server history. */
+  private warnIfClientHistoryReplacesConversation;
+  /** Applies retry replacement or optimistic user insertion. */
+  private applyLocalSubmissionState;
+  /** Builds the request input for the next transport call. */
+  private buildRequestInput;
+  /** Runs one request through final delivery. */
+  private runFinalDelivery;
+  /** Runs one request through streamed delivery. */
+  private runStreamDelivery;
+  /** Handles aborts, fallback-to-run, and terminal submission errors. */
+  private handleSubmissionFailure;
+  /** Marks the optimistic user message as sent after a successful request. */
+  private markOptimisticMessageSent;
+  /** Applies optimistic-message failure handling. */
+  private applyOptimisticFailure;
+  /** Stores the latest run result from final delivery. */
+  private captureNormalizedRunResult;
+  private setStatus;
+  /** Stores the latest controller error without notifying listeners. */
+  private setError;
+  /** Normalizes unknown failures into an `Error` with a fallback message. */
+  private toError;
+  /** Starts one controller operation. */
+  private startOperation;
+  /** Clears the tracked active operation if it matches the provided controller. */
+  private finishOperation;
+  /** Aborts and forgets any in-flight controller operation. */
+  private cancelActiveWork;
+  /** Merges the controller abort signal with an optional external signal. */
+  private mergeSignals;
+  /** Throws an abort-shaped error when the given signal has already aborted. */
+  private throwIfAborted;
+  /** Rejects work after the controller has been destroyed. */
+  private throwIfDestroyed;
+  /** Returns `true` when a failure should be treated as an abort. */
+  private isAbortError;
+  /** Returns true when a failure came from stream disconnection. */
+  private isStreamDisconnectError;
+  /** Returns true when the page is being torn down during navigation or refresh. */
+  private isPageTeardownLike;
+  /** Converts an abort reason into a standard `AbortError` instance. */
+  private toAbortError;
+  /** Wraps one failure as a stream disconnect. */
+  private toStreamDisconnectError;
+  /** Binds an already-visible current user turn to the replay run identity. */
+  private reconcileReplayUserMessage;
+  /** Reconstructs the replayed current user turn from one RUN_STARTED event. */
+  private toReplayUserMessage;
+  /** Detects one structured replay message item. */
+  private isSingleReplayMessageInput;
+  /** Matches one already-visible user turn to its replayed equivalent. */
+  private isSameUserTurn;
+  /** Generates a local message id using the configured factory when present. */
+  private generateMessageId;
+  /** Ensures every incoming UI message has a stable local id. */
+  private normalizeMessages;
+  /** Detects option changes that require resetting conversation session state. */
+  private hasSessionConfigurationChanged;
+  /** Resets controller state after a session-defining option changes. */
+  private resetForSessionChange;
+  /** Reads the initial resume stream id from controller options. */
+  private getConfiguredInitialStreamId;
+  /** Returns one message by local id from the current message state. */
+  private getMessageByLocalId;
+  /** Updates one message by local id and notifies listeners when found. */
+  private updateMessageByLocalId;
+  /** Removes one local message from state and notifies listeners. */
+  private removeMessageByLocalId;
+  /** Resolves the effective delivery mode for the next submission. */
+  private shouldUseStreamDelivery;
+  /** Detects stream capability errors that should retry through `run()`. */
+  private shouldFallbackToRun;
+  /** Appends model response messages to local state after final delivery. */
+  private appendResponseMessages;
+  /** Normalizes supported final-run response shapes into one controller shape. */
+  private normalizeFinalRunResult;
+  /** Builds the input payload, optionally serializing client history into it. */
+  private prepareInputForRequest;
+  /** Builds the run payload for one request. */
+  private createRunPayload;
+  /** Builds stream request hooks for ids, callbacks, and optimistic updates. */
+  private buildStreamRequestOptions;
+  /** Replaces one user message slot with a pending retry version. */
+  private replaceRetryMessage;
+  /** Derives a pending user message from retry input when possible. */
+  private createPendingUserMessage;
+  /** Normalizes supported input shapes into input items when possible. */
+  private normalizeInputItems;
+  /** Returns true when input is safely representable as one optimistic user turn. */
+  private canOptimisticallyRenderUserTurn;
+  /** Returns true when serialized history can reuse the optimistic user turn. */
+  private canOmitSubmittedInputFromSerializedHistory;
+  /** Calls `onFinish` with the latest completion data. */
+  private emitFinish;
+}
+/**
+ * Creates an `AgentChatController`.
+ */
+declare function createAgentChatController<TApp, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>>(client: BetterAgentClient<TApp>, options: AgentChatControllerOptions<TApp, TAgentName>): AgentChatController<TApp, TAgentName>;
+//#endregion
+//#region src/core/utils.d.ts
+/** Converts UI messages into model input messages. */
+declare const toModelMessages: (msgs: UIMessage[]) => Array<GenerativeModelInputItem<{
+  inputModalities: {
+    text: true;
+    audio: true;
+    image: true;
+    file: true;
+    video: true;
+  };
+  additionalSupportedRoles: readonly string[];
+}>>;
+/** Converts model input messages back into UI messages. */
+declare const fromModelMessages: (messages: GenerativeModelInputItem[], options?: {
+  generateId?: () => string;
+}) => UIMessage[];
+/** Converts durable conversation items back into UI messages. */
+declare const fromConversationItems: (items: ConversationItem[], options?: {
+  generateId?: () => string;
+}) => UIMessage[];
+//#endregion
+export { type AgentChatController, type AgentChatControllerOptions, type AgentChatSnapshot, type AgentClientError, type AgentContext, type AgentNameFromApp, type AgentRunInput, type AgentStatus, type AgentsFromApp, type ApproveToolCallParams, type AudioPart, type BetterAgentClient, type ClientConfig, type ClientEvent, type EmbeddingPart, type FilePart, type ImagePart, type InferClient, type ModalitiesForAgent, type NormalizeClientApp, type OnFinishParams, type OnToolCall, type PendingToolApproval, type PrepareMessages, type ReasoningPart, type ReplayInput, type RequestOptions, type ResumeOption, type RetryResult, type RunInputForAgent, type SendMessageOptions, type SendResult, type SetMessagesInput, type StreamRequestOptions, type SubmitInput, type SubmitToolApprovalRequest, type SubmitToolResultRequest, type TextInputShorthandForAgent, type TextPart, type ToolCallContext, type ToolCallPart, type ToolCallRequest, type ToolHandlers, type ToolResultPart, type TranscriptPart, type UIMessage, type UIMessageInput, type UIMessagePart, type VideoPart, createAgentChatController, createClient, fromConversationItems, fromModelMessages, getEventErrorMessage, pruneInputByCapabilities, toAgentClientError, toModelMessages };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/core/client/index.ts","../src/core/controller.ts","../src/core/utils.ts"],"mappings":"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"}