feat(sdk): add cloud runtime preflight

Author: vamgan

README.md

@@ -8,7 +8,7 @@ JavaScript and TypeScript SDK for AgentDispatch. Use it to call the MCP server f
 ## What it does
 
 - Wraps the provider-neutral AgentDispatch MCP tools.
-- Provides typed requests for `spawn_cloud_agent`, `dispatch_task`, polling, logs, results, and cancellation.
+- Provides typed requests for `check_cloud_agent_runtime`, `spawn_cloud_agent`, `dispatch_task`, polling, logs, results, and cancellation.
 - Preserves provider-neutral inputs so future adapters do not require SDK API churn.
 - Returns cloud-agent metadata for A2A, MCP, AG-UI, or HTTP interaction after spawn.
 
@@ -28,6 +28,14 @@ const client = await AgentDispatchStdioClient.connect({
   args: ["agentdispatch-mcp", "--config", "/absolute/path/agentdispatch.config.json"]
 });
 
+const readiness = await client.checkCloudAgentRuntime({
+  runtime: "research-agent",
+  live: true
+});
+if (!readiness.ok) {
+  throw new Error(`Cloud agent runtime is not ready: ${JSON.stringify(readiness.checks)}`);
+}
+
 const task = await client.spawnCloudAgent({
   instruction: "Run a long-running repo analysis task.",
   protocol: "a2a",

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dispatch/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "TypeScript SDK for AgentDispatch.",
   "type": "module",
   "license": "Apache-2.0",

package.json

@@ -123,6 +123,40 @@ export interface CloudAgentA2AResult {
   metadata?: Record<string, unknown>;
 }
 
+export interface CloudAgentRuntimeCheckRequest {
+  runtime?: string;
+  provider?: string;
+  accountProfile?: string;
+  account_profile?: string;
+  live?: boolean;
+  runtimeArn?: string;
+  runtime_arn?: string;
+  target?: {
+    mode?: string;
+    protocol?: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+export interface CloudAgentRuntimeCheck {
+  name: string;
+  status: "pass" | "warn" | "fail";
+  message: string;
+}
+
+export interface CloudAgentRuntimeCheckResult {
+  ok: boolean;
+  runtime?: string;
+  provider?: string;
+  accountProfile?: string;
+  account_profile?: string;
+  backend?: string;
+  adapter?: string;
+  targetMode?: string;
+  target_mode?: string;
+  checks: CloudAgentRuntimeCheck[];
+}
+
 export type CloudAgentA2ATransport =
   | ((request: CloudAgentA2AHttpRequest) => Promise<unknown>)
   | { send(request: CloudAgentA2AHttpRequest): Promise<unknown> };
@@ -195,6 +229,18 @@ export class AgentDispatchMcpClient {
     });
   }
 
+  async checkCloudAgentRuntime(request: CloudAgentRuntimeCheckRequest = {}): Promise<CloudAgentRuntimeCheckResult> {
+    return this.call<CloudAgentRuntimeCheckResult>("check_cloud_agent_runtime", {
+      runtime: request.runtime,
+      provider: request.provider,
+      account_profile: request.accountProfile ?? request.account_profile,
+      live: request.live,
+      runtimeArn: request.runtimeArn,
+      runtime_arn: request.runtime_arn,
+      target: request.target
+    });
+  }
+
   async getTaskStatus(taskId: string): Promise<TaskRecord> {
     return this.call<TaskRecord>("get_task_status", { task_id: taskId });
   }

src/index.ts

@@ -117,6 +117,15 @@ describe("AgentDispatchMcpClient", () => {
         const responses: Record<string, unknown> = {
           dispatch_task: { taskId: "task_mcp", status: "provisioning", provider: "aws", accountProfile: "dev-aws" },
           spawn_cloud_agent: { taskId: "task_spawn", status: "provisioning", provider: "aws", accountProfile: "dev-aws" },
+          check_cloud_agent_runtime: {
+            ok: true,
+            runtime: "research-agent",
+            provider: "aws",
+            accountProfile: "dev-aws",
+            backend: "aws-agentcore",
+            targetMode: "session",
+            checks: [{ name: "aws.research-agent.runtime", status: "pass", message: "runtime reachable" }]
+          },
           get_task_status: task,
           get_task_logs: { taskId: "task_mcp", cursor: 0, nextCursor: 5, data: "hello" },
           get_task_result: { taskId: "task_mcp", status: "succeeded", artifacts: [] },
@@ -144,6 +153,12 @@ describe("AgentDispatchMcpClient", () => {
       executionRoleArn: "arn:aws:iam::123456789012:role/agentcore-runtime",
       environmentVariables: { AGENT_FRAMEWORK: "openclaw" }
     })).resolves.toMatchObject({ taskId: "task_spawn" });
+    await expect(client.checkCloudAgentRuntime({
+      runtime: "research-agent",
+      runtimeArn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/research-agent",
+      live: true,
+      target: { mode: "session", protocol: "a2a" }
+    })).resolves.toMatchObject({ ok: true, backend: "aws-agentcore" });
     await expect(client.getTaskStatus("task_mcp")).resolves.toMatchObject({ status: "running" });
     await expect(client.getTaskLogs("task_mcp", 0, 128)).resolves.toMatchObject({ data: "hello" });
     await expect(client.getTaskResult("task_mcp")).resolves.toMatchObject({ status: "succeeded" });
@@ -154,6 +169,7 @@ describe("AgentDispatchMcpClient", () => {
     expect(calls.map((call) => call.toolName)).toEqual([
       "dispatch_task",
       "spawn_cloud_agent",
+      "check_cloud_agent_runtime",
       "get_task_status",
       "get_task_logs",
       "get_task_result",
@@ -180,6 +196,12 @@ describe("AgentDispatchMcpClient", () => {
       executionRoleArn: "arn:aws:iam::123456789012:role/agentcore-runtime",
       environmentVariables: { AGENT_FRAMEWORK: "openclaw" }
     });
+    expect(calls[2].input).toMatchObject({
+      runtime: "research-agent",
+      live: true,
+      runtimeArn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/research-agent",
+      target: { mode: "session", protocol: "a2a" }
+    });
   });
 
   it("supports transports that return decoded JSON directly", async () => {
@@ -190,6 +212,30 @@ describe("AgentDispatchMcpClient", () => {
     await expect(client.listProviders()).resolves.toEqual(["aws", "gcp"]);
   });
 
+  it("accepts MCP-native runtime check aliases", async () => {
+    let forwarded: Record<string, unknown> | undefined;
+    const client = new AgentDispatchMcpClient({
+      callTool: async (_toolName, input) => {
+        forwarded = input;
+        return { ok: true, checks: [] };
+      }
+    });
+
+    await client.checkCloudAgentRuntime({
+      provider: "aws",
+      account_profile: "dev-aws",
+      runtime_arn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/alias",
+      target: { mode: "session" }
+    });
+
+    expect(forwarded).toMatchObject({
+      provider: "aws",
+      account_profile: "dev-aws",
+      runtime_arn: "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/alias",
+      target: { mode: "session" }
+    });
+  });
+
   it("accepts MCP-native spawn aliases for clarification retries", async () => {
     let forwarded: Record<string, unknown> | undefined;
     const client = new AgentDispatchMcpClient({