@amigo-ai/platform-sdk 0.62.1 → 0.64.0

package/api.md

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

package/dist/index.cjs

@@ -2206,21 +2206,47 @@ var ConversationsResource = class extends WorkspaceScopedResource {
    * 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.
+   *
+   * Pass `options.poll: true` for a no-message drain-and-report poll (see
+   * {@link pollTurn} for the ergonomic wrapper): the agent surfaces any
+   * background tool results that completed since the last turn. A poll must
+   * NOT carry a `request.message` (the server rejects it 422); prefer
+   * {@link pollTurn}.
    */
   async createTurn(conversationId, request, options) {
+    if (options?.poll && request.message) {
+      throw new ConfigurationError("poll cannot be combined with a message; use pollTurn() instead");
+    }
+    const query = {};
+    if (options?.includeToolCalls !== void 0) query.include_tool_calls = options.includeToolCalls;
+    if (options?.poll !== void 0) query.poll = options.poll;
     return extractData(
       await this.client.POST("/v1/{workspace_id}/conversations/{conversation_id}/turns", {
         params: {
           path: { workspace_id: this.workspaceId, conversation_id: conversationId },
-          ...options?.includeToolCalls !== void 0 && {
-            query: { include_tool_calls: options.includeToolCalls }
-          }
+          ...Object.keys(query).length > 0 && { query }
         },
         body: request,
         headers: { Accept: "application/json" }
       })
     );
   }
+  /**
+   * Poll a conversation for background tool results without sending a user
+   * message. Drains any background tool calls that completed since the last
+   * turn and returns the agent's report; when nothing is pending the response
+   * has empty `output` and `tool_calls` (the idle case) — treat that as "keep
+   * polling". Poll no more than once every ~5s per conversation.
+   *
+   * @example
+   * ```ts
+   * const res = await client.conversations.pollTurn(convId, { includeToolCalls: true });
+   * if (res.output.length || res.tool_calls?.length) render(res); // else poll again later
+   * ```
+   */
+  async pollTurn(conversationId, options) {
+    return this.createTurn(conversationId, {}, { ...options, poll: true });
+  }
   /**
    * Send a message and receive the agent's response as an SSE byte stream.
    *