@sema-agent/settings-schema 11.0.0 → 11.2.0

package/dist/web-admin-session-url.js

@@ -0,0 +1,64 @@
+/**
+ * web-admin 里**一个会话的网页链接**:模板函数 {@link webAdminSessionUrl} 与它的配对解析 {@link parseWebAdminSessionUrl} —— 一处定义路由与参数名
+ * (纯函数、零 I/O,浏览器安全)。链接形:
+ *
+ *     <webBaseUrl>/chat?agent=<worker>&session=<sessionId>
+ *
+ * 路由属于 web-admin(聊天页只读 `agent` 与 `session` 两个查询参数);谁要给用户一个会话链接 —— 壳、客户端、服务端文档 —— 调模板函数,不按地址形手拼。
+ * 聊天页读写地址栏改读配对解析,于是路径和参数名只有这一份。
+ *
+ * **两位都必填**:只带 `session` 的链接不够 —— 缺 `agent` 时页面按「URL > 本机记住的 > 第一个在线」挑 worker,再去那一台的会话里找这个 id,
+ * 会话不在那一台上就落空。所以模板函数拒绝铸只带一位的链接;解析却**宽读**(旧链接、手输的链接可能缺 `agent`),缺的那一位就是缺席。
+ * 链接没有 scope 位(跨空间深链不在这一形里);日后加 scope 时作可选第三位、同一函数,不另开函数。
+ */
+import { httpUrlFlaws, httpUrlRule } from "./url-shape.js";
+/** 链接的路径与两个参数名 —— 本文件私有,唯一一处。 */
+const SESSION_LINK_PATH = "/chat";
+const WORKER_PARAM = "agent";
+const SESSION_PARAM = "session";
+function requiredPart(label, value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`webAdminSessionUrl: ${label} is required (a non-empty string) — a session link without it cannot be opened`);
+    return value;
+}
+/**
+ * 铸一个会话的绝对网页链接。`webBaseUrl` 必须是干净的绝对 http(s) 基址(无 userinfo / query / fragment;可带路径前缀;尾斜杠折掉);
+ * `worker` 与 `sessionId` 必填,逐位 `encodeURIComponent`(含 `&` `#` `=` `?` 的 id 不会串位)。坏输入一律抛,不铸半截链接;
+ * 含孤立代理项的串(坏 UTF-16)由 `encodeURIComponent` 抛 `URIError`,不静默替换。
+ */
+export function webAdminSessionUrl(webBaseUrl, target) {
+    if (typeof webBaseUrl !== "string")
+        throw new TypeError("webAdminSessionUrl: webBaseUrl must be a string (an absolute http(s) URL)");
+    const flaws = httpUrlFlaws(webBaseUrl, ["userinfo", "query", "fragment"]);
+    if (flaws.length > 0)
+        throw new TypeError(`webAdminSessionUrl: webBaseUrl ${httpUrlRule(flaws[0])}`);
+    const worker = requiredPart("worker", target?.worker);
+    const sessionId = requiredPart("sessionId", target?.sessionId);
+    const base = new URL(webBaseUrl).href.replace(/\/+$/, ""); // 解析后的规范形:没有 query / fragment(上面已判),尾斜杠折掉
+    return `${base}${SESSION_LINK_PATH}?${WORKER_PARAM}=${encodeURIComponent(worker)}&${SESSION_PARAM}=${encodeURIComponent(sessionId)}`;
+}
+/**
+ * {@link webAdminSessionUrl} 的配对解析:从一个链接读回 `worker` / `sessionId`。输入可以是绝对 URL 串、相对串(`/chat?…`)、`URL` 或
+ * `URLSearchParams`(聊天页读当前地址栏的形)。**宽读**:缺的那一位不出现在结果里(空值等于缺席);重复参数取第一个(同 `searchParams.get`);
+ * 路径与别的查询参数不看。串解析不出来(不是 URL)⇒ 抛 `TypeError`,不静默当成「没有参数」。
+ */
+export function parseWebAdminSessionUrl(link) {
+    let params;
+    if (link instanceof URLSearchParams)
+        params = link;
+    else if (link instanceof URL)
+        params = link.searchParams;
+    else {
+        if (typeof link !== "string" || !URL.canParse(link, "http://relative.invalid"))
+            throw new TypeError("parseWebAdminSessionUrl: link is not a URL (pass an absolute URL, a relative `/chat?…` string, a URL or URLSearchParams)");
+        params = new URL(link, "http://relative.invalid").searchParams;
+    }
+    const out = {};
+    const worker = params.get(WORKER_PARAM);
+    const sessionId = params.get(SESSION_PARAM);
+    if (worker !== null && worker !== "")
+        out.worker = worker;
+    if (sessionId !== null && sessionId !== "")
+        out.sessionId = sessionId;
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "11.0.0",
+  "version": "11.2.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",