@agent-os-sdk/client 0.4.1 → 0.4.2

package/README.md

@@ -64,6 +64,66 @@ await api.runs.resume(runId, { approved: true });
 | `triggers` | Webhooks, crons |
 | `credentials` | BYOK secrets |
 
+## Hints (hints.v1) — o que são
+
+**Hints** são um **side-channel** de UX: o DP/meta-agent **sugere** ações/atenções visuais, o **CP repassa** (sem virar fonte de verdade), e o **Frontend anima** (glow, badge, shake, toast etc).
+Eles **não alteram** `graph_spec` e não são “estado do sistema” — são **sugestões descartáveis**.
+
+### Onde aparecem
+
+Hoje, no builder do meta-agent, eles saem **junto do update do grafo**:
+
+* **SSE event**: `graph_update`
+  Payload inclui `graph_spec` e `hints`.
+
+E também existem no modelo de retorno não-streaming (`ChatResponse.hints`), se você usar o caminho sync.
+
+**Regra kernel**: `Content-Type: text/event-stream` só depois de validações; hints são dados normais dentro do JSON do evento.
+
+### Estrutura rápida do HintModel
+
+Campos principais:
+
+* `type` *(string)*: um dos 12 tipos canônicos
+* `severity` *(info|warn|error|success)*
+* `scope` *(graph|thread|run)* — onde isso “vive”
+* `target` *(opcional)*: `{ node_id?, edge_id?, panel?, action? }`
+* `message` *(opcional)*: texto curto pra UI
+* `ttl_ms` *(opcional)*: tempo pra auto-dismiss
+* `id` *(opcional)*: fingerprint pra dedupe
+* `data` *(opcional)*: payload pequeno (ex.: `code`, `path`, `credential_slug`, `fields`…)
+
+### Como usar (frontend)
+
+Fluxo recomendado:
+
+1. Consumir evento `graph_update`
+2. Ler `payload.hints[]`
+3. Para cada hint, despachar por `hint.type`
+4. Aplicar animação/efeito no alvo (`hint.target`) e opcionalmente mostrar mensagem (`hint.message`)
+5. Respeitar `ttl_ms` quando existir (auto-remover/auto-dismiss)
+
+### Mini exemplo
+
+```json
+event: graph_update
+data: {
+  "type": "graph_update",
+  "graph_spec": { "...": "..." },
+  "hints": [
+    {
+      "type": "error_marker",
+      "id": "error:node_1:UNKNOWN_TOOL:/nodes/3/config/tool",
+      "scope": "graph",
+      "severity": "error",
+      "target": { "node_id": "node_1" },
+      "message": "Unknown tool slug",
+      "data": { "code": "UNKNOWN_TOOL", "path": "/nodes/3/config/tool" }
+    }
+  ]
+}
+```
+
 ## Rule
 
 > ❌ **NEVER** use `fetch`, `axios`, or `ky` in frontend.

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export { collectAll, getFirst, paginate, type CursorPaginatedResponse, type Curs
 export { createRawClient, createTypedClient, type APIResponse, type ClientOptions, type HookErrorContext, type HookRequestContext, type HookResponseContext, type RawClient, type SDKHooks, type TypedClient } from "./client/raw.js";
 export type { components, paths } from "./client/raw.js";
 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 { 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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/modules/builder.d.ts

@@ -37,38 +37,81 @@ export type ChatHistoryMessage = {
     role: 'user' | 'assistant';
     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_slug?: string;
+    reason?: string;
+    fields?: string[];
+    code?: string;
+    path?: string;
+    run_id?: string;
+    error_code?: string;
+    tokens_in?: number;
+    tokens_out?: number;
+    usd_estimate?: number;
+    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 = {
     action: string;
-    node_name?: string;
-    node_type?: string;
-    properties?: Record<string, unknown>;
-    edge_from?: string;
-    edge_to?: string;
+} | {
+    graph_spec: Record<string, unknown>;
+    hints?: HintModel[];
+    has_errors?: boolean;
 };
 export type BuilderStreamEvent = {
     type: "message";
     data: {
         text: string;
     };
+} | {
+    type: "validation";
+    data: {
+        valid: boolean;
+        errors: any[];
+    };
 } | {
     type: "graph_update";
-    data: GraphUpdateAction;
+    data: {
+        graph_spec: Record<string, unknown>;
+        hints: HintModel[];
+        has_errors?: boolean;
+    };
 } | {
     type: "done";
     data: {
         response: string;
-        actions: GraphUpdateAction[];
         thread_id: string;
     };
 } | {
@@ -79,8 +122,11 @@ export type BuilderStreamEvent = {
 };
 export type BuilderChatResponse = {
     response: string;
-    actions: GraphUpdateAction[];
+    graph_spec?: Record<string, unknown>;
+    valid: boolean;
+    errors: any[];
     thread_id: string;
+    hints: HintModel[];
 };
 export declare class BuilderModule {
     private client;

package/dist/modules/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/modules/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC7B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GACxB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,iBAAiB,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC7F;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,qBAAa,aAAa;IACV,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;;;;OAKG;IACI,IAAI,CACP,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,UAAU,GACrB,cAAc,CAAC,kBAAkB,CAAC;IAyDrC;;;;OAIG;IACG,QAAQ,CACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,GAC5B,OAAO,CAAC,mBAAmB,CAAC;IAgB/B;;OAEG;IACG,WAAW,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,GAC5B,OAAO,CAAC,mBAAmB,CAAC;CAqBlC"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/modules/builder.ts"],"names":[],"mappings":"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"}

package/dist/modules/builder.js

@@ -110,14 +110,28 @@ export class BuilderModule {
      */
     async chatCollect(agentId, request) {
         let fullResponse = "";
-        const allActions = [];
+        let lastGraphSpec;
+        let allHints = [];
+        const allErrors = [];
         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;
@@ -125,7 +139,10 @@ export class BuilderModule {
         }
         return {
             response: fullResponse,
-            actions: allActions,
+            graph_spec: lastGraphSpec,
+            hints: allHints,
+            valid: isValid,
+            errors: allErrors,
             thread_id: threadId,
         };
     }

package/package.json

@@ -1,51 +1,52 @@
 {
-  "name": "@agent-os-sdk/client",
-  "version": "0.4.1",
-  "description": "Official TypeScript SDK for Agent OS platform",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "keywords": [
-    "agent-os",
-    "sdk",
-    "ai",
-    "agents",
-    "typescript"
-  ],
-  "author": "Agent OS Team",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/yuri12344/agent-os.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "openapi-fetch": "^0.13.0"
-  },
-  "devDependencies": {
-    "openapi-typescript": "^7.4.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.0",
-    "vitest": "^4.0.18"
-  },
-  "files": [
-    "dist",
-    "src"
-  ],
-  "scripts": {
-    "generate": "tsx scripts/generate.ts",
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  }
+    "name": "@agent-os-sdk/client",
+    "version": "0.4.2",
+    "description": "Official TypeScript SDK for Agent OS platform",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "generate": "tsx scripts/generate.ts",
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "test": "vitest run",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "pnpm build"
+    },
+    "keywords": [
+        "agent-os",
+        "sdk",
+        "ai",
+        "agents",
+        "typescript"
+    ],
+    "author": "Agent OS Team",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/yuri12344/agent-os.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "openapi-fetch": "^0.13.0"
+    },
+    "devDependencies": {
+        "openapi-typescript": "^7.4.0",
+        "tsx": "^4.19.0",
+        "typescript": "^5.5.0",
+        "vitest": "^4.0.18"
+    },
+    "files": [
+        "dist",
+        "src"
+    ]
 }

package/src/index.ts

@@ -115,7 +115,7 @@ 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 { 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";

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,
         };
     }