@agent-os-sdk/client 0.9.14 → 0.9.16

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

package/src/modules/graphs.ts

@@ -1,188 +0,0 @@
-/**
- * Graphs Module - V2 Graph Specification Management
- * 
- * Pure V2 contract - no legacy. All types namespaced with "Graphs" prefix.
- */
-
-import type { RawClient, APIResponse } from "../client/raw.js";
-
-// ============ Shared Types ============
-
-export interface GraphsValidationMessage {
-    code: string;
-    message: string;
-    path?: string;
-    node_id?: string;
-    severity?: "error" | "warning";
-}
-
-export interface GraphsValidationResult {
-    valid: boolean;
-    errors?: GraphsValidationMessage[];
-}
-
-// ============ GET /v2/api/graph/{agentId} ============
-
-export interface GraphsGetResponse {
-    agent_id: string;
-    revision: string;
-    canonical_spec: unknown;
-    committed_at: string;
-    warnings?: GraphsValidationMessage[];
-    validation?: GraphsValidationResult;
-}
-
-// ============ POST /v2/api/graph/commit ============
-
-export interface GraphsCommitRequest {
-    agent_id: string;
-    graph_spec: unknown;
-    expected_revision?: string;
-    source?: string;
-}
-
-export type GraphsCommitStatus = "committed" | "no_change";
-
-export interface GraphsCommitResponse {
-    status: GraphsCommitStatus;
-    agent_id: string;
-    revision: string;
-    canonical_spec: unknown;
-    committed_at: string;
-    warnings?: GraphsValidationMessage[];
-    validation?: GraphsValidationResult;
-}
-
-// 409 Conflict body (ProblemDetails.Extensions)
-// Envelope around GET response - agent_id lives in current.agent_id
-export interface GraphsConflictPayload {
-    hint: "reload_and_retry";
-    expected_revision: string;
-    current: GraphsGetResponse;
-}
-
-// ============ GET /v2/api/graph/{agentId}/revisions ============
-
-export interface GraphsRevisionSummary {
-    revision: string;
-    created_at: string;
-    source?: string;
-}
-
-export interface GraphsRevisionsListResponse {
-    agent_id: string;
-    revisions: GraphsRevisionSummary[];
-}
-
-// ============ GET /v2/api/graph/{agentId}/revisions/{revision} ============
-
-export interface GraphsRevisionResponse {
-    revision: string;
-    canonical_spec: unknown;
-    created_at: string;
-    source?: string;
-    warnings?: GraphsValidationMessage[];
-    validation?: GraphsValidationResult;
-}
-
-// ============ Validation (DP) ============
-
-export interface GraphsValidateRequest {
-    graph_spec: unknown;
-    normalize?: boolean;
-    catalog_versions?: Record<string, string>;
-}
-
-export interface GraphsValidateResponse {
-    valid: boolean;
-    canonical_spec_json?: string;
-    mermaid?: string;
-    nodes?: string[];
-    edges?: [string, string][];
-    errors?: GraphsValidationMessage[];
-    warnings?: GraphsValidationMessage[];
-}
-
-// ============ Introspection (DP) ============
-
-export interface GraphsIntrospectRequest {
-    agent_id?: string;
-    graph_spec?: unknown;
-    catalog_versions?: Record<string, string>;
-}
-
-export interface GraphsIntrospectResponse {
-    mermaid: string;
-    nodes: string[];
-    edges: [string, string][];
-    type?: string;
-}
-
-// ============ Module ============
-
-export class GraphsModule {
-    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
-
-    // ============ V2 Graph Spec (CP) ============
-
-    /**
-     * Get current graph spec by revision.
-     * @returns 200 with graph spec, or 404 if not initialized
-     */
-    async get(agentId: string): Promise<APIResponse<GraphsGetResponse>> {
-        return this.client.GET<GraphsGetResponse>(`/v1/api/graph/${agentId}`, {
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * Commit graph spec atomically.
-     * @returns 200 (committed/no_change), or 409 on conflict
-     */
-    async commit(request: GraphsCommitRequest): Promise<APIResponse<GraphsCommitResponse>> {
-        return this.client.POST<GraphsCommitResponse>("/v1/api/graph/commit", {
-            body: request,
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * List revision history for an agent.
-     */
-    async listRevisions(agentId: string): Promise<APIResponse<GraphsRevisionsListResponse>> {
-        return this.client.GET<GraphsRevisionsListResponse>(`/v1/api/graph/${agentId}/revisions`, {
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * Get a specific revision.
-     */
-    async getRevision(agentId: string, revision: string): Promise<APIResponse<GraphsRevisionResponse>> {
-        return this.client.GET<GraphsRevisionResponse>(`/v1/api/graph/${agentId}/revisions/${revision}`, {
-            headers: this.headers(),
-        });
-    }
-
-    // ============ Validation (DP proxy) ============
-
-    /**
-     * Validate a graph specification.
-     */
-    async validate(body: GraphsValidateRequest): Promise<APIResponse<GraphsValidateResponse>> {
-        return this.client.POST<GraphsValidateResponse>("/v1/api/graphs/validate", {
-            body,
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * Introspect a graph structure.
-     */
-    async introspect(body: GraphsIntrospectRequest): Promise<APIResponse<GraphsIntrospectResponse>> {
-        return this.client.POST<GraphsIntrospectResponse>("/v1/api/graphs/introspect", {
-            body,
-            headers: this.headers(),
-        });
-    }
-}