@ragable/sdk 0.6.22 → 0.6.23

package/dist/index.js

@@ -58,6 +58,7 @@ __export(index_exports, {
   asPostgrestResponse: () => asPostgrestResponse,
   assertPostgrestSuccess: () => assertPostgrestSuccess,
   bindFetch: () => bindFetch,
+  collectAssistantTextFromUiSegments: () => collectAssistantTextFromUiSegments,
   collectionRecordToRowWithMeta: () => collectionRecordToRowWithMeta,
   collectionRecordsToRowWithMeta: () => collectionRecordsToRowWithMeta,
   createBrowserClient: () => createBrowserClient,
@@ -68,14 +69,22 @@ __export(index_exports, {
   detectStorage: () => detectStorage,
   effectiveDataAuth: () => effectiveDataAuth,
   extractErrorMessage: () => extractErrorMessage,
+  finalizeAgentChatUiTurn: () => finalizeAgentChatUiTurn,
+  foldAgentStreamIntoUiSegments: () => foldAgentStreamIntoUiSegments,
   formatPostgrestError: () => formatPostgrestError,
   formatRetrievalContext: () => formatRetrievalContext,
   formatSdkError: () => formatSdkError,
   generateIdempotencyKey: () => generateIdempotencyKey,
+  isIncompleteAgentStreamError: () => isIncompleteAgentStreamError,
   normalizeBrowserApiBase: () => normalizeBrowserApiBase,
+  parseAgentStreamAgentInfo: () => parseAgentStreamAgentInfo,
+  parseAgentStreamDone: () => parseAgentStreamDone,
   parseSseDataLine: () => parseSseDataLine,
   parseTransportResponse: () => parseTransportResponse,
   readSseStream: () => readSseStream,
+  runAgentChatStream: () => runAgentChatStream,
+  runAgentChatStreamForUi: () => runAgentChatStreamForUi,
+  runAgentChatStreamLenient: () => runAgentChatStreamLenient,
   toRagableResult: () => toRagableResult,
   unwrapPostgrest: () => unwrapPostgrest
 });
@@ -406,6 +415,442 @@ function toArrayBuffer(value) {
   return copy.buffer;
 }
 
+// src/agent-stream.ts
+function assertAborted(signal) {
+  if (signal?.aborted) {
+    throw new RagableAbortError();
+  }
+}
+function asString(v, fallback = "") {
+  return typeof v === "string" ? v : fallback;
+}
+function asNumber(v, fallback = 0) {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function asUnknownArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+function parseAgentStreamDone(e) {
+  if (e.type !== "done") return null;
+  return {
+    response: asString(e["response"]),
+    traces: asUnknownArray(e["traces"]),
+    totalDurationMs: asNumber(e["totalDurationMs"]),
+    ...e["httpResponse"] !== void 0 ? { httpResponse: e["httpResponse"] } : {},
+    ...typeof e["inputTokens"] === "number" ? { inputTokens: e["inputTokens"] } : {},
+    ...typeof e["outputTokens"] === "number" ? { outputTokens: e["outputTokens"] } : {},
+    ...typeof e["cachedPromptTokens"] === "number" ? { cachedPromptTokens: e["cachedPromptTokens"] } : {},
+    ...typeof e["cacheCreationInputTokens"] === "number" ? { cacheCreationInputTokens: e["cacheCreationInputTokens"] } : {},
+    ...Array.isArray(e["completionProviders"]) ? {
+      completionProviders: e["completionProviders"].map((x) => String(x))
+    } : {},
+    ...typeof e["creditsCharged"] === "number" ? { creditsCharged: e["creditsCharged"] } : {},
+    ...typeof e["agentSteps"] === "number" ? { agentSteps: e["agentSteps"] } : {},
+    ...e["finishReason"] !== void 0 ? { finishReason: e["finishReason"] } : {},
+    ...e["stopReason"] !== void 0 ? { stopReason: e["stopReason"] } : {},
+    ...e["turnMessages"] !== void 0 ? { turnMessages: e["turnMessages"] } : {},
+    ...typeof e["promptTokensEstimated"] === "number" ? { promptTokensEstimated: e["promptTokensEstimated"] } : {},
+    ...typeof e["contextWindow"] === "number" ? { contextWindow: e["contextWindow"] } : {}
+  };
+}
+function parseAgentStreamAgentInfo(e) {
+  if (e.type !== "agent:info") return null;
+  return {
+    type: "agent:info",
+    name: asString(e["name"]),
+    agent_name: asString(e["agent_name"])
+  };
+}
+function parseAgentInfo(e) {
+  return parseAgentStreamAgentInfo(e);
+}
+async function runAgentChatStream(source, handlers = {}, options = {}) {
+  const { signal } = options;
+  let assistantText = "";
+  let reasoningText = "";
+  let donePayload = null;
+  try {
+    for await (const event of source) {
+      assertAborted(signal);
+      handlers.onEvent?.(event);
+      const info = parseAgentInfo(event);
+      if (info) {
+        handlers.onAgentInfo?.(info);
+        continue;
+      }
+      switch (event.type) {
+        case "ping":
+          handlers.onPing?.();
+          break;
+        case "token": {
+          const nodeId = asString(event["nodeId"], "__self__");
+          const token = asString(event["token"]);
+          assistantText += token;
+          handlers.onToken?.(token, { nodeId });
+          break;
+        }
+        case "reasoning_token": {
+          const nodeId = asString(event["nodeId"], "__self__");
+          const token = asString(event["token"]);
+          reasoningText += token;
+          handlers.onReasoningToken?.(token, { nodeId });
+          break;
+        }
+        case "tool:call":
+          handlers.onToolCall?.({
+            nodeId: asString(event["nodeId"]),
+            toolName: asString(event["toolName"]),
+            args: event["args"]
+          });
+          break;
+        case "tool:args_update": {
+          const raw = event["args"];
+          const args = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+          handlers.onToolArgsUpdate?.({
+            nodeId: asString(event["nodeId"]),
+            args
+          });
+          break;
+        }
+        case "tool:result":
+          handlers.onToolResult?.({
+            nodeId: asString(event["nodeId"]),
+            toolName: asString(event["toolName"]),
+            durationMs: asNumber(event["durationMs"]),
+            ...typeof event["result"] === "string" ? { result: event["result"] } : {}
+          });
+          break;
+        case "node:start":
+          handlers.onNodeStart?.({
+            nodeId: asString(event["nodeId"]),
+            nodeType: asString(event["nodeType"]),
+            label: asString(event["label"])
+          });
+          break;
+        case "node:complete":
+          handlers.onNodeComplete?.({
+            nodeId: asString(event["nodeId"]),
+            output: event["output"],
+            durationMs: asNumber(event["durationMs"])
+          });
+          break;
+        case "node:error":
+          handlers.onNodeError?.({
+            nodeId: asString(event["nodeId"]),
+            error: asString(event["error"])
+          });
+          break;
+        case "done": {
+          const parsed = parseAgentStreamDone(event);
+          if (parsed) {
+            donePayload = parsed;
+            handlers.onDone?.(parsed);
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+  } catch (err) {
+    handlers.onError?.(err);
+    throw err;
+  }
+  if (!donePayload) {
+    const err = new RagableError(
+      "Agent stream ended without a done event",
+      502,
+      { code: "SDK_AGENT_STREAM_INCOMPLETE" }
+    );
+    handlers.onError?.(err);
+    throw err;
+  }
+  const result = {
+    ...donePayload,
+    assistantText,
+    reasoningText
+  };
+  handlers.onComplete?.(result);
+  return result;
+}
+async function runAgentChatStreamLenient(source, handlers = {}, options = {}) {
+  try {
+    return await runAgentChatStream(source, handlers, options);
+  } catch (e) {
+    if (e instanceof RagableError && e.code === "SDK_AGENT_STREAM_INCOMPLETE") {
+      return null;
+    }
+    throw e;
+  }
+}
+function isIncompleteAgentStreamError(e) {
+  return e instanceof RagableError && e.code === "SDK_AGENT_STREAM_INCOMPLETE";
+}
+
+// src/agent-chat-ui.ts
+function asString2(v, fallback = "") {
+  return typeof v === "string" ? v : fallback;
+}
+function asNumber2(v, fallback = 0) {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function assertAborted2(signal) {
+  if (signal?.aborted) {
+    throw new RagableAbortError();
+  }
+}
+function recordFromUnknown(v) {
+  if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+    return { ...v };
+  }
+  return {};
+}
+function lastToolBlocksStream(last) {
+  return last?.type === "tool" && last.status === "started";
+}
+function toolSegmentId(event) {
+  const nid = event["nodeId"];
+  if (typeof nid === "string" && nid.length > 0) return nid;
+  const tn = event["toolName"];
+  if (typeof tn === "string" && tn.length > 0) return tn;
+  return "__tool__";
+}
+function normalizeContextSummarizedMode(m) {
+  if (m === "llm" || m === "heuristic" || m === "llm+heuristic" || m === "aggressive") {
+    return m;
+  }
+  return void 0;
+}
+function normalizeContextSummarizedReason(r) {
+  if (r === "soft_limit" || r === "forced") return r;
+  return void 0;
+}
+function foldContextSummarized(prev, event) {
+  const step = asNumber2(event["step"], 0);
+  const mode = normalizeContextSummarizedMode(event["mode"]);
+  const reason = normalizeContextSummarizedReason(event["reason"]);
+  const tro = event["tokensRemovedEstimate"];
+  const eta = event["estimatedTokensAfter"];
+  return [
+    ...prev,
+    {
+      type: "context_summarized",
+      step,
+      ...mode ? { mode } : {},
+      ...reason ? { reason } : {},
+      ...typeof tro === "number" && tro > 0 ? { tokensRemovedEstimate: tro } : {},
+      ...typeof eta === "number" && eta > 0 ? { estimatedTokensAfter: eta } : {}
+    }
+  ];
+}
+function collectAssistantTextFromUiSegments(segments) {
+  return segments.filter((s) => s.type === "text").map((s) => s.content).join("");
+}
+function foldAgentStreamIntoUiSegments(prev, event) {
+  switch (event.type) {
+    case "token": {
+      const last = prev[prev.length - 1];
+      if (lastToolBlocksStream(last)) return prev;
+      const token = asString2(event["token"]);
+      if (!token) return prev;
+      if (last?.type === "text") {
+        return [
+          ...prev.slice(0, -1),
+          { type: "text", content: last.content + token }
+        ];
+      }
+      return [...prev, { type: "text", content: token }];
+    }
+    case "reasoning_token": {
+      const last = prev[prev.length - 1];
+      if (lastToolBlocksStream(last)) return prev;
+      const token = asString2(event["token"]);
+      if (!token) return prev;
+      if (last?.type === "reasoning") {
+        return [
+          ...prev.slice(0, -1),
+          { type: "reasoning", content: last.content + token }
+        ];
+      }
+      return [...prev, { type: "reasoning", content: token }];
+    }
+    case "tool:call": {
+      const id = toolSegmentId(event);
+      const toolName = asString2(event["toolName"], "tool");
+      const argsRaw = event["args"];
+      const args = argsRaw !== null && typeof argsRaw === "object" && !Array.isArray(argsRaw) ? argsRaw : void 0;
+      return [
+        ...prev,
+        {
+          type: "tool",
+          id,
+          toolName,
+          status: "started",
+          ...args !== void 0 ? { args } : {}
+        }
+      ];
+    }
+    case "tool:args_update": {
+      const nodeId = asString2(event["nodeId"]);
+      const patch = recordFromUnknown(event["args"]);
+      return prev.map((seg) => {
+        if (seg.type !== "tool" || seg.id !== nodeId) return seg;
+        const merged = { ...recordFromUnknown(seg.args), ...patch };
+        return {
+          ...seg,
+          args: merged
+        };
+      });
+    }
+    case "tool:result": {
+      const nodeId = asString2(event["nodeId"]);
+      const toolName = asString2(event["toolName"]) || asString2(event["nodeId"]);
+      const durationMs = typeof event["durationMs"] === "number" ? event["durationMs"] : void 0;
+      const resultStr = typeof event["result"] === "string" ? event["result"] : void 0;
+      let idx = -1;
+      if (nodeId) {
+        for (let i = prev.length - 1; i >= 0; i--) {
+          const s = prev[i];
+          if (s.type === "tool" && s.status === "started" && s.id === nodeId) {
+            idx = i;
+            break;
+          }
+        }
+      }
+      if (idx < 0 && toolName) {
+        for (let i = prev.length - 1; i >= 0; i--) {
+          const s = prev[i];
+          if (s.type === "tool" && s.status === "started" && s.toolName === toolName) {
+            idx = i;
+            break;
+          }
+        }
+      }
+      if (idx < 0) return prev;
+      const next = [...prev];
+      const seg = next[idx];
+      if (seg.type !== "tool") return prev;
+      next[idx] = {
+        ...seg,
+        status: "completed",
+        ...durationMs !== void 0 ? { durationMs } : {},
+        ...resultStr !== void 0 ? { result: resultStr } : {}
+      };
+      return next;
+    }
+    case "context_summarized":
+      return foldContextSummarized(prev, event);
+    case "llm_step": {
+      return [
+        ...prev,
+        {
+          type: "llm_step",
+          step: Number(event["step"]),
+          inputTokens: Number(event["inputTokens"] ?? 0),
+          outputTokens: Number(event["outputTokens"] ?? 0),
+          ...typeof event["cachedPromptTokens"] === "number" ? { cachedPromptTokens: event["cachedPromptTokens"] } : {},
+          ...typeof event["cacheCreationInputTokens"] === "number" ? { cacheCreationInputTokens: event["cacheCreationInputTokens"] } : {},
+          creditsEstimated: Number(event["creditsEstimated"] ?? 0),
+          ...typeof event["apiCostUsd"] === "number" && Number.isFinite(event["apiCostUsd"]) ? { apiCostUsd: event["apiCostUsd"] } : {},
+          ...typeof event["provider"] === "string" && event["provider"] ? { provider: event["provider"] } : {}
+        }
+      ];
+    }
+    default:
+      return prev;
+  }
+}
+function finalizeAgentChatUiTurn(segments, done) {
+  let segs = segments.length > 0 ? [...segments] : void 0;
+  if (done.stopReason) {
+    const stopSeg = {
+      type: "stop_reason",
+      content: done.stopReason,
+      finishReason: done.finishReason ?? "error"
+    };
+    segs = segs ? [...segs, stopSeg] : [stopSeg];
+  }
+  const fromText = segs ? collectAssistantTextFromUiSegments(segs) : "";
+  const content = done.response || fromText || "No response.";
+  const message = {
+    role: "ai",
+    content,
+    ...segs && segs.length > 0 ? { segments: segs } : {},
+    finishReason: done.finishReason ?? null,
+    ...Array.isArray(done.completionProviders) && done.completionProviders.length > 0 ? { completionProviders: done.completionProviders } : {},
+    ...typeof done.agentSteps === "number" && Number.isFinite(done.agentSteps) && done.agentSteps > 0 ? { agentSteps: Math.floor(done.agentSteps) } : {},
+    usage: {
+      inputTokens: done.inputTokens ?? 0,
+      outputTokens: done.outputTokens ?? 0,
+      creditsCharged: done.creditsCharged ?? 0,
+      ...typeof done.cachedPromptTokens === "number" && done.cachedPromptTokens > 0 ? { cachedPromptTokens: done.cachedPromptTokens } : {},
+      ...typeof done.cacheCreationInputTokens === "number" && done.cacheCreationInputTokens > 0 ? { cacheCreationInputTokens: done.cacheCreationInputTokens } : {}
+    },
+    ...typeof done.totalDurationMs === "number" && done.totalDurationMs > 0 ? { durationMs: done.totalDurationMs } : {}
+  };
+  return { segments: segs ?? [], message };
+}
+async function runAgentChatStreamForUi(source, handlers = {}, options = {}) {
+  const { signal } = options;
+  let segments = [];
+  let donePayload = null;
+  try {
+    for await (const event of source) {
+      assertAborted2(signal);
+      handlers.onEvent?.(event);
+      const info = parseAgentStreamAgentInfo(event);
+      if (info) {
+        handlers.onAgentInfo?.(info);
+        continue;
+      }
+      if (event.type === "ping") continue;
+      if (event.type === "done") {
+        const parsed = parseAgentStreamDone(event);
+        if (parsed) {
+          donePayload = parsed;
+          handlers.onDone?.(parsed);
+        }
+        break;
+      }
+      const next = foldAgentStreamIntoUiSegments(segments, event);
+      if (next !== segments) {
+        segments = next;
+        handlers.onSegments?.(segments);
+        if (event.type === "token") {
+          handlers.onStreamingText?.(
+            collectAssistantTextFromUiSegments(segments)
+          );
+        }
+      }
+    }
+  } catch (err) {
+    handlers.onError?.(err);
+    throw err;
+  }
+  if (!donePayload) {
+    const err = new RagableError(
+      "Agent stream ended without a done event",
+      502,
+      { code: "SDK_AGENT_STREAM_INCOMPLETE" }
+    );
+    handlers.onError?.(err);
+    throw err;
+  }
+  const segmentsMidTurn = [...segments];
+  const { segments: finalSegs, message } = finalizeAgentChatUiTurn(
+    segments,
+    donePayload
+  );
+  const result = {
+    segmentsMidTurn,
+    segments: finalSegs,
+    message,
+    done: donePayload
+  };
+  handlers.onComplete?.(result);
+  return result;
+}
+
 // src/sse.ts
 async function parseMaybeJsonBody(response) {
   const contentType = response.headers.get("content-type") ?? "";
@@ -505,7 +950,8 @@ var AgentsClient = class {
         body: {
           message: params.message,
           ...params.history !== void 0 ? { history: params.history } : {}
-        }
+        },
+        ...params.signal !== void 0 ? { signal: params.signal } : {}
       }
     );
     if (!response.ok) {
@@ -519,6 +965,24 @@ var AgentsClient = class {
     }
     yield* readSseStream(body);
   }
+  /**
+   * Stream an agent turn with callbacks; returns the final `done` payload plus streamed text.
+   * Prefer this over manual iteration when building chat UIs against the server API key client.
+   */
+  async runChatStream(agentId, params, handlers = {}) {
+    return runAgentChatStream(this.chatStream(agentId, params), handlers, {
+      signal: params.signal
+    });
+  }
+  /**
+   * Stream with dashboard-style `AgentChat` ergonomics: {@link AgentChatStreamUiHandlers.onSegments}
+   * / `onStreamingText` for live UI; returns a persisted-shaped assistant message on `done`.
+   */
+  async runChatUi(agentId, params, handlers = {}) {
+    return runAgentChatStreamForUi(this.chatStream(agentId, params), handlers, {
+      signal: params.signal
+    });
+  }
 };
 
 // src/transport.ts
@@ -2376,6 +2840,18 @@ var BrowserCollectionApi = class {
         this.databaseInstanceId
       )
     ));
+    /**
+     * Insert multiple rows in one request (server multi-value `INSERT`, single transaction).
+     * Empty **`items`** resolves to an empty array. Max batch size is enforced on the server (500).
+     */
+    __publicField(this, "insertMany", (items) => asPostgrestResponse(
+      () => this.database._requestCollection(
+        "POST",
+        `/${encodeURIComponent(this.name)}/records/batch`,
+        { items },
+        this.databaseInstanceId
+      )
+    ));
     /**
      * Update rows matching `where` (JSON fields, plus envelope `id` / `createdAt` / `updatedAt`).
      */
@@ -2404,6 +2880,21 @@ var BrowserCollectionApi = class {
         this.databaseInstanceId
       )
     ));
+    /**
+     * Like {@link BrowserCollectionApi.delete} but the success payload includes **`meta.count`**
+     * (number of deleted rows), matching {@link BrowserCollectionApi.updateMany}.
+     */
+    __publicField(this, "deleteMany", async (where, options) => {
+      const r = await this.delete(where, options);
+      if (r.error) return r;
+      return {
+        data: {
+          records: r.data.records,
+          meta: { count: r.data.deleted }
+        },
+        error: null
+      };
+    });
   }
   normalizeFindArgs(whereOrParams) {
     const hasQueryKeys = typeof whereOrParams === "object" && whereOrParams !== null && FIND_QUERY_KEYS.some(
@@ -2848,7 +3339,8 @@ var RagableBrowserAgentsClient = class {
       {
         method: "POST",
         headers,
-        body: JSON.stringify(body)
+        body: JSON.stringify(body),
+        ...params.signal !== void 0 ? { signal: params.signal } : {}
       }
     );
     if (!response.ok) {
@@ -2877,7 +3369,8 @@ var RagableBrowserAgentsClient = class {
         body: JSON.stringify({
           message: params.message,
           ...params.history !== void 0 ? { history: params.history } : {}
-        })
+        }),
+        ...params.signal !== void 0 ? { signal: params.signal } : {}
       }
     );
     if (!response.ok) {
@@ -2888,6 +3381,26 @@ var RagableBrowserAgentsClient = class {
     if (!response.body) return;
     yield* readSseStream(response.body);
   }
+  /**
+   * Stream a project agent (`/agents/*.json`) with callbacks; returns the final `done` payload
+   * plus streamed assistant text. Prefer this over manual `for await` when building chat UIs.
+   */
+  async runChatStreamByName(agentName, params, handlers = {}) {
+    return runAgentChatStream(this.chatStreamByName(agentName, params), handlers, {
+      signal: params.signal
+    });
+  }
+  /**
+   * Same as {@link runChatStreamByName} but folds events into `AgentChat`-style segments
+   * (`onSegments` / `onStreamingText`) and returns a history-ready assistant message.
+   */
+  async runChatUiByName(agentName, params, handlers = {}) {
+    return runAgentChatStreamForUi(
+      this.chatStreamByName(agentName, params),
+      handlers,
+      { signal: params.signal }
+    );
+  }
   createConversation(params) {
     const headers = new Headers(this.options.headers);
     headers.set("Content-Type", "application/json");
@@ -3135,6 +3648,7 @@ function createRagableServerClient(options) {
   asPostgrestResponse,
   assertPostgrestSuccess,
   bindFetch,
+  collectAssistantTextFromUiSegments,
   collectionRecordToRowWithMeta,
   collectionRecordsToRowWithMeta,
   createBrowserClient,
@@ -3145,14 +3659,22 @@ function createRagableServerClient(options) {
   detectStorage,
   effectiveDataAuth,
   extractErrorMessage,
+  finalizeAgentChatUiTurn,
+  foldAgentStreamIntoUiSegments,
   formatPostgrestError,
   formatRetrievalContext,
   formatSdkError,
   generateIdempotencyKey,
+  isIncompleteAgentStreamError,
   normalizeBrowserApiBase,
+  parseAgentStreamAgentInfo,
+  parseAgentStreamDone,
   parseSseDataLine,
   parseTransportResponse,
   readSseStream,
+  runAgentChatStream,
+  runAgentChatStreamForUi,
+  runAgentChatStreamLenient,
   toRagableResult,
   unwrapPostgrest
 });