pass structured error (#12)

Author: augustas1

.gitignore

@@ -1,2 +1,3 @@
 node_modules
-dist
+dist
+.npmrc

src/query/agent.ts

@@ -1,9 +1,19 @@
 import { WeaviateClient } from "weaviate-client";
-import { QueryAgentResponse, ProgressMessage, StreamedTokens } from "./response/response.js";
-import { mapResponse, mapProgressMessageFromSSE, mapStreamedTokensFromSSE, mapResponseFromSSE } from "./response/response-mapping.js";
+import {
+  QueryAgentResponse,
+  ProgressMessage,
+  StreamedTokens,
+} from "./response/response.js";
+import {
+  mapResponse,
+  mapProgressMessageFromSSE,
+  mapStreamedTokensFromSSE,
+  mapResponseFromSSE,
+} from "./response/response-mapping.js";
 import { mapApiResponse } from "./response/api-response-mapping.js";
 import { fetchServerSentEvents } from "./response/server-sent-events.js";
 import { mapCollections, QueryAgentCollectionConfig } from "./collection.js";
+import { handleError } from "./response/error.js";
 
 /**
  * An agent for executing agentic queries against Weaviate.
@@ -74,7 +84,7 @@ export class QueryAgent {
     });
 
     if (!response.ok) {
-      throw Error(`Query agent failed. ${await response.text()}`);
+      await handleError(response);
     }
 
     return mapResponse(await response.json());
@@ -100,22 +110,25 @@ export class QueryAgent {
     const { host, bearerToken, headers } =
       await this.client.getConnectionDetails();
 
-    const sseStream = fetchServerSentEvents(`${this.agentsHost}/agent/stream_query`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: bearerToken!,
-        "X-Weaviate-Cluster-Url": host,
-      },
-      body: JSON.stringify({
-        headers,
-        query,
-        collections: mapCollections(targetCollections),
-        system_prompt: this.systemPrompt,
-        previous_response: context ? mapApiResponse(context) : undefined,
-        include_progress: includeProgress ?? true,
-      }),
-    });
+    const sseStream = fetchServerSentEvents(
+      `${this.agentsHost}/agent/stream_query`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: bearerToken!,
+          "X-Weaviate-Cluster-Url": host,
+        },
+        body: JSON.stringify({
+          headers,
+          query,
+          collections: mapCollections(targetCollections),
+          system_prompt: this.systemPrompt,
+          previous_response: context ? mapApiResponse(context) : undefined,
+          include_progress: includeProgress ?? true,
+        }),
+      }
+    );
 
     for await (const event of sseStream) {
       let output: ProgressMessage | StreamedTokens | QueryAgentResponse;

src/query/response/error.ts

@@ -0,0 +1,37 @@
+export const handleError = async (response: Response) => {
+  const responseText = await response.text();
+  const json = getJson(responseText);
+
+  if (json?.error) {
+    const error = json.error as ErrorResponse;
+    throw new QueryAgentError(error.message, error.code, error.details);
+  }
+
+  throw new Error(`Query agent failed. ${responseText}`);
+};
+
+const getJson = (responseText: string): Record<string, unknown> | null => {
+  try {
+    return JSON.parse(responseText);
+  } catch {
+    return null;
+  }
+};
+
+export class QueryAgentError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+type ErrorResponse = {
+  message: string;
+  code: string;
+  details?: Record<string, unknown>;
+};

src/query/response/index.ts

@@ -1 +1,2 @@
 export * from "./response.js";
+export { QueryAgentError } from "./error.js";