@sema-agent/settings-schema 11.1.0 → 11.3.0

package/dist/web-admin-credential.d.ts

@@ -32,8 +32,8 @@ export declare const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND: "user-session";
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
- *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ *    同不同源由读方比。URL 形判据是包内 URL 判官的「非存量座位」那一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据;issuer 是 wire 输入、不是存量,一次性迁移不碰它,fragment 拒句因此不指路)—— 本包不另写一份更窄的 URL 律。
  */
 export declare const WebAdminCredentialEnvelope: z.ZodObject<{
     kind: z.ZodLiteral<"user-session">;

package/dist/web-admin-credential.js

@@ -22,16 +22,11 @@
 import { z } from "zod";
 import { looksLikeJwt } from "./api/auth-bridge.js";
 import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
+import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (a project registration's `archivedAt` reads the same one)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
-/** RFC 3339 `date-time` 的**剖面**:zod 的 `z.iso.datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
- *  这里的正则自己判另三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(`10:00Z`、`+0800` 与 `+99:99`
- *  都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。这三处的判据在本正则,不随 zod 哪一版收不收而变。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
- *  `Date.parse` 取时刻,这是那组形里它处处读得准的子集。 */
-const RFC3339_DATE_TIME = z.iso
-    .datetime({ offset: true })
-    .regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/, "must be an RFC 3339 date-time: seconds and a Z / ±hh:mm offset (hh 00-23, mm 00-59) are required");
 /** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
  *  (0x20–0x7E),首尾是可见字符(0x21–0x7E)、中间可有空格(共享令牌可以是一句口令 —— 验修轮 N2:今天走得通的
  *  这种令牌不许被本律拒掉)。控制字符、制表、非 ASCII、不可见字符一律不是令牌:判别器把它判 `unreadable`,而不是
@@ -50,13 +45,13 @@ const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable AS
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
- *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ *    同不同源由读方比。URL 形判据是包内 URL 判官的「非存量座位」那一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据;issuer 是 wire 输入、不是存量,一次性迁移不碰它,fragment 拒句因此不指路)—— 本包不另写一份更窄的 URL 律。
  */
 export const WebAdminCredentialEnvelope = z
     .object({
     kind: z.literal(WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND),
-    accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
+    accessToken: TokenString.refine(looksLikeJwt, buildQuotedIssue `must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope`),
     refreshToken: TokenString,
     expiresAt: RFC3339_DATE_TIME,
     issuer: NON_SECRET_URL_NO_MIGRATION,

package/dist/web-admin-env.d.ts

@@ -17,7 +17,8 @@
  *  · `adminToken` —— 引擎以管理身份写 web-admin 时用的令牌(起服上报执行公钥)。
  *
  * 渲染器给每台 worker 写的三键(`url` / `worker` / `token`)同时是 worker env 的**保留名**(`RESERVED_WORKER_ENV`):运维在 worker 规格的
- * `env` 里写它们,会与渲染器写的值打架。
+ * `env` 里写它们,会与渲染器写的值打架。断言令牌的值键 `assertionToken` 也是保留名(由编排器注入);两把凭证的文件键(`tokenFile` / `assertionTokenFile`)同样是保留名:
+ * 只给不经编排器的手接引擎、由运维直设,与同一份凭证的值键互斥,规格里写任一个都与注入撞。
  */
 export declare const WEB_ADMIN_ENV: {
     readonly url: "SEMA_WEB_ADMIN_URL";

package/dist/web-admin-env.js

@@ -17,7 +17,8 @@
  *  · `adminToken` —— 引擎以管理身份写 web-admin 时用的令牌(起服上报执行公钥)。
  *
  * 渲染器给每台 worker 写的三键(`url` / `worker` / `token`)同时是 worker env 的**保留名**(`RESERVED_WORKER_ENV`):运维在 worker 规格的
- * `env` 里写它们,会与渲染器写的值打架。
+ * `env` 里写它们,会与渲染器写的值打架。断言令牌的值键 `assertionToken` 也是保留名(由编排器注入);两把凭证的文件键(`tokenFile` / `assertionTokenFile`)同样是保留名:
+ * 只给不经编排器的手接引擎、由运维直设,与同一份凭证的值键互斥,规格里写任一个都与注入撞。
  */
 export const WEB_ADMIN_ENV = {
     url: "SEMA_WEB_ADMIN_URL",

package/dist/web-admin-session-url.d.ts

@@ -0,0 +1,17 @@
+/** 一个会话在 web-admin 里的坐标:它在哪台 worker 上、会话 id 是什么。 */
+export interface WebAdminSessionTarget {
+    readonly worker: string;
+    readonly sessionId: string;
+}
+/**
+ * 铸一个会话的绝对网页链接。`webBaseUrl` 必须是干净的绝对 http(s) 基址(无 userinfo / query / fragment;可带路径前缀;尾斜杠折掉);
+ * `worker` 与 `sessionId` 必填,逐位 `encodeURIComponent`(含 `&` `#` `=` `?` 的 id 不会串位)。坏输入一律抛,不铸半截链接;
+ * 含孤立代理项的串(坏 UTF-16)由 `encodeURIComponent` 抛 `URIError`,不静默替换。
+ */
+export declare function webAdminSessionUrl(webBaseUrl: string, target: WebAdminSessionTarget): string;
+/**
+ * {@link webAdminSessionUrl} 的配对解析:从一个链接读回 `worker` / `sessionId`。输入可以是绝对 URL 串、相对串(`/chat?…`)、`URL` 或
+ * `URLSearchParams`(聊天页读当前地址栏的形)。**宽读**:缺的那一位不出现在结果里(空值等于缺席);重复参数取第一个(同 `searchParams.get`);
+ * 路径与别的查询参数不看。串解析不出来(不是 URL)⇒ 抛 `TypeError`,不静默当成「没有参数」。
+ */
+export declare function parseWebAdminSessionUrl(link: string | URL | URLSearchParams): Partial<WebAdminSessionTarget>;

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.1.0",
+  "version": "11.3.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",