@amigo-ai/platform-sdk 0.21.0 → 0.23.0

package/api.md

@@ -240,6 +240,7 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `close`
 - `createTurn`
 - `createTurnStream`
+- `streamTurn`
 - `textStreamUrl`
 - `sessionConnectUrl`
 

package/dist/index.cjs

@@ -1979,11 +1979,22 @@ var ConversationsResource = class extends WorkspaceScopedResource {
       }
     });
   }
-  async createTurn(conversationId, request) {
+  /**
+   * Send a user message and receive the agent's synchronous JSON response.
+   *
+   * Pass `options.includeToolCalls: true` to request tool-call metadata
+   * alongside the response turns. Server-side default is `false` — without
+   * this opt-in the `tool_calls` array on the `TurnResponse` will be empty
+   * even when the agent invoked tools during the turn.
+   */
+  async createTurn(conversationId, request, options) {
     return extractData(
       await this.client.POST("/v1/{workspace_id}/conversations/{conversation_id}/turns", {
         params: {
-          path: { workspace_id: this.workspaceId, conversation_id: conversationId }
+          path: { workspace_id: this.workspaceId, conversation_id: conversationId },
+          ...options?.includeToolCalls !== void 0 && {
+            query: { include_tool_calls: options.includeToolCalls }
+          }
         },
         body: request,
         headers: { Accept: "application/json" }
@@ -2013,7 +2024,10 @@ var ConversationsResource = class extends WorkspaceScopedResource {
       "/v1/{workspace_id}/conversations/{conversation_id}/turns",
       {
         params: {
-          path: { workspace_id: this.workspaceId, conversation_id: conversationId }
+          path: { workspace_id: this.workspaceId, conversation_id: conversationId },
+          ...options?.includeToolCalls !== void 0 && {
+            query: { include_tool_calls: options.includeToolCalls }
+          }
         },
         body: request,
         headers: { Accept: "text/event-stream" },
@@ -2026,6 +2040,35 @@ var ConversationsResource = class extends WorkspaceScopedResource {
     }
     return result.data;
   }
+  /**
+   * Send a message and receive the agent's response as a typed
+   * `TurnStreamEvent` async iterable.
+   *
+   * The bytes-and-parser dance from `createTurnStream` is now hidden inside
+   * the SDK — consumers iterate strongly typed events directly. Each yielded
+   * value is a member of the `TurnStreamEvent` discriminated union (`token`,
+   * `thinking`, `tool_call_started`, `tool_call_completed`, `message`,
+   * `done`, `error`), validated as a record with a known `event`
+   * discriminator. Unknown / malformed frames are dropped silently — this
+   * matches the wire-format-drift behavior of the lower-level
+   * `createTurnStream` while keeping the strict `TurnStreamEvent` static
+   * contract intact for consumers.
+   *
+   * @example
+   * ```ts
+   * for await (const event of client.conversations.streamTurn(convId, { message: "Hello" })) {
+   *   if (event.event === "token") process.stdout.write(event.text);
+   *   else if (event.event === "done") break;
+   * }
+   * ```
+   */
+  async *streamTurn(conversationId, request, options) {
+    const byteStream = await this.createTurnStream(conversationId, request, options);
+    for await (const frame of parseSSEFrames(byteStream)) {
+      const event = parseTurnStreamFrame(frame.event, frame.data);
+      if (event) yield event;
+    }
+  }
   /** Build the real-time text WebSocket URL for browser or custom clients. */
   textStreamUrl(params) {
     const url = buildTextStreamUrl({
@@ -2217,6 +2260,80 @@ function describeInvalidSubprotocolChars(token) {
   }
   return [...chars].map((char) => JSON.stringify(char)).join(", ");
 }
+async function* parseSSEFrames(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  function* drain(text) {
+    buffer += text;
+    while (true) {
+      const idx = findFrameTerminator(buffer);
+      if (idx === null) break;
+      const block = buffer.slice(0, idx.terminatorStart);
+      buffer = buffer.slice(idx.terminatorEnd);
+      const frame = parseSSEBlock(block);
+      if (frame) yield frame;
+    }
+  }
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield* drain(decoder.decode(value, { stream: true }));
+    }
+    yield* drain(decoder.decode());
+    if (buffer.trim().length > 0) {
+      const frame = parseSSEBlock(buffer);
+      if (frame) yield frame;
+      buffer = "";
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function findFrameTerminator(s) {
+  const lf = s.indexOf("\n\n");
+  const crlf = s.indexOf("\r\n\r\n");
+  if (lf < 0 && crlf < 0) return null;
+  if (lf < 0) return { terminatorStart: crlf, terminatorEnd: crlf + 4 };
+  if (crlf < 0) return { terminatorStart: lf, terminatorEnd: lf + 2 };
+  return lf < crlf ? { terminatorStart: lf, terminatorEnd: lf + 2 } : { terminatorStart: crlf, terminatorEnd: crlf + 4 };
+}
+function parseSSEBlock(block) {
+  let event = "";
+  const dataLines = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colon = line.indexOf(":");
+    const field = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+  }
+  if (!event || dataLines.length === 0) return null;
+  return { event, data: dataLines.join("\n") };
+}
+var KNOWN_TURN_STREAM_EVENTS = /* @__PURE__ */ new Set([
+  "token",
+  "thinking",
+  "tool_call_started",
+  "tool_call_completed",
+  "message",
+  "done",
+  "error"
+]);
+function parseTurnStreamFrame(eventName, dataJson) {
+  if (!KNOWN_TURN_STREAM_EVENTS.has(eventName)) return null;
+  let payload;
+  try {
+    payload = JSON.parse(dataJson);
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
+  return { ...payload, event: eventName };
+}
 
 // src/resources/phone-numbers.ts
 var PhoneNumbersResource = class extends WorkspaceScopedResource {