feat: sync-first API, typed models, CursorPage auto-pagination, and client.async()

Refactor AgentStudio SDK to follow sync-first convention: default methods
return T directly, *Async() variants return CompletableFuture<T>. Add typed
model configs (Configs.ModelConfig, ToolConfig), CursorPage Iterable support
for auto-pagination, client.async() helper, and comprehensive unit tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: foleydang

src/main/java/com/alibaba/dashscope/agentstudio/AgentStudioClient.java

@@ -8,11 +8,8 @@
 import com.alibaba.dashscope.agentstudio.resource.Skills;
 import com.alibaba.dashscope.agentstudio.resource.Vaults;
 import com.alibaba.dashscope.protocol.ConnectionOptions;
-import com.alibaba.dashscope.utils.Constants;
 import java.io.Closeable;
 import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.ForkJoinPool;
 import java.util.function.Supplier;
 
 public class AgentStudioClient implements Closeable {
@@ -23,61 +20,34 @@ public class AgentStudioClient implements Closeable {
   private final Vaults vaults;
   private final Files files;
   private final String baseUrl;
-  private final ExecutorService asyncExecutor;
 
-  /** All from env vars: DASHSCOPE_API_KEY, DASHSCOPE_WORKSPACE, DASHSCOPE_API_REGION. */
   public AgentStudioClient() {
     this(null, null, null, null, null);
   }
 
-  /**
-   * Workspace only, apiKey from DASHSCOPE_API_KEY env var.
-   *
-   * @param workspace workspace ID (required)
-   */
   public AgentStudioClient(String workspace) {
     this(null, null, workspace, null, null);
   }
 
-  /**
-   * Most common: apiKey + workspace for production.
-   *
-   * @param apiKey API Key (or set DASHSCOPE_API_KEY env var)
-   * @param workspace workspace ID (required)
-   */
   public AgentStudioClient(String apiKey, String workspace) {
     this(apiKey, null, workspace, null, null);
   }
 
-  /**
-   * Full constructor — prefer {@link #builder()} for readability.
-   *
-   * @param apiKey API Key (nullable → read from DASHSCOPE_API_KEY)
-   * @param baseUrl full base URL (nullable → use workspace + region)
-   * @param workspace workspace ID (required if baseUrl is null)
-   * @param region region (nullable → default cn-beijing)
-   * @param connectionOptions timeout / retry config (nullable)
-   */
   public AgentStudioClient(
       String apiKey,
       String baseUrl,
       String workspace,
       String region,
       ConnectionOptions connectionOptions) {
-    if (apiKey != null && !apiKey.isEmpty()) {
-      Constants.apiKey = apiKey;
-    }
     this.baseUrl = resolveBaseUrl(baseUrl, workspace, region);
-    this.agents = new Agents(this.baseUrl, connectionOptions);
-    this.sessions = new Sessions(this.baseUrl, connectionOptions);
-    this.environments = new Environments(this.baseUrl, connectionOptions);
-    this.skills = new Skills(this.baseUrl, connectionOptions);
-    this.vaults = new Vaults(this.baseUrl, connectionOptions);
-    this.files = new Files(this.baseUrl, connectionOptions);
-    this.asyncExecutor = ForkJoinPool.commonPool();
+    this.agents = new Agents(this.baseUrl, connectionOptions, apiKey);
+    this.sessions = new Sessions(this.baseUrl, connectionOptions, apiKey);
+    this.environments = new Environments(this.baseUrl, connectionOptions, apiKey);
+    this.files = new Files(this.baseUrl, connectionOptions, apiKey);
+    this.skills = new Skills(this.baseUrl, connectionOptions, apiKey, this.files);
+    this.vaults = new Vaults(this.baseUrl, connectionOptions, apiKey);
   }
 
-  /** Builder for advanced use cases (pre-env baseUrl, custom region, etc.). */
   public static Builder builder() {
     return new Builder();
   }
@@ -147,26 +117,15 @@ public String getBaseUrl() {
     return baseUrl;
   }
 
-  ExecutorService getAsyncExecutor() {
-    return asyncExecutor;
-  }
-
-  /**
-   * Run any sync SDK call asynchronously.
-   *
-   * <pre>{@code
-   * client.async(() -> client.agents().create(param))
-   *     .thenAccept(agent -> System.out.println(agent.getId()));
-   * }</pre>
-   */
   public <T> CompletableFuture<T> async(Supplier<T> supplier) {
-    return CompletableFuture.supplyAsync(supplier, asyncExecutor);
+    return CompletableFuture.supplyAsync(supplier);
   }
 
   @Override
   public void close() {
     sessions.events().close();
-    asyncExecutor.shutdownNow();
+    skills.close();
+    files.close();
   }
 
   private static String resolveBaseUrl(String explicitUrl, String workspace, String region) {
@@ -180,22 +139,6 @@ private static String resolveBaseUrl(String explicitUrl, String workspace, Strin
     if (envUrl != null && !envUrl.isEmpty()) {
       return envUrl;
     }
-    String ws = workspace;
-    if (ws == null || ws.isEmpty()) {
-      ws = System.getenv(AgentStudioConstants.ENV_WORKSPACE);
-    }
-    if (ws == null || ws.isEmpty()) {
-      throw new IllegalArgumentException(
-          "workspace is required. Pass it to the constructor, "
-              + "set DASHSCOPE_WORKSPACE env var, or set DASHSCOPE_AGENTSTUDIO_URL.");
-    }
-    String r = region;
-    if (r == null || r.isEmpty()) {
-      r = System.getenv(AgentStudioConstants.ENV_REGION);
-    }
-    if (r == null || r.isEmpty()) {
-      r = AgentStudioConstants.DEFAULT_REGION;
-    }
-    return String.format(AgentStudioConstants.BASE_URL_TEMPLATE, ws, r);
+    return AgentStudioConstants.resolveBaseUrl(workspace, region);
   }
 }

src/main/java/com/alibaba/dashscope/agentstudio/AgentStudioConstants.java

@@ -1,6 +1,14 @@
 // Copyright (c) Alibaba, Inc. and its affiliates.
 package com.alibaba.dashscope.agentstudio;
 
+import com.alibaba.dashscope.base.HalfDuplexParamBase;
+import com.alibaba.dashscope.protocol.GeneralServiceOption;
+import com.alibaba.dashscope.protocol.HttpMethod;
+import com.alibaba.dashscope.protocol.Protocol;
+import com.alibaba.dashscope.protocol.StreamingMode;
+import java.io.UnsupportedEncodingException;
+import java.net.URLEncoder;
+
 public final class AgentStudioConstants {
   public static final String BASE_URL_TEMPLATE =
       "https://%s.%s.maas.aliyuncs.com/api/v1/agentstudio";
@@ -13,4 +21,120 @@ public final class AgentStudioConstants {
   public static final String ENV_REGION = "DASHSCOPE_API_REGION";
 
   private AgentStudioConstants() {}
+
+  public static final class SSEEventType {
+    public static final String MESSAGE = "message";
+    public static final String INTERRUPT = "interrupt";
+    public static final String TOOL_CONFIRMATION = "tool_confirmation";
+    public static final String FUNCTION_CALL_OUTPUT = "function_call_output";
+    public static final String TOOL_CALL_OUTPUT = "tool_call_output";
+    public static final String DEFINE_OUTCOME = "define_outcome";
+    public static final String FUNCTION_CALL = "function_call";
+    public static final String TOOL_CALL = "tool_call";
+    public static final String REASONING = "reasoning";
+    public static final String MCP_CALL = "mcp_call";
+    public static final String MCP_CALL_OUTPUT = "mcp_call_output";
+    public static final String SESSION_STATUS = "session_status";
+    public static final String ERROR = "error";
+    public static final String SESSION_UPDATED = "session_updated";
+    public static final String OUTCOME_EVALUATION = "outcome_evaluation";
+
+    private SSEEventType() {}
+  }
+
+  public static final class MessageRole {
+    public static final String USER = "user";
+    public static final String ASSISTANT = "assistant";
+    public static final String TOOL = "tool";
+
+    private MessageRole() {}
+  }
+
+  public static final class BlockType {
+    public static final String TEXT = "text";
+    public static final String IMAGE = "image";
+    public static final String AUDIO = "audio";
+    public static final String DATA = "data";
+    public static final String FILE = "file";
+    public static final String REFUSAL = "refusal";
+    public static final String ERROR = "error";
+
+    private BlockType() {}
+  }
+
+  public static final class SessionStatusValue {
+    public static final String IDLE = "idle";
+    public static final String RUNNING = "running";
+    public static final String RESCHEDULING = "rescheduling";
+    public static final String TERMINATED = "terminated";
+
+    private SessionStatusValue() {}
+  }
+
+  public static String resolveBaseUrl(String workspace, String region) {
+    String ws = workspace;
+    if (ws == null || ws.isEmpty()) {
+      ws = System.getenv(ENV_WORKSPACE);
+    }
+    if (ws == null || ws.isEmpty()) {
+      throw new IllegalArgumentException(
+          "workspace is required. Pass it to the constructor, "
+              + "set DASHSCOPE_WORKSPACE env var, or set DASHSCOPE_AGENTSTUDIO_URL.");
+    }
+    String r = region;
+    if (r == null || r.isEmpty()) {
+      r = System.getenv(ENV_REGION);
+    }
+    if (r == null || r.isEmpty()) {
+      r = DEFAULT_REGION;
+    }
+    return String.format(BASE_URL_TEMPLATE, ws, r);
+  }
+
+  /**
+   * Build a {@link GeneralServiceOption} for an agentstudio endpoint. When {@code baseUrl} is
+   * non-null it overrides the global default; otherwise the request falls back to {@code
+   * Constants.baseHttpApiUrl} via {@code GeneralApi}.
+   */
+  public static GeneralServiceOption newServiceOption(
+      HttpMethod method, String path, String baseUrl) {
+    GeneralServiceOption opt =
+        GeneralServiceOption.builder()
+            .protocol(Protocol.HTTP)
+            .httpMethod(method)
+            .streamingMode(StreamingMode.OUT)
+            .path(path)
+            .build();
+    if (baseUrl != null) {
+      opt.setBaseHttpUrl(baseUrl);
+    }
+    return opt;
+  }
+
+  /**
+   * Stamp the client's instance apiKey onto a param if the caller didn't set one. The global
+   * fallback chain in {@link com.alibaba.dashscope.utils.ApiKey#getApiKey} still applies when
+   * {@code apiKey} is null.
+   */
+  public static <P extends HalfDuplexParamBase> P withApiKey(String apiKey, P param) {
+    if (apiKey != null && param.getApiKey() == null) {
+      param.setApiKey(apiKey);
+    }
+    return param;
+  }
+
+  /** Append {@code key=value} (URL-encoded) to {@code sb} if value is non-null. Joins with &. */
+  public static void appendParam(StringBuilder sb, String key, Object value) {
+    if (value == null) {
+      return;
+    }
+    if (sb.length() > 0) {
+      sb.append("&");
+    }
+    try {
+      sb.append(key).append("=").append(URLEncoder.encode(value.toString(), "UTF-8"));
+    } catch (UnsupportedEncodingException e) {
+      sb.append(key).append("=").append(value);
+    }
+  }
 }