aws-runtime-bridge 1.3.9 → 1.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 AgentsWorkStudio 机器实例运行时桥接服务，用于在实例上管理 Agent 运行时、终端、配置与回调通信。
 
+> `aws-runtime-bridge` 面向机器实例宿主机运行，需要访问本机工作区、终端、运行时配置和文件系统；不要将它作为 Docker/Compose 服务部署。Docker Compose 仅用于仓库根目录的 `aws-dashboard` 与 `aws-mcp-server` Web 服务。
+
 ## 全局安装
 
 从 npm 包安装时：
@@ -23,7 +25,7 @@ npm install -g .
 
 ## 启动
 
-首次运行 `awsb` / `aws-bridge` 时，如果不存在 `~/.aws-bridge/config.json`，CLI 会进入交互式配置引导；也可以在提示中选择跳过。跳过时仍会创建配置文件并自动生成随机 `connectionKey`，终端会输出该密钥，请保存后在 server/面板连接此 Bridge 时使用。非交互环境（如 systemd、CI、Docker 后台启动）不会阻塞等待输入，也会自动生成随机 `connectionKey` 并跳过引导。
+首次运行 `awsb` / `aws-bridge` 时，如果不存在 `~/.aws-bridge/config.json`，CLI 会进入交互式配置引导；也可以在提示中选择跳过。跳过时仍会创建配置文件并自动生成随机 `connectionKey`，终端会输出该密钥，请保存后在 server/面板连接此 Bridge 时使用。非交互环境（如 systemd、CI 后台启动）不会阻塞等待输入，也会自动生成随机 `connectionKey` 并跳过引导。
 
 引导会生成类似下面的配置：
 
@@ -45,11 +47,14 @@ npm install -g .
 
 ```bash
 AWS_RUNTIME_BRIDGE_PORT=18081 \
-AWS_RUNTIME_SCHEDULER_BASE_URL=http://your-server-host:7380 \
 AWS_RUNTIME_HOME_DIR=/opt/agentswork/runtime-home \
 aws-bridge
 ```
 
+当 `~/.aws-bridge/config.json` 只配置了一个 `autoRegisterTargets[].serverUrl` 时，bridge 会自动将该地址作为 `/runtime/ping` 回连调度中心的地址，无需重复配置 `AWS_RUNTIME_SCHEDULER_BASE_URL`。如需显式覆盖，或同一个 bridge 配置了多个自动注册目标，请设置 `AWS_RUNTIME_SCHEDULER_BASE_URL` 指定当前实例测试连接时应回连的调度中心。
+
+If an existing runtime binding still stores an old scheduler URL such as `http://127.0.0.1:8080`, re-run auto-register, refresh the runtime token, or re-pair after changing `serverUrl` / `AWS_RUNTIME_SCHEDULER_BASE_URL`; bridge will not reuse a token issued for the old scheduler URL against the new scheduler URL.
+
 `aws-runtime-bridge` 命令仍作为兼容别名保留。安装 `aws-runtime-bridge` 后，包内会随附
 `aws-client-agent-mcp` 的编译产物；bridge 启动时只负责准备该 MCP 产物，不再在 Agent 启动时默认动态注入 `aws-mcp`。
 
@@ -84,8 +89,8 @@ sudo awsb service uninstall
 | 变量名 | 说明 | 默认值 |
 | --- | --- | --- |
 | `AWS_RUNTIME_BRIDGE_PORT` | Bridge HTTP 端口 | `18081` |
-| `AWS_RUNTIME_SCHEDULER_BASE_URL` | aws-mcp-server 地址 | `http://localhost:8080` |
+| `AWS_RUNTIME_SCHEDULER_BASE_URL` | aws-mcp-server 地址；显式配置优先级最高，未配置且只有一个 `autoRegisterTargets[].serverUrl` 时自动使用该地址 | 单目标自动注册地址；否则 `http://localhost:8080` |
 | `AWS_RUNTIME_HOME_DIR` | Bridge 管理配置与状态的主目录 | 当前用户 Home |
 | `AWS_RUNTIME_CORS_ORIGINS` | 允许访问 bridge 的来源，逗号分隔 | 本地开发地址 |
 
-生产环境中，`AWS_RUNTIME_SCHEDULER_BASE_URL` 必须填写机器实例可访问的 `aws-mcp-server` 地址，不能使用容器内的 `localhost`。
+生产环境中，bridge 最终解析出的调度中心地址必须是机器实例可访问的 `aws-mcp-server` 地址，不能使用不可达的容器内 `localhost`。如果配置了多个 `autoRegisterTargets`，bridge 不会静默选择第一个目标，需通过 `AWS_RUNTIME_SCHEDULER_BASE_URL` 或后续多调度中心身份路由明确目标。

package/dist/config.d.ts

@@ -5,7 +5,20 @@
  */
 /** 服务端口 */
 export declare const port: number;
-/** 调度器基础 URL */
+/** 默认调度器基础 URL */
+export declare const DEFAULT_SCHEDULER_BASE_URL = "http://localhost:8080";
+export type SchedulerBaseUrlSource = "env" | "single-auto-register-target" | "default" | "ambiguous-auto-register-targets";
+export interface SchedulerBaseUrlResolution {
+    url: string;
+    source: SchedulerBaseUrlSource;
+    ambiguousTargetUrls: string[];
+}
+/**
+ * 解析调度中心基础 URL。
+ * 主流程：显式环境变量优先；未配置时，单个自动注册目标可作为宿主机部署的零额外配置回退；多目标不静默取第一个。
+ */
+export declare function resolveSchedulerBaseUrl(): SchedulerBaseUrlResolution;
+/** 调度器基础 URL（兼容旧导入；请求处理应优先调用 resolveSchedulerBaseUrl 获取最新值） */
 export declare const schedulerBaseUrl: string;
 /** Node 环境 */
 export declare const nodeEnv: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,WAAW;AACX,eAAO,MAAM,IAAI,EAAE,MAElB,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,gBAAgB,EAAE,MACwC,CAAC;AAExE,cAAc;AACd,eAAO,MAAM,OAAO,EAAE,MAA8C,CAAC;AAErE,oCAAoC;AACpC,eAAO,MAAM,oBAAoB,EAAE,OACiB,CAAC;AAErD,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,EAAE,MAAM,EAMC,CAAC;AAEzC,gEAAgE;AAChE,wBAAgB,uBAAuB,IAAI,IAAI,CAAG;AAElD,eAAe;AACf,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,8CAA8C;AAC9C,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,2BAA2B;AAC3B,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,0BAA0B;AAC1B,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED,yBAAyB;AACzB,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,sBAAsB;AACtB,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED,yBAAyB;AACzB,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,4BAA4B;AAC5B,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED;;GAEG;AAEH,yBAAyB;AACzB,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB,EACrB,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1C,eAAe;AACf,eAAO,MAAM,mBAAmB,SACiB,CAAC;AAElD,iCAAiC;AACjC,eAAO,MAAM,2BAA2B,QAEvC,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,uBAAuB,QAEnC,CAAC;AAEF;;GAEG;AAEH,eAAe;AACf,eAAO,MAAM,qBAAqB,SAA2C,CAAC;AAE9E,YAAY;AACZ,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAEvE,iBAAiB;AACjB,eAAO,MAAM,sBAAsB,QAAiC,CAAC;AAErE,oBAAoB;AACpB,eAAO,MAAM,2BAA2B,QAAsC,CAAC;AAE/E,WAAW;AACX,eAAO,MAAM,0BAA0B,QAAqC,CAAC;AAE7E,WAAW;AACX,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAEvE,aAAa;AACb,eAAO,MAAM,4BAA4B,QACH,CAAC;AAEvC,kCAAkC;AAClC,eAAO,MAAM,wBAAwB,QAC4B,CAAC;AAElE,aAAa;AACb,eAAO,MAAM,yBAAyB,QAErC,CAAC;AAEF,iBAAiB;AACjB,eAAO,MAAM,4BAA4B,QAExC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,WAAW;AACX,eAAO,MAAM,IAAI,EAAE,MAElB,CAAC;AAEF,kBAAkB;AAClB,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE,MAAM,MAAM,sBAAsB,GAC9B,KAAK,GACL,6BAA6B,GAC7B,SAAS,GACT,iCAAiC,CAAC;AAEtC,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,sBAAsB,CAAC;IAC/B,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AA+ED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,0BAA0B,CAiCpE;AAED,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,EAAE,MAEH,CAAC;AAE7B,cAAc;AACd,eAAO,MAAM,OAAO,EAAE,MAA8C,CAAC;AAErE,oCAAoC;AACpC,eAAO,MAAM,oBAAoB,EAAE,OACiB,CAAC;AAErD,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,EAAE,MAAM,EAMC,CAAC;AAEzC,gEAAgE;AAChE,wBAAgB,uBAAuB,IAAI,IAAI,CAAG;AAElD,eAAe;AACf,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,8CAA8C;AAC9C,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,2BAA2B;AAC3B,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,0BAA0B;AAC1B,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED,yBAAyB;AACzB,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,sBAAsB;AACtB,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED,yBAAyB;AACzB,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,4BAA4B;AAC5B,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED;;GAEG;AAEH,yBAAyB;AACzB,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,sBAAsB,EACrB,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1C,eAAe;AACf,eAAO,MAAM,mBAAmB,SACiB,CAAC;AAElD,iCAAiC;AACjC,eAAO,MAAM,2BAA2B,QAEvC,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,uBAAuB,QAEnC,CAAC;AAEF;;GAEG;AAEH,eAAe;AACf,eAAO,MAAM,qBAAqB,SAA2C,CAAC;AAE9E,YAAY;AACZ,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAEvE,iBAAiB;AACjB,eAAO,MAAM,sBAAsB,QAAiC,CAAC;AAErE,oBAAoB;AACpB,eAAO,MAAM,2BAA2B,QAAsC,CAAC;AAE/E,WAAW;AACX,eAAO,MAAM,0BAA0B,QAAqC,CAAC;AAE7E,WAAW;AACX,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAEvE,aAAa;AACb,eAAO,MAAM,4BAA4B,QACH,CAAC;AAEvC,kCAAkC;AAClC,eAAO,MAAM,wBAAwB,QAC4B,CAAC;AAElE,aAAa;AACb,eAAO,MAAM,yBAAyB,QAErC,CAAC;AAEF,iBAAiB;AACjB,eAAO,MAAM,4BAA4B,QAExC,CAAC"}

package/dist/config.js

@@ -3,12 +3,111 @@
  *
  * 集中管理所有环境变量和配置常量
  */
-import os from "node:os";
+import { homedir } from "node:os";
 import path from "node:path";
+import fs from "node:fs";
 /** 服务端口 */
 export const port = Number(process.env.AWS_RUNTIME_BRIDGE_PORT || 18081);
-/** 调度器基础 URL */
-export const schedulerBaseUrl = process.env.AWS_RUNTIME_SCHEDULER_BASE_URL || "http://localhost:8080";
+/** 默认调度器基础 URL */
+export const DEFAULT_SCHEDULER_BASE_URL = "http://localhost:8080";
+function normalizeOptionalString(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const normalized = String(value).trim();
+    return normalized || undefined;
+}
+function normalizeSchedulerHttpBaseUrl(value) {
+    const raw = normalizeOptionalString(value);
+    if (!raw) {
+        return undefined;
+    }
+    const repaired = raw.replace(/^((?:https?|wss?):\/\/(?:\[[^\]]+\]|[^/:?#]+):\d+):\d+(?=\/|$)/i, "$1");
+    try {
+        const url = new URL(repaired);
+        if (url.protocol === "ws:") {
+            url.protocol = "http:";
+        }
+        else if (url.protocol === "wss:") {
+            url.protocol = "https:";
+        }
+        else {
+            url.protocol = url.protocol.toLowerCase();
+        }
+        url.hostname = url.hostname.toLowerCase();
+        return url.origin;
+    }
+    catch {
+        return repaired.replace(/\/+$/, "");
+    }
+}
+function getAutoRegisterConfigFilePath() {
+    const testHomeDir = String(process.env.AWS_TEST_HOME || "").trim();
+    return path.join(testHomeDir || homedir(), ".aws-bridge", "config.json");
+}
+function readAutoRegisterTargetUrls() {
+    const configPath = getAutoRegisterConfigFilePath();
+    try {
+        if (!fs.existsSync(configPath)) {
+            return [];
+        }
+        const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        const rawTargets = Array.isArray(parsed.autoRegisterTargets)
+            ? parsed.autoRegisterTargets
+            : [];
+        const targetUrls = rawTargets
+            .filter((item) => Boolean(item && typeof item === "object" && !Array.isArray(item)))
+            .map((target) => normalizeSchedulerHttpBaseUrl(target.serverUrl) ||
+            normalizeSchedulerHttpBaseUrl(target.schedulerBaseUrl))
+            .filter((url) => Boolean(url));
+        if (targetUrls.length > 0) {
+            return Array.from(new Set(targetUrls));
+        }
+        const topLevelUrl = normalizeSchedulerHttpBaseUrl(parsed.serverUrl) ||
+            normalizeSchedulerHttpBaseUrl(parsed.schedulerBaseUrl);
+        return topLevelUrl ? [topLevelUrl] : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 解析调度中心基础 URL。
+ * 主流程：显式环境变量优先；未配置时，单个自动注册目标可作为宿主机部署的零额外配置回退；多目标不静默取第一个。
+ */
+export function resolveSchedulerBaseUrl() {
+    const envSchedulerBaseUrl = normalizeSchedulerHttpBaseUrl(process.env.AWS_RUNTIME_SCHEDULER_BASE_URL);
+    if (envSchedulerBaseUrl) {
+        return {
+            url: envSchedulerBaseUrl,
+            source: "env",
+            ambiguousTargetUrls: [],
+        };
+    }
+    const autoRegisterTargetUrls = readAutoRegisterTargetUrls();
+    if (autoRegisterTargetUrls.length === 1) {
+        return {
+            url: autoRegisterTargetUrls[0] || DEFAULT_SCHEDULER_BASE_URL,
+            source: "single-auto-register-target",
+            ambiguousTargetUrls: [],
+        };
+    }
+    if (autoRegisterTargetUrls.length > 1) {
+        return {
+            url: DEFAULT_SCHEDULER_BASE_URL,
+            source: "ambiguous-auto-register-targets",
+            ambiguousTargetUrls: autoRegisterTargetUrls,
+        };
+    }
+    return {
+        url: DEFAULT_SCHEDULER_BASE_URL,
+        source: "default",
+        ambiguousTargetUrls: [],
+    };
+}
+/** 调度器基础 URL（兼容旧导入；请求处理应优先调用 resolveSchedulerBaseUrl 获取最新值） */
+export const schedulerBaseUrl = normalizeSchedulerHttpBaseUrl(process.env.AWS_RUNTIME_SCHEDULER_BASE_URL) ||
+    DEFAULT_SCHEDULER_BASE_URL;
 /** Node 环境 */
 export const nodeEnv = process.env.NODE_ENV || "development";
 /** 是否允许浏览宿主机任意目录（默认关闭，仅建议本地排障启用） */
@@ -23,7 +122,7 @@ export const allowedCorsOrigins = String(process.env.AWS_RUNTIME_CORS_ORIGINS ||
 export function validateProductionToken() { }
 /** 获取运行时主目录 */
 export function getRuntimeHomeDir() {
-    return String(process.env.AWS_RUNTIME_HOME_DIR || "").trim() || os.homedir();
+    return String(process.env.AWS_RUNTIME_HOME_DIR || "").trim() || homedir();
 }
 /** 获取 Claude 配置文件路径（AI 配置写入 settings.json） */
 export function getClaudeConfigFile(runtimeHome) {

package/dist/config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":""}

package/dist/config.test.js

@@ -0,0 +1,95 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("node:os", async () => {
+    const actual = await vi.importActual("node:os");
+    const mocked = {
+        ...actual,
+        homedir: () => process.env.AWS_TEST_HOME || actual.homedir(),
+    };
+    return {
+        ...mocked,
+        default: mocked,
+    };
+});
+const originalEnv = { ...process.env };
+const tempRoots = [];
+function createRuntimeHome() {
+    const root = mkdtempSync(path.join(os.tmpdir(), "aws-config-"));
+    tempRoots.push(root);
+    return root;
+}
+function useRuntimeHome(runtimeHome) {
+    process.env.AWS_TEST_HOME = runtimeHome;
+    process.env.HOME = runtimeHome;
+    process.env.USERPROFILE = runtimeHome;
+    process.env.AWS_RUNTIME_HOME_DIR = runtimeHome;
+    delete process.env.AWS_RUNTIME_SCHEDULER_BASE_URL;
+}
+function writeBridgeConfig(runtimeHome, autoRegisterTargets) {
+    const configPath = path.join(runtimeHome, ".aws-bridge", "config.json");
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify({ connectionKey: "bridge-key", autoRegisterTargets }, null, 2)}\n`, "utf-8");
+}
+afterEach(() => {
+    process.env = { ...originalEnv };
+    vi.resetModules();
+    vi.clearAllMocks();
+    vi.restoreAllMocks();
+    for (const root of tempRoots.splice(0)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+describe("scheduler base URL resolution", () => {
+    it("keeps explicit AWS_RUNTIME_SCHEDULER_BASE_URL as the highest priority", async () => {
+        const runtimeHome = createRuntimeHome();
+        useRuntimeHome(runtimeHome);
+        process.env.AWS_RUNTIME_SCHEDULER_BASE_URL = "http://explicit.local:7380/path";
+        writeBridgeConfig(runtimeHome, [{ serverUrl: "http://target.local:7380" }]);
+        const { resolveSchedulerBaseUrl } = await import("./config.js");
+        expect(resolveSchedulerBaseUrl()).toEqual({
+            url: "http://explicit.local:7380",
+            source: "env",
+            ambiguousTargetUrls: [],
+        });
+    });
+    it("uses a single auto-register target serverUrl when scheduler env is absent", async () => {
+        const runtimeHome = createRuntimeHome();
+        useRuntimeHome(runtimeHome);
+        writeBridgeConfig(runtimeHome, [{ serverUrl: "http://127.0.0.1:7380" }]);
+        const { resolveSchedulerBaseUrl } = await import("./config.js");
+        expect(resolveSchedulerBaseUrl()).toEqual({
+            url: "http://127.0.0.1:7380",
+            source: "single-auto-register-target",
+            ambiguousTargetUrls: [],
+        });
+    });
+    it("does not silently select the first auto-register target when multiple URLs exist", async () => {
+        const runtimeHome = createRuntimeHome();
+        useRuntimeHome(runtimeHome);
+        writeBridgeConfig(runtimeHome, [
+            { serverUrl: "http://scheduler-a.local:7380" },
+            { serverUrl: "http://scheduler-b.local:7380" },
+        ]);
+        const { DEFAULT_SCHEDULER_BASE_URL, resolveSchedulerBaseUrl } = await import("./config.js");
+        expect(resolveSchedulerBaseUrl()).toEqual({
+            url: DEFAULT_SCHEDULER_BASE_URL,
+            source: "ambiguous-auto-register-targets",
+            ambiguousTargetUrls: [
+                "http://scheduler-a.local:7380",
+                "http://scheduler-b.local:7380",
+            ],
+        });
+    });
+    it("falls back to the legacy localhost default when no scheduler source exists", async () => {
+        const runtimeHome = createRuntimeHome();
+        useRuntimeHome(runtimeHome);
+        const { DEFAULT_SCHEDULER_BASE_URL, resolveSchedulerBaseUrl } = await import("./config.js");
+        expect(resolveSchedulerBaseUrl()).toEqual({
+            url: DEFAULT_SCHEDULER_BASE_URL,
+            source: "default",
+            ambiguousTargetUrls: [],
+        });
+    });
+});

package/dist/routes/instance.d.ts

@@ -18,9 +18,24 @@ export interface SchedulerPingFailureResponse {
     schedulerBaseUrl: string;
     hint: string;
 }
+interface AmbiguousSchedulerBaseUrlResponse {
+    ok: false;
+    error: "ambiguous_scheduler_base_url";
+    failureStage: "scheduler_ping";
+    runtimeBridge: "healthy";
+    schedulerBaseUrl: string;
+    autoRegisterTargetUrls: string[];
+    hint: string;
+}
 /**
  * 构建调度中心 ping 失败响应。
  * 主流程：保留底层错误与 scheduler 地址，同时明确 bridge 本身已连通、失败点在 bridge 回连调度中心。
  */
 export declare function buildSchedulerPingFailureResponse(error: Error, configuredSchedulerBaseUrl: string): SchedulerPingFailureResponse;
+/**
+ * Build the response for ambiguous scheduler targets.
+ * Main flow: never silently pick the first target; require an explicit scheduler URL or future scheduler identity routing.
+ */
+export declare function buildAmbiguousSchedulerBaseUrlResponse(targetUrls: string[]): AmbiguousSchedulerBaseUrlResponse;
+export {};
 //# sourceMappingURL=instance.d.ts.map

package/dist/routes/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/routes/instance.ts"],"names":[],"mappings":"AA6BA,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,IAAI,CAEN;AAED,eAAO,MAAM,cAAc,4CAAW,CAAC;AAyBvC,wBAAgB,4BAA4B,CAAC,gBAAgB,EAAE,MAAM,GAAG;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QACJ,EAAE,EAAE,OAAO,CAAC;QACZ,aAAa,CAAC,EAAE,SAAS,CAAC;QAC1B,oBAAoB,EAAE,OAAO,CAAC;QAC9B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAqCA;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,SAAS,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,KAAK,EACZ,0BAA0B,EAAE,MAAM,GACjC,4BAA4B,CAiB9B"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/routes/instance.ts"],"names":[],"mappings":"AA6BA,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,IAAI,CAEN;AAED,eAAO,MAAM,cAAc,4CAAW,CAAC;AAyBvC,wBAAgB,4BAA4B,CAAC,gBAAgB,EAAE,MAAM,GAAG;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QACJ,EAAE,EAAE,OAAO,CAAC;QACZ,aAAa,CAAC,EAAE,SAAS,CAAC;QAC1B,oBAAoB,EAAE,OAAO,CAAC;QAC9B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAqCA;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,SAAS,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,iCAAiC;IACzC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,8BAA8B,CAAC;IACtC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,SAAS,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,KAAK,EACZ,0BAA0B,EAAE,MAAM,GACjC,4BAA4B,CAiB9B;AAED;;;GAGG;AACH,wBAAgB,sCAAsC,CACpD,UAAU,EAAE,MAAM,EAAE,GACnB,iCAAiC,CAUnC"}

package/dist/routes/instance.js

@@ -2,7 +2,7 @@ import { Router } from "express";
 import axios from "axios";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { validateToken } from "../middleware/auth.js";
-import { schedulerBaseUrl } from "../config.js";
+import { resolveSchedulerBaseUrl } from "../config.js";
 import { getRuntimeAccessToken } from "../services/runtime-binding.js";
 import { loadInstanceState, saveInstanceState, } from "../services/instance-state.js";
 import { initInstance } from "../services/instance-init-service.js";
@@ -91,6 +91,21 @@ export function buildSchedulerPingFailureResponse(error, configuredSchedulerBase
             : "aws-runtime-bridge 已连通，但它回连调度中心失败。请确认 AWS_RUNTIME_SCHEDULER_BASE_URL 指向的调度中心地址可从 bridge 机器访问，并且运行时访问令牌仍有效。",
     };
 }
+/**
+ * Build the response for ambiguous scheduler targets.
+ * Main flow: never silently pick the first target; require an explicit scheduler URL or future scheduler identity routing.
+ */
+export function buildAmbiguousSchedulerBaseUrlResponse(targetUrls) {
+    return {
+        ok: false,
+        error: "ambiguous_scheduler_base_url",
+        failureStage: "scheduler_ping",
+        runtimeBridge: "healthy",
+        schedulerBaseUrl: "",
+        autoRegisterTargetUrls: targetUrls,
+        hint: "Multiple autoRegisterTargets.serverUrl values were found, so bridge cannot safely infer which scheduler /runtime/ping should call back. Set AWS_RUNTIME_SCHEDULER_BASE_URL explicitly, or use future schedulerId/token-bound multi-scheduler routing.",
+    };
+}
 instanceRouter.get("/healthz", (_req, res) => {
     res.json({
         ok: true,
@@ -103,8 +118,16 @@ instanceRouter.get("/connection-check", (req, res) => {
     res.status(result.status).json(result.body);
 });
 instanceRouter.get("/ping", validateToken, async (_req, res) => {
+    const schedulerBaseUrlResolution = resolveSchedulerBaseUrl();
+    if (schedulerBaseUrlResolution.source === "ambiguous-auto-register-targets") {
+        res
+            .status(400)
+            .json(buildAmbiguousSchedulerBaseUrlResponse(schedulerBaseUrlResolution.ambiguousTargetUrls));
+        return;
+    }
+    const schedulerBaseUrl = schedulerBaseUrlResolution.url;
     try {
-        const runtimeAccessToken = getRuntimeAccessToken(undefined, schedulerBaseUrl) || getRuntimeAccessToken();
+        const runtimeAccessToken = getRuntimeAccessToken(undefined, schedulerBaseUrl);
         if (!runtimeAccessToken) {
             res.status(401).json({ ok: false, error: "runtime_access_token_required" });
             return;

package/dist/routes/instance.test.js

@@ -119,4 +119,23 @@ describe('instance route validation', () => {
         expect(response.runtimeBridge).toBe('healthy');
         expect(response.hint).toContain('运行时访问令牌仍有效');
     });
+    it('explains ambiguous auto-register scheduler targets without picking the first one', async () => {
+        const { buildAmbiguousSchedulerBaseUrlResponse } = await import('./instance.js');
+        const response = buildAmbiguousSchedulerBaseUrlResponse([
+            'http://scheduler-a.local:7380',
+            'http://scheduler-b.local:7380',
+        ]);
+        expect(response).toEqual({
+            ok: false,
+            error: 'ambiguous_scheduler_base_url',
+            failureStage: 'scheduler_ping',
+            runtimeBridge: 'healthy',
+            schedulerBaseUrl: '',
+            autoRegisterTargetUrls: [
+                'http://scheduler-a.local:7380',
+                'http://scheduler-b.local:7380',
+            ],
+            hint: expect.stringContaining('AWS_RUNTIME_SCHEDULER_BASE_URL'),
+        });
+    });
 });

package/dist/services/aws-client-agent-mcp.test.js

@@ -199,6 +199,7 @@ describe('aws-client-agent-mcp service', () => {
         process.env.AWS_CLIENT_AGENT_MCP_COMMAND = 'aws-client-agent-mcp';
         process.env.CUSTOM_SECRET = 'should-not-leak';
         process.env.AWS_RUNTIME_HOME_DIR = mkdtempSync(path.join(os.tmpdir(), 'aws-mcp-config-'));
+        process.env.AWS_TEST_HOME = process.env.AWS_RUNTIME_HOME_DIR;
         process.env.AWS_RUNTIME_SCHEDULER_BASE_URL = '';
         process.env.AWS_SERVER_URL = '';
         process.env.AWS_MCP_HTTP_URL = '';

package/dist/services/runtime-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-binding.d.ts","sourceRoot":"","sources":["../../src/services/runtime-binding.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2DF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAqB5E;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAiCD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,CAYR;AAsCD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAWT;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,OAAO,CAeT;AAcD,wBAAgB,kBAAkB,IAAI,mBAAmB,CAgBxD;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAClD,mBAAmB,EACnB,WAAW,GAAG,aAAa,CAC5B,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAWtB;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcnE;AAED,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,OAAO,GACtB,MAAM,GAAG,SAAS,CAepB;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,mBAAmB,CAwCtB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAkB1C"}
+{"version":3,"file":"runtime-binding.d.ts","sourceRoot":"","sources":["../../src/services/runtime-binding.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2DF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAqB5E;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAiCD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,CAYR;AAsCD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAWT;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,MAAM,GAAG,SAAS,CAUpB;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,OAAO,GACrB,OAAO,CAeT;AAcD,wBAAgB,kBAAkB,IAAI,mBAAmB,CAgBxD;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAClD,mBAAmB,EACnB,WAAW,GAAG,aAAa,CAC5B,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAWtB;AAED,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcnE;AAED,wBAAgB,qBAAqB,CACnC,MAAM,CAAC,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE,OAAO,GACtB,MAAM,GAAG,SAAS,CAyBpB;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,mBAAmB,CAwCtB;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAkB1C"}

package/dist/services/runtime-binding.js

@@ -254,13 +254,20 @@ export function getRuntimeAccessToken(userId, serverBaseUrl) {
     if (scopedToken) {
         return scopedToken;
     }
-    if (serverBaseUrl) {
-        return undefined;
-    }
     const state = loadRuntimeBinding();
     if (state.status !== "paired") {
         return undefined;
     }
+    if (serverBaseUrl) {
+        const requestedSchedulerBaseUrl = normalizeSchedulerBaseUrl(serverBaseUrl);
+        const boundSchedulerBaseUrl = normalizeSchedulerBaseUrl(state.schedulerBaseUrl);
+        if (requestedSchedulerBaseUrl &&
+            boundSchedulerBaseUrl &&
+            requestedSchedulerBaseUrl === boundSchedulerBaseUrl) {
+            return normalizeToken(state.accessToken) || undefined;
+        }
+        return undefined;
+    }
     return normalizeToken(state.accessToken) || undefined;
 }
 export function validateRuntimePairingCode(code) {

package/dist/services/runtime-binding.test.js

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { buildRuntimeTokenKey, clearScopedRuntimeAccessToken, getScopedRuntimeAccessToken, normalizeSchedulerBaseUrl, saveScopedRuntimeAccessToken, } from "./runtime-binding.js";
+import { buildRuntimeTokenKey, clearScopedRuntimeAccessToken, getRuntimeAccessToken, getScopedRuntimeAccessToken, normalizeSchedulerBaseUrl, saveScopedRuntimeAccessToken, } from "./runtime-binding.js";
 const originalEnv = { ...process.env };
 const tempRoots = [];
 function useRuntimeHome() {
@@ -28,6 +28,18 @@ describe('runtime binding scheduler URL normalization', () => {
         expect(normalizeSchedulerBaseUrl('ws://127.0.0.1:8080/ws/agent')).toBe('http://127.0.0.1:8080');
         expect(normalizeSchedulerBaseUrl('wss://example.com/ws/agent')).toBe('https://example.com');
     });
+    it("returns paired binding token only when requested scheduler URL matches", async () => {
+        useRuntimeHome();
+        const { saveRuntimeBinding } = await import("./runtime-binding.js");
+        saveRuntimeBinding({
+            accessToken: "paired-runtime-token-123456",
+            instanceId: "bridge-1",
+            userId: "user-a",
+            schedulerBaseUrl: "http://scheduler.local:7380",
+        });
+        expect(getRuntimeAccessToken(undefined, "http://scheduler.local:7380/api")).toBe("paired-runtime-token-123456");
+        expect(getRuntimeAccessToken(undefined, "http://scheduler.local:8080")).toBeUndefined();
+    });
     it("scopes runtime tokens by user and full scheduler origin", () => {
         useRuntimeHome();
         const key7380 = saveScopedRuntimeAccessToken({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aws-runtime-bridge",
-  "version": "1.3.9",
+  "version": "1.4.0",
   "description": "AgentsWorkStudio runtime bridge service for machine-level agent runtime integration",
   "type": "module",
   "main": "dist/index.js",