bs-agent 0.0.9 → 0.0.12

package/dist/react/index.d.ts

@@ -0,0 +1,287 @@
+import { T as ToolType } from '../types-DryLPWU9.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import 'zod';
+
+type ToolExecutionItem = {
+    itemType: "tool_call";
+    toolName: string;
+    callId: string;
+    toolType: ToolType;
+    status: "progress" | "complete" | "error";
+    inputs?: unknown;
+    output?: unknown;
+    error?: string;
+    serverName?: string;
+};
+type ReasoningItem = {
+    itemType: "reasoning";
+    reasoning: string;
+    index?: number;
+};
+type HandoffItem = {
+    itemType: "handoff";
+    agentName: string;
+};
+type RunErrorItem = {
+    itemType: "run_error";
+    message: string;
+    code?: string;
+};
+type WidgetExecutionItem = {
+    toolName: string;
+    callId: string;
+    inputs: any;
+};
+type ClientToolDefinition = {
+    name: string;
+    description: string;
+    parameters: unknown;
+    await?: boolean;
+};
+type DebugDataType = Array<ToolExecutionItem | ReasoningItem | HandoffItem | RunErrorItem>;
+type MessagePart = {
+    type: "text";
+    text: string;
+    firstSequence: number;
+    lastSequence: number;
+} | {
+    type: "widget";
+    toolName: string;
+    callId: string;
+    inputs: any;
+    sequence: number;
+    paused?: boolean;
+    status?: "pending" | "submitted";
+    /** Persisted result from a tool submission (handler or widget submit). */
+    result?: any;
+};
+type Message = {
+    role: "user" | "agent";
+    content: string;
+    parts?: Array<MessagePart>;
+    executionId?: string;
+};
+type Session = {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    messages: Array<Message>;
+    name?: string;
+};
+type ToolConfig = {
+    name: string;
+    description: string;
+    schema: unknown;
+    await?: boolean;
+};
+
+/**
+ * Infer the output type from a Zod schema's structural shape (`_zod.output`).
+ * Falls back to `any` for raw JSON Schema objects or untyped parameters.
+ * @internal
+ */
+type InferInput<T> = T extends {
+    _zod: {
+        output: infer O;
+    };
+} ? O : any;
+interface ClientToolRenderProps<T = any> {
+    /** Parsed inputs from the agent. */
+    inputs: T;
+    /** Submit a result back to the agent (only available when `await: true`). */
+    submit: (result: any) => void;
+    /** Current status of this widget instance. */
+    status: "pending" | "submitted";
+    /** The persisted result from a previous submission (available after submit or on reload). */
+    result?: any;
+}
+interface ClientToolConfig<TParams = any> {
+    /** Tool name — must match the name the agent knows. */
+    name: string;
+    /** Description of what the tool does. */
+    description: string;
+    /**
+     * Tool parameters — accepts a **Zod schema** or a raw JSON Schema object.
+     * When a Zod schema is provided, `handler` and `render` inputs are
+     * automatically typed — no explicit generic needed.
+     *
+     * @example
+     * parameters: z.object({ question: z.string() })
+     */
+    parameters: TParams;
+    /** If true, agent pauses and waits for the tool result before continuing. */
+    await?: boolean;
+    /**
+     * Handler function for headless tools (no UI).
+     * If `await: true`, the return value is sent back to the agent.
+     * If `await: false`, runs as fire-and-forget.
+     * Inputs are automatically typed when `parameters` is a Zod schema.
+     */
+    handler?: (inputs: InferInput<TParams>) => any | Promise<any>;
+    /**
+     * Render function for widget tools (with UI).
+     * Receives `{ inputs, submit, status }`.
+     * - `submit(result)` resumes the agent when `await: true`.
+     * - `status` is `"pending"` until submitted, then `"submitted"`.
+     * Inputs are automatically typed when `parameters` is a Zod schema.
+     */
+    render?: (props: ClientToolRenderProps<InferInput<TParams>>) => any;
+}
+/**
+ * Register a client tool for a specific agent.
+ *
+ * @example
+ * ```tsx
+ * // Headless tool
+ * useClientTool("agent-123", {
+ *   name: "get_location",
+ *   description: "Gets user location",
+ *   parameters: z.object({}),
+ *   handler: async () => {
+ *     const pos = await getPosition();
+ *     return { lat: pos.coords.latitude, lng: pos.coords.longitude };
+ *   },
+ * });
+ *
+ * // Widget tool with submission
+ * useClientTool("agent-123", {
+ *   name: "feedback_form",
+ *   description: "Collects feedback",
+ *   parameters: z.object({ question: z.string() }),
+ *   await: true,
+ *   render: ({ inputs, submit, status }) => (
+ *     <form onSubmit={() => submit({ answer: "..." })}>
+ *       <p>{inputs.question}</p>
+ *       <button disabled={status !== "pending"}>Submit</button>
+ *     </form>
+ *   ),
+ * });
+ * ```
+ */
+declare function useClientTool<TParams>(agentId: string, config: ClientToolConfig<TParams>): void;
+interface ToolRendererProps {
+    /** The agent ID this tool belongs to. */
+    agentId: string;
+    /** The widget message part to render. */
+    part: {
+        toolName: string;
+        callId: string;
+        inputs: any;
+        paused?: boolean;
+        status?: "pending" | "submitted";
+        result?: any;
+    };
+}
+/**
+ * Renders a registered widget tool.
+ * Looks up the tool by name from the registry and renders it with
+ * the appropriate props (inputs, submit, status).
+ *
+ * @example
+ * ```tsx
+ * {message.parts?.map((part) => {
+ *   if (part.type === "widget") {
+ *     return <ToolRenderer key={part.callId} agentId="agent-123" part={part} />;
+ *   }
+ *   return <Markdown key={part.firstSequence}>{part.text}</Markdown>;
+ * })}
+ * ```
+ */
+declare function ToolRenderer({ agentId, part }: ToolRendererProps): any;
+
+interface AgentRunner {
+    messages: Message[];
+    inProgress: boolean;
+    sessionId: string;
+    sessions: Session[];
+    debugData: Record<string, DebugDataType>;
+    handleSend: (input: string, options?: {
+        context?: Record<string, unknown>;
+        skipUserMessage?: boolean;
+        additionalHeaders?: Record<string, string>;
+        additionalBody?: Record<string, unknown>;
+        /** @deprecated Use `useClientTool` hook instead. */
+        clientTools?: Array<{
+            name: string;
+            description: string;
+            parameters: unknown;
+            await?: boolean;
+        }>;
+    }) => Promise<void>;
+    resumeTool: (callId: string, result: any) => Promise<void>;
+    switchSession: (sessionId?: string) => void;
+    deleteSession: (sessionId: string) => void;
+    addOptimisticMessage: (input: string) => void;
+    abort: () => void;
+}
+interface AgentToolContextValue {
+    registerTool: (agentId: string, config: ClientToolConfig) => void;
+    unregisterTool: (agentId: string, toolName: string) => void;
+    getTool: (agentId: string, toolName: string) => ClientToolConfig | undefined;
+    getToolsForAgent: (agentId: string) => ClientToolConfig[];
+    resumeTool: (agentId: string, callId: string, result: any) => void;
+}
+declare const AgentToolContext: react.Context<AgentToolContextValue | null>;
+declare function AgentContextProvider({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useAgentContext(agentId: string, agentUrl: string, accessKey?: string): AgentRunner;
+declare function useAgentGlobalState(): {
+    allSessions: Record<string, Record<string, Session>>;
+    setAllSessions: (value: Record<string, Record<string, Session>> | ((prev: Record<string, Record<string, Session>>) => Record<string, Record<string, Session>>)) => void;
+    debugData: Record<string, DebugDataType>;
+    setDebugData: (value: Record<string, DebugDataType> | ((prev: Record<string, DebugDataType>) => Record<string, DebugDataType>)) => void;
+};
+
+declare function useAgent(agentId: string, agentUrl: string, accessKey?: string): {
+    inProgress: boolean;
+    messages: Message[];
+    handleSend: (input: string, options?: {
+        context?: object;
+        skipUserMessage?: boolean;
+        additionalHeaders?: Record<string, string>;
+        additionalBody?: Record<string, unknown>;
+        /** @deprecated Use `useClientTool` hook instead. */
+        clientTools?: Array<{
+            name: string;
+            description: string;
+            parameters: unknown;
+            await?: boolean;
+        }>;
+    }) => Promise<void>;
+    resumeTool: (callId: string, result: any) => Promise<void>;
+    addOptimisticMessage: (input: string) => void;
+    abort: () => void;
+    sessionId: string;
+    switchSession: (sessionId?: string) => void;
+    deleteSession: (sessionId: string) => void;
+    sessions: Session[];
+    debugData: Record<string, DebugDataType>;
+};
+
+declare const AGENT_SESSIONS_KEY = "buildship:agent:conversations";
+declare const AGENT_DEBUG_DATA_KEY = "buildship:agent:debug";
+declare const DEFAULT_SESSION_NAME = "New Chat";
+declare const TEMPORARY_SESSION_ID = "sess_temp";
+
+/**
+ * Helper to clean JSON Schema for LLM compatibility.
+ * Replaces modern Draft 2020-12 features with older, more compatible alternatives.
+ * Specifically handles OpenAI's 'Strict Mode' requirements.
+ */
+declare function cleanSchema(obj: unknown): unknown;
+/**
+ * Safely attempts to parse a value as JSON if it's a string.
+ */
+declare function tryParseJSON(value: unknown): any;
+
+/**
+ * Updates a list of message parts with a new part,
+ * appending it and merging with the previous part if both are contiguous text deltas.
+ * Parts are kept in arrival order (no sorting) since events stream chronologically.
+ */
+declare function updateAgentMessageParts(parts: MessagePart[], newPart: MessagePart): MessagePart[];
+
+export { AGENT_DEBUG_DATA_KEY, AGENT_SESSIONS_KEY, AgentContextProvider, type AgentRunner, AgentToolContext, type AgentToolContextValue, type ClientToolConfig, type ClientToolDefinition, type ClientToolRenderProps, DEFAULT_SESSION_NAME, type DebugDataType, type HandoffItem, type Message, type MessagePart, type ReasoningItem, type RunErrorItem, type Session, TEMPORARY_SESSION_ID, type ToolConfig, type ToolExecutionItem, ToolRenderer, ToolType, type WidgetExecutionItem, cleanSchema, tryParseJSON, updateAgentMessageParts, useAgent, useAgentContext, useAgentGlobalState, useClientTool };