bs-agent 0.0.12 → 0.0.15

package/dist/agent-CyJqP9_x.d.cts

@@ -0,0 +1,305 @@
+import { ZodSchema } from 'zod';
+
+/**
+ * Unified tool type discriminator.
+ */
+type ToolType = "flow" | "node" | "mcp" | "client" | "builtin" | "agent";
+type StreamEventMeta = {
+    executionId: string;
+    sequence: number;
+    timestamp?: number;
+    agentId: string;
+};
+type TextDeltaEvent = {
+    type: "text_delta";
+    data: string;
+    meta: StreamEventMeta;
+};
+type ReasoningDeltaEvent = {
+    type: "reasoning_delta";
+    data: {
+        delta: string;
+        index: number;
+    };
+    meta: StreamEventMeta;
+};
+type AgentHandoffEvent = {
+    type: "agent_handoff";
+    data: {
+        agentName: string;
+    };
+    meta: StreamEventMeta;
+};
+type ToolCallStartEvent = {
+    type: "tool_call_start";
+    data: {
+        callId: string;
+        toolName: string;
+        toolType: ToolType;
+        inputs?: any;
+        serverName?: string;
+        paused?: boolean;
+    };
+    meta: StreamEventMeta;
+};
+type ToolCallEndEvent = {
+    type: "tool_call_end";
+    data: {
+        callId: string;
+        toolName: string;
+        toolType: ToolType;
+        result?: any;
+        error?: string;
+        executionTime?: number;
+    };
+    meta: StreamEventMeta;
+};
+type RunErrorEvent = {
+    type: "run_error";
+    data: {
+        message: string;
+        code?: string;
+    };
+    meta: StreamEventMeta;
+};
+type StreamEvent = TextDeltaEvent | ReasoningDeltaEvent | AgentHandoffEvent | ToolCallStartEvent | ToolCallEndEvent | RunErrorEvent;
+/** Branded session ID type. */
+type SessionId = string & {
+    readonly __brand: unique symbol;
+};
+/** Configuration for the BuildShipAgent constructor. */
+interface AgentConfig {
+    /** Your BuildShip agent ID. */
+    agentId: string;
+    /** Access key if your agent requires authentication. */
+    accessKey?: string;
+    /** Custom API base URL. Defaults to `https://api.buildship.run`. */
+    baseUrl?: string;
+}
+/** Options for agent execution. */
+interface ExecuteOptions {
+    /** Additional context variables for the prompt. */
+    context?: Record<string, any>;
+    /** Custom headers to include in the request. */
+    headers?: Record<string, string>;
+    /** Additional top-level properties to merge into the request body. */
+    body?: Record<string, any>;
+    /** Fired internally when session ID is extracted from response headers. */
+    onSessionId?: (sessionId: string, sessionName?: string) => void;
+}
+/** Callbacks for streaming responses. */
+interface StreamCallbacks {
+    /** Called for each text chunk from the agent. */
+    onText?: (text: string) => void;
+    /** Called for each reasoning chunk (models with chain-of-thought). */
+    onReasoning?: (delta: string, index: number) => void;
+    /** Called when control is handed off to a sub-agent. */
+    onAgentHandoff?: (agentName: string) => void;
+    /** Called when a tool execution starts. */
+    onToolStart?: (toolName: string, toolType: ToolType) => void;
+    /** Called when a tool execution completes. */
+    onToolEnd?: (toolName: string, result?: any, error?: string) => void;
+    /** Called when agent pauses for a blocking client tool. */
+    onPaused?: (toolName: string, args: any) => void;
+    /** Called when the stream completes successfully. */
+    onComplete?: (fullText: string) => void;
+    /** Called if an error occurs during streaming. */
+    onError?: (error: Error) => void;
+    /** Called for every stream event. Useful for advanced consumers (e.g. debug panels). */
+    onEvent?: (event: StreamEvent) => void;
+}
+/** A client-side tool that the agent can invoke. */
+interface ClientTool {
+    /** 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.
+     *
+     * @example
+     * // Zod
+     * parameters: z.object({ message: z.string() })
+     *
+     * // JSON Schema
+     * parameters: { type: "object", properties: { message: { type: "string" } } }
+     */
+    parameters: ZodSchema | Record<string, any>;
+    /** If true, agent pauses until result is provided. */
+    await?: boolean;
+    /** Handler function. If provided with `await: true`, auto-resumes. */
+    handler?: (args: any) => any | Promise<any>;
+}
+/** Information about a paused tool call. */
+interface PausedToolInfo {
+    callId: string;
+    toolName: string;
+    args: any;
+}
+/** @internal Body sent to the /executeAgent endpoint. */
+interface ExecuteRequestBody {
+    input?: string;
+    stream: true;
+    clientTools?: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+        await?: boolean;
+    }>;
+    toolCallResult?: {
+        callId: string;
+        result: any;
+    };
+}
+/** @internal Options passed to the internal stream executor. */
+interface StreamOptions {
+    url: string;
+    body: ExecuteRequestBody;
+    headers: Record<string, string>;
+    callbacks: StreamCallbacks;
+    clientTools: Map<string, ClientTool>;
+    signal?: AbortSignal;
+    /** Called when session ID is received from response headers. */
+    onSessionId?: (sessionId: SessionId, sessionName?: string) => void;
+    /** Called when paused tool info is detected. */
+    onPaused?: (info: PausedToolInfo) => void;
+    /** Called to auto-resume after a client tool handler completes. */
+    onAutoResume?: (callId: string, result: any) => void;
+    /** Called with the raw Response object after the HTTP request completes. */
+    onResponse?: (response: Response) => void;
+}
+
+/**
+ * Represents a conversation session with a BuildShip agent.
+ *
+ * Sessions maintain history across multiple turns and support
+ * pause/resume for blocking client tools.
+ */
+declare class AgentSession {
+    /** @internal */ private _agent;
+    /** @internal */ private _sessionId;
+    /** @internal */ private _paused;
+    /** @internal */ private _pausedToolInfo;
+    /** @internal */ private _abortController;
+    /** @internal */
+    constructor(agent: BuildShipAgent, sessionId?: SessionId);
+    /**
+     * Send a message in this session.
+     *
+     * @param message   - The message to send
+     * @param callbacks - Event handlers for the stream
+     * @param callbacks - Event handlers for the stream
+     * @param options   - Optional settings like context, headers, or body
+     * @returns This session (for chaining)
+     */
+    execute(message: string, callbacks: StreamCallbacks, options?: ExecuteOptions): Promise<AgentSession>;
+    /**
+     * Resume a paused session with a tool result.
+     *
+     * @param result    - The result to send back to the agent
+     * @param callbacks - Event handlers for the resumed stream
+     * @param options   - Optional settings like headers or body
+     * @returns This session (for chaining)
+     */
+    resume(result: any, callbacks: StreamCallbacks, options?: Omit<ExecuteOptions, "context">): Promise<AgentSession>;
+    /**
+     * Resume a session with an explicit tool call ID and result.
+     *
+     * Unlike `resume()`, this does NOT require the session to be in a paused state,
+     * making it suitable for external resume flows (e.g. React widget submissions)
+     * where the session object may have been re-created.
+     *
+     * @param callId    - The tool call ID to resume
+     * @param result    - The result to send back to the agent
+     * @param callbacks - Event handlers for the resumed stream
+     * @param options   - Optional settings like headers or body
+     * @returns This session (for chaining)
+     */
+    resumeWithCallId(callId: string, result: any, callbacks: StreamCallbacks, options?: Omit<ExecuteOptions, "context">): Promise<AgentSession>;
+    /**
+     * Check if this session is waiting for a tool result.
+     */
+    isPaused(): boolean;
+    /**
+     * Get information about the paused tool call.
+     * Returns `null` if the session is not paused.
+     */
+    getPausedTool(): PausedToolInfo | null;
+    /**
+     * Get the session ID.
+     * May be `undefined` if the session hasn't executed yet.
+     */
+    getSessionId(): SessionId;
+    /**
+     * Cancel the current streaming operation.
+     */
+    abort(): void;
+    /** @internal */
+    private _run;
+    /** @internal */
+    private _getClientToolDefs;
+}
+
+/**
+ * Main entry point for interacting with a BuildShip agent.
+ *
+ * @example
+ * ```ts
+ * import { BuildShipAgent } from "buildship-agent-sdk/core";
+ *
+ * const agent = new BuildShipAgent({
+ *   agentId: "your-agent-id",
+ *   accessKey: "your-access-key",
+ * });
+ *
+ * const session = await agent.execute("Hello!", {
+ *   onText: (text) => console.log(text),
+ *   onComplete: (fullText) => console.log("Done!", fullText),
+ * });
+ * ```
+ */
+declare class BuildShipAgent {
+    /** @internal */ readonly _agentId: string;
+    /** @internal */ readonly _accessKey?: string;
+    /** @internal */ readonly _baseUrl: string;
+    /** @internal */ readonly _clientTools: Map<string, ClientTool>;
+    constructor(config: AgentConfig);
+    /**
+     * The URL for the agent's execute endpoint.
+     * @internal
+     */
+    get _url(): string;
+    /**
+     * Build the authorization / common headers.
+     * @internal
+     */
+    _buildHeaders(sessionId?: SessionId): Record<string, string>;
+    /**
+     * Start a new conversation.
+     *
+     * Creates a fresh session and sends the first message.
+     *
+     * @param message  - The message to send
+     * @param callbacks - Event handlers for the stream
+     * @param options   - Optional execution settings (context, headers, body, onSessionId)
+     * @returns The new session
+     */
+    execute(message: string, callbacks: StreamCallbacks, options?: ExecuteOptions): Promise<AgentSession>;
+    /**
+     * Get an existing session by ID to continue a conversation.
+     *
+     * @param sessionId - The session ID from a previous conversation
+     * @returns The session object
+     */
+    session(sessionId: SessionId | string): AgentSession;
+    /**
+     * Register a client-side tool that the agent can call.
+     */
+    registerClientTool(tool: ClientTool): void;
+    /**
+     * Remove a registered client tool.
+     */
+    unregisterClientTool(name: string): void;
+}
+
+export { AgentSession as A, BuildShipAgent as B, type ClientTool as C, type ExecuteRequestBody as E, type PausedToolInfo as P, type ReasoningDeltaEvent as R, type StreamOptions as S, type ToolType as T, type AgentConfig as a, type SessionId as b, type StreamCallbacks as c, type StreamEvent as d, type StreamEventMeta as e, type TextDeltaEvent as f, type AgentHandoffEvent as g, type ToolCallStartEvent as h, type ToolCallEndEvent as i, type RunErrorEvent as j };

package/dist/agent-CyJqP9_x.d.ts

@@ -0,0 +1,305 @@
+import { ZodSchema } from 'zod';
+
+/**
+ * Unified tool type discriminator.
+ */
+type ToolType = "flow" | "node" | "mcp" | "client" | "builtin" | "agent";
+type StreamEventMeta = {
+    executionId: string;
+    sequence: number;
+    timestamp?: number;
+    agentId: string;
+};
+type TextDeltaEvent = {
+    type: "text_delta";
+    data: string;
+    meta: StreamEventMeta;
+};
+type ReasoningDeltaEvent = {
+    type: "reasoning_delta";
+    data: {
+        delta: string;
+        index: number;
+    };
+    meta: StreamEventMeta;
+};
+type AgentHandoffEvent = {
+    type: "agent_handoff";
+    data: {
+        agentName: string;
+    };
+    meta: StreamEventMeta;
+};
+type ToolCallStartEvent = {
+    type: "tool_call_start";
+    data: {
+        callId: string;
+        toolName: string;
+        toolType: ToolType;
+        inputs?: any;
+        serverName?: string;
+        paused?: boolean;
+    };
+    meta: StreamEventMeta;
+};
+type ToolCallEndEvent = {
+    type: "tool_call_end";
+    data: {
+        callId: string;
+        toolName: string;
+        toolType: ToolType;
+        result?: any;
+        error?: string;
+        executionTime?: number;
+    };
+    meta: StreamEventMeta;
+};
+type RunErrorEvent = {
+    type: "run_error";
+    data: {
+        message: string;
+        code?: string;
+    };
+    meta: StreamEventMeta;
+};
+type StreamEvent = TextDeltaEvent | ReasoningDeltaEvent | AgentHandoffEvent | ToolCallStartEvent | ToolCallEndEvent | RunErrorEvent;
+/** Branded session ID type. */
+type SessionId = string & {
+    readonly __brand: unique symbol;
+};
+/** Configuration for the BuildShipAgent constructor. */
+interface AgentConfig {
+    /** Your BuildShip agent ID. */
+    agentId: string;
+    /** Access key if your agent requires authentication. */
+    accessKey?: string;
+    /** Custom API base URL. Defaults to `https://api.buildship.run`. */
+    baseUrl?: string;
+}
+/** Options for agent execution. */
+interface ExecuteOptions {
+    /** Additional context variables for the prompt. */
+    context?: Record<string, any>;
+    /** Custom headers to include in the request. */
+    headers?: Record<string, string>;
+    /** Additional top-level properties to merge into the request body. */
+    body?: Record<string, any>;
+    /** Fired internally when session ID is extracted from response headers. */
+    onSessionId?: (sessionId: string, sessionName?: string) => void;
+}
+/** Callbacks for streaming responses. */
+interface StreamCallbacks {
+    /** Called for each text chunk from the agent. */
+    onText?: (text: string) => void;
+    /** Called for each reasoning chunk (models with chain-of-thought). */
+    onReasoning?: (delta: string, index: number) => void;
+    /** Called when control is handed off to a sub-agent. */
+    onAgentHandoff?: (agentName: string) => void;
+    /** Called when a tool execution starts. */
+    onToolStart?: (toolName: string, toolType: ToolType) => void;
+    /** Called when a tool execution completes. */
+    onToolEnd?: (toolName: string, result?: any, error?: string) => void;
+    /** Called when agent pauses for a blocking client tool. */
+    onPaused?: (toolName: string, args: any) => void;
+    /** Called when the stream completes successfully. */
+    onComplete?: (fullText: string) => void;
+    /** Called if an error occurs during streaming. */
+    onError?: (error: Error) => void;
+    /** Called for every stream event. Useful for advanced consumers (e.g. debug panels). */
+    onEvent?: (event: StreamEvent) => void;
+}
+/** A client-side tool that the agent can invoke. */
+interface ClientTool {
+    /** 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.
+     *
+     * @example
+     * // Zod
+     * parameters: z.object({ message: z.string() })
+     *
+     * // JSON Schema
+     * parameters: { type: "object", properties: { message: { type: "string" } } }
+     */
+    parameters: ZodSchema | Record<string, any>;
+    /** If true, agent pauses until result is provided. */
+    await?: boolean;
+    /** Handler function. If provided with `await: true`, auto-resumes. */
+    handler?: (args: any) => any | Promise<any>;
+}
+/** Information about a paused tool call. */
+interface PausedToolInfo {
+    callId: string;
+    toolName: string;
+    args: any;
+}
+/** @internal Body sent to the /executeAgent endpoint. */
+interface ExecuteRequestBody {
+    input?: string;
+    stream: true;
+    clientTools?: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+        await?: boolean;
+    }>;
+    toolCallResult?: {
+        callId: string;
+        result: any;
+    };
+}
+/** @internal Options passed to the internal stream executor. */
+interface StreamOptions {
+    url: string;
+    body: ExecuteRequestBody;
+    headers: Record<string, string>;
+    callbacks: StreamCallbacks;
+    clientTools: Map<string, ClientTool>;
+    signal?: AbortSignal;
+    /** Called when session ID is received from response headers. */
+    onSessionId?: (sessionId: SessionId, sessionName?: string) => void;
+    /** Called when paused tool info is detected. */
+    onPaused?: (info: PausedToolInfo) => void;
+    /** Called to auto-resume after a client tool handler completes. */
+    onAutoResume?: (callId: string, result: any) => void;
+    /** Called with the raw Response object after the HTTP request completes. */
+    onResponse?: (response: Response) => void;
+}
+
+/**
+ * Represents a conversation session with a BuildShip agent.
+ *
+ * Sessions maintain history across multiple turns and support
+ * pause/resume for blocking client tools.
+ */
+declare class AgentSession {
+    /** @internal */ private _agent;
+    /** @internal */ private _sessionId;
+    /** @internal */ private _paused;
+    /** @internal */ private _pausedToolInfo;
+    /** @internal */ private _abortController;
+    /** @internal */
+    constructor(agent: BuildShipAgent, sessionId?: SessionId);
+    /**
+     * Send a message in this session.
+     *
+     * @param message   - The message to send
+     * @param callbacks - Event handlers for the stream
+     * @param callbacks - Event handlers for the stream
+     * @param options   - Optional settings like context, headers, or body
+     * @returns This session (for chaining)
+     */
+    execute(message: string, callbacks: StreamCallbacks, options?: ExecuteOptions): Promise<AgentSession>;
+    /**
+     * Resume a paused session with a tool result.
+     *
+     * @param result    - The result to send back to the agent
+     * @param callbacks - Event handlers for the resumed stream
+     * @param options   - Optional settings like headers or body
+     * @returns This session (for chaining)
+     */
+    resume(result: any, callbacks: StreamCallbacks, options?: Omit<ExecuteOptions, "context">): Promise<AgentSession>;
+    /**
+     * Resume a session with an explicit tool call ID and result.
+     *
+     * Unlike `resume()`, this does NOT require the session to be in a paused state,
+     * making it suitable for external resume flows (e.g. React widget submissions)
+     * where the session object may have been re-created.
+     *
+     * @param callId    - The tool call ID to resume
+     * @param result    - The result to send back to the agent
+     * @param callbacks - Event handlers for the resumed stream
+     * @param options   - Optional settings like headers or body
+     * @returns This session (for chaining)
+     */
+    resumeWithCallId(callId: string, result: any, callbacks: StreamCallbacks, options?: Omit<ExecuteOptions, "context">): Promise<AgentSession>;
+    /**
+     * Check if this session is waiting for a tool result.
+     */
+    isPaused(): boolean;
+    /**
+     * Get information about the paused tool call.
+     * Returns `null` if the session is not paused.
+     */
+    getPausedTool(): PausedToolInfo | null;
+    /**
+     * Get the session ID.
+     * May be `undefined` if the session hasn't executed yet.
+     */
+    getSessionId(): SessionId;
+    /**
+     * Cancel the current streaming operation.
+     */
+    abort(): void;
+    /** @internal */
+    private _run;
+    /** @internal */
+    private _getClientToolDefs;
+}
+
+/**
+ * Main entry point for interacting with a BuildShip agent.
+ *
+ * @example
+ * ```ts
+ * import { BuildShipAgent } from "buildship-agent-sdk/core";
+ *
+ * const agent = new BuildShipAgent({
+ *   agentId: "your-agent-id",
+ *   accessKey: "your-access-key",
+ * });
+ *
+ * const session = await agent.execute("Hello!", {
+ *   onText: (text) => console.log(text),
+ *   onComplete: (fullText) => console.log("Done!", fullText),
+ * });
+ * ```
+ */
+declare class BuildShipAgent {
+    /** @internal */ readonly _agentId: string;
+    /** @internal */ readonly _accessKey?: string;
+    /** @internal */ readonly _baseUrl: string;
+    /** @internal */ readonly _clientTools: Map<string, ClientTool>;
+    constructor(config: AgentConfig);
+    /**
+     * The URL for the agent's execute endpoint.
+     * @internal
+     */
+    get _url(): string;
+    /**
+     * Build the authorization / common headers.
+     * @internal
+     */
+    _buildHeaders(sessionId?: SessionId): Record<string, string>;
+    /**
+     * Start a new conversation.
+     *
+     * Creates a fresh session and sends the first message.
+     *
+     * @param message  - The message to send
+     * @param callbacks - Event handlers for the stream
+     * @param options   - Optional execution settings (context, headers, body, onSessionId)
+     * @returns The new session
+     */
+    execute(message: string, callbacks: StreamCallbacks, options?: ExecuteOptions): Promise<AgentSession>;
+    /**
+     * Get an existing session by ID to continue a conversation.
+     *
+     * @param sessionId - The session ID from a previous conversation
+     * @returns The session object
+     */
+    session(sessionId: SessionId | string): AgentSession;
+    /**
+     * Register a client-side tool that the agent can call.
+     */
+    registerClientTool(tool: ClientTool): void;
+    /**
+     * Remove a registered client tool.
+     */
+    unregisterClientTool(name: string): void;
+}
+
+export { AgentSession as A, BuildShipAgent as B, type ClientTool as C, type ExecuteRequestBody as E, type PausedToolInfo as P, type ReasoningDeltaEvent as R, type StreamOptions as S, type ToolType as T, type AgentConfig as a, type SessionId as b, type StreamCallbacks as c, type StreamEvent as d, type StreamEventMeta as e, type TextDeltaEvent as f, type AgentHandoffEvent as g, type ToolCallStartEvent as h, type ToolCallEndEvent as i, type RunErrorEvent as j };