@better-agent/client 0.1.0-canary.0

package/README.md

@@ -0,0 +1,3 @@
+# @better-agent/client
+
+Framework client bindings for Better Agent.

package/dist/controller-CJ79_cSR.d.mts

@@ -0,0 +1,657 @@
+import { Event } from "@better-agent/core/events";
+import { BetterAgentApp, ConversationReplayOptions, InferSchemaInput, RunAdvancedOptions, RunResult, SubmitToolApprovalParams, SubmitToolResultParams, ToolTarget } from "@better-agent/core";
+import { AudioContentBase, Capabilities, ConversationItem, EmbeddingContentBase, FileContentBase, GenerativeModel, GenerativeModelInput, GenerativeModelInputItem, GenerativeModelResponse, ImageContentBase, InputEnabled, ModalitiesParam, Modality, ModalityOptionsFor, ModelOptions, OutputSchemaForCaps, TextContentBase, VideoContentBase } from "@better-agent/core/providers";
+
+//#region src/types/client-type-helpers.d.ts
+type InferPortableOrSchemaInput<TValue> = TValue extends {
+  "~standard"?: {
+    types?: {
+      input?: unknown;
+    };
+  };
+} ? InferSchemaInput<TValue> : TValue extends {
+  type: unknown;
+} ? InferSchemaInput<TValue> : TValue;
+type InferPortableOrSchemaOutput<TValue> = TValue extends {
+  schema: infer TSchema;
+} ? InferPortableOrSchemaInput<NonNullable<TSchema>> : TValue;
+/** Extracts `config.agents` from the typed app config. */
+type AgentsFromApp<TApp> = TApp extends {
+  __appTypes?: {
+    agents: infer TAgents;
+  };
+} ? TAgents extends readonly {
+  name: string;
+}[] ? TAgents : never : TApp extends {
+  config: {
+    agents: infer TAgents;
+  };
+} ? TAgents extends readonly {
+  name: string;
+}[] ? TAgents : never : TApp extends BetterAgentApp<infer TAgents, infer _TPlugins> ? TAgents extends readonly {
+  name: string;
+}[] ? TAgents : never : never;
+/**
+ * Agent names available from the typed server app.
+ *
+ * Falls back to `string` for untyped clients.
+ */
+type AgentNameFromApp<TApp> = [AgentsFromApp<TApp>] extends [never] ? string : AgentsFromApp<TApp>[number]["name"];
+type AgentsRawFromApp<TApp> = TApp extends {
+  __appTypes?: {
+    agents: infer TAgents;
+  };
+} ? TAgents extends readonly unknown[] ? TAgents : never : TApp extends {
+  config: {
+    agents: infer TAgents;
+  };
+} ? TAgents extends readonly unknown[] ? TAgents : never : TApp extends BetterAgentApp<infer TAgents, infer _TPlugins> ? TAgents extends readonly unknown[] ? TAgents : never : never;
+type AppToolsArrayFromApp<TApp> = TApp extends {
+  __appTypes?: {
+    tools: infer TTools extends readonly unknown[];
+  };
+} ? TTools : TApp extends {
+  config: {
+    tools?: infer TTools extends readonly unknown[];
+  };
+} ? TTools : never;
+type SlimAgentForClient<TAgent> = TAgent extends {
+  name: infer TName extends string;
+} ? {
+  name: TName;
+} & (TAgent extends {
+  model: infer TModel;
+} ? {
+  model: TModel;
+} : Record<never, never>) & {} & (TAgent extends {
+  contextSchema: infer TContextSchema;
+} ? {
+  contextSchema: TContextSchema;
+} : Record<never, never>) & (TAgent extends {
+  outputSchema: infer TOutputSchema;
+} ? {
+  outputSchema: TOutputSchema;
+} : Record<never, never>) & (TAgent extends {
+  execution?: infer TExecution;
+} ? {
+  execution: TExecution;
+} : Record<never, never>) & (TAgent extends {
+  tools?: infer TTools;
+} ? {
+  tools: TTools;
+} : Record<never, never>) : never;
+type SlimAgentsForClient<TAgents extends readonly unknown[]> = { readonly [TIndex in keyof TAgents]: SlimAgentForClient<TAgents[TIndex]> };
+/** Normalized app shape used for client-side type inference. */
+type NormalizeClientApp<TApp> = [AgentsRawFromApp<TApp>] extends [never] ? unknown : {
+  config: {
+    agents: SlimAgentsForClient<AgentsRawFromApp<TApp>>;
+    tools?: AppToolsArrayFromApp<TApp>;
+  };
+};
+type AppLevelToolsFromApp<TApp> = TApp extends {
+  __appTypes?: {
+    tools: infer TTools extends readonly unknown[];
+  };
+} ? TTools[number] : TApp extends {
+  config: {
+    tools?: infer TTools extends readonly unknown[];
+  };
+} ? TTools[number] : never;
+type AgentStaticToolsFromAgent<TAgent> = TAgent extends {
+  tools?: infer TTools;
+} ? TTools extends readonly unknown[] ? TTools[number] : never : never;
+type AgentStaticToolsFromApp<TApp> = [AgentsFromApp<TApp>] extends [never] ? never : AgentStaticToolsFromAgent<AgentsRawFromApp<TApp>[number]>;
+type ClientToolFromApp<TApp> = Extract<AppLevelToolsFromApp<TApp> | AgentStaticToolsFromApp<TApp>, {
+  kind: "client";
+  name: string;
+  schema: unknown;
+}>;
+/** Keeps only named client tools with literal names. */
+type LiteralClientToolFromApp<TApp> = ClientToolFromApp<TApp> extends infer TTool ? TTool extends {
+  kind: "client";
+  name: string;
+  schema: unknown;
+} ? string extends TTool["name"] ? never : TTool : never : never;
+type KnownToolNameFromApp<TApp> = LiteralClientToolFromApp<TApp>["name"];
+type ToolNameFromApp<TApp> = [KnownToolNameFromApp<TApp>] extends [never] ? string : KnownToolNameFromApp<TApp>;
+type ToolByName<TApp, TToolName extends ToolNameFromApp<TApp>> = Extract<LiteralClientToolFromApp<TApp>, {
+  name: TToolName;
+}>;
+/** Input type for a specific client tool. */
+type ToolInputFromApp<TApp, TToolName extends ToolNameFromApp<TApp>> = [ToolByName<TApp, TToolName>] extends [never] ? unknown : ToolByName<TApp, TToolName>["schema"] extends infer TSchema ? TSchema extends object ? InferPortableOrSchemaInput<TSchema> : unknown : unknown;
+/** Client tool names available from the typed server app. */
+type ToolNameForApp<TApp> = ToolNameFromApp<TApp>;
+type UntypedRunInput = {
+  input: unknown;
+  context?: unknown;
+  output?: unknown;
+  modalities?: readonly Modality[];
+  modelOptions?: Record<string, unknown>;
+  maxSteps?: number;
+  conversationId?: string;
+  [key: string]: unknown;
+};
+type AgentByNameFromApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = Extract<AgentsFromApp<TApp>[number], {
+  name: TAgentName;
+}>;
+type AgentFromApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = AgentByNameFromApp<TApp, TAgentName>;
+type AgentModelFromApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = AgentFromApp<TApp, TAgentName> extends {
+  model: infer TModel;
+} ? TModel : never;
+type AgentOutputSchemaFromApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = AgentFromApp<TApp, TAgentName> extends {
+  outputSchema: infer TOutputSchema;
+} ? TOutputSchema : never;
+type AgentCapsFromApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = AgentModelFromApp<TApp, TAgentName> extends {
+  caps: infer TCaps extends Capabilities;
+} ? TCaps : Capabilities;
+type AgentModelOptionsFromApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = AgentModelFromApp<TApp, TAgentName> extends GenerativeModel<infer TOptions, infer _TProviderId, infer _TModelId, infer _TCaps> ? ModelOptions<TOptions> : AgentModelFromApp<TApp, TAgentName> extends {
+  options: infer TOptions extends Record<string, unknown>;
+} ? ModelOptions<TOptions> : Record<never, never>;
+type AgentOutputOverrideForApp<TApp, TAgentName extends AgentNameFromApp<TApp>> = OutputSchemaForCaps<AgentCapsFromApp<TApp, TAgentName>>;
+type TypedModalitiesForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>> = ModalitiesParam<AgentCapsFromApp<TApp, TAgentName>>;
+type ModalitiesForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>> = [AgentsFromApp<TApp>] extends [never] ? readonly Modality[] : TypedModalitiesForAgent<TApp, TAgentName>;
+type TextInputShorthandForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>> = [AgentsFromApp<TApp>] extends [never] ? string : InputEnabled<AgentCapsFromApp<TApp, TAgentName>, "text"> extends true ? string : never;
+type StructuredOutputForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>, TOutput> = [AgentsFromApp<TApp>] extends [never] ? unknown : [TOutput] extends [undefined] ? InferPortableOrSchemaOutput<AgentOutputSchemaFromApp<TApp, TAgentName>> : InferPortableOrSchemaOutput<TOutput>;
+type DefaultStructuredOutputForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>> = StructuredOutputForAgent<TApp, TAgentName, undefined>;
+type StructuredRunResult<TStructured> = Omit<RunResult<TStructured>, "structured"> & {
+  structured: TStructured;
+};
+type UnstructuredRunResult = Omit<RunResult<never>, "structured">;
+type TypedContextInput<TApp, TAgentName extends AgentNameFromApp<TApp>> = [AgentsFromApp<TApp>] extends [never] ? {
+  context?: unknown;
+} : AgentByNameFromApp<TApp, TAgentName> extends {
+  contextSchema: infer TContextSchema;
+} ? {
+  context: InferPortableOrSchemaInput<TContextSchema>;
+} : {
+  context?: never;
+};
+type TypedRunnerInputForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>, TModalities extends TypedModalitiesForAgent<TApp, TAgentName> | undefined = undefined> = [AgentsFromApp<TApp>] extends [never] ? UntypedRunInput : {
+  input: GenerativeModelInput<AgentCapsFromApp<TApp, TAgentName>>;
+  modalities?: TModalities;
+  modelOptions?: AgentModelOptionsFromApp<TApp, TAgentName> & ModalityOptionsFor<AgentCapsFromApp<TApp, TAgentName>, TModalities> & Record<string, unknown>;
+  conversationId?: string;
+  conversationReplay?: ConversationReplayOptions;
+  replaceHistory?: boolean;
+  maxSteps?: number;
+  advanced?: RunAdvancedOptions;
+} & TypedContextInput<TApp, TAgentName>;
+/**
+ * Typed run input for one agent.
+ *
+ * This excludes `onClientToolCall`, client-side tool handling is configured through stream request options.
+ */
+type RunInputForAgent<TApp = unknown, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>, TModalities = undefined> = [AgentsFromApp<TApp>] extends [never] ? UntypedRunInput : TypedRunnerInputForAgent<TApp, TAgentName, Extract<TModalities, TypedModalitiesForAgent<TApp, TAgentName> | undefined>>;
+type RunResultForAgent<TApp, TAgentName extends AgentNameFromApp<TApp>, TOutput> = [AgentsFromApp<TApp>] extends [never] ? RunResult<unknown> : [StructuredOutputForAgent<TApp, TAgentName, Extract<TOutput, AgentOutputOverrideForApp<TApp, TAgentName> | undefined>>] extends [never] ? UnstructuredRunResult : StructuredRunResult<StructuredOutputForAgent<TApp, TAgentName, Extract<TOutput, AgentOutputOverrideForApp<TApp, TAgentName> | undefined>>>;
+type AgentRunInput<TApp, TAgentName extends AgentNameFromApp<TApp>> = RunInputForAgent<TApp, TAgentName>;
+type AgentContext<TApp, TAgentName extends AgentNameFromApp<TApp>> = AgentByNameFromApp<TApp, TAgentName> extends {
+  contextSchema: infer TContextSchema;
+} ? InferPortableOrSchemaInput<TContextSchema> : [AgentsFromApp<TApp>] extends [never] ? unknown : never;
+type AgentContextInputField<TApp, TAgentName extends AgentNameFromApp<TApp>> = [AgentsFromApp<TApp>] extends [never] ? {
+  context?: unknown;
+} : AgentByNameFromApp<TApp, TAgentName> extends {
+  contextSchema: infer TContextSchema;
+} ? {
+  context: InferPortableOrSchemaInput<TContextSchema>;
+} : {
+  context?: AgentContext<TApp, TAgentName>;
+};
+//#endregion
+//#region src/types/client.d.ts
+/** Configuration for `createClient`. */
+interface ClientConfig<TApp = unknown> {
+  /** Better Agent API base URL. */
+  baseURL: string;
+  /** Better Agent auth secret, when the server requires bearer auth. */
+  secret?: string;
+  /** Default request headers. */
+  headers?: Headers | Record<string, string>;
+  /** Custom fetch implementation. */
+  fetch?: typeof fetch;
+  /** Default client tool handlers. */
+  toolHandlers?: ToolHandlers<TApp>;
+  /** Advanced options. */
+  advanced?: {
+    /** Rewrites outgoing requests. */prepareRequest?: (context: PrepareRequestContext) => PrepareRequestResult | undefined | Promise<PrepareRequestResult | undefined>; /** Max retries for tool results and approvals. */
+    toolSubmissionMaxAttempts?: number; /** Base retry delay for tool results and approvals. */
+    toolSubmissionRetryDelayMs?: number;
+  };
+}
+/** Standard HTTP request methods. */
+type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH";
+/** Context passed to `prepareRequest`. */
+type PrepareRequestContext = {
+  /** Request operation. */operation: "run" | "stream" | "resume-stream" | "resume-conversation" | "load-conversation" | "abort-run" | "tool-result" | "tool-approval"; /** Request URL before overrides. */
+  url: string; /** Request method. */
+  method: HttpMethod; /** Request headers before overrides. */
+  headers: Headers | Record<string, string>; /** Request body, when present. */
+  body?: BodyInit | null;
+};
+/** Overrides returned by `prepareRequest`. */
+type PrepareRequestResult = {
+  /** URL override. */url?: string; /** Method override. */
+  method?: HttpMethod; /** Headers override. */
+  headers?: Headers | Record<string, string>; /** Body override. */
+  body?: BodyInit | null;
+};
+/** Per-request transport options. */
+interface RequestOptions<_TApp = unknown> {
+  /** Request-scoped headers. */
+  headers?: Headers | Record<string, string>;
+  /** Abort signal. */
+  signal?: AbortSignal | null;
+  /** Called after the HTTP response is received. */
+  onResponse?: (response: Response) => void;
+}
+/** Options for streaming requests. */
+interface StreamRequestOptions<TApp = unknown> extends RequestOptions<TApp> {
+  /** Request-scoped function tool handler. */
+  onToolCall?: OnToolCall<TApp>;
+  /** Request-scoped map tool handlers. */
+  toolHandlers?: ToolHandlers<TApp>;
+}
+/** Request payload for `submitToolResult`. */
+type SubmitToolResultRequest<TApp = unknown> = {
+  agent: AgentNameFromApp<TApp>;
+} & SubmitToolResultParams;
+/** Request payload for `submitToolApproval`. */
+type SubmitToolApprovalRequest<TApp = unknown> = {
+  agent: AgentNameFromApp<TApp>;
+} & SubmitToolApprovalParams;
+/** Request payload for `abortRun`. */
+type AbortRunRequest<TApp = unknown> = {
+  /** Agent name. */agent: AgentNameFromApp<TApp>; /** Run id. */
+  runId: string;
+};
+interface BetterAgentClient<TApp = unknown> {
+  /**
+   * Runs an agent and returns the final response.
+   *
+   * Use `stream()` when the agent may use client tools or approvals.
+   */
+  run<TAgentName extends AgentNameFromApp<TApp>, const TModalities extends ModalitiesForAgent<TApp, TAgentName> | undefined = undefined, TOutput = undefined>(agent: TAgentName, input: RunInputForAgent<TApp, TAgentName, TModalities> & {
+    output?: TOutput;
+  }, options?: RequestOptions<TApp>): Promise<RunResultForAgent<TApp, TAgentName, Extract<TOutput, unknown>>>;
+  /** Runs an agent and streams events. */
+  stream<TAgentName extends AgentNameFromApp<TApp>, const TModalities extends ModalitiesForAgent<TApp, TAgentName> | undefined = undefined>(agent: TAgentName, input: RunInputForAgent<TApp, TAgentName, TModalities>, options?: StreamRequestOptions<TApp>): AsyncIterable<ClientEvent>;
+  /** Resumes one stream. */
+  resumeStream<TAgentName extends AgentNameFromApp<TApp>>(agent: TAgentName, input: ReplayInput, options?: RequestOptions<TApp>): AsyncIterable<ClientEvent>;
+  /** Resumes the active stream for a conversation. */
+  resumeConversation<TAgentName extends AgentNameFromApp<TApp>>(agent: TAgentName, input: {
+    conversationId: string;
+    afterSeq?: number;
+  }, options?: RequestOptions<TApp>): AsyncIterable<ClientEvent>;
+  /**
+   * Loads persisted conversation items.
+   *
+   * Returns `null` when no stored history exists.
+   */
+  loadConversation?(agent: AgentNameFromApp<TApp>, conversationId: string, options?: RequestOptions<TApp>): Promise<{
+    items: ConversationItem[];
+  } | null>;
+  /** Aborts an active run. */
+  abortRun(req: AbortRunRequest<TApp>, options?: RequestOptions<TApp>): Promise<void>;
+  /** Submits a client tool result. */
+  submitToolResult(req: SubmitToolResultRequest<TApp>): Promise<void>;
+  /** Submits a tool approval decision. */
+  submitToolApproval(req: SubmitToolApprovalRequest<TApp>): Promise<void>;
+}
+/** Context passed to client tool handlers. */
+type ToolCallContext<TApp = unknown> = {
+  /** Agent name. */agent: AgentNameFromApp<TApp>; /** Run id. */
+  runId: string; /** Tool-call id. */
+  toolCallId: string; /** Aborts when the run ends or disconnects. */
+  signal?: AbortSignal;
+};
+/**
+ * Map of tool handlers keyed by tool name.
+ */
+type ToolHandlers<TApp = unknown> = Partial<{ [TToolName in ToolNameForApp<TApp>]: (input: ToolInputFromApp<TApp, TToolName>, context: ToolCallContext<TApp>) => unknown | Promise<unknown> }>;
+/**
+ * Tool-call payload for function handlers.
+ */
+type ToolCallRequest<TApp = unknown> = {
+  /** Tool name. */toolName: ToolNameForApp<TApp>; /** Tool input. */
+  input: unknown; /** Tool call context. */
+  context: ToolCallContext<TApp>;
+};
+/** Function form for handling client tool calls. */
+type OnToolCall<TApp = unknown> = (params: ToolCallRequest<TApp>) => unknown | Promise<unknown>;
+/** Input for replay and resume APIs. */
+type ReplayInput = {
+  streamId: string;
+  /**
+   * Cursor to continue after.
+   *
+   * Use `-1` to resume from the start.
+   */
+  afterSeq?: number;
+};
+/**
+ * Events emitted by client streams.
+ *
+ * `seq`, `streamId`, and `runId` are added by the client transport when needed.
+ */
+type ClientEvent = Event & {
+  seq?: number;
+  streamId?: string;
+  runId?: string;
+};
+/** Helper type for exposing the inferred client and agent-name union together. */
+type InferClient<TApp> = {
+  agentNames: AgentNameFromApp<TApp>;
+  client: BetterAgentClient<TApp>;
+};
+//#endregion
+//#region src/core/error.d.ts
+/** One frame from a serialized Better Agent error trace. */
+interface AgentClientErrorTraceFrame {
+  /** Trace step name. */
+  at: string;
+  /** Optional trace metadata. */
+  data?: Record<string, unknown>;
+}
+/** Client-normalized Better Agent error shape. */
+interface AgentClientError extends Error {
+  /** Stable error code. */
+  code?: string;
+  /** HTTP status when available. */
+  status?: number;
+  /** Whether the request may succeed on retry. */
+  retryable?: boolean;
+  /** Short human title. */
+  title?: string;
+  /** Detailed error message. */
+  detail?: string;
+  /** Validation or structured issues. */
+  issues?: unknown[];
+  /** Server trace id. */
+  traceId?: string;
+  /** Extra error context. */
+  context?: Record<string, unknown>;
+  /** Structured trace frames. */
+  trace?: AgentClientErrorTraceFrame[];
+  /** Original thrown value. */
+  raw?: unknown;
+}
+/** Normalizes unknown failures into `AgentClientError`. */
+declare const toAgentClientError: (error: unknown, fallbackMessage?: string) => AgentClientError;
+/**
+ * Resolves a user-facing message from an event error payload.
+ */
+declare const getEventErrorMessage: (error: unknown) => string;
+//#endregion
+//#region src/types/ui.d.ts
+interface TextPart extends TextContentBase {
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface AudioPart extends AudioContentBase {
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface ImagePart extends ImageContentBase {
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface FilePart extends FileContentBase {
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface VideoPart extends VideoContentBase {
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface EmbeddingPart extends EmbeddingContentBase {
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface TranscriptPart {
+  /** Part type. */
+  type: "transcript";
+  /** Transcript text. */
+  text: string;
+  /** Transcript segments. */
+  segments?: Array<{
+    /** Segment id. */id: string; /** Segment start time in seconds. */
+    start: number; /** Segment end time in seconds. */
+    end: number; /** Segment text. */
+    text: string; /** Speaker label. */
+    speaker?: string;
+  }>;
+  /** Provider metadata. */
+  providerMetadata?: Record<string, unknown>;
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface ReasoningPart {
+  /** Part type. */
+  type: "reasoning";
+  /** Reasoning text. */
+  text: string;
+  /** Reasoning visibility. */
+  visibility: "summary" | "full";
+  /** Provider name. */
+  provider?: string;
+  /** Provider metadata. */
+  providerMetadata?: Record<string, unknown>;
+  /** Present when the part is complete. */
+  state?: "complete";
+}
+interface ToolCallPart {
+  /** Part type. */
+  type: "tool-call";
+  /** Tool-call id. */
+  callId: string;
+  /** Tool name. */
+  name?: string;
+  /** Tool arguments as JSON. */
+  args?: string;
+  /** Tool location. */
+  toolTarget?: ToolTarget;
+  /** Approval details. */
+  approval?: {
+    /** Approval input. */input?: unknown; /** Approval metadata. */
+    meta?: Record<string, unknown>; /** Approval note. */
+    note?: string; /** Actor id. */
+    actorId?: string;
+  };
+  /** Tool-call status. */
+  status: "pending" | "success" | "error";
+  /** Tool-call lifecycle state. */
+  state?: "awaiting-input" | "input-streaming" | "input-complete" | "approval-requested" | "approval-approved" | "approval-denied" | "approval-expired" | "completed";
+}
+interface ToolResultPart {
+  /** Part type. */
+  type: "tool-result";
+  /** Tool-call id. */
+  callId: string;
+  /** Tool result payload. */
+  result?: unknown;
+  /** Tool-result status. */
+  status: "pending" | "success" | "error";
+}
+/** One part inside a `UIMessage`. */
+type UIMessagePart = TextPart | AudioPart | ImagePart | FilePart | VideoPart | EmbeddingPart | TranscriptPart | ReasoningPart | ToolCallPart | ToolResultPart;
+interface UIMessage {
+  /**
+   * Local message id.
+   *
+   * `setMessages` may omit this field; Better Agent will generate one.
+   */
+  localId: string;
+  /** Server message id. */
+  id?: string;
+  /** Message role. */
+  role: "system" | "assistant" | "user" | (string & {});
+  /** Message parts. */
+  parts: UIMessagePart[];
+  /** Local delivery state. */
+  status?: "pending" | "sent" | "failed";
+  /** Local error message. */
+  error?: string;
+}
+/** Pending approval extracted from the current message state. */
+interface PendingToolApproval {
+  /** Tool-call id. */
+  toolCallId: string;
+  /** Tool name. */
+  toolName?: string;
+  /** Tool arguments as JSON. */
+  args?: string;
+  /** Tool location. */
+  toolTarget?: ToolTarget;
+  /** Approval input. */
+  input?: unknown;
+  /** Approval metadata. */
+  meta?: Record<string, unknown>;
+  /** Approval note. */
+  note?: string;
+  /** Actor id. */
+  actorId?: string;
+}
+//#endregion
+//#region src/types/controller.d.ts
+/** Input for a `UIMessage` before `localId` is assigned. */
+type UIMessageInput = Omit<UIMessage, "localId"> & {
+  localId?: string;
+};
+/** Next messages or a function that returns them. */
+type SetMessagesInput = UIMessageInput[] | ((messages: UIMessage[]) => UIMessageInput[]);
+/** Input for `sendMessage`. */
+type SubmitInput<TApp = unknown, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>, TModalities extends ModalitiesForAgent<TApp, TAgentName> | undefined = undefined> = Omit<RunInputForAgent<TApp, TAgentName, TModalities>, "conversationId" | "sendClientHistory">;
+/** Public `sendMessage` input. */
+type SendMessageInputForAgent<TApp = unknown, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>, TModalities extends ModalitiesForAgent<TApp, TAgentName> | undefined = undefined> = TextInputShorthandForAgent<TApp, TAgentName> | SubmitInput<TApp, TAgentName, TModalities>;
+/** Custom model-history preparation for `sendClientHistory`. */
+type PrepareMessages = (params: {
+  messages: UIMessage[];
+  input: unknown;
+}) => GenerativeModelInputItem[];
+/** Internal controller run input shape. */
+type ControllerRunInput = Record<string, unknown> & {
+  input: unknown;
+  context?: unknown | undefined;
+  modalities?: readonly string[] | undefined;
+  modelOptions?: Record<string, unknown> | undefined;
+};
+/** Immutable controller snapshot. */
+interface AgentChatSnapshot {
+  /** Stable local chat id. */
+  id: string;
+  /** Conversation id, when provided. */
+  conversationId: string | undefined;
+  /** Conversation messages. */
+  messages: UIMessage[];
+  /** Current request status. */
+  status: AgentStatus;
+  /** Latest client error. */
+  error: AgentClientError | undefined;
+  /** Latest stream id. */
+  streamId: string | undefined;
+  /** Latest run id. */
+  runId: string | undefined;
+  /** True while a request is active. */
+  isLoading: boolean;
+  /** True while streaming events are being consumed. */
+  isStreaming: boolean;
+  /** Pending tool approvals. */
+  pendingToolApprovals: PendingToolApproval[];
+}
+/** Chat request status. */
+type AgentStatus = "ready" | "hydrating" | "submitted" | "streaming" | "error";
+/** Startup resume behavior. */
+type ResumeOption = boolean | {
+  afterSeq?: number;
+  streamId?: string;
+};
+/** Options for `AgentChatController`. */
+type AgentChatControllerOptions<TApp = unknown, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>> = {
+  /** Stable local chat id. */id?: string; /** Agent name. */
+  agent: TAgentName; /** Conversation id. */
+  conversationId?: string; /** Default provider model options. */
+  modelOptions?: RunInputForAgent<TApp, TAgentName> extends {
+    modelOptions?: infer TModelOptions;
+  } ? TModelOptions : Record<string, unknown>; /** Delivery strategy. */
+  delivery?: "auto" | "stream" | "final"; /** Initial UI messages. */
+  initialMessages?: UIMessageInput[]; /** Resumes a stream or conversation on init. */
+  resume?: ResumeOption; /** Sends full client-side history with each request. */
+  sendClientHistory?: boolean; /** Fully overrides client history serialization when replay is enabled. */
+  prepareMessages?: PrepareMessages;
+  /**
+   * Loads conversation history from the server on init when `conversationId` is set.
+   *
+   * Server history replaces `initialMessages` when found.
+   */
+  hydrateFromServer?: boolean; /** Generates local message ids. */
+  generateMessageId?: (message?: Partial<UIMessageInput>) => string; /** Controls optimistic user-message insertion. */
+  optimisticUserMessage?: boolean | {
+    enabled?: boolean;
+    onError?: "fail" | "remove";
+  }; /** Per-run function tool handler. */
+  onToolCall?: OnToolCall<TApp>; /** Per-run map-based tool handlers. */
+  toolHandlers?: ToolHandlers<TApp>; /** Called when a run ends. */
+  onFinish?: (opts: OnFinishParams<TApp, TAgentName>) => void; /** Called when an optimistic user message fails. */
+  onOptimisticUserMessageError?: (params: {
+    message: UIMessage;
+    error: Error;
+  }) => void; /** Called for `DATA_PART` events. */
+  onData?: (part: {
+    id?: string;
+    data: unknown;
+  }) => void; /** Called after the HTTP response is received. */
+  onResponse?: (response: Response) => void; /** Called when the run fails. */
+  onError?: (error: Error) => void; /** Called for every streamed event. */
+  onEvent?: (event: ClientEvent) => void; /** Called when streaming disconnects. */
+  onDisconnect?: (info: {
+    error: Error;
+    runId?: string;
+    streamId?: string;
+  }) => void;
+} & AgentContextInputField<TApp, TAgentName>;
+type OnFinishStructuredField<TApp, TAgentName extends AgentNameFromApp<TApp>> = [DefaultStructuredOutputForAgent<TApp, TAgentName>] extends [never] ? object : {
+  /** Final parsed structured output, when this agent has a output schema. */structured: DefaultStructuredOutputForAgent<TApp, TAgentName>;
+};
+/** `onFinish` callback parameters. */
+type OnFinishParams<TApp = unknown, TAgentName extends AgentNameFromApp<TApp> = AgentNameFromApp<TApp>> = {
+  /** Final local messages. */messages: UIMessage[]; /** Run id, when available. */
+  runId?: string; /** Stream id, when available. */
+  streamId?: string; /** Conversation id, when configured. */
+  conversationId?: string; /** Final model response, when available. */
+  response?: GenerativeModelResponse; /** Finish reason, when available. */
+  finishReason?: GenerativeModelResponse["finishReason"]; /** Usage, when available. */
+  usage?: GenerativeModelResponse["usage"]; /** True when the run was aborted. */
+  isAbort: boolean;
+} & OnFinishStructuredField<TApp, TAgentName>;
+/** Result from `sendMessage`. */
+interface SendResult {
+  /** Run id, when available. */
+  runId?: string;
+  /** Stream id, when available. */
+  streamId?: string;
+}
+/** Result from `retryMessage`. */
+interface RetryResult {
+  /** Stream id, when available. */
+  streamId?: string;
+}
+/** Parameters for `approveToolCall`. */
+interface ApproveToolCallParams {
+  /** Tool-call id. */
+  toolCallId: string;
+  /** Run id override. Defaults to the latest run id. */
+  runId?: string;
+  /** Approval decision. */
+  decision: "approved" | "denied";
+  /** Approval note. */
+  note?: string;
+  /** Actor id. */
+  actorId?: string;
+}
+/** Options for `sendMessage`. */
+interface SendMessageOptions {
+  /** Abort signal. */
+  signal?: AbortSignal;
+}
+//#endregion
+export { getEventErrorMessage as A, SubmitToolApprovalRequest as B, ToolCallPart as C, UIMessagePart as D, UIMessage as E, InferClient as F, AgentContext as G, ToolCallContext as H, OnToolCall as I, AgentsFromApp as J, AgentNameFromApp as K, ReplayInput as L, BetterAgentClient as M, ClientConfig as N, VideoPart as O, ClientEvent as P, TextInputShorthandForAgent as Q, RequestOptions as R, TextPart as S, TranscriptPart as T, ToolCallRequest as U, SubmitToolResultRequest as V, ToolHandlers as W, NormalizeClientApp as X, ModalitiesForAgent as Y, RunInputForAgent as Z, EmbeddingPart as _, ControllerRunInput as a, PendingToolApproval as b, ResumeOption as c, SendMessageOptions as d, SendResult as f, AudioPart as g, UIMessageInput as h, ApproveToolCallParams as i, toAgentClientError as j, AgentClientError as k, RetryResult as l, SubmitInput as m, AgentChatSnapshot as n, OnFinishParams as o, SetMessagesInput as p, AgentRunInput as q, AgentStatus as r, PrepareMessages as s, AgentChatControllerOptions as t, SendMessageInputForAgent as u, FilePart as v, ToolResultPart as w, ReasoningPart as x, ImagePart as y, StreamRequestOptions as z };
+//# sourceMappingURL=controller-CJ79_cSR.d.mts.map