SDK References - Java

public final class QoderClient implements AutoCloseable {
    public static Builder builder();
    public QoderQuery query(OneShotQueryRequest request);
    public CompletionStage<QoderSession> openSession(SessionOptions options);
    public CompletionStage<PreparedQuery> prepare(SessionOptions options);
    public SessionRepository sessions();
    public SessionRepository sessions(SessionOptions options);
    public CompletionStage<Path> installRuntime();
    public CompletionStage<Integer> pruneRuntimes();
    public CompletionStage<Void> closeAsync();
    public void close();
}

public final class QoderQuery implements AutoCloseable {
    public MessageStream messages();
    public CompletionStage<InitializationResult> initialization();
    public CompletionStage<InterruptResult> interrupt();
    public CompletionStage<Void> flushMemory();
    public CompletionStage<Void> refreshMemory();
    public CompletionStage<Void> closeAsync();
    public void close();
}

public final class QoderSession implements AutoCloseable {
    public MessageStream messages();
    public CompletionStage<InitializationResult> initialization();
    public CompletionStage<MessageId> send(UserInput input);
    public MessageSubmission submit(UserInput input);
    public CompletionStage<Void> completeInput();
    public CompletionStage<Boolean> cancelQueuedMessage(MessageId id);
    public CompletionStage<InterruptResult> interrupt();
    public CompletionStage<Void> setPermissionMode(PermissionMode mode);
    public CompletionStage<PlanModeSnapshot> getPlanMode();
    public CompletionStage<PlanModeSnapshot> setPlanMode(boolean active);
    public CompletionStage<Void> setPermissionModePreservingPlan(PermissionMode mode);
    public CompletionStage<Void> setProxy(ProxySettings proxy);
    public CompletionStage<Void> addDirectories(List<Path> directories);
    public CompletionStage<Void> applyFlagSettings(FlagSettings settings);
    public CompletionStage<SessionTitle> generateSessionTitle();
    public CompletionStage<SessionTitle> generateSessionTitle(String description);
    public CompletionStage<Void> seedReadState(ReadStateSeed seed);
    public CompletionStage<List<String>> supportedCommands();
    public CompletionStage<List<CommandInfo>> commandCatalog();
    public CompletionStage<Optional<ModelCatalogSnapshot>> modelCatalogSnapshot();
    public CompletionStage<List<CommandInfo>> reloadSkills();
    public CompletionStage<List<ModelInfo>> getAvailableModels();
    public CompletionStage<List<ModelInfo>> getAvailableModels(ModelCatalogOptions options);
    public CompletionStage<Boolean> backgroundTasks();
    public CompletionStage<Boolean> backgroundTasks(String toolUseId);
    public CompletionStage<Void> stopTask(TaskId taskId);
    public CompletionStage<Void> reloadPlugins();
    public CompletionStage<List<McpServerStatus>> mcpServerStatus();
    public CompletionStage<McpAuthenticationResult> beginMcpAuthentication(String serverName);
    public CompletionStage<McpAuthenticationResult> beginMcpAuthentication(String serverName, McpAuthenticationOptions options);
    public CompletionStage<Void> mcpSubmitOAuthCallbackUrl(String serverName, String callbackUrl);
    public CompletionStage<Void> rewindHistory(MessageId toMessageId);
    public CompletionStage<RewindFilesResult> rewindFiles(MessageId messageId, RewindFilesOptions options);
    public CompletionStage<Void> flushMemory();
    public CompletionStage<Void> refreshMemory();
    public CompletionStage<Void> closeAsync();
    public void close();
}

public final class CommandInfo {
    public static CommandInfo of(String name, JsonObject raw);
    public String name();
    public Optional<String> description();
    public Optional<String> argumentHint();
    public JsonObject raw();
}

public final class PreparedQuery implements AutoCloseable {
    public CompletionStage<InitializationResult> initialization();
    public QoderQuery toQuery(UserInput input);
    public QoderSession toSession();
    public CompletionStage<Void> closeAsync();
    public void close();
}

public final class MessageStream {
    public MessageCursor openCursor();
    public CompletionStage<Void> consume(MessageHandler handler, Executor executor);
}

public interface MessageCursor extends AutoCloseable {
    boolean hasNext();
    SdkMessage next();
    void close();
}

@FunctionalInterface
public interface MessageHandler {
    void onMessage(SdkMessage message) throws Exception;
}

public final class SessionOptions {
    public static Builder builder();
    public static SessionOptions defaults();   // 等同于 builder().build()
    public Builder toBuilder();                // 以当前值预填新的 Builder
    // 每个 Builder 设置项都有同名 getter，例如 workingDirectory()、maxTurns()；
    // resume(String) 对应 resumeSessionId()。未设置的可选项返回 Optional.empty()。
}

public final class OneShotQueryRequest {
    public static OneShotQueryRequest of(String prompt);
    public static Builder builder();
    public UserInput input();
    public SessionOptions options();

    public static final class Builder {
        public Builder prompt(String prompt);
        public Builder input(UserInput input);
        public Builder options(SessionOptions options);
        public OneShotQueryRequest build();
    }
}

public final class UserInput {
    public static UserInput text(String text);
    public static Builder builder();
    public List<Content> content();
    public SendPriority priority();
    public boolean shouldQuery();
    public Optional<Map<String, String>> customContext();
    public Optional<Boolean> clientComposed();
    public List<SelectedSkill> selectedSkills();
}

public final class SelectedSkill {
    public static SelectedSkill of(String name);
    public static SelectedSkill of(String name, String arguments);
    public String name();
    public Optional<String> arguments();
}

public final class ReadStateSeed {
    public ReadStateSeed(List<String> readFiles);
    public static ReadStateSeed of(String path, long mtime);
    public List<String> readFiles();
}

public enum SendPriority { NOW, NEXT, LATER }

public final class FlagSettings {
    public FlagSettings(Map<String, Boolean> flags);
    public Map<String, Boolean> flags();
}

public final class ProxySettings {
    public static ProxySettings of(SecretValue proxyUrl);
    public static ProxySettings clear();
    public SecretValue proxyUrlSecret();
    @Deprecated public ProxySettings(String proxyUrl);
    @Deprecated public String proxyUrl();
}

public final class ManagedRuntimeOptions {
    public static final long DEFAULT_IO_TIMEOUT_MS = 30_000L;
    public static final long DEFAULT_TOTAL_TIMEOUT_MS = 600_000L;

    public enum DownloadPolicy { ALLOW, DISALLOW }

    public static Builder builder();
    public static ManagedRuntimeOptions defaults();
    public Builder toBuilder();
    public Optional<Path> cacheDirectory();
    public DownloadPolicy downloadPolicy();
    public Optional<URI> baseUrl();
    public Optional<SecretValue> authorization();
    public Optional<Path> localArchive();
    public long connectTimeoutMs();
    public long readTimeoutMs();
    public long totalTimeoutMs();
}

public abstract class Auth {
    public static Auth qoderCli();
    public static Auth accessToken(SecretValue token);
    public static Auth accessTokenEnv();
    public static Auth accessTokenEnv(String environmentVariable);
    public static Auth serviceAccountKey(SecretValue key);
    public static Auth serviceAccountTokenProvider(ServiceAccountTokenProvider provider);
    public static Auth jobTokenProvider(JobTokenProvider provider);
}

public interface ServiceAccountTokenProvider {
    CompletionStage<SecretValue> fetchServiceAccountToken();
}

public interface JobTokenProvider {
    CompletionStage<SecretValue> fetchJobToken();
}

public final class SecretValue {
    public static SecretValue of(char[] value);
    public static SecretValue of(String value);
    public char[] reveal();
    public int length();
}

@FunctionalInterface
public interface ToolPermissionHandler {
    CompletionStage<PermissionResult> canUseTool(ToolPermissionRequest request,
                                                 CancellationToken cancellation)
            throws Exception;
}

public final class ToolPermissionRequest {
    public String toolName();
    public JsonValue toolInput();
    public List<JsonValue> suggestions();
    public Optional<String> toolUseId();
    public Optional<String> agentId();
    public Optional<String> title();
    public Optional<String> displayName();
    public Optional<String> description();
    public Optional<String> blockedPath();
    public Optional<String> decisionReason();
    public Optional<String> decisionReasonType();
    public Optional<String> permissionKind();
    public Optional<Boolean> classifierApprovable();
    public List<PermissionOption> options();
    public Optional<PermissionDetails> details();
    public JsonObject raw();
}

public enum PermissionScope {
    ONCE, SESSION, PERSIST;
    public String wireValue();
    public String outcome();
}

public final class PermissionResult {
    public static PermissionResult allow();
    public static PermissionResult allow(JsonValue updatedInput);
    public static PermissionResult deny(String reason);
    public PermissionResult withScope(PermissionScope scope);
    public boolean isAllowed();
    public Optional<JsonValue> updatedInput();
    public Optional<String> denyReason();
    public Optional<PermissionScope> scope();
}

public final class PermissionMode {
    public static final PermissionMode DEFAULT;
    public static final PermissionMode ACCEPT_EDITS;
    public static final PermissionMode BYPASS_PERMISSIONS;
    public static final PermissionMode PLAN;
    public static final PermissionMode DONT_ASK;
    public static final PermissionMode AUTO;
    public static PermissionMode of(String value);
    public String value();
}

public interface CancellationToken {
    boolean isCancelled();
    void onCancel(Runnable action);
    default CancellationRegistration registerOnCancel(Runnable action);
}

public interface CancellationRegistration extends AutoCloseable {
    @Override void close();
}

public final class PlanModeSnapshot {
    public boolean active();
}

// SessionOptions.Builder
public Builder planMode(boolean active);

// QoderSession
public CompletionStage<PlanModeSnapshot> setPlanMode(boolean active);
public CompletionStage<PlanModeSnapshot> getPlanMode();
public CompletionStage<Void> setPermissionModePreservingPlan(PermissionMode mode);

public final class HookRegistration {
    public static Builder builder();
    public String event();
    public Optional<String> matcher();
    public HookHandler handler();
    public long timeoutMs();
}

@FunctionalInterface
public interface HookHandler {
    CompletionStage<JsonValue> onHookEvent(HookEvent event) throws Exception;
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "..."
  }
}

public final class HookEvent {
    public String eventName();
    public Optional<String> matcher();
    public JsonValue payload();
}

public final class McpServerConfig {
    public static McpServerConfig stdio(String name, String command, List<String> args);
    public static McpServerConfig sse(String name, String url);
    public static McpServerConfig http(String name, String url);
    public static McpServerConfig inProcess(String name, InProcessMcpHandler handler);

    // 返回新实例
    public McpServerConfig withEnv(String envName, String value);
    public McpServerConfig withSecretEnv(String envName, SecretValue value);
    public McpServerConfig withHeader(String headerName, String value);
    public McpServerConfig withSecretHeader(String headerName, SecretValue value);

    public String name();
    public String type();
    public Optional<String> command();
    public List<String> args();
    public Map<String, String> env();
    public Map<String, SecretValue> secretEnv();
    public Optional<String> url();
    public Map<String, String> headers();
    public Map<String, SecretValue> secretHeaders();
    public Optional<InProcessMcpHandler> inProcessHandler();
    public boolean hasSecrets();
}

@FunctionalInterface
public interface InProcessMcpHandler {
    CompletionStage<JsonValue> handle(JsonValue message) throws Exception;
    default CompletionStage<JsonValue> handle(JsonValue message,
                                              CancellationToken cancellation) throws Exception;
    default InProcessMcpHandler newConnection();
}

public final class McpServerStatus {
    public String name();
    public String status();
    public JsonValue raw();
}

public final class McpAuthenticationResult {
    public boolean requiresUserAction();
    public Optional<String> authUrl();
}

public final class McpAuthenticationOptions {
    public static McpAuthenticationOptions defaults();
    public static McpAuthenticationOptions redirectUri(String redirectUri);
    public Optional<String> redirectUri();
}

@FunctionalInterface
public interface ElicitationHandler {
    CompletionStage<ElicitationResult> onElicitation(ElicitationRequest request)
            throws Exception;
}

public final class ElicitationRequest {
    public String serverName();
    public String message();
    public JsonValue requestedSchema();
    public JsonValue raw();
}

public final class ElicitationResult {
    public static ElicitationResult accept(JsonValue content);
    public static ElicitationResult decline();
    public static ElicitationResult cancel();
    public String action();
    public Optional<JsonValue> content();
}

public abstract class ModelSelection {
    public static StaticModelSelection staticModel(ModelId model);
    public static DynamicModelSelection dynamic(ModelPolicyProvider provider);
    public static DynamicModelSelection dynamic(ModelId initialModel, ModelPolicyProvider provider);
    public static PolicyModelSelection policy(ModelDecisionProvider provider);
    public static PolicyModelSelection policy(ModelId initialModel, ModelDecisionProvider provider);
}

public final class StaticModelSelection extends ModelSelection {
    public Optional<ModelId> model();
}

public final class DynamicModelSelection extends ModelSelection {
    public ModelPolicyProvider provider();
    public Optional<ModelId> initialModel();
}

public final class PolicyModelSelection extends ModelSelection {
    public ModelDecisionProvider provider();
    public Optional<ModelId> initialModel();
}

@FunctionalInterface
public interface ModelPolicyProvider {
    CompletionStage<ModelId> resolveModel(ModelRequestContext context) throws Exception;
}

@FunctionalInterface
public interface ModelDecisionProvider {
    CompletionStage<ModelPolicyResult> resolve(ModelRequestContext context) throws Exception;
}

public final class ModelPolicyResult {
    public static ModelPolicyResult keepCurrent();
    public static ModelPolicyResult select(ModelId model);
    public static Builder builder();
    public Optional<ModelId> model();
    public Optional<JsonObject> parameters();
    public Optional<String> taskId();
    public Optional<String> subTask();
}

public final class ModelRequestContext {
    public Optional<String> sessionId();
    public Optional<String> purpose();
    public Optional<Integer> turnIndex();
    public Optional<String> agentId();
    public Optional<String> agentType();
    public Optional<ModelId> resolvedModel();
    public List<ModelInfo> availableModels();
}

public final class ModelInfo {
    public ModelId modelId();
    public Optional<String> displayName();
    public Optional<String> description();
    public Optional<String> source();
    public Optional<String> outerProvider();
    public Optional<String> descriptionEn();
    public boolean isEnabled();
    public JsonValue raw();
}

public final class ModelCatalogOptions {
    public enum FetchStrategy { LIVE, CACHE }
    public static ModelCatalogOptions defaults();
    public static Builder builder();
    public Optional<FetchStrategy> fetchStrategy();
    public Optional<String> uid();
}

public final class ModelCatalogSnapshot {
    public List<ModelInfo> models();
    public Optional<ModelId> currentModel();
}

public final class ModelId {
    public static ModelId of(String value);
    public String value();
}

public final class SessionStorage {
    public enum Mode { INHERIT, CLI_LOCAL, EXTERNAL }
    public static SessionStorage inherit();
    public static SessionStorage cliLocal();
    public static SessionStorage external(SessionStore store);
    public Mode mode();
    public Optional<SessionStore> externalStore();
}

public interface SessionStore {
    CompletionStage<AppendResult> append(SessionKey key, AppendBatch batch);
    CompletionStage<Optional<SessionSnapshot>> load(SessionKey key);
}

public interface ListableSessionStore extends SessionStore {
    CompletionStage<List<SessionKey>> listSessions(String projectKey);
    CompletionStage<Void> deleteSession(SessionKey key);
}

public interface SessionDeletionStore extends ListableSessionStore {
    CompletionStage<Void> deleteSessionTree(String projectKey, String sessionId);
}

public final class InMemorySessionStore implements SessionDeletionStore {
    public InMemorySessionStore();
}

public interface SessionRepository {
    CompletionStage<List<String>> list();
    CompletionStage<Optional<SessionSnapshot>> get(String sessionId);
    CompletionStage<Void> delete(String sessionId);
    CompletionStage<QoderSession> continueSession(String sessionId, SessionOptions options);
    CompletionStage<QoderSession> fork(String sessionId, SessionOptions options);
}

public final class SessionKey {
    public static final String DEFAULT_PROJECT; // "default"
    public static SessionKey of(String projectKey, String sessionId);
    public static SessionKey of(String projectKey, String sessionId, String subpath);
    public static String projectKeyFor(Path workingDirectory);
    public String projectKey();
    public String sessionId();
    public String subpath();
}

public final class AppendBatch {
    public static Builder builder();
    public OperationId operationId();
    public VersionToken expectedVersion();
    public long firstSequence();
    public List<SessionStoreEntry> entries();
}

public final class AppendResult {
    public static AppendResult applied(VersionToken newVersion, int appendedCount);
    public static AppendResult replayed(VersionToken newVersion, int appendedCount);
    public VersionToken newVersion();
    public int appendedCount();
    public boolean alreadyApplied();
}

public final class SessionSnapshot {
    public static SessionSnapshot of(List<SessionStoreEntry> entries, VersionToken version);
    public List<SessionStoreEntry> entries();
    public VersionToken version();
}

public final class SessionStoreEntry {
    public static SessionStoreEntry of(String rawJson);
    public String rawJson();
    public Optional<String> type();
    public Optional<String> uuid();
    public Optional<String> timestamp();
}

public final class OperationId {
    public static OperationId of(String value);
    public static OperationId random();
    public String value();
}

public final class VersionToken {
    public static VersionToken of(String value);
    public static VersionToken initial();
    public String value();
}

public class SessionStoreDeletedException extends QoderException {
    public static final String CODE = "SESSION_STORE_DELETED";
    public SessionStoreDeletedException(String message);
    public SessionStoreDeletedException(String message, Throwable cause);
}

public final class InitializationResult {
    public Map<String, CapabilityState> capabilities();
    public CapabilityState capability(String capability);
    public Optional<String> cliVersion();
    public Optional<String> wireVersion();
    public Optional<String> sessionId();
    public Optional<EffectiveMemoryConfig> memory();
}

public enum CapabilityState { SUPPORTED, UNSUPPORTED, UNKNOWN }