@kittymi/openclaw-generic-http 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KittyMi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# openclaw-generic-http
+
+`openclaw-generic-http` 是 OpenClaw 的 `generic-http` channel 插件。
+
+它负责把 OpenClaw 接到一个遵循 `generic-http protocol v1` 的 bridge / relay / platform 上：
+
+- 通过 `GET /stream/inbound` 消费入站事件
+- 通过 `POST /stream/acks` 确认已处理事件
+- 通过 `POST /outbound/messages` 发送 OpenClaw 出站消息
+- 处理配置、安全签名、会话路由和宿主生命周期适配
+
+## 当前完整度
+
+当前版本已经具备 `0.1.x` 首次独立发布所需的最小闭环：
+
+- `webhook + stream` ingress 运行时
+- OpenClaw 宿主注册入口与 host adapter
+- `health / probe / resolve / capabilities`
+- 文本、图片、文件附件规范化
+- 构建、测试与 npm 打包检查
+
+当前仍未完成的平台级能力：
+
+- 还没有覆盖多个 OpenClaw 版本的兼容矩阵
+- 只有基础 CI 和手动发布流程，尚未形成完整发布自动化
+- 只有最小真实 bridge 回归脚本，尚未形成更完整的端到端样例集
+- 多账号、复杂附件和更细粒度错误映射仍是后续增强项
+
+结论：
+
+- 适合作为 `0.1.x` 预览版公开发布
+- 还不应宣称为“生产级已完全收口”
+
+## 兼容性
+
+当前声明的支持范围：
+
+- OpenClaw Desktop `2026.5.x`
+- Node.js `>=22.16.0`
+
+当前已验证环境：
+
+- OpenClaw `2026.5.12 (f066dd2)`
+
+| Item | Status |
+| --- | --- |
+| OpenClaw Desktop `2026.5.12` | Verified locally |
+| OpenClaw Desktop `2026.5.x` | Supported release line |
+| Node.js `22.x` | Verified in local/dev and CI |
+| Node.js `24.x` | Verified in local/dev and CI |
+
+说明：
+
+- `2026.5.x` 是当前 `0.1.2` 发布线声明支持的 OpenClaw 版本范围
+- 当前只在 `2026.5.12` 做过实际本机验证
+- 对 `2026.4.x` 及更早版本、以及 `2026.6.x` 及更高版本，当前不承诺兼容
+
+## 安装
+
+```bash
+openclaw plugins install @kittymi/openclaw-generic-http
+```
+
+或：
+
+```bash
+npm install -g @kittymi/openclaw-generic-http
+```
+
+当前更推荐通过 OpenClaw 插件机制安装，而不是只做全局 npm 安装。
+
+## 配置示例
+
+最小单账号配置：
+
+```json
+{
+  "channels": {
+    "generic-http": {
+      "enabled": true,
+      "defaultAccount": "default",
+      "accounts": {
+        "default": {
+          "baseUrl": "https://bridge.example.com",
+          "apiKey": "replace-me",
+          "signingSecret": "replace-me"
+        }
+      }
+    }
+  }
+}
+```
+
+本地联调样例见 [dev-config/README.md](./dev-config/README.md) 和 [dev-config/openclaw-generic-http.local.json](./dev-config/openclaw-generic-http.local.json)。
+
+## 适用场景
+
+适合：
+
+- 本地或内网运行的 OpenClaw
+- 第三方系统通过 webhook 写入 bridge
+- OpenClaw 通过 stream 主动拉取入站事件
+
+不适合：
+
+- 需要插件直接暴露公网入站地址的场景
+- 一开始就要覆盖复杂卡片、多租户工作台、重型消息总线的场景
+
+## 本地开发
+
+```bash
+npm install
+npm run build
+npm test
+npm run pack:check
+npm run test:e2e
+```
+
+当前 OpenClaw 桌面版本下，更可靠的启用方式仍然是：
+
+1. 安装插件
+2. 手工写入 `channels.generic-http`
+3. 执行 `openclaw channels list --all`
+4. 执行 `openclaw channels status --channel generic-http`
+
+`openclaw channels add --channel ...` 仍主要依赖内置静态 catalog，不一定能直接枚举第三方 channel。
+
+## 文档
+
+- 安装与配置：[docs/01-installation-guide.md](./docs/01-installation-guide.md)
+- 常见问题：[docs/02-faq.md](./docs/02-faq.md)
+- 本地联调：[docs/03-local-dev.md](./docs/03-local-dev.md)

package/dist/channel/account.d.ts

@@ -0,0 +1,7 @@
+import type { GenericHttpAccountConfig, GenericHttpPluginConfig } from "../config/schema.js";
+export interface ResolvedGenericHttpAccount {
+    accountId: string;
+    config: GenericHttpAccountConfig;
+}
+export declare function listConfiguredAccountIds(config: GenericHttpPluginConfig): string[];
+export declare function resolveConfiguredAccount(config: GenericHttpPluginConfig, accountId?: string | null): ResolvedGenericHttpAccount;

package/dist/channel/account.js

@@ -0,0 +1,18 @@
+import { ERROR_CODES } from "../errors/codes.js";
+import { GenericHttpPluginError } from "../errors/exceptions.js";
+export function listConfiguredAccountIds(config) {
+    return Object.keys(config.accounts);
+}
+export function resolveConfiguredAccount(config, accountId) {
+    const normalizedAccountId = typeof accountId === "string" && accountId.trim() !== ""
+        ? accountId.trim()
+        : config.defaultAccount;
+    const resolvedConfig = config.accounts[normalizedAccountId];
+    if (resolvedConfig === undefined) {
+        throw new GenericHttpPluginError(ERROR_CODES.INVALID_REQUEST, "Unknown accountId for generic-http channel runtime.", { accountId: normalizedAccountId });
+    }
+    return {
+        accountId: normalizedAccountId,
+        config: resolvedConfig
+    };
+}

package/dist/channel/capabilities.d.ts

@@ -0,0 +1,10 @@
+export interface GenericHttpCapabilities {
+    textInbound: boolean;
+    textOutbound: boolean;
+    attachments: boolean;
+    threading: boolean;
+    replies: boolean;
+    deliveryReceipt: boolean;
+}
+export declare const DEFAULT_GENERIC_HTTP_CAPABILITIES: GenericHttpCapabilities;
+export declare function getGenericHttpCapabilities(): GenericHttpCapabilities;

package/dist/channel/capabilities.js

@@ -0,0 +1,11 @@
+export const DEFAULT_GENERIC_HTTP_CAPABILITIES = {
+    textInbound: true,
+    textOutbound: true,
+    attachments: true,
+    threading: true,
+    replies: true,
+    deliveryReceipt: false
+};
+export function getGenericHttpCapabilities() {
+    return { ...DEFAULT_GENERIC_HTTP_CAPABILITIES };
+}

package/dist/channel/host-adapter.d.ts

@@ -0,0 +1,28 @@
+import type { GenericHttpPluginConfig } from "../config/schema.js";
+import type { NormalizedInboundMessageEvent } from "../inbound/mapper.js";
+import { type GenericHttpChannelLifecycle, type GenericHttpChannelLifecycleHandlers } from "./lifecycle.js";
+import type { GenericHttpCapabilities } from "./capabilities.js";
+import type { GenericHttpChannelPlugin, GenericHttpChannelPluginRuntimeOptions, GenericHttpChannelPluginStatus } from "./plugin.js";
+import type { InternalOutboundMessage, OutboundMessageResult } from "../outbound/mapper.js";
+import type { ProbeResult } from "./probe.js";
+import type { ResolveRequest, ResolveResponse } from "./resolve.js";
+export interface GenericHttpHostAdapterHandlers extends GenericHttpChannelLifecycleHandlers {
+}
+export interface GenericHttpHostAdapter {
+    readonly plugin: GenericHttpChannelPlugin;
+    readonly lifecycle: GenericHttpChannelLifecycle;
+    activate(accountId?: string | null): Promise<void>;
+    deactivate(): void;
+    dispose(): void;
+    status(): GenericHttpChannelPluginStatus;
+    capabilities(): GenericHttpCapabilities;
+    probe(accountId?: string | null): Promise<ProbeResult>;
+    resolve(request: ResolveRequest): Promise<ResolveResponse>;
+    sendOutboundMessage(message: InternalOutboundMessage): Promise<OutboundMessageResult>;
+}
+/**
+ * Adapt the generic HTTP runtime to a host-friendly contract with explicit
+ * activate/deactivate lifecycle methods and delegated inbound event dispatch.
+ */
+export declare function createGenericHttpHostAdapter(rawConfig: Partial<GenericHttpPluginConfig>, handlers: GenericHttpHostAdapterHandlers, options?: Omit<GenericHttpChannelPluginRuntimeOptions, "onInboundStreamMessage" | "onInboundStreamError">): GenericHttpHostAdapter;
+export type { NormalizedInboundMessageEvent };

package/dist/channel/host-adapter.js

@@ -0,0 +1,36 @@
+import { createGenericHttpChannelLifecycle } from "./lifecycle.js";
+/**
+ * Adapt the generic HTTP runtime to a host-friendly contract with explicit
+ * activate/deactivate lifecycle methods and delegated inbound event dispatch.
+ */
+export function createGenericHttpHostAdapter(rawConfig, handlers, options = {}) {
+    const lifecycle = createGenericHttpChannelLifecycle(rawConfig, handlers, options);
+    return {
+        plugin: lifecycle.plugin,
+        lifecycle,
+        activate(accountId) {
+            return lifecycle.start(accountId);
+        },
+        deactivate() {
+            lifecycle.stop();
+        },
+        dispose() {
+            lifecycle.close();
+        },
+        status() {
+            return lifecycle.plugin.status();
+        },
+        capabilities() {
+            return lifecycle.plugin.capabilities();
+        },
+        probe(accountId) {
+            return lifecycle.plugin.probe(accountId);
+        },
+        resolve(request) {
+            return lifecycle.plugin.resolve(request);
+        },
+        sendOutboundMessage(message) {
+            return lifecycle.plugin.sendOutboundMessage(message);
+        }
+    };
+}

package/dist/channel/lifecycle.d.ts

@@ -0,0 +1,18 @@
+import type { GenericHttpPluginConfig } from "../config/schema.js";
+import type { NormalizedInboundMessageEvent } from "../inbound/mapper.js";
+import { type GenericHttpChannelPlugin, type GenericHttpChannelPluginRuntimeOptions } from "./plugin.js";
+export interface GenericHttpChannelLifecycleHandlers {
+    dispatchInboundEvent(event: NormalizedInboundMessageEvent): Promise<void> | void;
+    onStreamError?(error: unknown): Promise<void> | void;
+}
+export interface GenericHttpChannelLifecycle {
+    plugin: GenericHttpChannelPlugin;
+    start(accountId?: string | null): Promise<void>;
+    stop(): void;
+    close(): void;
+}
+/**
+ * Bridge the protocol runtime into a host lifecycle shape. The host provides
+ * the event dispatcher and decides when the stream loop should start or stop.
+ */
+export declare function createGenericHttpChannelLifecycle(rawConfig: Partial<GenericHttpPluginConfig>, handlers: GenericHttpChannelLifecycleHandlers, options?: Omit<GenericHttpChannelPluginRuntimeOptions, "onInboundStreamMessage" | "onInboundStreamError">): GenericHttpChannelLifecycle;

package/dist/channel/lifecycle.js

@@ -0,0 +1,28 @@
+import { createGenericHttpChannelPlugin } from "./plugin.js";
+/**
+ * Bridge the protocol runtime into a host lifecycle shape. The host provides
+ * the event dispatcher and decides when the stream loop should start or stop.
+ */
+export function createGenericHttpChannelLifecycle(rawConfig, handlers, options = {}) {
+    const plugin = createGenericHttpChannelPlugin(rawConfig, {
+        ...options,
+        async onInboundStreamMessage(item) {
+            await handlers.dispatchInboundEvent(item.normalizedEvent);
+        },
+        async onInboundStreamError(error) {
+            await handlers.onStreamError?.(error);
+        }
+    });
+    return {
+        plugin,
+        start(accountId) {
+            return plugin.startStreamIngress(accountId);
+        },
+        stop() {
+            plugin.stopStreamIngress();
+        },
+        close() {
+            plugin.close();
+        }
+    };
+}

package/dist/channel/plugin.d.ts

@@ -0,0 +1,46 @@
+import type { GenericHttpPluginConfig } from "../config/schema.js";
+import { type HttpOutboundClientOptions, type OutboundClient } from "../outbound/client.js";
+import type { InternalOutboundMessage, OutboundMessageResult } from "../outbound/mapper.js";
+import { type GenericHttpCapabilities } from "./capabilities.js";
+import { type ProbeAccountOptions, type ProbeResult } from "./probe.js";
+import { type ResolveAccountOptions, type ResolveRequest, type ResolveResponse } from "./resolve.js";
+import { type AckInboundMessagesResult, type PullInboundMessagesResult, type StreamAckOptions, type StreamPullOptions } from "./stream.js";
+type OutboundClientFactory = (config: GenericHttpPluginConfig, accountId: string) => OutboundClient;
+export interface GenericHttpChannelPluginStatus {
+    enabled: boolean;
+    defaultAccount: string;
+    accounts: string[];
+}
+export interface GenericHttpChannelPluginRuntimeOptions {
+    outboundClientFactory?: OutboundClientFactory;
+    outboundClientOptions?: HttpOutboundClientOptions;
+    probeOptions?: ProbeAccountOptions;
+    resolveOptions?: ResolveAccountOptions;
+    streamPullOptions?: StreamPullOptions;
+    streamAckOptions?: StreamAckOptions;
+    streamIngressPollIntervalMillis?: number;
+    onInboundStreamMessage?: (message: PullInboundMessagesResult["items"][number]) => Promise<void> | void;
+    onInboundStreamError?: (error: unknown) => Promise<void> | void;
+}
+export interface GenericHttpStreamIngressStatus {
+    running: boolean;
+    accountId: string | null;
+}
+export interface GenericHttpChannelPlugin {
+    name: string;
+    config: GenericHttpPluginConfig;
+    status(): GenericHttpChannelPluginStatus;
+    capabilities(): GenericHttpCapabilities;
+    probe(accountId?: string | null): Promise<ProbeResult>;
+    resolve(request: ResolveRequest): Promise<ResolveResponse>;
+    pullInboundMessages(accountId?: string | null): Promise<PullInboundMessagesResult>;
+    ackInboundMessages(accountId: string, eventIds: string[]): Promise<AckInboundMessagesResult>;
+    startStreamIngress(accountId?: string | null): Promise<void>;
+    stopStreamIngress(): void;
+    streamIngressStatus(): GenericHttpStreamIngressStatus;
+    sendOutboundMessage(message: InternalOutboundMessage): Promise<OutboundMessageResult>;
+    close(): void;
+}
+export declare function createGenericHttpChannelPlugin(rawConfig?: Partial<GenericHttpPluginConfig>, options?: GenericHttpChannelPluginRuntimeOptions): GenericHttpChannelPlugin;
+export declare const genericHttpChannelPlugin: GenericHttpChannelPlugin;
+export {};

package/dist/channel/plugin.js

@@ -0,0 +1,120 @@
+import { loadConfig } from "../config/loader.js";
+import { HttpOutboundClient } from "../outbound/client.js";
+import { handleOutboundMessage } from "../outbound/controller.js";
+import { getGenericHttpCapabilities } from "./capabilities.js";
+import { listConfiguredAccountIds, resolveConfiguredAccount } from "./account.js";
+import { probeAccountConfig } from "./probe.js";
+import { resolveRemotely, resolveLocally } from "./resolve.js";
+import { ackInboundMessages, pullInboundMessages } from "./stream.js";
+function createDefaultOutboundClientFactory(options = {}) {
+    return (config, accountId) => {
+        const account = resolveConfiguredAccount(config, accountId);
+        return new HttpOutboundClient(account.config, options);
+    };
+}
+export function createGenericHttpChannelPlugin(rawConfig = {}, options = {}) {
+    const config = loadConfig(rawConfig);
+    const outboundClientFactory = options.outboundClientFactory ??
+        createDefaultOutboundClientFactory(options.outboundClientOptions);
+    const streamIngressPollIntervalMillis = options.streamIngressPollIntervalMillis ?? 1000;
+    let streamIngressRunning = false;
+    let streamIngressAccountId = null;
+    let streamIngressTimer;
+    function clearStreamIngressTimer() {
+        if (streamIngressTimer !== undefined) {
+            clearTimeout(streamIngressTimer);
+            streamIngressTimer = undefined;
+        }
+    }
+    async function runStreamIngressCycle(accountId) {
+        if (!streamIngressRunning || streamIngressAccountId !== accountId) {
+            return;
+        }
+        try {
+            const pulled = await pullInboundMessages(accountId, resolveConfiguredAccount(config, accountId).config, options.streamPullOptions);
+            const ackedEventIds = [];
+            for (const item of pulled.items) {
+                await options.onInboundStreamMessage?.(item);
+                ackedEventIds.push(item.eventId);
+            }
+            if (ackedEventIds.length > 0) {
+                await ackInboundMessages(accountId, ackedEventIds, resolveConfiguredAccount(config, accountId).config, options.streamAckOptions);
+            }
+        }
+        catch (error) {
+            await options.onInboundStreamError?.(error);
+        }
+        finally {
+            if (streamIngressRunning && streamIngressAccountId === accountId) {
+                streamIngressTimer = setTimeout(() => {
+                    void runStreamIngressCycle(accountId);
+                }, streamIngressPollIntervalMillis);
+            }
+        }
+    }
+    return {
+        name: "generic-http",
+        config,
+        status() {
+            return {
+                enabled: config.enabled,
+                defaultAccount: config.defaultAccount,
+                accounts: listConfiguredAccountIds(config)
+            };
+        },
+        capabilities() {
+            return getGenericHttpCapabilities();
+        },
+        probe(accountId) {
+            const account = resolveConfiguredAccount(config, accountId);
+            return probeAccountConfig(account.accountId, account.config, options.probeOptions);
+        },
+        async resolve(request) {
+            const account = resolveConfiguredAccount(config, request.accountId);
+            try {
+                return await resolveRemotely(account.config, request, options.resolveOptions);
+            }
+            catch {
+                return resolveLocally(request);
+            }
+        },
+        async pullInboundMessages(accountId) {
+            const account = resolveConfiguredAccount(config, accountId);
+            return await pullInboundMessages(account.accountId, account.config, options.streamPullOptions);
+        },
+        async ackInboundMessages(accountId, eventIds) {
+            const account = resolveConfiguredAccount(config, accountId);
+            return await ackInboundMessages(account.accountId, eventIds, account.config, options.streamAckOptions);
+        },
+        async startStreamIngress(accountId) {
+            const account = resolveConfiguredAccount(config, accountId);
+            streamIngressRunning = true;
+            streamIngressAccountId = account.accountId;
+            clearStreamIngressTimer();
+            await runStreamIngressCycle(account.accountId);
+        },
+        stopStreamIngress() {
+            streamIngressRunning = false;
+            streamIngressAccountId = null;
+            clearStreamIngressTimer();
+        },
+        streamIngressStatus() {
+            return {
+                running: streamIngressRunning,
+                accountId: streamIngressRunning ? streamIngressAccountId : null
+            };
+        },
+        async sendOutboundMessage(message) {
+            const account = resolveConfiguredAccount(config, message.accountId);
+            const client = outboundClientFactory(config, account.accountId);
+            const response = await handleOutboundMessage(client, message);
+            return response.result;
+        },
+        close() {
+            streamIngressRunning = false;
+            streamIngressAccountId = null;
+            clearStreamIngressTimer();
+        }
+    };
+}
+export const genericHttpChannelPlugin = createGenericHttpChannelPlugin();

package/dist/channel/probe.d.ts

@@ -0,0 +1,19 @@
+import type { GenericHttpAccountConfig } from "../config/schema.js";
+export interface ProbeCheckResult {
+    name: string;
+    status: "OK" | "ERROR";
+    detail?: string;
+}
+export interface ProbeResult {
+    success: true;
+    status: "OK" | "ERROR";
+    accountId: string;
+    checks: ProbeCheckResult[];
+}
+export interface ProbeAccountOptions {
+    fetchImpl?: typeof fetch;
+    nowEpochSeconds?: () => number;
+    nonceFactory?: () => string;
+    requestIdFactory?: () => string;
+}
+export declare function probeAccountConfig(accountId: string, accountConfig: GenericHttpAccountConfig, options?: ProbeAccountOptions): Promise<ProbeResult>;

package/dist/channel/probe.js

@@ -0,0 +1,149 @@
+import { randomUUID } from "node:crypto";
+import { serializeProtocolObject } from "../protocol/serializer.js";
+import { signPayload } from "../security/signer.js";
+function hasValue(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function buildLocalChecks(accountConfig) {
+    return [
+        {
+            name: "base-url",
+            status: hasValue(accountConfig.baseUrl) ? "OK" : "ERROR",
+            detail: hasValue(accountConfig.baseUrl)
+                ? accountConfig.baseUrl
+                : "baseUrl is not configured"
+        },
+        {
+            name: "signing-secret",
+            status: hasValue(accountConfig.outboundSecret) || hasValue(accountConfig.signingSecret)
+                ? "OK"
+                : "ERROR",
+            detail: hasValue(accountConfig.outboundSecret) || hasValue(accountConfig.signingSecret)
+                ? "available"
+                : "signingSecret or outboundSecret is required"
+        },
+        {
+            name: "inbound-secret",
+            status: hasValue(accountConfig.inboundSecret) || hasValue(accountConfig.signingSecret)
+                ? "OK"
+                : "ERROR",
+            detail: hasValue(accountConfig.inboundSecret) || hasValue(accountConfig.signingSecret)
+                ? "available"
+                : "signingSecret or inboundSecret is required"
+        }
+    ];
+}
+function buildSignedHeaders(accountConfig, method, path, rawBody, timestamp, nonce, requestId) {
+    const signingSecret = accountConfig.outboundSecret ?? accountConfig.signingSecret ?? "";
+    const signature = signPayload(signingSecret, {
+        method,
+        path,
+        timestamp,
+        nonce,
+        rawBody
+    });
+    return {
+        accept: "application/json",
+        "content-type": "application/json",
+        "x-request-id": requestId,
+        "x-generic-http-version": "1",
+        "x-timestamp": timestamp,
+        "x-nonce": nonce,
+        "x-signature": signature,
+        "x-api-key": accountConfig.apiKey ?? ""
+    };
+}
+function buildErrorCheck(name, detail) {
+    return {
+        name,
+        status: "ERROR",
+        detail
+    };
+}
+async function runRemoteHealthCheck(accountConfig, options) {
+    const endpoint = new URL("/health", accountConfig.baseUrl);
+    const timestamp = String(options.nowEpochSeconds());
+    const nonce = options.nonceFactory();
+    const requestId = options.requestIdFactory();
+    const headers = buildSignedHeaders(accountConfig, "GET", endpoint.pathname, "", timestamp, nonce, requestId);
+    try {
+        const response = await options.fetchImpl(endpoint.toString(), {
+            method: "GET",
+            headers
+        });
+        if (!response.ok) {
+            return buildErrorCheck("health", `GET /health failed with ${response.status} ${response.statusText}`);
+        }
+        const payload = (await response.json());
+        if (payload.success !== true || payload.status !== "UP") {
+            return buildErrorCheck("health", "GET /health returned an invalid success/status payload");
+        }
+        return {
+            name: "health",
+            status: "OK",
+            detail: payload.service ?? "remote health check passed"
+        };
+    }
+    catch (error) {
+        return buildErrorCheck("health", error instanceof Error ? error.message : String(error));
+    }
+}
+async function runRemoteProbeCheck(accountId, accountConfig, options) {
+    const endpoint = new URL("/probe", accountConfig.baseUrl);
+    const rawBody = serializeProtocolObject({ accountId });
+    const timestamp = String(options.nowEpochSeconds());
+    const nonce = options.nonceFactory();
+    const requestId = options.requestIdFactory();
+    const headers = buildSignedHeaders(accountConfig, "POST", endpoint.pathname, rawBody, timestamp, nonce, requestId);
+    try {
+        const response = await options.fetchImpl(endpoint.toString(), {
+            method: "POST",
+            headers,
+            body: rawBody
+        });
+        if (!response.ok) {
+            return buildErrorCheck("probe-api", `POST /probe failed with ${response.status} ${response.statusText}`);
+        }
+        const payload = (await response.json());
+        if (payload.success !== true || typeof payload.status !== "string") {
+            return buildErrorCheck("probe-api", "POST /probe returned an invalid success/status payload");
+        }
+        return {
+            name: "probe-api",
+            status: payload.status === "OK" ? "OK" : "ERROR",
+            detail: Array.isArray(payload.checks) && payload.checks.length > 0
+                ? payload.checks
+                    .map((check) => `${check.name ?? "unknown"}=${check.status ?? "unknown"}`)
+                    .join(", ")
+                : "remote probe completed"
+        };
+    }
+    catch (error) {
+        return buildErrorCheck("probe-api", error instanceof Error ? error.message : String(error));
+    }
+}
+export async function probeAccountConfig(accountId, accountConfig, options = {}) {
+    const checks = buildLocalChecks(accountConfig);
+    if (checks.some((check) => check.status === "ERROR")) {
+        return {
+            success: true,
+            status: "ERROR",
+            accountId,
+            checks
+        };
+    }
+    const resolvedOptions = {
+        fetchImpl: options.fetchImpl ?? fetch,
+        nowEpochSeconds: options.nowEpochSeconds ?? (() => Math.floor(Date.now() / 1000)),
+        nonceFactory: options.nonceFactory ?? (() => randomUUID()),
+        requestIdFactory: options.requestIdFactory ?? (() => randomUUID())
+    };
+    checks.push(await runRemoteHealthCheck(accountConfig, resolvedOptions));
+    checks.push(await runRemoteProbeCheck(accountId, accountConfig, resolvedOptions));
+    return {
+        success: true,
+        status: checks.every((check) => check.status === "OK") ? "OK" : "ERROR",
+        accountId,
+        checks
+    };
+}