@agent-os-sdk/client 0.5.0 → 0.5.2

package/src/modules/agents.ts

@@ -28,8 +28,6 @@ export interface Agent {
     live_bundle_id?: string | null;
 }
 
-
-
 export interface AgentBundle extends AgentBundleSchema { }
 
 export interface ImportAgentResponse {
@@ -38,13 +36,6 @@ export interface ImportAgentResponse {
     versions_imported: number;
 }
 
-export interface ImportAgentResponse {
-    agent_id: string;
-    message: string;
-    versions_imported: number;
-}
-
-
 export interface AgentGraphResponse {
     mermaid?: string;
     json?: unknown;
@@ -58,10 +49,6 @@ export interface GraphValidationResponse {
 
 export type AgentListResponse = PaginatedResponse<Agent>;
 
-// Draft types
-export type AgentDraftResponse = components["schemas"]["AgentDraftResponse"];
-export type UpdateDraftGraphRequest = components["schemas"]["UpdateDraftGraphRequest"];
-
 export class AgentsModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
@@ -191,50 +178,7 @@ export class AgentsModule {
         });
     }
 
-    /**
-     * Get the draft graph for an agent (source of truth).
-     * Studio should use this instead of generating graphs locally.
-     * @param agentId The agent UUID
-     * @returns Draft response with graph_json and ETag for subsequent updates
-     */
-    async getDraftGraph(agentId: string): Promise<APIResponse<components["schemas"]["AgentDraftResponse"]>> {
-        return this.client.GET<components["schemas"]["AgentDraftResponse"]>("/v1/api/agents/{id}/draft/graph", {
-            params: { path: { id: agentId } },
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * Update the draft graph for an agent (autosave).
-     * @param agentId The agent UUID
-     * @param graph_json The graph specification
-     * @param expected_ticks The expected ticks for optimistic concurrency (from If-Match)
-     */
-    async updateDraftGraph(
-        agentId: string,
-        graph_json: Record<string, unknown>,
-        expected_ticks: number | null
-    ): Promise<APIResponse<components["schemas"]["AgentDraftResponse"]>> {
-        // Construct If-Match header 
-        // If expected_ticks is null, we don't send header (or send something else? Logic says If-Match required if strictly following docs)
-        // But docs say: "Requires If-Match header with ETag from previous GET/PUT".
-        // If client passes 0, we send "agentId:0".
-        // If client passes null, maybe it's a force overwrite or initial save? UseCase handles logic.
-        // We will strictly set If-Match if expected_ticks is number.
-
-        const headers = this.headers();
-        if (expected_ticks !== null && expected_ticks !== undefined) {
-            headers["If-Match"] = `"${agentId}:${expected_ticks}"`;
-        }
-
-        return this.client.PUT<components["schemas"]["AgentDraftResponse"]>("/v1/api/agents/{id}/draft/graph", {
-            params: { path: { id: agentId } },
-            body: {
-                graph_json
-            } as components["schemas"]["UpdateDraftGraphRequest"],
-            headers
-        });
-    }
+    // ======================== Publishing ========================
 
     /**
      * Publish a new version (bundle) of the agent.

package/src/modules/graphs.ts

@@ -1,62 +1,186 @@
 /**
- * Graphs Module - Validation and Introspection
+ * Graphs Module - V2 Graph Specification Management
+ * 
+ * Pure V2 contract - no legacy. All types namespaced with "Graphs" prefix.
  */
 
-import type { RawClient, APIResponse, components } from "../client/raw.js";
+import type { RawClient, APIResponse } from "../client/raw.js";
 
-export interface GraphValidationResult {
+// ============ Shared Types ============
+
+export interface GraphsValidationMessage {
+    code: string;
+    message: string;
+    path?: string;
+    node_id?: string;
+    severity?: "error" | "warning";
+}
+
+export interface GraphsValidationResult {
     valid: boolean;
-    errors?: string[];
-    warnings?: string[];
+    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;
+    proposed_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 GraphIntrospectionResult {
-    nodes: Array<{ id: string; type: string; label?: string }>;
-    edges: Array<{ from: string; to: string }>;
-    entrypoints?: string[];
+export interface GraphsIntrospectResponse {
+    mermaid: string;
+    nodes: string[];
+    edges: [string, string][];
+    graph_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>(`/v2/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>("/v2/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>(`/v2/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>(`/v2/api/graph/${agentId}/revisions/${revision}`, {
+            headers: this.headers(),
+        });
+    }
+
+    // ============ Validation (DP proxy) ============
+
     /**
      * Validate a graph specification.
-     * Uses canonical GraphValidator for deep validation.
      */
-    async validate(body: {
-        graph_spec: {
-            type: string;
-            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", {
+    async validate(body: GraphsValidateRequest): Promise<APIResponse<GraphsValidateResponse>> {
+        return this.client.POST<GraphsValidateResponse>("/v1/api/graphs/validate", {
             body,
             headers: this.headers(),
         });
     }
 
     /**
-     * Introspect a graph to get its structure.
-     * Uses canonical GraphValidator with world-fixed context.
+     * Introspect a graph structure.
      */
-    async introspect(body: {
-        agent_id?: string;
-        graph_spec?: Record<string, unknown>;
-        /** Catalog versions for deterministic introspection */
-        catalog_versions?: {
-            nodes: string;
-            tools: string;
-            triggers: string;
-        };
-    }): Promise<APIResponse<GraphIntrospectionResult>> {
-        return this.client.POST<GraphIntrospectionResult>("/v1/api/graphs/introspect", {
+    async introspect(body: GraphsIntrospectRequest): Promise<APIResponse<GraphsIntrospectResponse>> {
+        return this.client.POST<GraphsIntrospectResponse>("/v1/api/graphs/introspect", {
             body,
             headers: this.headers(),
         });