@agent-os-sdk/client 0.4.1 → 0.4.3

package/src/index.ts

@@ -114,8 +114,8 @@ export type { components, paths } from "./client/raw.js";
 // ============================================================================
 
 // Core modules
-export { AgentsModule, type Agent, type AgentGraphResponse, type AgentListResponse, type AgentVersion } from "./modules/agents.js";
-export { BuilderModule, type BuilderChatRequest, type BuilderChatResponse, type BuilderStreamEvent, type GraphUpdateAction } from "./modules/builder.js";
+export { AgentsModule, type Agent, type AgentGraphResponse, type AgentListResponse } from "./modules/agents.js";
+export { BuilderModule, type BuilderChatRequest, type BuilderChatResponse, type BuilderStreamEvent, type GraphUpdateAction, type HintModel, type HintTargetModel, type HintDataModel } from "./modules/builder.js";
 export { CredentialsModule, type Credential, type CredentialListResponse, type CredentialType } from "./modules/credentials.js";
 export { KnowledgeModule, type KnowledgeDataset, type KnowledgeSearchResponse } from "./modules/knowledge.js";
 export { MembersModule, type Member, type MemberListResponse, type Role } from "./modules/members.js";
@@ -168,7 +168,7 @@ export type {
     CancelRunResponse,
     // Checkpoint types
     CheckpointDetail,
-    CheckpointListResponse, CreateAgentRequest, CreateAgentVersionRequest,
+    CheckpointListResponse, CreateAgentRequest,
     // Credential types
     CreateCredentialRequest,
     // Cron types

package/src/modules/agents.ts

@@ -11,7 +11,7 @@ import type { RawClient, APIResponse, components } from "../client/raw.js";
 import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
 
 // Type aliases for this module
-type AgentSchema = components["schemas"]["AgentBundleAgent"];
+type AgentSchema = components["schemas"]["AgentExportAgent"];
 // Response types
 export interface Agent {
     id: string;

package/src/modules/builder.ts

@@ -41,37 +41,105 @@ export type ChatHistoryMessage = {
     content: string;
 };
 
+/**
+ * Builder chat request.
+ * 
+ * KERNEL-FIRST: Frontend sends INTENTION only.
+ * - Graph spec is loaded from artifact storage by CP
+ * - Catalogs are loaded from DB by CP
+ * - Frontend should NOT send graph_spec or catalogs
+ */
 export type BuilderChatRequest = {
+    /** Chat message/intention */
     message: string;
-    current_graph_spec?: Record<string, unknown>;
+    /** Thread ID for conversation continuity */
     thread_id?: string;
-    /** Previous conversation history for context */
-    history?: ChatHistoryMessage[];
-    /** Catalog versions to use for validation */
-    catalog_versions?: CatalogVersions;
-    /** Combined hash of all catalogs for integrity */
-    catalog_ref?: string;
+    /** Optional ETag for concurrency control */
+    base_graph_etag?: string;
+};
+
+export type HintTargetModel = {
+    node_id?: string;
+    edge_id?: string;
+    panel?: "credentials" | "triggers" | "logs" | "validation" | "deploy" | string;
+    action?: "create_credential" | "save_draft" | "publish_version" | string;
+};
+
+export type HintDataModel = {
+    // Credential hints
+    credential_slug?: string;
+    reason?: string;
+
+    // Config hints
+    fields?: string[];
+
+    // Error/validation hints
+    code?: string;
+    path?: string;
+
+    // Run/execution hints
+    run_id?: string;
+    error_code?: string;
+
+    // Cost/performance hints
+    tokens_in?: number;
+    tokens_out?: number;
+    usd_estimate?: number;
+
+    // Action hints
+    action_id?: string;
+    params?: Record<string, any>;
+};
+
+export type HintModel = {
+    id?: string;
+    scope: "graph" | "thread" | "run" | string;
+    type:
+    | "highlight_node"
+    | "needs_credential"
+    | "missing_config"
+    | "error_marker"
+    | "warning_marker"
+    | "toast"
+    | "run_started"
+    | "node_running"
+    | "node_failed"
+    | "rate_limited"
+    | "cost_estimate"
+    | "action_suggested"
+    | string;
+    severity: "info" | "warn" | "error" | "success";
+    target?: HintTargetModel;
+    message?: string;
+    ttl_ms?: number;
+    data?: HintDataModel;
 };
 
 export type GraphUpdateAction = {
+    // Legacy support
     action: string;
-    node_name?: string;
-    node_type?: string;
-    properties?: Record<string, unknown>;
-    edge_from?: string;
-    edge_to?: string;
+    // ... legacy fields omitted for brevity, keeping strict new protocol
+} | {
+    // New protocol (WAVE-3)
+    graph_spec: Record<string, unknown>;
+    hints?: HintModel[];
+    has_errors?: boolean;
 };
 
 export type BuilderStreamEvent =
     | { type: "message"; data: { text: string } }
-    | { type: "graph_update"; data: GraphUpdateAction }
-    | { type: "done"; data: { response: string; actions: GraphUpdateAction[]; thread_id: string } }
+    | { type: "validation"; data: { valid: boolean; errors: any[] } }
+    | { type: "graph_update"; data: { graph_spec: Record<string, unknown>; hints: HintModel[]; has_errors?: boolean } }
+    | { type: "done"; data: { response: string; thread_id: string } }
     | { type: "error"; data: { error: string } };
 
 export type BuilderChatResponse = {
     response: string;
-    actions: GraphUpdateAction[];
+    graph_spec?: Record<string, unknown>;
+    valid: boolean;
+    errors: any[];
     thread_id: string;
+    hints: HintModel[];
 };
 
 export class BuilderModule {
@@ -176,14 +244,27 @@ export class BuilderModule {
         request: BuilderChatRequest
     ): Promise<BuilderChatResponse> {
         let fullResponse = "";
-        const allActions: GraphUpdateAction[] = [];
+        let lastGraphSpec: Record<string, unknown> | undefined;
+        let allHints: HintModel[] = [];
+        const allErrors: any[] = [];
         let threadId = request.thread_id ?? "";
+        let isValid = true;
 
         for await (const event of this.chat(agentId, request)) {
             if (event.type === "message") {
                 fullResponse += event.data.text;
             } else if (event.type === "graph_update") {
-                allActions.push(event.data);
+                if ('graph_spec' in event.data) {
+                    lastGraphSpec = event.data.graph_spec;
+                    if (event.data.hints) {
+                        allHints.push(...event.data.hints);
+                    }
+                }
+            } else if (event.type === "validation") {
+                isValid = event.data.valid;
+                if (event.data.errors) {
+                    allErrors.push(...event.data.errors);
+                }
             } else if (event.type === "done") {
                 threadId = event.data.thread_id;
             }
@@ -191,7 +272,10 @@ export class BuilderModule {
 
         return {
             response: fullResponse,
-            actions: allActions,
+            graph_spec: lastGraphSpec,
+            hints: allHints,
+            valid: isValid,
+            errors: allErrors,
             thread_id: threadId,
         };
     }