@agent-os-sdk/client 0.3.0 → 0.3.2

package/src/generated/swagger.json

@@ -1222,6 +1222,50 @@
         }
       }
     },
+    "/v1/api/catalog/nodes": {
+      "get": {
+        "tags": [
+          "Catalog"
+        ],
+        "summary": "Get the Node Catalog (v1).",
+        "parameters": [
+          {
+            "name": "version",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
+    "/v1/api/triggers/templates": {
+      "get": {
+        "tags": [
+          "Catalog"
+        ],
+        "summary": "Get the Trigger Templates Catalog (v1).",
+        "parameters": [
+          {
+            "name": "version",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK"
+          }
+        }
+      }
+    },
     "/v1/api/workspaces/{workspaceId}/runs/{runId}/checkpoints": {
       "get": {
         "tags": [
@@ -5233,7 +5277,17 @@
         "tags": [
           "Tools"
         ],
-        "summary": "List all tool definitions.",
+        "summary": "List all tool definitions.\nSupports ?version=1 for canonical ToolCatalog format.",
+        "parameters": [
+          {
+            "name": "version",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "default": "1"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK"
@@ -5246,7 +5300,17 @@
         "tags": [
           "Tools"
         ],
-        "summary": "List all tool definitions.",
+        "summary": "List all tool definitions.\nSupports ?version=1 for canonical ToolCatalog format.",
+        "parameters": [
+          {
+            "name": "version",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "default": "1"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "OK"
@@ -5826,25 +5890,13 @@
         }
       }
     },
-    "/v1/api/workspaces/{workspaceId}/vector-stores": {
+    "/v1/api/vector-stores": {
       "post": {
         "tags": [
           "VectorStores"
         ],
         "summary": "Creates a new vector store for semantic document search.",
         "description": "Creates a vector store with the specified embedding configuration.\nThe store is ready to accept file attachments immediately after creation.\n\n**Default Configuration:**\n- Provider: `openai`\n- Model: `text-embedding-3-small`\n- Dimension: `1536`",
-        "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "description": "The workspace to create the vector store in.",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          }
-        ],
         "requestBody": {
           "description": "Vector store configuration.",
           "content": {
@@ -5876,6 +5928,16 @@
               }
             }
           },
+          "401": {
+            "description": "Authentication or Workspace context required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Workspace not found.",
             "content": {
@@ -5894,15 +5956,6 @@
         ],
         "summary": "List vector stores in a workspace.",
         "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "limit",
             "in": "query",
@@ -5935,26 +5988,27 @@
                 }
               }
             }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
     },
-    "/v1/api/workspaces/{workspaceId}/vector-stores/{vectorStoreId}": {
+    "/v1/api/vector-stores/{vectorStoreId}": {
       "get": {
         "tags": [
           "VectorStores"
         ],
         "summary": "Get a vector store by ID.",
         "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "vectorStoreId",
             "in": "path",
@@ -5976,6 +6030,16 @@
               }
             }
           },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Not Found",
             "content": {
@@ -5994,15 +6058,6 @@
         ],
         "summary": "Delete a vector store.",
         "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "vectorStoreId",
             "in": "path",
@@ -6017,6 +6072,16 @@
           "204": {
             "description": "No Content"
           },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Not Found",
             "content": {
@@ -6030,22 +6095,13 @@
         }
       }
     },
-    "/v1/api/workspaces/{workspaceId}/vector-stores/{vectorStoreId}/files": {
+    "/v1/api/vector-stores/{vectorStoreId}/files": {
       "post": {
         "tags": [
           "VectorStores"
         ],
         "summary": "Attach a file to a vector store for embedding.",
         "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "vectorStoreId",
             "in": "path",
@@ -6086,6 +6142,16 @@
               }
             }
           },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Not Found",
             "content": {
@@ -6099,7 +6165,7 @@
         }
       }
     },
-    "/v1/api/workspaces/{workspaceId}/vector-stores/{vectorStoreId}/query": {
+    "/v1/api/vector-stores/{vectorStoreId}/query": {
       "post": {
         "tags": [
           "VectorStores"
@@ -6107,16 +6173,6 @@
         "summary": "Performs semantic similarity search against the vector store.",
         "description": "Executes a cosine similarity search to find document chunks most relevant\nto the query. Results are ranked by similarity score.\n\n**Note:** The query is automatically embedded using the store's configured\nembedding provider before search.\n\n**Example Request:**\n```json\n{\n  \"query\": \"How do I configure authentication?\",\n  \"top_k\": 5,\n  \"min_score\": 0.7\n}\n```",
         "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "description": "The workspace containing the vector store.",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "vectorStoreId",
             "in": "path",
@@ -6159,6 +6215,16 @@
               }
             }
           },
+          "401": {
+            "description": "Authentication or Workspace context required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Vector store not found.",
             "content": {
@@ -6172,22 +6238,13 @@
         }
       }
     },
-    "/v1/api/workspaces/{workspaceId}/vector-stores/{vectorStoreId}/bind-agent": {
+    "/v1/api/vector-stores/{vectorStoreId}/bind-agent": {
       "post": {
         "tags": [
           "VectorStores"
         ],
         "summary": "Bind a vector store to an agent.",
         "parameters": [
-          {
-            "name": "workspaceId",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
           {
             "name": "vectorStoreId",
             "in": "path",
@@ -6221,6 +6278,16 @@
           "204": {
             "description": "No Content"
           },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
           "404": {
             "description": "Not Found",
             "content": {
@@ -6934,14 +7001,6 @@
       "CreateAgentRequest": {
         "type": "object",
         "properties": {
-          "tenant_id": {
-            "type": "string",
-            "format": "uuid"
-          },
-          "workspace_id": {
-            "type": "string",
-            "format": "uuid"
-          },
           "name": {
             "type": "string",
             "nullable": true
@@ -8716,6 +8775,9 @@
     {
       "name": "Builder"
     },
+    {
+      "name": "Catalog"
+    },
     {
       "name": "Checkpoints"
     },

package/src/index.ts

@@ -115,6 +115,7 @@ export { MeModule, type MeResponse } from "./modules/me.js";
 export { InfoModule, type ServerInfo } from "./modules/info.js";
 export { MetricsModule, type MetricsResponse } from "./modules/metrics.js";
 export { GraphsModule, type GraphValidationResult, type GraphIntrospectionResult } from "./modules/graphs.js";
+export { CatalogModule, type CatalogVersions, type NodeCatalogResponse, type ToolCatalogResponse, type TriggerCatalogResponse, type NodeDefinition, type ToolDefinition, type TriggerTemplate } from "./modules/catalog.js";
 
 // FUTURE modules - All return 501 Not Implemented. When backend is ready, implement real calls.
 export { HandoffModule, type HandoffOptions, type HandoffResult, type ForkOptions, type ForkResult, type RunChain, type RunChainNode, type HandoffMode, type HandoffConstraints } from "./modules/handoff.js";

package/src/modules/builder.ts

@@ -7,6 +7,8 @@
  * 
  * Flow: Frontend → CP:5000/v1/api/builder/{agentId}/chat → DP:8001/v1/internal/builder/{agentId}/chat
  * 
+ * ALL HTTP goes through rawClient - no direct fetch calls.
+ * 
  * @example
  * ```ts
  * const client = new AgentOsClient({ ... })
@@ -25,12 +27,23 @@
  * ```
  */
 
-import { streamSSE, type SSEEvent, type SSEOptions } from "../sse/client.js";
+import type { RawClient, APIResponse } from "../client/raw.js";
+import type { SSEOptions } from "../sse/client.js";
+
+export type CatalogVersions = {
+    nodes: string;
+    tools: string;
+    triggers: string;
+};
 
 export type BuilderChatRequest = {
     message: string;
     current_graph_spec?: Record<string, unknown>;
     thread_id?: string;
+    /** Catalog versions to use for validation */
+    catalog_versions?: CatalogVersions;
+    /** Combined hash of all catalogs for integrity */
+    catalog_ref?: string;
 };
 
 export type GraphUpdateAction = {
@@ -55,36 +68,29 @@ export type BuilderChatResponse = {
 };
 
 export class BuilderModule {
-    constructor(
-        private baseUrl: string,
-        private headers: () => Record<string, string>
-    ) { }
+    constructor(private client: RawClient) { }
 
     /**
      * Stream chat with meta-agent (SSE).
      * Returns async generator of events.
+     * 
+     * Uses rawClient.streamPost() - headers resolved asynchronously.
      */
     async *chat(
         agentId: string,
         request: BuilderChatRequest,
         options?: SSEOptions
     ): AsyncGenerator<BuilderStreamEvent> {
-        // Use public API route (CP proxies to DP)
-        const url = `${this.baseUrl}/v1/api/builder/${agentId}/chat`;
-
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Accept: "text/event-stream",
-                ...this.headers(),
-            },
-            body: JSON.stringify(request),
+        // Use rawClient.streamPost() - ALL auth headers resolved automatically
+        const response = await this.client.streamPost("/v1/api/builder/{agentId}/chat", {
+            params: { path: { agentId } },
+            body: request,
             signal: options?.signal,
         });
 
         if (!response.ok) {
-            throw new Error(`Builder chat failed: ${response.status}`);
+            const errorText = await response.text();
+            throw new Error(`Builder chat failed: ${response.status} - ${errorText}`);
         }
 
         if (!response.body) {
@@ -133,29 +139,26 @@ export class BuilderModule {
 
     /**
      * Sync chat with meta-agent (no streaming).
+     * 
+     * Uses rawClient.POST() - headers resolved asynchronously.
      */
     async chatSync(
         agentId: string,
         request: BuilderChatRequest
     ): Promise<BuilderChatResponse> {
-        // Use public API route (CP proxies to DP)
-        const url = `${this.baseUrl}/v1/api/builder/${agentId}/chat/sync`;
-
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                ...this.headers(),
-            },
-            body: JSON.stringify(request),
-        });
+        const { data, error } = await this.client.POST<BuilderChatResponse>(
+            "/v1/api/builder/{agentId}/chat/sync",
+            {
+                params: { path: { agentId } },
+                body: request,
+            }
+        );
 
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`Builder chat failed: ${response.status} - ${error}`);
+        if (error) {
+            throw new Error(`Builder chat failed: ${error.code} - ${error.message}`);
         }
 
-        return response.json();
+        return data!;
     }
 
     /**

package/src/modules/catalog.ts

@@ -0,0 +1,155 @@
+/**
+ * Catalog Module - Canonical Catalog Access
+ * 
+ * Provides access to versioned catalogs:
+ * - Node Catalog (node types, config schemas)
+ * - Tool Catalog (tool definitions) 
+ * - Trigger Templates (trigger configurations)
+ * 
+ * All responses include:
+ * - ETag header for caching
+ * - X-Content-Hash header for integrity verification
+ * 
+ * @example
+ * ```ts
+ * const client = new AgentOsClient({ ... })
+ * 
+ * // Get all catalogs
+ * const nodes = await unwrap(client.catalog.getNodes())
+ * const tools = await unwrap(client.catalog.getTools())
+ * const triggers = await unwrap(client.catalog.getTriggers())
+ * 
+ * // Use returned metadata for caching
+ * console.log(nodes.etag, nodes.contentHash)
+ * ```
+ */
+
+import type { RawClient, APIResponse } from "../client/raw.js";
+
+export interface CatalogVersions {
+    nodes: string;
+    tools: string;
+    triggers: string;
+}
+
+export interface CatalogMetadata {
+    version: string;
+    etag?: string;
+    contentHash?: string;
+}
+
+export interface NodeCatalogResponse extends CatalogMetadata {
+    nodes: Record<string, NodeDefinition>;
+}
+
+export interface NodeDefinition {
+    kind: string;
+    category: string;
+    description: string;
+    config_schema?: Record<string, unknown>;
+}
+
+export interface ToolCatalogResponse extends CatalogMetadata {
+    tools: ToolDefinition[];
+}
+
+export interface ToolDefinition {
+    slug: string;
+    name: string;
+    description?: string;
+    type: string;
+    version?: number;
+    input_schema?: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    credential_requirements?: unknown[];
+}
+
+export interface TriggerCatalogResponse extends CatalogMetadata {
+    triggers: TriggerTemplate[];
+}
+
+export interface TriggerTemplate {
+    slug: string;
+    kind: string;
+    description?: string;
+    run_input_schema?: Record<string, unknown>;
+}
+
+export class CatalogModule {
+    constructor(private client: RawClient) { }
+
+    /**
+     * Get the Node Catalog.
+     * Returns node types with their configuration schemas.
+     */
+    async getNodes(version: string = "1"): Promise<APIResponse<NodeCatalogResponse>> {
+        const response = await this.client.GET<NodeCatalogResponse>("/v1/api/catalog/nodes", {
+            params: { query: { version } },
+        });
+
+        // Extract headers for metadata (if available from raw response)
+        return response;
+    }
+
+    /**
+     * Get the Tool Catalog.
+     * Returns tool definitions with input/output schemas.
+     */
+    async getTools(version: string = "1"): Promise<APIResponse<ToolCatalogResponse>> {
+        const response = await this.client.GET<ToolCatalogResponse>("/v1/api/tools/definitions", {
+            params: { query: { version } },
+        });
+
+        return response;
+    }
+
+    /**
+     * Get the Trigger Templates Catalog.
+     * Returns trigger configurations and input schemas.
+     */
+    async getTriggers(version: string = "1"): Promise<APIResponse<TriggerCatalogResponse>> {
+        const response = await this.client.GET<TriggerCatalogResponse>("/v1/api/triggers/templates", {
+            params: { query: { version } },
+        });
+
+        return response;
+    }
+
+    /**
+     * Get all catalogs at once for convenience.
+     * Returns combined catalog data with versions.
+     */
+    async getAll(version: string = "1"): Promise<{
+        data?: {
+            nodes: NodeCatalogResponse;
+            tools: ToolCatalogResponse;
+            triggers: TriggerCatalogResponse;
+            catalog_versions: CatalogVersions;
+        };
+        error?: { code: string; message: string; details?: unknown };
+    }> {
+        const [nodesRes, toolsRes, triggersRes] = await Promise.all([
+            this.getNodes(version),
+            this.getTools(version),
+            this.getTriggers(version),
+        ]);
+
+        if (nodesRes.error) return { data: undefined, error: nodesRes.error };
+        if (toolsRes.error) return { data: undefined, error: toolsRes.error };
+        if (triggersRes.error) return { data: undefined, error: triggersRes.error };
+
+        return {
+            data: {
+                nodes: nodesRes.data!,
+                tools: toolsRes.data!,
+                triggers: triggersRes.data!,
+                catalog_versions: {
+                    nodes: version,
+                    tools: version,
+                    triggers: version,
+                },
+            },
+            error: undefined,
+        };
+    }
+}

package/src/modules/graphs.ts

@@ -21,6 +21,7 @@ export class GraphsModule {
 
     /**
      * Validate a graph specification.
+     * Uses canonical GraphValidator for deep validation.
      */
     async validate(body: {
         graph_spec: {
@@ -28,6 +29,12 @@ export class GraphsModule {
             nodes: Array<{ id: string; type: string; label?: string }>;
             edges: Array<{ from: string; to: string }>;
         };
+        /** Catalog versions for referential integrity checks */
+        catalog_versions?: {
+            nodes: string;
+            tools: string;
+            triggers: string;
+        };
     }): Promise<APIResponse<GraphValidationResult>> {
         return this.client.POST<GraphValidationResult>("/v1/api/graphs/validate", {
             body,