@sema-agent/settings-schema 1.0.0

package/dist/scheduler-store.js

@@ -0,0 +1,89 @@
+/**
+ * @sema-agent/settings-schema/scheduler-store — the PURE, dep-free CONTRACT for the self-wake scheduler store
+ * (R7 自唤醒). The shared seam between the WRITER (server-side `SchedulerCapability`, persists the model's
+ * CronCreate/Sleep intents) and the READER (TOC shell `SchedulerDaemon`, fires due intents). One canonical
+ * on-disk SHAPE + parse/serialize ⇒ the two independently-built sides never drift on the format.
+ *
+ * 🔴 Contract discipline (this is a third-party contract lib, not an impl dump):
+ *   - ABSTRACT: this module is the type + the parse/serialize FORMAT + the `SchedulerStore` interface. It has
+ *     ZERO runtime IO and ZERO deps (no `@sema-agent/*`, no `node:*`) so it lives in the browser-safe barrel.
+ *     The concrete filesystem binding is `@sema-agent/settings-schema/node` (`loadSchedulerStore`/`saveSchedulerStore`).
+ *   - EXTENSIBLE: `parseSchedulerStore` is FORWARD-COMPATIBLE — it validates only the required shape and
+ *     PRESERVES unknown fields, so a newer writer can add fields without an older reader dropping them on
+ *     round-trip. New optional `SchedulerRecord` fields are additive (no breaking change).
+ *   - CONTRACTUAL: `when` is an inlined structural union kept byte-compatible with core `ScheduledIntent['when']`
+ *     but NOT imported — the contract stands alone, independent of the engine.
+ *
+ * 🔴 `principal` is pinned by the writer from Runner-held ctx (never the model); persisted opaquely, passed
+ * through to `runTask` unchanged by the daemon (no privilege escalation).
+ */
+/** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
+export function isSchedulerRecord(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    if (typeof r.id !== 'string' || typeof r.scope !== 'string' || typeof r.prompt !== 'string' || typeof r.createdMs !== 'number')
+        return false;
+    const w = r.when;
+    if (typeof w !== 'object' || w === null)
+        return false;
+    if (w.kind === 'cron')
+        return typeof w.expr === 'string';
+    if (w.kind === 'at')
+        return typeof w.atMs === 'number';
+    if (w.kind === 'delay')
+        return typeof w.delaySec === 'number';
+    return false;
+}
+/**
+ * Parse the durable store from its serialized form. FAIL-SOFT + FORWARD-COMPATIBLE: corrupt/non-array/non-JSON
+ * ⇒ `[]`; malformed individual records are dropped (the store self-heals on next save); well-formed records keep
+ * ALL their fields (incl. unknown future ones) so a newer writer's data survives an older reader's round-trip.
+ * `onWarning` (optional, additive — mirrors the `FileConfigStore`/`EffectiveReadWarning` precedent): called once
+ * per dropped record so a caller can surface the loss instead of it vanishing silently (C5/C6 — a dropped
+ * record must leave a trace reachable by whoever can act on it).
+ */
+/**
+ * core 5.5.0 durable 键分叉的迁移半场(board [2439]/[2440]/[2444];server 裁 (a) 一次性迁移,拒读侧
+ * 双键容忍窗)。旧铸键链 `sessionId ?? principal ?? taskId ?? "default"` 让 durable 行的隔离键随会话
+ * 走——新会话新 sessionId ⇒ 旧 durable job 永远 not_found。core 5.5.0 起 durable 铸键=
+ * `principal ?? "default"`;存量旧键行由**本层**在 parse 时重铸(纯函数,幂等:重写后判据自不满足)。
+ *
+ * 为什么放 parse 而不是 loader:`loadSchedulerStore` 与 `mutateSchedulerStore` 都各自经
+ * `parseSchedulerStore`——归一放这里=两条读路径、两个读者(server 写侧 backend / shell daemon)
+ * 单点同愈,无第二机制。盘面在下一次 save 收敛(读侧恒一致,不做读时写放大)。
+ *
+ * 窄读判据:`lifetime` 不在本契约的显式键上(server 写侧作为 forward-compat 字段随行),按未知
+ * 字段窄读——`"session"` 行是会话链键,零触碰;其余(缺席=durable 默认)按 durable 归一。
+ */
+function normalizeDurableScope(r) {
+    if (r.lifetime === 'session')
+        return r;
+    const want = r.principal ?? 'default';
+    return r.scope === want ? r : { ...r, scope: want };
+}
+export function parseSchedulerStore(text, onWarning) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    if (!onWarning)
+        return parsed.filter(isSchedulerRecord).map(normalizeDurableScope);
+    const out = [];
+    parsed.forEach((record, index) => {
+        if (isSchedulerRecord(record))
+            out.push(normalizeDurableScope(record));
+        else
+            onWarning({ index, kind: 'malformed-record', record });
+    });
+    return out;
+}
+/** Serialize the store to its canonical on-disk form (stable, pretty JSON). The WRITE half of the format contract. */
+export function serializeSchedulerStore(records) {
+    return JSON.stringify(records, null, 2);
+}

package/dist/secret-refs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Secret-reference inventory (Phase-3 "密钥引用校验"). sema-registry stores only env-NAMEs, never secret
+ * values (the ENV_NAME boundary). This collects EVERY env-NAME the effective config references, grouped by
+ * name with where each is used — so an operator can audit "which env vars must each host/service provide?"
+ * before a worker/model fails at runtime.
+ *
+ * Note: sema-registry can't verify a name actually EXISTS in a consumer's environment (that's the consumer's
+ * own env). For workers, the reconciler already reports a missing one as a `SecretMissing` status condition
+ * (surfaced on /fleet). This inventory is the center-side half — every referenced env-NAME, incl. the general
+ * `secretEnv` passthrough, so a rotation runbook built on it isn't blind to app-specific tokens.
+ */
+import type { EffectiveConfig } from "./types.js";
+export interface EnvRefUse {
+    domain: string;
+    detail: string;
+}
+export interface EnvRef {
+    envName: string;
+    refs: EnvRefUse[];
+}
+/** Every env-NAME referenced across models / workers / mcp, grouped + sorted by name.
+ *  (integrations domain DELETED in 0.6.0 — OA/Gitea coordinates ride worker.env/secretEnv, EXPERT-REDESIGN §9.) */
+export declare function collectEnvRefs(eff: EffectiveConfig): EnvRef[];
+/**
+ * Names of workers that reference a given env-NAME — via any of the 4 structured `secretRefs` OR the general
+ * `secretEnv` passthrough. Drives batch-rotate (POST /secrets/<name>/rotate): after a credential write, recreate
+ * exactly the workers that project it. Reads the raw workers domain (the same shape collectEnvRefs would see).
+ */
+export declare function workersReferencingSecret(workers: {
+    name: string;
+    secretRefs?: Record<string, string | undefined>;
+    secretEnv?: Record<string, string>;
+}[], envName: string): string[];

package/dist/secret-refs.js

@@ -0,0 +1,48 @@
+/** Every env-NAME referenced across models / workers / mcp, grouped + sorted by name.
+ *  (integrations domain DELETED in 0.6.0 — OA/Gitea coordinates ride worker.env/secretEnv, EXPERT-REDESIGN §9.) */
+export function collectEnvRefs(eff) {
+    const map = new Map();
+    const add = (envName, domain, detail) => {
+        if (!envName)
+            return;
+        const list = map.get(envName) ?? [];
+        list.push({ domain, detail });
+        map.set(envName, list);
+    };
+    for (const m of eff.models.models)
+        add(m.apiKeyEnv, "models", `model "${m.name}".apiKeyEnv`);
+    for (const w of eff.workers.workers) {
+        const r = w.secretRefs;
+        add(r.apiKeyEnv, "workers", `worker "${w.name}".secretRefs.apiKeyEnv`);
+        add(r.serviceAuthTokenEnv, "workers", `worker "${w.name}".secretRefs.serviceAuthTokenEnv`);
+        add(r.gitTokenEnv, "workers", `worker "${w.name}".secretRefs.gitTokenEnv`);
+        add(r.tidbPasswordEnv, "workers", `worker "${w.name}".secretRefs.tidbPasswordEnv`);
+        // the general secretEnv passthrough also references env-NAMEs (worker-env.ts merges them) — include them
+        // so the rotation inventory isn't blind to app-specific tokens like OA_SERVICE_TOKEN→OA_CALLBACK_TOKEN.
+        for (const [key, envName] of Object.entries(w.secretEnv ?? {}))
+            add(envName, "workers", `worker "${w.name}".secretEnv.${key}`);
+    }
+    for (const s of eff.mcp.servers) {
+        const t = s.transport;
+        const refs = t.kind === "stdio" ? t.envRefs : t.headerRefs;
+        const kind = t.kind === "stdio" ? "envRefs" : "headerRefs";
+        for (const [key, envName] of Object.entries(refs ?? {}))
+            add(envName, "mcp", `server "${s.name}" ${kind}.${key}`);
+    }
+    return [...map.entries()].map(([envName, refs]) => ({ envName, refs })).sort((a, b) => a.envName.localeCompare(b.envName));
+}
+/**
+ * Names of workers that reference a given env-NAME — via any of the 4 structured `secretRefs` OR the general
+ * `secretEnv` passthrough. Drives batch-rotate (POST /secrets/<name>/rotate): after a credential write, recreate
+ * exactly the workers that project it. Reads the raw workers domain (the same shape collectEnvRefs would see).
+ */
+export function workersReferencingSecret(workers, envName) {
+    const out = [];
+    for (const w of workers) {
+        const inStructured = Object.values(w.secretRefs ?? {}).includes(envName);
+        const inPassthrough = Object.values(w.secretEnv ?? {}).includes(envName);
+        if (inStructured || inPassthrough)
+            out.push(w.name);
+    }
+    return out;
+}

package/dist/sha256.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure, dependency-free, **synchronous** SHA-256 over a UTF-8 string → lowercase hex.
+ *
+ * WHY a hand-rolled impl instead of `node:crypto`: this module sits in the PURE barrel
+ * (re-exported via skills-manifest.ts → resolve-roster.ts → index.ts). sema-registry's CLIENT components
+ * import that barrel for the zod types, so anything in it ships into the BROWSER bundle. A `node:crypto`
+ * import there breaks (or bloats with a polyfill) the client build — the exact blocker flagged in review.
+ * Web Crypto (`crypto.subtle.digest`) is async-only, but `skillContentHash` is a sync contract used in
+ * hot paths (the /effective manifest transform, the content-endpoint lookup), so we need a sync digest.
+ *
+ * Byte-for-byte identical to `createHash("sha256").update(s,"utf8").digest("hex")` — verified against
+ * node:crypto in the tests — so the `sha256:<hex>` content-address the service re-hashes after pulling
+ * (tamper detection) still matches. This is content-addressing/integrity, NOT a secret/MAC.
+ */
+/** SHA-256 of a UTF-8 string → 64-char lowercase hex. */
+export declare function sha256Hex(input: string): string;

package/dist/sha256.js

@@ -0,0 +1,114 @@
+/**
+ * Pure, dependency-free, **synchronous** SHA-256 over a UTF-8 string → lowercase hex.
+ *
+ * WHY a hand-rolled impl instead of `node:crypto`: this module sits in the PURE barrel
+ * (re-exported via skills-manifest.ts → resolve-roster.ts → index.ts). sema-registry's CLIENT components
+ * import that barrel for the zod types, so anything in it ships into the BROWSER bundle. A `node:crypto`
+ * import there breaks (or bloats with a polyfill) the client build — the exact blocker flagged in review.
+ * Web Crypto (`crypto.subtle.digest`) is async-only, but `skillContentHash` is a sync contract used in
+ * hot paths (the /effective manifest transform, the content-endpoint lookup), so we need a sync digest.
+ *
+ * Byte-for-byte identical to `createHash("sha256").update(s,"utf8").digest("hex")` — verified against
+ * node:crypto in the tests — so the `sha256:<hex>` content-address the service re-hashes after pulling
+ * (tamper detection) still matches. This is content-addressing/integrity, NOT a secret/MAC.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** Encode a JS string to UTF-8 bytes (no Node Buffer / TextEncoder dependency required — but use
+ *  TextEncoder when present for speed; it exists in both modern Node and browsers). */
+function utf8Bytes(s) {
+    if (typeof TextEncoder !== "undefined")
+        return new TextEncoder().encode(s);
+    // Minimal fallback encoder (very old runtimes only).
+    const out = [];
+    for (let i = 0; i < s.length; i++) {
+        let c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+            const c2 = s.charCodeAt(i + 1);
+            if (c2 >= 0xdc00 && c2 <= 0xdfff) {
+                c = 0x10000 + ((c - 0xd800) << 10) + (c2 - 0xdc00);
+                i++;
+            }
+        }
+        if (c < 0x80)
+            out.push(c);
+        else if (c < 0x800)
+            out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
+        else if (c < 0x10000)
+            out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+        else
+            out.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 0x3f), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+    }
+    return Uint8Array.from(out);
+}
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+/** SHA-256 of a UTF-8 string → 64-char lowercase hex. */
+export function sha256Hex(input) {
+    const msg = utf8Bytes(input);
+    const bitLen = msg.length * 8;
+    // Pad: 0x80, then zeros, then 64-bit big-endian length, to a multiple of 64 bytes.
+    const withOne = msg.length + 1;
+    const total = withOne + ((56 - (withOne % 64) + 64) % 64) + 8;
+    const buf = new Uint8Array(total);
+    buf.set(msg);
+    buf[msg.length] = 0x80;
+    // 64-bit length, big-endian. bitLen fits in 53 bits safely for any realistic skill body.
+    const hi = Math.floor(bitLen / 0x100000000);
+    const lo = bitLen >>> 0;
+    buf[total - 8] = (hi >>> 24) & 0xff;
+    buf[total - 7] = (hi >>> 16) & 0xff;
+    buf[total - 6] = (hi >>> 8) & 0xff;
+    buf[total - 5] = hi & 0xff;
+    buf[total - 4] = (lo >>> 24) & 0xff;
+    buf[total - 3] = (lo >>> 16) & 0xff;
+    buf[total - 2] = (lo >>> 8) & 0xff;
+    buf[total - 1] = lo & 0xff;
+    let h0 = 0x6a09e667, h1 = 0xbb67ae85, h2 = 0x3c6ef372, h3 = 0xa54ff53a;
+    let h4 = 0x510e527f, h5 = 0x9b05688c, h6 = 0x1f83d9ab, h7 = 0x5be0cd19;
+    const w = new Uint32Array(64);
+    for (let off = 0; off < total; off += 64) {
+        for (let i = 0; i < 16; i++) {
+            w[i] = (buf[off + i * 4] << 24) | (buf[off + i * 4 + 1] << 16) | (buf[off + i * 4 + 2] << 8) | buf[off + i * 4 + 3];
+        }
+        for (let i = 16; i < 64; i++) {
+            const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+            const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        let a = h0, b = h1, c = h2, d = h3, e = h4, f = h5, g = h6, h = h7;
+        for (let i = 0; i < 64; i++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (h + S1 + ch + K[i] + w[i]) | 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) | 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+        h5 = (h5 + f) | 0;
+        h6 = (h6 + g) | 0;
+        h7 = (h7 + h) | 0;
+    }
+    const toHex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+    return toHex(h0) + toHex(h1) + toHex(h2) + toHex(h3) + toHex(h4) + toHex(h5) + toHex(h6) + toHex(h7);
+}

package/dist/skills-manifest.d.ts

@@ -0,0 +1,12 @@
+import type { SkillsConfig, SkillsManifest } from "./types.js";
+/** Content-address a skill body → algorithm-prefixed sha256 hex. Self-describing (future alg), immutable,
+ *  and the SAME value carried in the manifest and used as the content-endpoint path. Memoized by content. */
+export declare function skillContentHash(content: string): string;
+/** Normalize a requested hash (bare 64-hex OR `sha256:<hex>`) to the canonical `sha256:<lowerhex>`, or null
+ *  if malformed — so a junk/oversized path param is rejected before any scan. */
+export declare function normalizeContentHash(raw: string): string | null;
+/** /effective transform: strip each skill's `content`, replace with its `contentHash` (manifest shape). */
+export declare function toSkillsManifest(cfg: SkillsConfig): SkillsManifest;
+/** Content-addressed lookup: the body whose hash == `hash`, or undefined (unknown / malformed hash). Identical
+ *  content across skills shares a hash → the first match's body is returned (bodies are identical by definition). */
+export declare function findSkillContent(cfg: SkillsConfig, hash: string): string | undefined;

package/dist/skills-manifest.js

@@ -0,0 +1,54 @@
+/**
+ * Skills content-addressing (docs/MCP-SKILLS.md §3.1, slice 2). The /effective payload ships skills as a
+ * MANIFEST — each skill's markdown `content` replaced by a `contentHash` — so the frequent 60s refresh stays
+ * small; the service pulls each body ONCE (at boot) via GET /api/config/skills/content/<hash>, caches it by
+ * hash, and re-pulls only when the hash changes (skills rarely change → big win). Bodies are immutable +
+ * deduped: identical content across skills shares one hash.
+ *
+ * sha256 here is for INTEGRITY + addressing (the service re-hashes after pulling to detect tampering/corruption)
+ * — distinct from the FNV `stableHash` in hash.ts, which is a fast non-crypto change-detector for ETags.
+ *
+ * The digest is a PURE-JS sha256 (./sha256.ts), NOT `node:crypto`: this module is re-exported through the
+ * package barrel, which sema-registry's CLIENT components import for the zod types — so a `node:crypto`
+ * import here would leak `node:*` into the browser bundle (the review-flagged blocker). Output is byte-identical to
+ * `createHash("sha256")`, so the `sha256:<hex>` content-address the service verifies still matches.
+ */
+import { sha256Hex } from "./sha256.js";
+// Memoize content→hash: the /effective poll path (toSkillsManifest) and the content-endpoint lookup
+// (findSkillContent) re-hash the same small, stable skill bodies repeatedly (× N workers × 60s). Skill
+// bodies are few + rarely change, so this stays tiny; a cap guards against unbounded growth.
+const _hashMemo = new Map();
+const _HASH_MEMO_CAP = 512;
+/** Content-address a skill body → algorithm-prefixed sha256 hex. Self-describing (future alg), immutable,
+ *  and the SAME value carried in the manifest and used as the content-endpoint path. Memoized by content. */
+export function skillContentHash(content) {
+    const hit = _hashMemo.get(content);
+    if (hit !== undefined)
+        return hit;
+    const h = `sha256:${sha256Hex(content)}`;
+    if (_hashMemo.size >= _HASH_MEMO_CAP)
+        _hashMemo.clear(); // bound — skills are few; simple evict-all is fine
+    _hashMemo.set(content, h);
+    return h;
+}
+/** Normalize a requested hash (bare 64-hex OR `sha256:<hex>`) to the canonical `sha256:<lowerhex>`, or null
+ *  if malformed — so a junk/oversized path param is rejected before any scan. */
+export function normalizeContentHash(raw) {
+    const m = /^(?:sha256:)?([0-9a-f]{64})$/i.exec(raw.trim());
+    return m ? `sha256:${m[1].toLowerCase()}` : null;
+}
+/** /effective transform: strip each skill's `content`, replace with its `contentHash` (manifest shape). */
+export function toSkillsManifest(cfg) {
+    return { skills: cfg.skills.map(({ content, ...rest }) => ({ ...rest, contentHash: skillContentHash(content) })) };
+}
+/** Content-addressed lookup: the body whose hash == `hash`, or undefined (unknown / malformed hash). Identical
+ *  content across skills shares a hash → the first match's body is returned (bodies are identical by definition). */
+export function findSkillContent(cfg, hash) {
+    const want = normalizeContentHash(hash);
+    if (!want)
+        return undefined;
+    for (const s of cfg.skills)
+        if (skillContentHash(s.content) === want)
+            return s.content;
+    return undefined;
+}