@paean-ai/harness-network 0.1.1-rc.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/paean/paean-network/README.md
+/:
+  en: b6693519d044a57a
+  zh: 44ba83c2f410a7dd
+/paean-ai-harness-network:
+  en: 6b0b2e4c5c4cf583
+  zh: 90e45981adc36810
+/paean-ai-harness-network/summary:
+  en: f78b5bf92eff01ee
+  zh: 0cef12cdce1f6117
+/paean-ai-harness-network/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 184c58005fb159f7
+/paean-ai-harness-network/use-this-package:
+  en: adc0bf49f2210f7a
+  zh: a3a1707b60f4cbf9
+/paean-ai-harness-network/understand-the-implementation:
+  en: 086dc88fc7d6e7e9
+  zh: f89902ec93f0a38c
+/paean-ai-harness-network/further-exploration:
+  en: b8390df89d3381ec
+  zh: 9d10572f26dc769d
+/paean-ai-harness-network/model-experience:
+  en: 19a12a60f8a5fa34
+  zh: b6133fca43308d46
+/paean-ai-harness-network/model-experience/kv-cache-effect:
+  en: 622085eff4b93114
+  zh: 229c9791ff2ed15a
+/paean-ai-harness-network/known-limitations-and-deferred-work:
+  en: dc938dc8217be3f2
+  zh: 9d0b1b030bf141fe
+/paean-ai-harness-network/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 8ec3e73528ddb1a6

package/README.md

@@ -0,0 +1,92 @@
+---
+description: "Select the Paean API ingress and compare credential-free connection latency without changing custom endpoints or system proxy settings."
+kind: "package-reference"
+---
+
+# `@paean-ai/harness-network`
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Choose the default Paean API or the OpenSOTA DCDN ingress for new requests. Compare response-header latency without sending an account token or calling a model. The selection persists in the profile configuration and takes effect without restarting. Custom endpoint configurations remain unchanged.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Paean compositions mount this plugin in both GUI and headless profiles. In Settings → API connection, select **Paean · default** (`api.paean.ai`) or **OpenSOTA · DCDN acceleration** (`api.opensota.cn`). The default is Paean. The comparison button measures both nodes but never switches automatically. The page reports DNS, TLS, proxy, timeout and HTTP failures with recovery guidance.
+
+Custom compositions mount the service through a `cordis.yml` row:
+
+```yaml
+- id: paean-network
+  name: '@paean-ai/harness-network'
+  config:
+    node: paean
+    probeTimeoutMs: 8000
+```
+
+`node` accepts only `paean` and `opensota` and is a live setting. `probeTimeoutMs` is a deployment-owned deadline from 1 to 60000 milliseconds. The service preserves paths such as `/v1`. URLs outside the two HTTPS origins remain unchanged, including development deployments and custom model providers.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The service owns one volatile preference. API consumers resolve it at the start of each request; the pi-ai provider-options waterfall resolves the same preference before creating an immutable adapter snapshot. Both `paean` and `paean-anthropic` model routes participate. Requests already using a snapshot retain their endpoint. The account plugin owns the localized settings section and loopback HTTP routes; settings persistence and concurrency remain owned by DSH ConfigEditor.
+
+Comparison performs concurrent unauthenticated `GET /user/profile` requests against the two fixed origins, refuses redirects and discards bodies. HTTP 401 is an expected reachable response, not evidence about the user's session. The Host's fetch policy owns process proxies; this plugin never changes OS network settings. Repeated calls share one pending comparison. Disposal aborts and drains it.
+
+**Runtime invariant:** No companion is published. The preference has one authority, and request snapshots are derived values rather than independently mutable records.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Paean account and Workspace](../paean-app/README.md) — the settings page and API consumers.
+- [pi-ai adapter](../../llm/llm-pi-ai/README.md) — provider snapshots and credential references.
+- [Live configuration forms](../../../docs/cookbook/adding-a-settings-card.md) — persistence and concurrent editing.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as ingress selection and connection diagnostics add no model-visible text.
+
+#### KV Cache effect
+
+The plugin does not change model input. A different ingress may use different server-side caches.
+
+## Known Limitations and Deferred Work
+
+Measurements describe this Host's current connection, not model throughput.
+
+- A single sample is affected by connection reuse, DNS caching and transient load.
+- The plugin does not route the browser sign-in site, downloads or custom endpoints.
+- Streaming Workspace proxy traffic uses its existing HTTP transport; the fetch probe does not verify every proxy transport path.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,92 @@
+---
+description: "选择 Paean API 接入节点并对比无凭据连接延迟，不改变自定义端点或系统代理设置。"
+kind: "package-reference"
+---
+
+# `@paean-ai/harness-network`
+
+[English](README.md) | 中文
+
+## 概述
+
+为新请求选择默认 Paean API 或 OpenSOTA DCDN 接入点。无需发送账号令牌或调用模型，即可对比收到响应头的延迟。选择保存在 profile 配置中，无需重启即可生效。自定义端点配置保持不变。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+Paean 组合在 GUI 和 headless profile 中都挂载此插件。在“设置 → API 接入节点”中，选择 **Paean · 默认节点**（`api.paean.ai`）或 **OpenSOTA · DCDN 加速节点**（`api.opensota.cn`）。默认为 Paean。测速按钮测量两个节点，但不会自动切换。页面分别显示 DNS、TLS、代理、超时和 HTTP 错误及修复指引。
+
+自定义组合通过 `cordis.yml` 条目挂载此服务：
+
+```yaml
+- id: paean-network
+  name: '@paean-ai/harness-network'
+  config:
+    node: paean
+    probeTimeoutMs: 8000
+```
+
+`node` 仅接受 `paean` 和 `opensota`，属于动态配置。`probeTimeoutMs` 是部署方指定的超时限制，范围为 1 至 60000 毫秒。服务保留 `/v1` 等路径。两个 HTTPS origin 之外的 URL 保持不变，包括开发环境和自定义模型提供方。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节 — 点击展开</summary>
+
+服务持有一个 volatile 偏好。API 消费方在每次请求开始时解析它；pi-ai 提供方选项 waterfall 在创建不可变适配器快照之前解析同一偏好。`paean` 和 `paean-anthropic` 两个模型路由均参与。已经使用快照的请求保留其端点。账号插件拥有本地化设置页和回环 HTTP 路由；配置持久化和并发编辑仍由 DSH ConfigEditor 负责。
+
+对比功能向两个固定 origin 并发发送无凭据的 `GET /user/profile` 请求，拒绝重定向并丢弃响应体。HTTP 401 是节点可达的预期响应，不代表用户会话状态。进程代理由 Host 的 fetch 策略负责；此插件不修改操作系统网络设置。重复调用共享同一次测速，卸载会取消并等待其结束。
+
+**运行时不变量：** 不发布配套检查器。偏好只有一个权威来源，请求快照是派生值，不是独立可变记录。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Paean 账号与 Workspace](../paean-app/README.zh.md) — 设置页与 API 消费方。
+- [pi-ai 适配器](../../llm/llm-pi-ai/README.zh.md) — 提供方快照与凭据引用。
+- [动态配置表单](../../../docs/cookbook/adding-a-settings-card.zh.md) — 持久化与并发编辑。
+
+<a id="model-experience"></a>
+## Model Experience
+
+无，因为接入选择和连接诊断不添加模型可见文本。
+
+#### KV Cache effect
+
+此插件不改变模型输入。不同接入点可能使用不同的服务端缓存。
+
+## Known Limitations and Deferred Work
+
+测量反映此 Host 当前的连接情况，不代表模型吞吐量。
+
+- 单次采样会受到连接复用、DNS 缓存和瞬时负载影响。
+- 此插件不调整浏览器登录站点、下载地址或自定义端点。
+- 流式 Workspace 代理流量使用原有 HTTP 传输；fetch 测速不能验证所有代理传输路径。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,151 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/probe.js
+/** Fixed destinations; callers cannot turn the diagnostic into an arbitrary URL fetch. */
+const PAEAN_NODES = {
+	paean: "https://api.paean.ai",
+	opensota: "https://api.opensota.cn"
+};
+/** Safe classification from transport error codes, without exposing their messages. */
+function failureOf(error) {
+	let cause = error;
+	const seen = /* @__PURE__ */ new Set();
+	while (typeof cause === "object" && cause !== null && !seen.has(cause)) {
+		seen.add(cause);
+		const code = "code" in cause && typeof cause.code === "string" ? cause.code : "";
+		if (code === "ENOTFOUND" || code === "EAI_AGAIN") return "dns";
+		if (code === "UND_ERR_PRX_TLS" || code === "UND_ERR_PROXY") return "proxy";
+		if (/CERT|TLS|SSL/.test(code)) return "tls";
+		cause = "cause" in cause ? cause.cause : void 0;
+	}
+	return "connection";
+}
+/**
+* Measure a fixed public endpoint without authentication, redirects, or response-body retention.
+* @param node - allowlisted ingress.
+* @param timeoutMs - maximum time to wait for response headers.
+* @param signal - owning plugin or caller cancellation.
+* @param fetcher - Host fetch implementation, including its process-local proxy policy.
+* @returns a safe result even when connection establishment fails.
+*/
+async function probeNode(node, timeoutMs, signal, fetcher = globalThis.fetch) {
+	const started = performance.now();
+	const timeout = new AbortController();
+	const timer = setTimeout(() => {
+		timeout.abort();
+	}, timeoutMs);
+	const result = () => ({
+		node,
+		endpoint: PAEAN_NODES[node],
+		elapsedMs: Math.round(performance.now() - started)
+	});
+	try {
+		const response = await fetcher(`${PAEAN_NODES[node]}/user/profile`, {
+			method: "GET",
+			redirect: "manual",
+			credentials: "omit",
+			cache: "no-store",
+			signal: AbortSignal.any([signal, timeout.signal]),
+			headers: { accept: "application/json" }
+		});
+		const measured = result();
+		await response.body?.cancel();
+		if (response.status === 200 || response.status === 401) return {
+			...measured,
+			reachable: true,
+			status: response.status
+		};
+		return {
+			...measured,
+			reachable: false,
+			status: response.status,
+			failure: response.status === 407 ? "proxy" : "http"
+		};
+	} catch (error) {
+		return {
+			...result(),
+			reachable: false,
+			failure: signal.aborted ? "aborted" : timeout.signal.aborted ? "timeout" : failureOf(error)
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+//#region lib/types/index.js
+/** Shared API ingress selection for Paean plugins and pi-ai provider routing. */
+/** Only the two public ingress nodes are selectable; custom deployments remain explicit. */
+const Config = z.object({
+	node: z.union(["paean", "opensota"]).default("paean").volatile(),
+	probeTimeoutMs: z.number().step(1).min(1).max(6e4).default(8e3)
+});
+/** One settings-backed preference shared by API consumers; it never owns credentials. */
+var PaeanNetwork = class extends Service {
+	config;
+	static Config = Config;
+	lifetime = new AbortController();
+	pending;
+	constructor(ctx, config) {
+		super(ctx, "paeanNetwork");
+		this.config = config;
+		ctx.inject(["settings"], (child) => {
+			child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
+		});
+		let previous;
+		let previousNode;
+		let routed;
+		ctx.on("llm-pi-ai/providers", (_configured, next) => {
+			const providers = next();
+			const node = config.node.get();
+			if (providers === previous && node === previousNode && routed !== void 0) return routed;
+			routed = providers;
+			for (const key of ["paean", "paean-anthropic"]) {
+				const profile = providers[key];
+				const base = profile?.baseURL;
+				const target = base === void 0 ? void 0 : this.resolve(base);
+				if (profile !== void 0 && target !== void 0 && target !== base) routed = {
+					...routed,
+					[key]: {
+						...profile,
+						baseURL: target
+					}
+				};
+			}
+			previous = providers;
+			previousNode = node;
+			return routed;
+		});
+		ctx.effect(() => async () => {
+			this.lifetime.abort();
+			await this.pending;
+		});
+	}
+	/**
+	* Resolve a branded API URL through the selected ingress, preserving its path.
+	* Custom endpoints remain owned by their explicit plugin configuration.
+	* @param base - deployment-configured API base or model URL.
+	* @returns the selected URL, or the unchanged custom URL.
+	*/
+	resolve(base) {
+		const url = new URL(base);
+		if (!Object.values(PAEAN_NODES).includes(url.origin) || url.username || url.password) return base;
+		const target = new URL(PAEAN_NODES[this.config.node.get()]);
+		target.pathname = url.pathname;
+		target.search = url.search;
+		target.hash = url.hash;
+		return url.pathname === "/" && !url.search && !url.hash ? target.origin : target.href;
+	}
+	/**
+	* Compare the two fixed nodes concurrently, sharing an in-flight comparison.
+	* Disposal cancels and drains outstanding fetches. No token is read or sent.
+	* @returns response-header latency and safe failure details for both nodes.
+	*/
+	compare() {
+		this.pending ??= Promise.all(["paean", "opensota"].map((node) => probeNode(node, this.config.probeTimeoutMs, this.lifetime.signal))).finally(() => {
+			this.pending = void 0;
+		});
+		return this.pending;
+	}
+};
+//#endregion
+export { Config, PaeanNetwork as default };

package/lib/types/index.d.ts

@@ -0,0 +1,53 @@
+/** Shared API ingress selection for Paean plugins and pi-ai provider routing. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { NodeProbe, PaeanNode } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        paeanNetwork: PaeanNetwork;
+    }
+}
+/** Live node preference and deployment-owned diagnostic deadline. */
+export interface Config {
+    /** Public ingress used for subsequent requests to branded Paean API URLs. */
+    node: Volatile<PaeanNode>;
+    /** Maximum response-header wait for each credential-free probe, in milliseconds. */
+    probeTimeoutMs: number;
+}
+/** Only the two public ingress nodes are selectable; custom deployments remain explicit. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    node: z<"paean" | "opensota", "paean" | "opensota", "volatile-defined">;
+    probeTimeoutMs: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    node: z<"paean" | "opensota", "paean" | "opensota", "volatile-defined">;
+    probeTimeoutMs: z<number, number, "defined">;
+}>>, "plain">;
+/** One settings-backed preference shared by API consumers; it never owns credentials. */
+export default class PaeanNetwork extends Service {
+    private readonly config;
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        node: z<"paean" | "opensota", "paean" | "opensota", "volatile-defined">;
+        probeTimeoutMs: z<number, number, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        node: z<"paean" | "opensota", "paean" | "opensota", "volatile-defined">;
+        probeTimeoutMs: z<number, number, "defined">;
+    }>>, "plain">;
+    private readonly lifetime;
+    private pending;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Resolve a branded API URL through the selected ingress, preserving its path.
+     * Custom endpoints remain owned by their explicit plugin configuration.
+     * @param base - deployment-configured API base or model URL.
+     * @returns the selected URL, or the unchanged custom URL.
+     */
+    resolve(base: string): string;
+    /**
+     * Compare the two fixed nodes concurrently, sharing an in-flight comparison.
+     * Disposal cancels and drains outstanding fetches. No token is read or sent.
+     * @returns response-header latency and safe failure details for both nodes.
+     */
+    compare(): Promise<NodeProbe[]>;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/probe.d.ts

@@ -0,0 +1,14 @@
+/** Bounded, credential-free Paean API response-header measurements. */
+import type { NodeProbe, PaeanNode } from './types.ts';
+/** Fixed destinations; callers cannot turn the diagnostic into an arbitrary URL fetch. */
+export declare const PAEAN_NODES: Readonly<Record<PaeanNode, string>>;
+/**
+ * Measure a fixed public endpoint without authentication, redirects, or response-body retention.
+ * @param node - allowlisted ingress.
+ * @param timeoutMs - maximum time to wait for response headers.
+ * @param signal - owning plugin or caller cancellation.
+ * @param fetcher - Host fetch implementation, including its process-local proxy policy.
+ * @returns a safe result even when connection establishment fails.
+ */
+export declare function probeNode(node: PaeanNode, timeoutMs: number, signal: AbortSignal, fetcher?: typeof fetch): Promise<NodeProbe>;
+//# sourceMappingURL=probe.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,23 @@
+/** Client-safe fields for Paean node selection and connection diagnostics. */
+/** Supported public Paean API ingress nodes. */
+export type PaeanNode = 'paean' | 'opensota';
+/** Safe diagnostic category; raw transport messages and proxy credentials are excluded. */
+export type ProbeFailure = 'timeout' | 'dns' | 'tls' | 'proxy' | 'connection' | 'http' | 'aborted';
+/** One credential-free response-header measurement, not model throughput. */
+interface ProbeTiming {
+    node: PaeanNode;
+    endpoint: string;
+    /** Wall duration until headers or failure, in milliseconds. */
+    elapsedMs: number;
+}
+/** Response-header timing with either expected reachability or a safe failure category. */
+export type NodeProbe = ProbeTiming & ({
+    reachable: true;
+    status: 200 | 401;
+} | {
+    reachable: false;
+    status?: number;
+    failure: ProbeFailure;
+});
+export {};
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,3 @@
+/** Client-safe fields for Paean node selection and connection diagnostics. */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@paean-ai/harness-network",
+  "description": "Shared Paean API node selection and credential-free connection diagnostics",
+  "version": "0.1.1-rc.16",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a8e-ai/paean-harness.git",
+    "directory": "packages/paean/paean-network"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-llm-pi-ai": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2",
+    "@deepseek-ai/cordis-plugin-timer": "~1.1.6",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-config-editor": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-hmr": "0.2.0-rc.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/types.js"
+  ]
+}