@yourgpt/llm-sdk 1.5.2 → 1.5.3

package/dist/index.d.mts

@@ -413,6 +413,29 @@ interface HandleRequestOptions {
      */
     onFinish?: (result: HandleRequestResult) => Promise<void> | void;
 }
+/**
+ * Options for runtime.generate()
+ *
+ * @example
+ * ```typescript
+ * const result = await runtime.generate(body, {
+ *   onFinish: async ({ messages }) => {
+ *     await db.saveMessages(messages);
+ *   },
+ * });
+ * ```
+ */
+interface GenerateOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** HTTP request for extracting headers (auth context) */
+    httpRequest?: Request;
+    /**
+     * Called after generation completes successfully.
+     * Use for server-side persistence.
+     */
+    onFinish?: (result: HandleRequestResult) => Promise<void> | void;
+}
 
 /**
  * StreamResult - Industry-standard streaming result object
@@ -677,6 +700,118 @@ declare class StreamResult {
  */
 declare function createStreamResult(generator: AsyncGenerator<StreamEvent>): StreamResult;
 
+/**
+ * GenerateResult - Result from non-streaming generation
+ *
+ * Similar to Vercel AI SDK's generateText() result.
+ * Provides both raw access and formatted response methods.
+ *
+ * @example
+ * ```typescript
+ * const result = await runtime.generate(body);
+ *
+ * // Raw access
+ * console.log(result.text);
+ * console.log(result.toolCalls);
+ *
+ * // CopilotChat format
+ * res.json(result.toResponse());
+ * ```
+ */
+
+interface GenerateResultData {
+    text: string;
+    messages: DoneEventMessage[];
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    requiresAction: boolean;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * Response format compatible with CopilotChat
+ */
+interface CopilotChatResponse {
+    success: boolean;
+    content: string;
+    messages?: DoneEventMessage[];
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    toolResults?: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    requiresAction?: boolean;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * GenerateResult - Non-streaming generation result
+ */
+declare class GenerateResult {
+    private data;
+    constructor(data: GenerateResultData);
+    /**
+     * Generated text content
+     */
+    get text(): string;
+    /**
+     * All messages from the conversation
+     */
+    get messages(): DoneEventMessage[];
+    /**
+     * Tool calls made during generation
+     */
+    get toolCalls(): GenerateResultData["toolCalls"];
+    /**
+     * Results from tool executions
+     */
+    get toolResults(): GenerateResultData["toolResults"];
+    /**
+     * Whether client action is required (e.g., tool approval)
+     */
+    get requiresAction(): boolean;
+    /**
+     * Error if generation failed
+     */
+    get error(): GenerateResultData["error"];
+    /**
+     * Whether generation was successful
+     */
+    get success(): boolean;
+    /**
+     * Convert to CopilotChat-compatible JSON response
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * res.json(result.toResponse());
+     *
+     * // Next.js
+     * return Response.json(result.toResponse());
+     * ```
+     */
+    toResponse(): CopilotChatResponse;
+    /**
+     * Convert to raw object (without methods)
+     */
+    toJSON(): GenerateResultData;
+}
+
 /**
  * Copilot SDK Runtime
  *
@@ -860,23 +995,42 @@ declare class Runtime {
      * console.log('Response:', text);
      * res.json({ response: text });
      *
-     * // With onFinish for usage tracking
-     * const result = await runtime.chat(body, {
-     *   onFinish: ({ usage }) => console.log('Tokens:', usage?.totalTokens)
-     * });
+     * // Usage is included in result - strip before sending to client
+     * const { usage, ...clientResult } = await runtime.chat(body);
+     * await billing.record(usage);
+     * res.json(clientResult);
      * ```
      */
     chat(request: ChatRequest, options?: {
         signal?: AbortSignal;
-        onFinish?: (result: {
-            messages: DoneEventMessage[];
-            usage?: {
-                promptTokens: number;
-                completionTokens: number;
-                totalTokens: number;
-            };
-        }) => Promise<void> | void;
     }): Promise<CollectedResult>;
+    /**
+     * Generate a complete response (non-streaming)
+     *
+     * Like Vercel AI SDK's generateText() - clean, non-streaming API.
+     * Returns GenerateResult with .toResponse() for CopilotChat format.
+     *
+     * @example
+     * ```typescript
+     * // Simple usage
+     * const result = await runtime.generate(body);
+     * console.log(result.text);
+     *
+     * // CopilotChat format response (Express)
+     * res.json(result.toResponse());
+     *
+     * // CopilotChat format response (Next.js)
+     * return Response.json(result.toResponse());
+     *
+     * // With persistence callback
+     * const result = await runtime.generate(body, {
+     *   onFinish: async ({ messages }) => {
+     *     await db.saveMessages(messages);
+     *   },
+     * });
+     * ```
+     */
+    generate(request: ChatRequest, options?: GenerateOptions): Promise<GenerateResult>;
     /**
      * Create Express-compatible handler middleware
      *
@@ -1179,4 +1333,4 @@ declare function generateThreadId(): string;
  */
 declare function generateToolCallId(): string;
 
-export { AIProvider, ActionDefinition, type ActionRequest, AgentLoopConfig, type AgentLoopOptions, type ChatRequest, type CollectedResult, DEFAULT_MAX_ITERATIONS, DoneEventMessage, GenerateTextParams, GenerateTextResult, LLMAdapter, Message, type RequestContext, Runtime, type RuntimeConfig, StreamEvent, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, TokenUsageRaw, Tool, ToolCallInfo, ToolContext, ToolDefinition, ToolResponse, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateMessageId, generateText, generateThreadId, generateToolCallId, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, streamText, tool };
+export { AIProvider, ActionDefinition, type ActionRequest, AgentLoopConfig, type AgentLoopOptions, type ChatRequest, type CollectedResult, type CopilotChatResponse, DEFAULT_MAX_ITERATIONS, DoneEventMessage, GenerateResult, type GenerateResultData, GenerateTextParams, GenerateTextResult, LLMAdapter, Message, type RequestContext, Runtime, type RuntimeConfig, StreamEvent, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, TokenUsageRaw, Tool, ToolCallInfo, ToolContext, ToolDefinition, ToolResponse, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateMessageId, generateText, generateThreadId, generateToolCallId, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, streamText, tool };

package/dist/index.d.ts

@@ -413,6 +413,29 @@ interface HandleRequestOptions {
      */
     onFinish?: (result: HandleRequestResult) => Promise<void> | void;
 }
+/**
+ * Options for runtime.generate()
+ *
+ * @example
+ * ```typescript
+ * const result = await runtime.generate(body, {
+ *   onFinish: async ({ messages }) => {
+ *     await db.saveMessages(messages);
+ *   },
+ * });
+ * ```
+ */
+interface GenerateOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** HTTP request for extracting headers (auth context) */
+    httpRequest?: Request;
+    /**
+     * Called after generation completes successfully.
+     * Use for server-side persistence.
+     */
+    onFinish?: (result: HandleRequestResult) => Promise<void> | void;
+}
 
 /**
  * StreamResult - Industry-standard streaming result object
@@ -677,6 +700,118 @@ declare class StreamResult {
  */
 declare function createStreamResult(generator: AsyncGenerator<StreamEvent>): StreamResult;
 
+/**
+ * GenerateResult - Result from non-streaming generation
+ *
+ * Similar to Vercel AI SDK's generateText() result.
+ * Provides both raw access and formatted response methods.
+ *
+ * @example
+ * ```typescript
+ * const result = await runtime.generate(body);
+ *
+ * // Raw access
+ * console.log(result.text);
+ * console.log(result.toolCalls);
+ *
+ * // CopilotChat format
+ * res.json(result.toResponse());
+ * ```
+ */
+
+interface GenerateResultData {
+    text: string;
+    messages: DoneEventMessage[];
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    requiresAction: boolean;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * Response format compatible with CopilotChat
+ */
+interface CopilotChatResponse {
+    success: boolean;
+    content: string;
+    messages?: DoneEventMessage[];
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    toolResults?: Array<{
+        id: string;
+        result: unknown;
+    }>;
+    requiresAction?: boolean;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * GenerateResult - Non-streaming generation result
+ */
+declare class GenerateResult {
+    private data;
+    constructor(data: GenerateResultData);
+    /**
+     * Generated text content
+     */
+    get text(): string;
+    /**
+     * All messages from the conversation
+     */
+    get messages(): DoneEventMessage[];
+    /**
+     * Tool calls made during generation
+     */
+    get toolCalls(): GenerateResultData["toolCalls"];
+    /**
+     * Results from tool executions
+     */
+    get toolResults(): GenerateResultData["toolResults"];
+    /**
+     * Whether client action is required (e.g., tool approval)
+     */
+    get requiresAction(): boolean;
+    /**
+     * Error if generation failed
+     */
+    get error(): GenerateResultData["error"];
+    /**
+     * Whether generation was successful
+     */
+    get success(): boolean;
+    /**
+     * Convert to CopilotChat-compatible JSON response
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * res.json(result.toResponse());
+     *
+     * // Next.js
+     * return Response.json(result.toResponse());
+     * ```
+     */
+    toResponse(): CopilotChatResponse;
+    /**
+     * Convert to raw object (without methods)
+     */
+    toJSON(): GenerateResultData;
+}
+
 /**
  * Copilot SDK Runtime
  *
@@ -860,23 +995,42 @@ declare class Runtime {
      * console.log('Response:', text);
      * res.json({ response: text });
      *
-     * // With onFinish for usage tracking
-     * const result = await runtime.chat(body, {
-     *   onFinish: ({ usage }) => console.log('Tokens:', usage?.totalTokens)
-     * });
+     * // Usage is included in result - strip before sending to client
+     * const { usage, ...clientResult } = await runtime.chat(body);
+     * await billing.record(usage);
+     * res.json(clientResult);
      * ```
      */
     chat(request: ChatRequest, options?: {
         signal?: AbortSignal;
-        onFinish?: (result: {
-            messages: DoneEventMessage[];
-            usage?: {
-                promptTokens: number;
-                completionTokens: number;
-                totalTokens: number;
-            };
-        }) => Promise<void> | void;
     }): Promise<CollectedResult>;
+    /**
+     * Generate a complete response (non-streaming)
+     *
+     * Like Vercel AI SDK's generateText() - clean, non-streaming API.
+     * Returns GenerateResult with .toResponse() for CopilotChat format.
+     *
+     * @example
+     * ```typescript
+     * // Simple usage
+     * const result = await runtime.generate(body);
+     * console.log(result.text);
+     *
+     * // CopilotChat format response (Express)
+     * res.json(result.toResponse());
+     *
+     * // CopilotChat format response (Next.js)
+     * return Response.json(result.toResponse());
+     *
+     * // With persistence callback
+     * const result = await runtime.generate(body, {
+     *   onFinish: async ({ messages }) => {
+     *     await db.saveMessages(messages);
+     *   },
+     * });
+     * ```
+     */
+    generate(request: ChatRequest, options?: GenerateOptions): Promise<GenerateResult>;
     /**
      * Create Express-compatible handler middleware
      *
@@ -1179,4 +1333,4 @@ declare function generateThreadId(): string;
  */
 declare function generateToolCallId(): string;
 
-export { AIProvider, ActionDefinition, type ActionRequest, AgentLoopConfig, type AgentLoopOptions, type ChatRequest, type CollectedResult, DEFAULT_MAX_ITERATIONS, DoneEventMessage, GenerateTextParams, GenerateTextResult, LLMAdapter, Message, type RequestContext, Runtime, type RuntimeConfig, StreamEvent, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, TokenUsageRaw, Tool, ToolCallInfo, ToolContext, ToolDefinition, ToolResponse, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateMessageId, generateText, generateThreadId, generateToolCallId, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, streamText, tool };
+export { AIProvider, ActionDefinition, type ActionRequest, AgentLoopConfig, type AgentLoopOptions, type ChatRequest, type CollectedResult, type CopilotChatResponse, DEFAULT_MAX_ITERATIONS, DoneEventMessage, GenerateResult, type GenerateResultData, GenerateTextParams, GenerateTextResult, LLMAdapter, Message, type RequestContext, Runtime, type RuntimeConfig, StreamEvent, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, TokenUsageRaw, Tool, ToolCallInfo, ToolContext, ToolDefinition, ToolResponse, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateMessageId, generateText, generateThreadId, generateToolCallId, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, streamText, tool };

package/dist/index.js

@@ -1909,6 +1909,84 @@ function createStreamResult(generator) {
   return new StreamResult(generator);
 }
 
+// src/server/generate-result.ts
+var GenerateResult = class {
+  constructor(data) {
+    this.data = data;
+  }
+  /**
+   * Generated text content
+   */
+  get text() {
+    return this.data.text;
+  }
+  /**
+   * All messages from the conversation
+   */
+  get messages() {
+    return this.data.messages;
+  }
+  /**
+   * Tool calls made during generation
+   */
+  get toolCalls() {
+    return this.data.toolCalls;
+  }
+  /**
+   * Results from tool executions
+   */
+  get toolResults() {
+    return this.data.toolResults;
+  }
+  /**
+   * Whether client action is required (e.g., tool approval)
+   */
+  get requiresAction() {
+    return this.data.requiresAction;
+  }
+  /**
+   * Error if generation failed
+   */
+  get error() {
+    return this.data.error;
+  }
+  /**
+   * Whether generation was successful
+   */
+  get success() {
+    return !this.data.error;
+  }
+  /**
+   * Convert to CopilotChat-compatible JSON response
+   *
+   * @example
+   * ```typescript
+   * // Express
+   * res.json(result.toResponse());
+   *
+   * // Next.js
+   * return Response.json(result.toResponse());
+   * ```
+   */
+  toResponse() {
+    return {
+      success: this.success,
+      content: this.data.text,
+      messages: this.data.messages.length > 0 ? this.data.messages : void 0,
+      toolCalls: this.data.toolCalls.length > 0 ? this.data.toolCalls : void 0,
+      toolResults: this.data.toolResults.length > 0 ? this.data.toolResults : void 0,
+      requiresAction: this.data.requiresAction || void 0,
+      error: this.data.error
+    };
+  }
+  /**
+   * Convert to raw object (without methods)
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+
 // src/server/runtime.ts
 function buildToolResultForAI(tool2, result, args) {
   const typedResult = result;
@@ -3071,14 +3149,119 @@ var Runtime = class {
    * console.log('Response:', text);
    * res.json({ response: text });
    *
-   * // With onFinish for usage tracking
-   * const result = await runtime.chat(body, {
-   *   onFinish: ({ usage }) => console.log('Tokens:', usage?.totalTokens)
-   * });
+   * // Usage is included in result - strip before sending to client
+   * const { usage, ...clientResult } = await runtime.chat(body);
+   * await billing.record(usage);
+   * res.json(clientResult);
    * ```
    */
   async chat(request, options) {
-    return this.stream(request, options).collect();
+    return this.stream(request, { signal: options?.signal }).collect({
+      includeUsage: true
+    });
+  }
+  /**
+   * Generate a complete response (non-streaming)
+   *
+   * Like Vercel AI SDK's generateText() - clean, non-streaming API.
+   * Returns GenerateResult with .toResponse() for CopilotChat format.
+   *
+   * @example
+   * ```typescript
+   * // Simple usage
+   * const result = await runtime.generate(body);
+   * console.log(result.text);
+   *
+   * // CopilotChat format response (Express)
+   * res.json(result.toResponse());
+   *
+   * // CopilotChat format response (Next.js)
+   * return Response.json(result.toResponse());
+   *
+   * // With persistence callback
+   * const result = await runtime.generate(body, {
+   *   onFinish: async ({ messages }) => {
+   *     await db.saveMessages(messages);
+   *   },
+   * });
+   * ```
+   */
+  async generate(request, options) {
+    const generator = this.processChatWithLoop(
+      { ...request, streaming: false },
+      options?.signal,
+      void 0,
+      void 0,
+      options?.httpRequest
+    );
+    let text = "";
+    const toolCalls = [];
+    const toolResults = [];
+    let messages = [];
+    let requiresAction = false;
+    let error;
+    try {
+      for await (const event of generator) {
+        switch (event.type) {
+          case "message:delta":
+            text += event.content;
+            break;
+          case "action:start":
+            toolCalls.push({ id: event.id, name: event.name, args: {} });
+            break;
+          case "action:args": {
+            const tc = toolCalls.find((t) => t.id === event.id);
+            if (tc) {
+              try {
+                tc.args = JSON.parse(event.args || "{}");
+              } catch {
+                tc.args = {};
+              }
+            }
+            break;
+          }
+          case "action:end":
+            toolResults.push({
+              id: event.id,
+              result: event.result || event.error
+            });
+            break;
+          case "done":
+            messages = event.messages || [];
+            requiresAction = event.requiresAction || false;
+            break;
+          case "error":
+            error = { message: event.message, code: event.code };
+            break;
+        }
+      }
+    } catch (err) {
+      error = {
+        message: err instanceof Error ? err.message : "Unknown error",
+        code: "GENERATION_ERROR"
+      };
+    }
+    if (options?.onFinish && messages.length > 0 && !error) {
+      try {
+        await options.onFinish({
+          messages,
+          threadId: request.threadId
+        });
+      } catch (callbackError) {
+        console.error(
+          "[Copilot SDK] generate() onFinish callback error:",
+          callbackError
+        );
+      }
+    }
+    return new GenerateResult({
+      text,
+      messages,
+      toolCalls,
+      toolResults,
+      requiresAction,
+      error
+    });
   }
   /**
    * Create Express-compatible handler middleware
@@ -3785,6 +3968,7 @@ async function executeToolCalls(toolCalls, tools, executeServerTool, waitForClie
 
 exports.DEFAULT_CAPABILITIES = DEFAULT_CAPABILITIES;
 exports.DEFAULT_MAX_ITERATIONS = DEFAULT_MAX_ITERATIONS;
+exports.GenerateResult = GenerateResult;
 exports.Runtime = Runtime;
 exports.StreamResult = StreamResult;
 exports.createEventStream = createEventStream;