@tool-bridge/server 0.1.0 → 0.3.0

package/dist/graphhopper-DF65ZNGK.js

@@ -0,0 +1,336 @@
+import {
+  createProviderPlugin,
+  guardedFetch,
+  requireApiKey,
+  upstreamError
+} from "./chunk-CSJEZHQO.js";
+import "./chunk-K7FVSFUX.js";
+import {
+  TBError,
+  external_exports
+} from "./chunk-JLTYA2B3.js";
+import "./chunk-MLKGABMK.js";
+
+// ../plugins/src/graphhopper/api.ts
+var SERVICE = "graphhopper";
+var API_BASE = "https://graphhopper.com";
+var API_PREFIX = "/api/1";
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function text(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function errorMessage(payload, response) {
+  if (typeof payload === "string" && payload.trim() !== "") return payload;
+  const body = record(payload);
+  if (body !== void 0) {
+    const direct = text(body.message) ?? text(body.error) ?? text(body.details);
+    if (direct !== void 0) return direct;
+    if (Array.isArray(body.hints)) {
+      for (const hint of body.hints) {
+        const message = text(record(hint)?.message);
+        if (message !== void 0) return message;
+      }
+    }
+  }
+  return text(response.statusText) ?? "GraphHopper request failed";
+}
+async function request(ctx, path, query) {
+  const url = new URL(`${API_PREFIX}${path}`, API_BASE);
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) url.searchParams.append(key, String(item));
+      continue;
+    }
+    url.searchParams.set(key, String(value));
+  }
+  url.searchParams.set("key", requireApiKey(ctx, SERVICE));
+  let response;
+  let payload = null;
+  try {
+    response = await guardedFetch(url.toString(), {
+      method: "GET",
+      headers: { accept: "application/json" }
+    });
+    const raw = await response.text();
+    if (raw.trim() !== "") {
+      try {
+        payload = JSON.parse(raw);
+      } catch {
+        payload = raw;
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? `GraphHopper request failed: ${error.message}` : "GraphHopper request failed";
+    throw upstreamError(502, message);
+  }
+  if (!response.ok) throw upstreamError(response.status, errorMessage(payload, response));
+  return payload;
+}
+async function calculateRoute(input, ctx) {
+  return request(ctx, "/route", {
+    "point": input.point,
+    "profile": input.profile,
+    "locale": input.locale,
+    "point_hint": input.pointHint,
+    "snap_prevention": input.snapPrevention,
+    "curbside": input.curbside,
+    "details": input.details,
+    "optimize": input.optimize,
+    "instructions": input.instructions,
+    "calc_points": input.calcPoints,
+    "points_encoded": input.pointsEncoded,
+    "elevation": input.elevation,
+    "debug": input.debug,
+    "ch.disable": input.chDisable,
+    "heading": input.heading,
+    "heading_penalty": input.headingPenalty,
+    "pass_through": input.passThrough,
+    "algorithm": input.algorithm,
+    "round_trip.distance": input.roundTripDistance,
+    "round_trip.seed": input.roundTripSeed,
+    "alternative_route.max_paths": input.alternativeRouteMaxPaths,
+    "alternative_route.max_weight_factor": input.alternativeRouteMaxWeightFactor,
+    "alternative_route.max_share_factor": input.alternativeRouteMaxShareFactor
+  });
+}
+async function geocode(input, ctx) {
+  if (input.reverse === true) {
+    if (input.point === void 0) {
+      throw new TBError("invalid_argument", "point is required when reverse is true");
+    }
+    if (input.q !== void 0) {
+      throw new TBError("invalid_argument", "q must be omitted when reverse is true");
+    }
+  } else if (input.q === void 0) {
+    throw new TBError("invalid_argument", "q is required for forward geocoding");
+  }
+  return request(ctx, "/geocode", {
+    q: input.q,
+    point: input.point,
+    reverse: input.reverse,
+    locale: input.locale,
+    limit: input.limit,
+    provider: input.provider,
+    debug: input.debug
+  });
+}
+async function computeMatrix(input, ctx) {
+  const symmetric = input.point !== void 0;
+  if (symmetric && (input.fromPoint !== void 0 || input.toPoint !== void 0)) {
+    throw new TBError("invalid_argument", "point cannot be combined with fromPoint or toPoint");
+  }
+  if (!symmetric && (input.fromPoint === void 0 || input.toPoint === void 0)) {
+    throw new TBError("invalid_argument", "provide either point or both fromPoint and toPoint");
+  }
+  return request(ctx, "/matrix", {
+    point: input.point,
+    from_point: input.fromPoint,
+    to_point: input.toPoint,
+    profile: input.profile,
+    point_hint: input.pointHint,
+    from_point_hint: input.fromPointHint,
+    to_point_hint: input.toPointHint,
+    snap_prevention: input.snapPrevention,
+    curbside: input.curbside,
+    from_curbside: input.fromCurbside,
+    to_curbside: input.toCurbside,
+    out_array: input.outArray,
+    fail_fast: input.failFast
+  });
+}
+async function computeIsochrone(input, ctx) {
+  if (input.timeLimit !== void 0 && input.distanceLimit !== void 0) {
+    throw new TBError("invalid_argument", "timeLimit and distanceLimit cannot be provided together");
+  }
+  return request(ctx, "/isochrone", {
+    point: input.point,
+    profile: input.profile,
+    time_limit: input.timeLimit,
+    distance_limit: input.distanceLimit,
+    buckets: input.buckets,
+    reverse_flow: input.reverseFlow
+  });
+}
+async function listProfiles(_input, ctx) {
+  const payload = await request(ctx, "/profiles", {});
+  if (Array.isArray(payload)) return { profiles: payload };
+  const profiles = record(payload)?.profiles;
+  return { profiles: Array.isArray(profiles) ? profiles : [] };
+}
+
+// ../plugins/src/graphhopper/schema.ts
+var calculateRouteInput = external_exports.strictObject({
+  point: external_exports.array(external_exports.string().min(3).describe("A coordinate string in `latitude,longitude` format.")).min(2).describe("Route waypoints in `latitude,longitude` format."),
+  profile: external_exports.string().min(1).describe("The GraphHopper routing profile, such as `car`, `bike`, `foot`, or a custom profile id.").optional(),
+  locale: external_exports.string().min(1).describe("The locale for turn instructions, such as `en`, `de`, or `fr`.").optional(),
+  pointHint: external_exports.array(external_exports.string().min(1).describe("One road name hint.")).min(1).describe("Optional road name hints for snapping each route waypoint.").optional(),
+  snapPrevention: external_exports.array(external_exports.string().min(1).describe("One snap prevention value such as `motorway`, `trunk`, `ferry`, `tunnel`, `bridge`, or `ford`.")).min(1).describe("Road types that should be avoided while snapping input points.").optional(),
+  curbside: external_exports.array(external_exports.enum(["any", "right", "left"]).describe("One curbside preference.")).describe("Curbside preferences for each route waypoint.").optional(),
+  details: external_exports.array(external_exports.string().min(1).describe("One GraphHopper path detail type.")).min(1).describe("Path detail types to include in the route response.").optional(),
+  optimize: external_exports.boolean().describe("Whether GraphHopper should reorder more than two points to reduce travel time.").optional(),
+  instructions: external_exports.boolean().describe("Whether GraphHopper should return turn-by-turn instructions.").optional(),
+  calcPoints: external_exports.boolean().describe("Whether GraphHopper should calculate route geometry points.").optional(),
+  pointsEncoded: external_exports.boolean().describe("Whether GraphHopper should return encoded polyline geometry.").optional(),
+  elevation: external_exports.boolean().describe("Whether GraphHopper should include altitude as a third coordinate.").optional(),
+  debug: external_exports.boolean().describe("Whether GraphHopper should format debug output.").optional(),
+  chDisable: external_exports.boolean().describe("Whether to enable flexible mode for advanced routing options.").optional(),
+  heading: external_exports.array(external_exports.int().min(0).max(360).describe("One heading direction in degrees.")).describe("Preferred heading directions in degrees, north-based clockwise.").optional(),
+  headingPenalty: external_exports.int().min(0).describe("The time penalty in seconds for not obeying heading.").optional(),
+  passThrough: external_exports.boolean().describe("Whether GraphHopper should avoid u-turns at via-points.").optional(),
+  algorithm: external_exports.enum(["round_trip", "alternative_route"]).describe("The special route algorithm to use.").optional(),
+  roundTripDistance: external_exports.int().min(0).describe("The approximate round-trip length in meters.").optional(),
+  roundTripSeed: external_exports.int().describe("The random seed used for deterministic round-trip results.").optional(),
+  alternativeRouteMaxPaths: external_exports.int().min(1).describe("The maximum number of alternative routes.").optional(),
+  alternativeRouteMaxWeightFactor: external_exports.number().min(0).describe("The maximum factor by which alternative routes may be longer than the optimal route.").optional(),
+  alternativeRouteMaxShareFactor: external_exports.number().min(0).max(1).describe("The maximum similarity factor between an alternative route and the optimal route.").optional()
+}).describe("Input parameters for calculating a GraphHopper route.");
+var calculateRouteOutput = external_exports.looseObject({
+  paths: external_exports.array(external_exports.looseObject({
+    distance: external_exports.number().describe("The total route distance in meters.").optional(),
+    time: external_exports.int().describe("The total route travel time in milliseconds.").optional(),
+    ascend: external_exports.number().describe("The total ascent in meters.").optional(),
+    descend: external_exports.number().describe("The total descent in meters.").optional(),
+    points: external_exports.unknown().describe("The route geometry, either encoded or a coordinate object.").optional(),
+    snapped_waypoints: external_exports.unknown().describe("The snapped input waypoints, either encoded or a coordinate object.").optional(),
+    points_encoded: external_exports.boolean().describe("Whether route geometry fields use encoded polyline strings.").optional(),
+    bbox: external_exports.array(external_exports.number().describe("One bounding box coordinate.")).describe("The route bounding box as `[minLon, minLat, maxLon, maxLat]`.").optional(),
+    instructions: external_exports.array(external_exports.looseObject({}).describe("An upstream GraphHopper object returned as-is.")).describe("The turn-by-turn route instructions returned by GraphHopper.").optional(),
+    details: external_exports.looseObject({}).describe("Path details keyed by requested detail type.").optional(),
+    points_order: external_exports.array(external_exports.int().describe("One zero-based input point index.")).describe("The optimized visit order when route optimization was requested.").optional()
+  }).describe("One route path returned by GraphHopper.")).describe("The calculated route paths.").optional(),
+  info: external_exports.looseObject({
+    copyrights: external_exports.array(external_exports.string().describe("One notice.")).describe("The copyright notices returned by GraphHopper.").optional(),
+    took: external_exports.number().describe("The time GraphHopper spent processing the request.").optional()
+  }).describe("Additional GraphHopper response metadata.").optional()
+}).describe("The route response returned by GraphHopper.");
+var geocodeInput = external_exports.strictObject({
+  q: external_exports.string().min(1).describe("The textual address or place query for forward geocoding.").optional(),
+  point: external_exports.string().min(1).describe("The `latitude,longitude` location bias for forward geocoding or target coordinate for reverse geocoding.").optional(),
+  reverse: external_exports.boolean().describe("Whether to perform reverse geocoding. When true, point is required and q must be omitted.").optional(),
+  locale: external_exports.string().min(1).describe("The locale used for localized geocoding results.").optional(),
+  limit: external_exports.int().min(1).describe("The maximum number of geocoding results to return.").optional(),
+  provider: external_exports.string().min(1).describe("The GraphHopper geocoding provider, such as `default`, `nominatim`, `gisgraphy`, or `opencagedata`.").optional(),
+  debug: external_exports.boolean().describe("Whether GraphHopper should format debug output.").optional()
+}).describe("Input parameters for forward or reverse geocoding with GraphHopper.");
+var geocodeOutput = external_exports.looseObject({
+  hits: external_exports.array(external_exports.looseObject({
+    point: external_exports.strictObject({
+      lat: external_exports.number().describe("The latitude coordinate.").optional(),
+      lng: external_exports.number().describe("The longitude coordinate.").optional()
+    }).describe("A latitude and longitude point returned by GraphHopper.").optional(),
+    osm_id: external_exports.int().describe("The OpenStreetMap entity id.").optional(),
+    osm_type: external_exports.string().describe("The OpenStreetMap entity type.").optional(),
+    osm_key: external_exports.string().describe("The OpenStreetMap key.").optional(),
+    osm_value: external_exports.string().describe("The OpenStreetMap value.").optional(),
+    name: external_exports.string().describe("The matched place, address, or entity name.").optional(),
+    country: external_exports.string().describe("The country of the result.").optional(),
+    city: external_exports.string().describe("The city of the result.").optional(),
+    state: external_exports.string().describe("The state or region of the result.").optional(),
+    street: external_exports.string().describe("The street of the result.").optional(),
+    housenumber: external_exports.string().describe("The house number of the result.").optional(),
+    postcode: external_exports.string().describe("The postal code of the result.").optional()
+  }).describe("One geocoding hit returned by GraphHopper.")).describe("The geocoding candidates returned by GraphHopper.").optional(),
+  took: external_exports.number().describe("The time GraphHopper spent processing the geocoding request in milliseconds.").optional()
+}).describe("The geocoding response returned by GraphHopper.");
+var computeMatrixInput = external_exports.strictObject({
+  point: external_exports.array(external_exports.string().min(3).describe("A coordinate string in `latitude,longitude` format.")).min(3).describe("Points in `latitude,longitude` format used as both origins and destinations.").optional(),
+  fromPoint: external_exports.array(external_exports.string().min(3).describe("A coordinate string in `latitude,longitude` format.")).min(1).describe("Origin points in `latitude,longitude` format.").optional(),
+  toPoint: external_exports.array(external_exports.string().min(3).describe("A coordinate string in `latitude,longitude` format.")).min(1).describe("Destination points in `latitude,longitude` format.").optional(),
+  profile: external_exports.string().min(1).describe("The GraphHopper routing profile, such as `car`, `bike`, `foot`, or a custom profile id.").optional(),
+  pointHint: external_exports.array(external_exports.string().min(1).describe("One point hint.")).min(1).describe("Hints for point entries.").optional(),
+  fromPointHint: external_exports.array(external_exports.string().min(1).describe("One origin point hint.")).min(1).describe("Hints for origin points.").optional(),
+  toPointHint: external_exports.array(external_exports.string().min(1).describe("One destination point hint.")).min(1).describe("Hints for destination points.").optional(),
+  snapPrevention: external_exports.array(external_exports.string().min(1).describe("One snap prevention value.")).min(1).describe("Road types that should be avoided while snapping matrix points.").optional(),
+  curbside: external_exports.array(external_exports.enum(["any", "right", "left"]).describe("One curbside preference.")).describe("Curbside preferences for point entries.").optional(),
+  fromCurbside: external_exports.array(external_exports.enum(["any", "right", "left"]).describe("One curbside preference.")).describe("Curbside preferences for origin points.").optional(),
+  toCurbside: external_exports.array(external_exports.enum(["any", "right", "left"]).describe("One curbside preference.")).describe("Curbside preferences for destination points.").optional(),
+  outArray: external_exports.array(external_exports.enum(["weights", "times", "distances"]).describe("One matrix output array name.")).min(1).describe("Matrix arrays to include in the response.").optional(),
+  failFast: external_exports.boolean().describe("Whether GraphHopper should fail immediately when points cannot be resolved.").optional()
+}).describe("Input parameters for computing a synchronous GraphHopper matrix.");
+var computeMatrixOutput = external_exports.looseObject({
+  distances: external_exports.array(external_exports.array(external_exports.number().describe("One matrix value, or null when the route could not be calculated.").nullable()).describe("One matrix row.")).describe("A GraphHopper matrix of numeric values or null entries.").optional(),
+  times: external_exports.array(external_exports.array(external_exports.number().describe("One matrix value, or null when the route could not be calculated.").nullable()).describe("One matrix row.")).describe("A GraphHopper matrix of numeric values or null entries.").optional(),
+  weights: external_exports.array(external_exports.array(external_exports.number().describe("One matrix value, or null when the route could not be calculated.").nullable()).describe("One matrix row.")).describe("A GraphHopper matrix of numeric values or null entries.").optional(),
+  info: external_exports.looseObject({
+    copyrights: external_exports.array(external_exports.string().describe("One notice.")).describe("The copyright notices returned by GraphHopper.").optional(),
+    took: external_exports.number().describe("The time GraphHopper spent processing the request.").optional()
+  }).describe("Additional GraphHopper response metadata.").optional(),
+  hints: external_exports.array(external_exports.looseObject({}).describe("An upstream GraphHopper object returned as-is.")).describe("Additional GraphHopper matrix hints.").optional()
+}).describe("The matrix response returned by GraphHopper.");
+var computeIsochroneInput = external_exports.strictObject({
+  point: external_exports.string().min(3).describe("A coordinate string in `latitude,longitude` format."),
+  profile: external_exports.string().min(1).describe("The GraphHopper routing profile, such as `car`, `bike`, `foot`, or a custom profile id.").optional(),
+  timeLimit: external_exports.int().min(1).describe("The travel time limit in seconds.").optional(),
+  distanceLimit: external_exports.int().min(1).describe("The travel distance limit in meters.").optional(),
+  buckets: external_exports.int().min(1).describe("The number of nested isochrone buckets to return.").optional(),
+  reverseFlow: external_exports.boolean().describe("Whether the flow should go from polygons toward the point.").optional()
+}).describe("Input parameters for computing GraphHopper isochrone polygons.");
+var computeIsochroneOutput = external_exports.looseObject({
+  polygons: external_exports.array(external_exports.looseObject({}).describe("An upstream GraphHopper object returned as-is.")).describe("The GeoJSON isochrone polygons returned by GraphHopper.").optional()
+}).describe("The isochrone response returned by GraphHopper.");
+var listProfilesInput = external_exports.strictObject({}).describe("Input parameters for listing GraphHopper custom profiles.");
+var listProfilesOutput = external_exports.strictObject({
+  profiles: external_exports.array(external_exports.looseObject({
+    id: external_exports.string().describe("The custom profile id.").optional(),
+    profile: external_exports.string().describe("The built-in routing profile this custom profile is based on.").optional(),
+    bounds: external_exports.looseObject({}).describe("The geographic bounds where this custom profile can be used.").optional(),
+    custom_model: external_exports.looseObject({}).describe("The custom model definition for this profile.").optional()
+  }).describe("One custom GraphHopper routing profile.")).describe("The available custom routing profiles.").optional()
+}).describe("The custom routing profiles returned by GraphHopper.");
+var graphhopperActions = {
+  calculate_route: {
+    description: "Calculate the best route connecting two or more coordinates with the GraphHopper Routing API.",
+    effect: "write",
+    inputSchema: calculateRouteInput,
+    outputSchema: external_exports.toJSONSchema(calculateRouteOutput, { io: "output", unrepresentable: "any" })
+  },
+  geocode: {
+    description: "Convert text to coordinates or coordinates to place candidates with the GraphHopper Geocoding API.",
+    effect: "write",
+    inputSchema: geocodeInput,
+    outputSchema: external_exports.toJSONSchema(geocodeOutput, { io: "output", unrepresentable: "any" })
+  },
+  compute_matrix: {
+    description: "Compute a synchronous travel time, distance, or weight matrix with the GraphHopper Matrix API.",
+    effect: "write",
+    inputSchema: computeMatrixInput,
+    outputSchema: external_exports.toJSONSchema(computeMatrixOutput, { io: "output", unrepresentable: "any" })
+  },
+  compute_isochrone: {
+    description: "Compute GeoJSON isochrone polygons around a coordinate with the GraphHopper Isochrone API.",
+    effect: "write",
+    inputSchema: computeIsochroneInput,
+    outputSchema: external_exports.toJSONSchema(computeIsochroneOutput, { io: "output", unrepresentable: "any" })
+  },
+  list_profiles: {
+    description: "List custom routing profiles available to the GraphHopper API key.",
+    effect: "read",
+    inputSchema: listProfilesInput,
+    outputSchema: external_exports.toJSONSchema(listProfilesOutput, { io: "output", unrepresentable: "any" })
+  }
+};
+
+// ../plugins/src/graphhopper/index.ts
+function createGraphhopperPlugin() {
+  return createProviderPlugin({
+    description: "GraphHopper",
+    actions: graphhopperActions,
+    // 上游 credentialValidators 打的就是 /profiles;它是唯一只读、无必填入参且不消耗路径配额的调用。
+    credentialProbe: "list_profiles",
+    handlers: {
+      calculate_route: calculateRoute,
+      geocode,
+      compute_matrix: computeMatrix,
+      compute_isochrone: computeIsochrone,
+      list_profiles: listProfiles
+    }
+  });
+}
+var graphhopper_default = createGraphhopperPlugin();
+export {
+  createGraphhopperPlugin,
+  graphhopper_default as default
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import * as http from 'node:http';
 import { Hono } from 'hono';
 
@@ -145,6 +146,161 @@ declare class SecretStoreImpl {
     resolve(name: string): Promise<string | undefined>;
 }
 
+/**
+ * Provider 型 OAuth2 的声明契约(与 mcp 上游的托管 OAuth 是**两套机制**)。
+ *
+ * mcp 那条(`app/src/oauth.ts`)靠 MCP SDK 的 `auth()`:从资源服务器 discovery 出授权服务器、
+ * 再动态注册客户端(DCR)。provider 型没有这些 —— 授权/令牌端点是**写死的已知值**,
+ * client_id/secret 是**用户自己去 provider 后台注册**的。两者只共用"授权码 + PKCE"这个骨架,
+ * 强行合并会让两边都变形,故分开声明、共用底层的 state 密封与回调渲染。
+ *
+ * 对应上游 open-connector 的 `OAuth2AuthDefinition`:那边每个 provider 自带一份端点与字段名
+ * 配置(不同 provider 的 token 请求字段名、响应信封形状都不一样),这里是它在 tool-bridge 侧
+ * 的落点。
+ */
+
+declare const pluginOAuthSchema: z.ZodObject<{
+    authorizationUrl: z.ZodString;
+    tokenUrl: z.ZodString;
+    refreshUrl: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scopeSeparator: z.ZodOptional<z.ZodEnum<{
+        " ": " ";
+        ",": ",";
+    }>>;
+    clientAuth: z.ZodOptional<z.ZodEnum<{
+        client_secret_basic: "client_secret_basic";
+        client_secret_post: "client_secret_post";
+        none: "none";
+    }>>;
+    authorizationParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    responseEnvelope: z.ZodOptional<z.ZodString>;
+    pkce: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * provider 型 OAuth2 的声明。
+ *
+ * client_id / client_secret **不在这里** —— 它们是每个部署自己的应用凭证,走
+ * `authRef` 指向的 secret(多字段:`clientId` + `clientSecret`),与其他上游凭证同一通道。
+ */
+type PluginOAuth = z.infer<typeof pluginOAuthSchema>;
+
+/**
+ * 注册时契约校验(plugin/v2)。
+ *
+ * 输入 = manifest + 平台抓取的 `/~describe` JSON;纯逻辑,抓取本身在宿主。
+ *
+ * **v2 的 `~describe` 返回 exports 列表**,每个 export 声明自己的 `profile`
+ * (tools/v1 或 context/v1)与实际提供的操作:
+ *
+ * ```json
+ * { "protocolVersion": "plugin/v2",
+ *   "exports": [
+ *     { "id": "actions",   "profile": "tools/v1",   "description": "Feishu actions" },
+ *     { "id": "documents", "profile": "context/v1", "methods": ["Get","List","Search"] } ] }
+ * ```
+ *
+ * v1 需要额外抓 `~help` 来数方法,是因为方法集合无处声明;v2 由 export 自报 `methods`,
+ * 校验不再依赖 `~help` 抓取(少一次往返,也不再受 help 表现形态影响)。
+ *
+ * context/v1 的 `methods` 与 Round 7 的「按 handler 存在性推导能力」同一套语义:
+ * 声明多少就是多少,平台只调用声明过的动词。
+ */
+
+/** export 的语义档位。 */
+type PluginProfile = 'tools/v1' | 'context/v1';
+/** 单个 export 的声明。 */
+interface PluginExport {
+    capabilities?: string[];
+    /**
+     * 多字段凭证的字段声明(仅 tools/v1)。
+     *
+     * 平台的凭证通道 `X-TB-Upstream-Auth` 传的是**一个字符串**:多数 provider 只要一个
+     * API key,够用。但一批 provider 需要多个字段(飞书要 app_id + app_secret、S3 要
+     * access key + secret + region…),此前只能靠"把 JSON 塞进那个单值"的**约定**——
+     * 平台不知道里面是什么,配错了要到第一次调用才发现,管理面也没法提示该填哪些字段。
+     *
+     * 声明了它:
+     * - `tb secret set <name> --field appId=x --field appSecret=y` 存成 JSON 对象;
+     * - 挂载时平台校验必填字段齐全,缺了当场拒并说清缺哪个;
+     * - 传输契约**不变**(仍是那个 base64url 字符串,内容是 JSON),故已有 plugin 零影响。
+     */
+    credentialFields?: PluginCredentialField[];
+    /**
+     * 凭证探针:一个只读、零副作用、无必填入参的工具名(仅 tools/v1)。
+     *
+     * 存在的问题:平台的凭证是 `tb secret set` 存进 SecretStore、挂载只写 `authRef`,
+     * 插件要到**第一次业务调用**才拿得到它 —— 配错的 key 不会在存入或挂载时报错,
+     * 而是等到某个 agent 真去调用时才 401。
+     *
+     * 声明了它,挂载时平台就用注入的凭证真实调一次这个工具:通则凭证可用,401/403 则
+     * 当场拒绝挂载并说清是凭证问题。用现有的 Call 通道,不新增协议动词 —— 上游
+     * open-connector 的 `credentialValidators`("打最便宜的接口试凭证")正是这个语义。
+     */
+    credentialProbe?: string;
+    description?: string;
+    id: string;
+    methods?: string[];
+    /**
+     * provider 型 OAuth2 的声明(仅 tools/v1)。
+     *
+     * 与 mcp 上游的托管 OAuth 是两套机制:那条从资源服务器 discovery + 动态注册客户端(DCR),
+     * 这条的端点是写死的已知值、client 由用户自己在 provider 后台注册。共用"授权码 + PKCE"
+     * 骨架与 state 密封,但配置来源不同,合并会让两边都变形。
+     *
+     * 声明了它,挂载配的 `authRef` 指向的 secret 存的是 **client 凭证**
+     * (`clientId` + `clientSecret`,见 `OAUTH_CLIENT_FIELDS`),而不是直接的 access token ——
+     * 后者由平台跑完授权流程后自己保管并按需刷新。
+     */
+    oauth?: PluginOAuth;
+    profile: PluginProfile;
+}
+/** 多字段凭证的单个字段声明。 */
+interface PluginCredentialField {
+    description?: string;
+    key: string;
+    label?: string;
+    required?: boolean;
+    /** 敏感字段:管理面不回显、日志不打印。缺省按敏感处理。 */
+    secret?: boolean;
+}
+/** `/~describe` 响应形状(v2)。 */
+interface PluginDescribe {
+    exports: PluginExport[];
+    protocolVersion: string;
+}
+
+/**
+ * 内置插件目录(catalog)与 integration 解析。
+ *
+ * **catalog 是编译期常量,不是运行时状态**:内置插件的 descriptor 由构建期求值
+ * `/~describe` 生成(`@tool-bridge/plugins` 的 `catalog.generated.ts`),与插件代码同一份
+ * 构建产物 —— 故不可能陈旧,也不需要落 KV。
+ *
+ * 这里定的是**解析函数的能力边界**。此前 `requirePluginExport` 拿的是 `deps`
+ * (含可写 `state`),于是 help/call 这类读操作也能写库:`manifest ??= autoRegisterBinding(…)`
+ * 让"删掉一个 plugin 后随便读一次就复活",而 7 个调用点里传 `deps` 还是传裸 store
+ * 是随手决定的 —— 同一个语义在四条链上有四种行为。
+ *
+ * 修法不是"约定读路径要传只读的东西",而是**让解析函数结构上拿不到写能力**:
+ * 下面三个函数的入参只有 catalog(纯值)与 {@link ReadOnlyStore}(只有 get)。
+ * 想在这里写库得先改签名,而那是 code review 能看见的事。
+ */
+
+/** 一个内置目录项:插件声明了什么,以及它的 descriptor 指纹。 */
+interface BuiltinCatalogEntry {
+    /** 求值出的 `~describe`。 */
+    describe: PluginDescribe;
+    /** descriptor 的 canonical JSON 的 sha256(hex);三宿主对拍与升级检测用。 */
+    digest: string;
+    /** 恒为 `binding:<id>`。 */
+    endpoint: string;
+    id: string;
+    kind: 'builtin';
+}
+/** binding 名 → 目录项。 */
+type BuiltinCatalog = Record<string, BuiltinCatalogEntry>;
+
 /**
  * Context Layer 类型(原样转写;方法签名异步化以兼容对象存储后端)。
  *
@@ -292,6 +448,14 @@ interface ToolSpec {
     inputSchema?: unknown;
     /** 工具名(虚拟化前为上游原名,虚拟化后为对外虚拟名)。 */
     name: string;
+    /**
+     * 返回值的 JSON Schema(可选)。与 `inputSchema` 对称,同为裸 JSON Schema。
+     *
+     * 来源:MCP 上游的 `Tool.outputSchema`、plugin 作者在 `OperationSpec.outputSchema` 里的声明。
+     * 去处:工具级全量 `~help`(JSON 的 `outputSchema` / DSL 的 `result` 行)与 MCP consumer 端点。
+     * 索引形态的 `~help` 不含它(同 inputSchema,两级披露)。
+     */
+    outputSchema?: unknown;
 }
 /**
  * 工具调用结果。`isError:true` 是**工具业务级错误**(上游 HTTP 200
@@ -546,6 +710,16 @@ interface TbAppDeps {
      * `binding:<name>` 的插件经此直调,零网络跳;未装配的 binding 注册/调用报 unavailable。
      */
     pluginBindings?: PluginBindings;
+    /**
+     * 内置插件目录(descriptor)。**编译期常量**,由 `@tool-bridge/plugins` 的
+     * `catalog.generated.ts` 求值生成 —— 内置插件的目录项与它的代码是同一份构建产物,
+     * 故不会陈旧、也不落库(见 `llmdoc/memory/decisions/builtin-catalog-not-registry.md`)。
+     *
+     * 与 {@link pluginBindings} **是一对**:catalog 说"声明了什么"(挂载校验、选 export、
+     * 列凭证字段),bindings 说"代码在哪"(实际调用)。装配了 binding 却没给 catalog,
+     * 那个插件解析不出 export;反之则解析得出但调不动(unavailable)。宿主该两者同源装配。
+     */
+    pluginCatalog?: BuiltinCatalog;
     /** context Get 的 $ref 内联阈值(字节,缺省 1 MiB)。 */
     refThresholdBytes?: number;
     /** $ref URL(presign 与 /~ref 中转)有效期秒(缺省 900)。 */
@@ -605,10 +779,15 @@ interface ServerConfig {
     encryptionKey?: string;
     host: string;
     /**
-     * 进程内插件装配表(binding 名 → fetch handler),供程序化嵌入方注入;
-     * `binding:<name>` 的插件经此直调,零网络跳。bin 入口暂不从 env 装配。
+     * 进程内插件装配表(binding 名 → fetch handler)。缺省时 bin 入口装配**全量内置目录**
+     * (见 `main.ts`);程序化嵌入方可给自己的表来覆盖或裁剪。
      */
     pluginBindings?: PluginBindings;
+    /**
+     * 内置插件目录的 descriptor。与 {@link pluginBindings} 同源装配 —— 只给 bindings
+     * 的话插件调得动但解析不出 export(挂载校验会报"未知 provider")。
+     */
+    pluginCatalog?: BuiltinCatalog;
     port: number;
     refThresholdBytes?: number;
     refTtlSec?: number;

package/dist/index.js

@@ -6,7 +6,8 @@ import {
   configFromEnv,
   createDataObjectStore,
   createTbServer
-} from "./chunk-6SMIQ6QU.js";
+} from "./chunk-KGYJEEBI.js";
+import "./chunk-JLTYA2B3.js";
 import "./chunk-MLKGABMK.js";
 export {
   DEVICE_WS_PATH,