@agent-os-sdk/client 0.9.14 → 0.9.15

package/src/modules/runs.ts

@@ -82,6 +82,9 @@ export interface RunEventDto {
     timestamp: string;
     attempt_id: string;
     payload: Record<string, unknown> | null;
+    operation_id: string;
+    parent_operation_id?: string | null;
+    root_operation_id: string;
 }
 
 export class RunsModule {
@@ -645,12 +648,15 @@ export interface FollowEvent {
     seq: number;
     timestamp: string;
     payload?: Record<string, unknown> | null;
+    operation_id?: string;
+    parent_operation_id?: string | null;
+    root_operation_id?: string;
     /** For run_event: the node that emitted this event */
     node?: string;
 }
 
 /** Narrow raw SSE event to FollowEvent */
-function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
+export function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
     const eventType = raw.event ?? "message";
     const validTypes = ["run_event", "heartbeat", "close", "error"];
 
@@ -668,6 +674,13 @@ function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
         const innerPayload = (typeof data.payload === "object" && data.payload !== null)
             ? (data.payload as Record<string, unknown>)
             : null;
+        const operationId = typeof data.operation_id === "string" ? data.operation_id : undefined;
+        const parentOperationId = typeof data.parent_operation_id === "string"
+            ? data.parent_operation_id
+            : data.parent_operation_id === null
+                ? null
+                : undefined;
+        const rootOperationId = typeof data.root_operation_id === "string" ? data.root_operation_id : undefined;
 
         return {
             type: "run_event",
@@ -677,7 +690,13 @@ function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
                 ...(innerPayload ?? {}),
                 type: typeof data.type === "string" ? data.type : "UNKNOWN",
                 attempt_id: typeof data.attempt_id === "string" ? data.attempt_id : undefined,
+                operation_id: operationId,
+                parent_operation_id: parentOperationId,
+                root_operation_id: rootOperationId,
             },
+            operation_id: operationId,
+            parent_operation_id: parentOperationId,
+            root_operation_id: rootOperationId,
             node: typeof innerPayload?.node === "string" ? innerPayload.node : undefined,
         };
     }

package/src/modules/templates.ts

@@ -0,0 +1,40 @@
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export interface AuthoringTemplateSummary {
+    template_ref: string;
+    version: string;
+    display_name: string;
+    description?: string | null;
+    template_kind: string;
+    category: string;
+    editability_mode: string;
+    required_capability_refs: string[];
+    default_policy_refs?: Record<string, unknown> | null;
+    default_runtime_config_refs?: Record<string, unknown> | null;
+}
+
+export interface AuthoringTemplateDetail extends AuthoringTemplateSummary {
+    base_agent_ir: Record<string, unknown>;
+}
+
+export interface AuthoringTemplateListResponse {
+    items: AuthoringTemplateSummary[];
+    total: number;
+}
+
+export class TemplatesModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) {}
+
+    async list(): Promise<APIResponse<AuthoringTemplateListResponse>> {
+        return this.client.GET<AuthoringTemplateListResponse>("/v1/api/templates", {
+            headers: this.headers(),
+        });
+    }
+
+    async get(templateRef: string): Promise<APIResponse<AuthoringTemplateDetail>> {
+        return this.client.GET<AuthoringTemplateDetail>("/v1/api/templates/{templateRef}", {
+            params: { path: { templateRef } },
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/builder.ts

@@ -1,456 +0,0 @@
-/**
- * Builder Module - Meta-Agent for Agent Building
- * 
- * Connects to the Control Plane's builder endpoint which proxies to the
- * Data Plane's meta-agent for AI-assisted agent creation.
- * Uses SSE streaming for real-time responses and graph updates.
- * 
- * 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({ ... })
- * 
- * // SSE streaming chat
- * for await (const event of client.builder.chat(agentId, {
- *   message: "Adicione um nó de pesquisa web",
- *   current_graph_spec: { nodes: [...], edges: [...] }
- * })) {
- *   if (event.type === 'message') console.log(event.data.text)
- *   if (event.type === 'graph_update') applyAction(event.data)
- * }
- * 
- * // Sync chat (no streaming)
- * const result = await client.builder.chatSync(agentId, { message: "Mude as instruções" })
- * ```
- */
-
-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 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;
-    /** Thread ID for conversation continuity */
-    thread_id?: string;
-    /** Chat history for context (optional, sent from frontend) */
-    history?: { role: 'user' | 'assistant'; content: 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 = {
-    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: { 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;
-    graph_spec?: Record<string, unknown>;
-    valid: boolean;
-    errors: any[];
-    thread_id: string;
-    hints: HintModel[];
-};
-
-// ============================================
-// PATCH-OPS ARCHITECTURE (Meta-Agent V2)
-// ============================================
-
-/** Supported patch operation types */
-export type OpType =
-    | "add_node"
-    | "remove_node"
-    | "update_node"
-    | "add_edge"
-    | "remove_edge"
-    | "set_entrypoint"
-    | "rename_node";
-
-/** A single graph modification operation */
-export type PatchOp = {
-    op: OpType;
-    node_id?: string;
-    kind?: string;
-    label?: string;
-    data?: Record<string, unknown>;
-    set?: Record<string, unknown>;
-    from?: string;
-    to?: string;
-    entrypoint?: string;
-};
-
-/** A collection of patch operations with deterministic ID */
-export type GraphPatch = {
-    patch_id: string;
-    ops: PatchOp[];
-    description?: string;
-};
-
-/** Validation error from applying patch */
-export type PatchValidationError = {
-    code: string;
-    message: string;
-    node_id?: string;
-    path?: string;
-};
-
-/** Meta-chat request */
-export type MetaChatRequest = {
-    instruction: string;
-};
-
-/** Meta-chat stream events */
-export type MetaChatStreamEvent =
-    | { type: "assistant.delta"; data: { text: string } }
-    | { type: "patch.validation"; data: { valid: boolean; errors: PatchValidationError[] } }
-    | { type: "patch.proposed"; data: GraphPatch }
-    | { type: "final"; data: { ok: boolean; patch_id: string } }
-    | { type: "error"; data: { error: string } };
-
-/** Meta-chat sync response */
-export type MetaChatResponse = {
-    patch: GraphPatch | null;
-    applied_spec: Record<string, unknown> | null;
-    valid: boolean;
-    errors: PatchValidationError[];
-    message: string;
-};
-
-
-export class BuilderModule {
-    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 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) {
-            const errorText = await response.text();
-            throw new Error(`Builder chat failed: ${response.status} - ${errorText}`);
-        }
-
-        if (!response.body) {
-            throw new Error("No response body");
-        }
-
-        options?.onOpen?.();
-
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-
-        try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done) break;
-
-                buffer += decoder.decode(value, { stream: true });
-                const lines = buffer.split("\n");
-                buffer = lines.pop() ?? "";
-
-                let eventType = "message";
-                let eventData = "";
-
-                for (const line of lines) {
-                    if (line.startsWith("event:")) {
-                        eventType = line.slice(6).trim();
-                    } else if (line.startsWith("data:")) {
-                        eventData = line.slice(5).trim();
-                    } else if (line === "" && eventData) {
-                        try {
-                            const parsed = JSON.parse(eventData);
-                            yield { type: eventType, data: parsed } as BuilderStreamEvent;
-                        } catch {
-                            // Skip invalid JSON
-                        }
-                        eventData = "";
-                        eventType = "message";
-                    }
-                }
-            }
-        } finally {
-            reader.releaseLock();
-        }
-    }
-
-    /**
-     * Sync chat with meta-agent (no streaming).
-     * 
-     * Uses rawClient.POST() - headers resolved asynchronously.
-     */
-    async chatSync(
-        agentId: string,
-        request: BuilderChatRequest
-    ): Promise<BuilderChatResponse> {
-        const { data, error } = await this.client.POST<BuilderChatResponse>(
-            "/v1/api/builder/{agentId}/chat/sync",
-            {
-                params: { path: { agentId } },
-                body: request,
-            }
-        );
-
-        if (error) {
-            throw new Error(`Builder chat failed: ${error.code} - ${error.message}`);
-        }
-
-        return data!;
-    }
-
-    /**
-     * Convenience method: chat and collect all events.
-     */
-    async chatCollect(
-        agentId: string,
-        request: BuilderChatRequest
-    ): Promise<BuilderChatResponse> {
-        let fullResponse = "";
-        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") {
-                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;
-            }
-        }
-
-        return {
-            response: fullResponse,
-            graph_spec: lastGraphSpec,
-            hints: allHints,
-            valid: isValid,
-            errors: allErrors,
-            thread_id: threadId,
-        };
-    }
-
-    // ============================================
-    // META-CHAT V2 (PATCH-OPS ARCHITECTURE)
-    // ============================================
-
-    /**
-     * Stream meta-chat with patch-ops architecture (SSE).
-     * Returns GraphPatch proposals instead of full graph specs.
-     * 
-     * @example
-     * ```ts
-     * for await (const event of client.builder.metaChat(agentId, {
-     *   instruction: "Add a log node after the main agent"
-     * })) {
-     *   if (event.type === 'patch.proposed') {
-     *     const patch = event.data;
-     *     console.log(`Proposed ${patch.ops.length} operations`);
-     *   }
-     * }
-     * ```
-     */
-    async *metaChat(
-        agentId: string,
-        request: MetaChatRequest,
-        options?: SSEOptions
-    ): AsyncGenerator<MetaChatStreamEvent> {
-        const response = await this.client.streamPost("/v1/builder/{agentId}/meta-chat", {
-            params: { path: { agentId } },
-            body: request,
-            signal: options?.signal,
-        });
-
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Meta-chat failed: ${response.status} - ${errorText}`);
-        }
-
-        if (!response.body) {
-            throw new Error("No response body");
-        }
-
-        options?.onOpen?.();
-
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-
-        try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done) break;
-
-                buffer += decoder.decode(value, { stream: true });
-                const lines = buffer.split("\n");
-                buffer = lines.pop() ?? "";
-
-                let eventType = "message";
-                let eventData = "";
-
-                for (const line of lines) {
-                    if (line.startsWith("event:")) {
-                        eventType = line.slice(6).trim();
-                    } else if (line.startsWith("data:")) {
-                        eventData = line.slice(5).trim();
-                    } else if (line === "" && eventData) {
-                        try {
-                            const parsed = JSON.parse(eventData);
-                            yield { type: eventType, data: parsed } as MetaChatStreamEvent;
-                        } catch {
-                            // Skip invalid JSON
-                        }
-                        eventData = "";
-                        eventType = "message";
-                    }
-                }
-            }
-        } finally {
-            reader.releaseLock();
-        }
-    }
-
-    /**
-     * Meta-chat and collect the proposed patch.
-     */
-    async metaChatCollect(
-        agentId: string,
-        request: MetaChatRequest
-    ): Promise<MetaChatResponse> {
-        let patch: GraphPatch | null = null;
-        let isValid = true;
-        const errors: PatchValidationError[] = [];
-        let message = "";
-
-        for await (const event of this.metaChat(agentId, request)) {
-            if (event.type === "assistant.delta") {
-                message += event.data.text;
-            } else if (event.type === "patch.proposed") {
-                patch = event.data;
-            } else if (event.type === "patch.validation") {
-                isValid = event.data.valid;
-                errors.push(...event.data.errors);
-            }
-        }
-
-        return {
-            patch,
-            applied_spec: null,  // Frontend should apply patch locally
-            valid: isValid,
-            errors,
-            message,
-        };
-    }
-}