@sema-agent/server 7.141.0 → 7.143.0

package/dist/project-bundle.d.ts

@@ -0,0 +1,38 @@
+/** 项目包的 mime(厂商类型;格式由类型定死 = gzip 的 POSIX tar)。普通 tar / gzip 用普通 mime 上传就仍是附件。 */
+export declare const PROJECT_BUNDLE_MIME = "application/vnd.sema.project-bundle";
+/** 一只附件行的种类。 */
+export type AttachmentKind = "attachment" | "project_bundle";
+/** 附件行种类的唯一判据:已存的 mime(一个事实一格 —— 内容类型本就在 mime 列)。 */
+export declare function attachmentKindOf(mime: string): AttachmentKind;
+/** `attachment.bundle_invalid` 拒体 `reason` 的闭集(wire 值;登记 = `trace/self-minted-wire.ts` 的 `projectBundleInvalidReason`)。 */
+export declare const PROJECT_BUNDLE_INVALID_REASONS: readonly ["not_archive", "unsafe_path", "entry_type", "reserved_path", "duplicate_path", "expanded_too_large", "too_many_entries"];
+export type ProjectBundleInvalidReason = (typeof PROJECT_BUNDLE_INVALID_REASONS)[number];
+/** 展开字节上限(解压后的 tar 流,含头与填充)。 */
+export declare const PROJECT_BUNDLE_MAX_EXPANDED_BYTES: number;
+/** 解出来的文件系统对象上限(普通文件 + 目录 + 符号链接 + 路径隐含的目录;归档根 `./` 不计)。 */
+export declare const PROJECT_BUNDLE_MAX_ENTRIES = 200000;
+/** 顶层保留名:`.git` 走 git 引用那条路、`attachments` 是附件物化的落点 —— 初始一刻一棵子树一个写者。 */
+export declare const PROJECT_BUNDLE_RESERVED_TOP_LEVEL: readonly string[];
+/** 一次读的结局。成功形:条目数、顶层名(播种前判「撞上已有路径」用)、按请求给出的规范归档(gzip 的 ustar)。 */
+export type ProjectBundleReading = {
+    readonly ok: true;
+    readonly entries: number;
+    readonly topLevel: readonly string[];
+    readonly canonical?: Uint8Array;
+} | {
+    readonly ok: false;
+    readonly reason: ProjectBundleInvalidReason;
+    readonly path?: string;
+    readonly detail: string;
+};
+/**
+ * 读一份字节是不是项目包(见模块头的规则)。`canonical: true` ⇒ 同时交出规范归档(播种用;上传只判不铸)。`limits` 只给钉换小上限。从不抛。
+ */
+export declare function readProjectBundle(bytes: Uint8Array, opts?: {
+    readonly canonical?: boolean;
+    readonly limits?: {
+        readonly maxExpandedBytes?: number;
+        readonly maxEntries?: number;
+    };
+}): Promise<ProjectBundleReading>;
+//# sourceMappingURL=project-bundle.d.ts.map

package/dist/project-bundle.js

@@ -0,0 +1,609 @@
+import { Readable } from "node:stream";
+import { once } from "node:events";
+import { createGunzip, createGzip } from "node:zlib";
+export const PROJECT_BUNDLE_MIME = "application/vnd.sema.project-bundle";
+export function attachmentKindOf(mime) {
+    return mime === PROJECT_BUNDLE_MIME ? "project_bundle" : "attachment";
+}
+export const PROJECT_BUNDLE_INVALID_REASONS = ["not_archive", "unsafe_path", "entry_type", "reserved_path", "duplicate_path", "expanded_too_large", "too_many_entries"];
+export const PROJECT_BUNDLE_MAX_EXPANDED_BYTES = 512 * 1024 * 1024;
+export const PROJECT_BUNDLE_MAX_ENTRIES = 200_000;
+export const PROJECT_BUNDLE_RESERVED_TOP_LEVEL = [".git", "attachments"];
+class Refusal extends Error {
+    reason;
+    detail;
+    entryPath;
+    constructor(reason, detail, entryPath) {
+        super(detail);
+        this.reason = reason;
+        this.detail = detail;
+        this.entryPath = entryPath;
+    }
+}
+const BLOCK = 512;
+const PATH_MAX_BYTES = 4095;
+const NAME_MAX_BYTES = 255;
+const MAX_LINK_HOPS = 40;
+const YIELD_STEPS = 1 << 16;
+const META_MAX_BYTES = 1024 * 1024;
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+export async function readProjectBundle(bytes, opts = {}) {
+    const maxExpanded = opts.limits?.maxExpandedBytes ?? PROJECT_BUNDLE_MAX_EXPANDED_BYTES;
+    const maxEntries = opts.limits?.maxEntries ?? PROJECT_BUNDLE_MAX_ENTRIES;
+    const writer = opts.canonical === true ? createCanonicalWriter() : undefined;
+    const gunzip = createGunzip();
+    try {
+        const walk = new TarWalk(maxEntries, writer);
+        let expanded = 0;
+        for await (const chunk of Readable.from([Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)]).pipe(gunzip)) {
+            expanded += chunk.length;
+            if (expanded > maxExpanded)
+                throw new Refusal("expanded_too_large", `the bundle expands past ${maxExpanded} bytes`);
+            await walk.feed(chunk);
+            if (walk.done)
+                break;
+        }
+        const judged = await walk.finish();
+        const canonical = writer === undefined ? undefined : await writer.end();
+        return { ok: true, entries: judged.entries, topLevel: judged.topLevel, ...(canonical !== undefined ? { canonical } : {}) };
+    }
+    catch (e) {
+        writer?.abort();
+        if (e instanceof Refusal)
+            return { ok: false, reason: e.reason, ...(e.entryPath !== undefined ? { path: e.entryPath } : {}), detail: e.detail };
+        return { ok: false, reason: "not_archive", detail: `not a gzip-compressed tar: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    finally {
+        gunzip.destroy();
+    }
+}
+class TarWalk {
+    writer;
+    done = false;
+    chunks = [];
+    queued = 0;
+    entries = 0;
+    tree;
+    body;
+    pax = {};
+    unsupportedPax;
+    longName;
+    longLink;
+    zeroBlocks = 0;
+    constructor(maxEntries, writer) {
+        this.writer = writer;
+        this.tree = new BundleTree(maxEntries);
+    }
+    async feed(chunk) {
+        this.chunks.push(chunk);
+        this.queued += chunk.length;
+        for (;;) {
+            if (this.done)
+                return;
+            if (this.body !== undefined) {
+                if (!(await this.drainBody()))
+                    return;
+                continue;
+            }
+            if (this.queued < BLOCK)
+                return;
+            await this.header(this.take(BLOCK));
+        }
+    }
+    async finish() {
+        if (!this.done && (this.body !== undefined || this.queued !== 0))
+            throw new Refusal("not_archive", "the archive ends inside an entry");
+        await this.tree.judge();
+        return { entries: this.entries, topLevel: this.tree.topLevel() };
+    }
+    take(n) {
+        const out = Buffer.allocUnsafe(n);
+        let off = 0;
+        while (off < n) {
+            const head = this.chunks[0];
+            const k = Math.min(head.length, n - off);
+            head.copy(out, off, 0, k);
+            off += k;
+            if (k === head.length)
+                this.chunks.shift();
+            else
+                this.chunks[0] = head.subarray(k);
+        }
+        this.queued -= n;
+        return out;
+    }
+    async drainBody() {
+        const b = this.body;
+        while (b.remaining > 0) {
+            if (this.queued === 0)
+                return false;
+            const head = this.chunks[0];
+            const k = Math.min(head.length, b.remaining);
+            const part = head.subarray(0, k);
+            if (k === head.length)
+                this.chunks.shift();
+            else
+                this.chunks[0] = head.subarray(k);
+            this.queued -= k;
+            b.remaining -= k;
+            if (b.sink === "write")
+                await this.writer.content(part);
+            else if (b.sink === "meta")
+                b.meta.push(Buffer.from(part));
+        }
+        if (this.queued < b.pad)
+            return false;
+        if (b.pad > 0)
+            this.take(b.pad);
+        this.body = undefined;
+        if (b.sink === "write")
+            await this.writer.endContent();
+        if (b.sink === "meta")
+            this.applyMeta(b.metaKind, Buffer.concat(b.meta));
+        return true;
+    }
+    async header(h) {
+        if (h.every((x) => x === 0)) {
+            this.zeroBlocks++;
+            if (this.zeroBlocks >= 2)
+                this.done = true;
+            return;
+        }
+        if (this.zeroBlocks > 0)
+            throw new Refusal("not_archive", "a header follows the end-of-archive marker");
+        if (!checksumHolds(h))
+            throw new Refusal("not_archive", "a tar header's checksum does not hold");
+        const magic = h.toString("latin1", 257, 263);
+        const posix = magic === "ustar\0";
+        if (!posix && magic !== "ustar ")
+            throw new Refusal("not_archive", "not a ustar archive (no ustar magic)");
+        const type = String.fromCharCode(h[156]);
+        const headerSize = octal(h, 124, 12, "size");
+        if (type === "x" || type === "g" || type === "L" || type === "K") {
+            if (headerSize > META_MAX_BYTES)
+                throw new Refusal("not_archive", `an extended header of ${headerSize} bytes is past the ${META_MAX_BYTES}-byte bound`);
+            this.body = { remaining: headerSize, pad: padOf(headerSize), sink: "meta", meta: [], metaKind: type };
+            return;
+        }
+        const size = this.pax.size ?? headerSize;
+        const rawName = this.pax.path ?? this.longName ?? joinUstarName(posix ? cstr(h, 345, 155) : "", cstr(h, 0, 100));
+        const rawLink = this.pax.linkpath ?? this.longLink ?? cstr(h, 157, 100);
+        const unsupported = this.unsupportedPax;
+        this.pax = {};
+        this.unsupportedPax = undefined;
+        this.longName = undefined;
+        this.longLink = undefined;
+        const entryType = type === "0" || type === "\0" ? "file" : type === "5" ? "dir" : type === "2" ? "symlink" : undefined;
+        const name = decodeName(rawName);
+        if (entryType === undefined)
+            throw new Refusal("entry_type", `'${name}' is a ${tarTypeWord(type)} — a project bundle holds regular files, directories and symbolic links only`, name);
+        if (unsupported !== undefined) {
+            throw new Refusal("entry_type", `'${name}' carries the pax extension '${printable(unsupported)}' — a project bundle holds plain regular files, directories and symbolic links only (a sparse map, a volume offset or an unknown extension changes how the entry reads)`, name);
+        }
+        const p = landingOf(name);
+        if (p === "") {
+            if (entryType !== "dir")
+                throw new Refusal("unsafe_path", `an entry with an empty path is not a ${entryType}`, name);
+            this.body = { remaining: size, pad: padOf(size), sink: "skip" };
+            return;
+        }
+        const slash = p.indexOf("/");
+        if (PROJECT_BUNDLE_RESERVED_TOP_LEVEL.includes(slash === -1 ? p : p.slice(0, slash)))
+            throw new Refusal("reserved_path", `'${p}' is under a reserved top-level name (${PROJECT_BUNDLE_RESERVED_TOP_LEVEL.join(", ")})`, p);
+        let linkname = "";
+        if (entryType === "symlink") {
+            linkname = decodeName(rawLink);
+            if (linkname === "" || linkname.startsWith("/") || /[\x00-\x1f\x7f]/.test(linkname) || Buffer.byteLength(linkname) > PATH_MAX_BYTES) {
+                throw new Refusal("unsafe_path", `the symbolic link '${p}' needs a non-empty relative target of at most ${PATH_MAX_BYTES} bytes without control characters`, p);
+            }
+        }
+        this.tree.place(p, entryType, linkname);
+        this.entries++;
+        const entry = { path: p, type: entryType, mode: octal(h, 100, 8, "mode"), mtime: octalOrZero(h, 136, 12), size: entryType === "file" ? size : 0, linkname };
+        if (this.writer !== undefined)
+            await this.writer.entry(entry);
+        this.body = { remaining: size, pad: padOf(size), sink: entryType === "file" && this.writer !== undefined ? "write" : "skip" };
+    }
+    applyMeta(kind, data) {
+        if (kind === "L")
+            return void (this.longName = data.toString("latin1").replace(/\0+$/, ""));
+        if (kind === "K")
+            return void (this.longLink = data.toString("latin1").replace(/\0+$/, ""));
+        const records = parsePax(data);
+        for (const key of records.keys()) {
+            if (paxKeyReading(key) !== "unsupported")
+                continue;
+            if (kind === "g")
+                throw new Refusal("entry_type", `a global pax header carries the extension '${printable(key)}' — a project bundle holds plain regular files, directories and symbolic links only`);
+            this.unsupportedPax ??= key;
+        }
+        if (kind === "g") {
+            if (records.has("path") || records.has("linkpath") || records.has("size"))
+                throw new Refusal("not_archive", "a global pax header sets path / linkpath / size");
+            return;
+        }
+        const sizeText = records.get("size");
+        if (sizeText !== undefined && !/^\d{1,12}$/.test(sizeText))
+            throw new Refusal("not_archive", "a pax size record is not a decimal byte count");
+        this.pax = {
+            ...(records.has("path") ? { path: records.get("path") } : {}),
+            ...(records.has("linkpath") ? { linkpath: records.get("linkpath") } : {}),
+            ...(sizeText !== undefined ? { size: Number(sizeText) } : {}),
+        };
+    }
+}
+function padOf(size) {
+    return (BLOCK - (size % BLOCK)) % BLOCK;
+}
+function checksumHolds(h) {
+    const stored = octalOrNaN(h, 148, 8);
+    let unsigned = 0;
+    let signed = 0;
+    for (let i = 0; i < BLOCK; i++) {
+        const b = i >= 148 && i < 156 ? 0x20 : h[i];
+        unsigned += b;
+        signed += b > 127 ? b - 256 : b;
+    }
+    return stored === unsigned || stored === signed;
+}
+function octalOrNaN(h, off, len) {
+    const s = h.toString("latin1", off, off + len).replace(/[\0 ]+$/, "").replace(/^ +/, "");
+    return /^[0-7]+$/.test(s) ? parseInt(s, 8) : Number.NaN;
+}
+function octal(h, off, len, field) {
+    if (h[off] & 0x80)
+        throw new Refusal("not_archive", `the ${field} field is in base-256 form`);
+    const s = h.toString("latin1", off, off + len).replace(/[\0 ]+$/, "").replace(/^ +/, "");
+    if (s === "")
+        return 0;
+    if (!/^[0-7]+$/.test(s))
+        throw new Refusal("not_archive", `the ${field} field is not octal`);
+    return parseInt(s, 8);
+}
+function octalOrZero(h, off, len) {
+    const v = octalOrNaN(h, off, len);
+    return Number.isFinite(v) && v >= 0 ? v : 0;
+}
+function cstr(h, off, len) {
+    const end = h.indexOf(0, off);
+    return h.toString("latin1", off, end === -1 || end > off + len ? off + len : end);
+}
+function joinUstarName(prefix, name) {
+    return prefix === "" ? name : `${prefix}/${name}`;
+}
+function decodeName(raw) {
+    try {
+        return UTF8.decode(Buffer.from(raw, "latin1"));
+    }
+    catch {
+        throw new Refusal("unsafe_path", "an entry path is not valid UTF-8", raw.replace(/[^\x20-\x7e]/g, "?"));
+    }
+}
+function parsePax(data) {
+    const out = new Map();
+    let off = 0;
+    while (off < data.length) {
+        const sp = data.indexOf(0x20, off);
+        if (sp === -1)
+            throw new Refusal("not_archive", "a pax record has no length");
+        const lenText = data.toString("latin1", off, sp);
+        if (!/^\d{1,7}$/.test(lenText))
+            throw new Refusal("not_archive", "a pax record length is not decimal");
+        const len = Number(lenText);
+        if (len <= sp - off + 1 || off + len > data.length || data[off + len - 1] !== 0x0a)
+            throw new Refusal("not_archive", "a pax record is malformed");
+        const rec = data.toString("latin1", sp + 1, off + len - 1);
+        const eq = rec.indexOf("=");
+        if (eq <= 0)
+            throw new Refusal("not_archive", "a pax record has no key");
+        out.set(rec.slice(0, eq), rec.slice(eq + 1));
+        off += len;
+    }
+    return out;
+}
+function tarTypeWord(type) {
+    switch (type) {
+        case "1":
+            return "hard link";
+        case "3":
+            return "character device";
+        case "4":
+            return "block device";
+        case "6":
+            return "FIFO";
+        case "7":
+            return "contiguous file";
+        case "S":
+            return "sparse file";
+        default:
+            return `tar entry of type '${type.replace(/[^\x20-\x7e]/g, "?")}'`;
+    }
+}
+function landingOf(name) {
+    if (/[\x00-\x1f\x7f]/.test(name))
+        throw new Refusal("unsafe_path", `an entry path carries a control character`, name.replace(/[\x00-\x1f\x7f]/g, "?"));
+    if (name.startsWith("/"))
+        throw new Refusal("unsafe_path", `'${name}' is an absolute path`, name);
+    const segs = [];
+    for (const seg of name.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..")
+            throw new Refusal("unsafe_path", `'${name}' has a '..' segment`, name);
+        segs.push(seg);
+    }
+    const p = segs.join("/");
+    if (Buffer.byteLength(p) > PATH_MAX_BYTES)
+        throw tooLong(p);
+    const wide = segs.find((seg) => Buffer.byteLength(seg) > NAME_MAX_BYTES);
+    if (wide !== undefined)
+        throw new Refusal("unsafe_path", `'${p}' has a name of ${Buffer.byteLength(wide)} bytes — the sandbox's filesystem holds at most ${NAME_MAX_BYTES} bytes per name`, p);
+    return p;
+}
+function tooLong(p) {
+    return new Refusal("unsafe_path", `an entry path of ${Buffer.byteLength(p)} bytes (starting '${printable(p.slice(0, 64))}…') — the sandbox's filesystem holds at most ${PATH_MAX_BYTES} bytes per path`);
+}
+function printable(s) {
+    return s.replace(/[^\x20-\x7e]/g, "?");
+}
+function paxKeyReading(key) {
+    switch (key) {
+        case "path":
+        case "linkpath":
+        case "size":
+            return key;
+        case "mtime":
+        case "atime":
+        case "ctime":
+        case "uid":
+        case "gid":
+        case "uname":
+        case "gname":
+        case "comment":
+        case "charset":
+        case "hdrcharset":
+        case "SCHILY.fflags":
+        case "SCHILY.dev":
+        case "SCHILY.ino":
+        case "SCHILY.nlink":
+        case "LIBARCHIVE.creationtime":
+        case "LIBARCHIVE.symlinktype":
+            return "metadata";
+        default:
+            return PAX_METADATA_FAMILIES.some((family) => key.startsWith(family)) ? "metadata" : "unsupported";
+    }
+}
+const PAX_METADATA_FAMILIES = ["SCHILY.xattr.", "LIBARCHIVE.xattr.", "SCHILY.acl.", "security.", "RHT.security."];
+class BundleTree {
+    maxObjects;
+    root = { path: "", parent: undefined, kind: "dir", children: new Map(), linkname: "", firstUnder: "" };
+    byPath = new Map();
+    links = [];
+    objects = 0;
+    offense;
+    steps = 0;
+    constructor(maxObjects) {
+        this.maxObjects = maxObjects;
+    }
+    place(p, type, linkname) {
+        const cut = p.lastIndexOf("/");
+        const parent = cut === -1 ? this.root : this.dirAt(p.slice(0, cut), p);
+        if (parent === undefined)
+            return;
+        if (parent.kind === "file" || parent.kind === "symlink")
+            return this.offend(p, parent);
+        const name = cut === -1 ? p : p.slice(cut + 1);
+        const known = parent.children.get(name);
+        if (known === undefined) {
+            this.add(parent, name, p, type, linkname, p);
+            return;
+        }
+        if (known.kind !== "implied")
+            throw new Refusal("duplicate_path", `'${p}' appears twice`, p);
+        known.kind = type;
+        known.linkname = linkname;
+        if (type === "symlink")
+            this.links.push(known);
+        if (type !== "dir")
+            this.offend(known.firstUnder, known);
+    }
+    dirAt(dirPath, entryPath) {
+        const known = this.byPath.get(dirPath);
+        if (known !== undefined)
+            return known;
+        const ends = [];
+        let base = this.root;
+        for (let end = dirPath.length;;) {
+            ends.push(end);
+            const up = dirPath.lastIndexOf("/", end - 1);
+            if (up === -1)
+                break;
+            const found = this.byPath.get(dirPath.slice(0, up));
+            if (found !== undefined) {
+                base = found;
+                break;
+            }
+            end = up;
+        }
+        let cur = base;
+        for (let k = ends.length - 1; k >= 0; k--) {
+            if (cur.kind === "file" || cur.kind === "symlink") {
+                this.offend(entryPath, cur);
+                return undefined;
+            }
+            const end = ends[k];
+            cur = this.add(cur, dirPath.slice(dirPath.lastIndexOf("/", end - 1) + 1, end), dirPath.slice(0, end), "implied", "", entryPath);
+        }
+        return cur;
+    }
+    add(parent, name, p, kind, linkname, firstUnder) {
+        if (this.objects >= this.maxObjects)
+            throw new Refusal("too_many_entries", `the bundle unpacks to more than ${this.maxObjects} filesystem objects (its entries and the directories their paths imply)`);
+        this.objects++;
+        const node = { path: p, parent, kind, children: new Map(), linkname, firstUnder };
+        parent.children.set(name, node);
+        this.byPath.set(p, node);
+        if (kind === "symlink")
+            this.links.push(node);
+        return node;
+    }
+    offend(entryPath, blocker) {
+        this.offense ??= { entryPath, blocker };
+    }
+    topLevel() {
+        return [...this.root.children.keys()].sort();
+    }
+    async judge() {
+        for (const link of this.links) {
+            this.landingOf(link, 0);
+            if (this.steps >= YIELD_STEPS) {
+                this.steps = 0;
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        if (this.offense !== undefined)
+            throw this.offenseRefusal(this.offense);
+    }
+    offenseRefusal({ entryPath, blocker }) {
+        if (blocker.kind === "file")
+            return new Refusal("unsafe_path", `'${entryPath}' is under the regular file '${blocker.path}'`, entryPath);
+        const end = this.walk(this.landingOf(blocker, 0), entryPath.slice(blocker.path.length + 1), 0, blocker);
+        const top = end.node === this.root && end.depth > 0 ? end.top : undefined;
+        if (top !== undefined && PROJECT_BUNDLE_RESERVED_TOP_LEVEL.includes(top)) {
+            return new Refusal("reserved_path", `'${entryPath}' lands under '${top}' through the symbolic link '${blocker.path}' of the bundle — a reserved top-level name`, entryPath);
+        }
+        return new Refusal("unsafe_path", `'${entryPath}' is written through a symbolic link of the bundle ('${blocker.path}')`, entryPath);
+    }
+    landingOf(link, hops) {
+        if (link.landing !== undefined)
+            return link.landing;
+        if (hops >= MAX_LINK_HOPS)
+            throw new Refusal("unsafe_path", `the symbolic link '${link.path}' -> '${link.linkname}' does not land within ${MAX_LINK_HOPS} links (the bundle's links form a loop, or a chain that deep)`, link.path);
+        const at = this.walk({ node: link.parent, depth: 0, top: undefined }, link.linkname, hops + 1, link);
+        link.landing = at;
+        return at;
+    }
+    walk(from, text, hops, owner) {
+        let { node, depth, top } = from;
+        for (let i = 0; i <= text.length;) {
+            let j = text.indexOf("/", i);
+            if (j === -1)
+                j = text.length;
+            const seg = text.slice(i, j);
+            i = j + 1;
+            this.steps++;
+            if (seg === "" || seg === ".")
+                continue;
+            if (seg === "..") {
+                if (depth > 0) {
+                    depth--;
+                    if (depth === 0)
+                        top = undefined;
+                    continue;
+                }
+                if (node.parent === undefined)
+                    throw new Refusal("unsafe_path", `the symbolic link '${owner.path}' -> '${owner.linkname}' does not stay inside the bundle (resolved through the bundle's own links)`, owner.path);
+                node = node.parent;
+                continue;
+            }
+            if (depth > 0) {
+                depth++;
+                continue;
+            }
+            const child = node.children.get(seg);
+            if (child === undefined) {
+                if (node === this.root)
+                    top = seg;
+                depth = 1;
+                continue;
+            }
+            if (child.kind === "symlink") {
+                ({ node, depth, top } = this.landingOf(child, hops));
+                continue;
+            }
+            node = child;
+        }
+        return { node, depth, top };
+    }
+}
+function createCanonicalWriter() {
+    const gz = createGzip();
+    const out = [];
+    gz.on("data", (b) => out.push(b));
+    let pending = 0;
+    const write = async (b) => {
+        if (!gz.write(b))
+            await once(gz, "drain");
+    };
+    return {
+        async entry(e) {
+            const name = e.type === "dir" ? `${e.path}/` : e.path;
+            const needsPax = Buffer.byteLength(name) > 100 || Buffer.byteLength(e.linkname) > 100;
+            if (needsPax) {
+                const recs = Buffer.from(paxRecord("path", name) + (Buffer.byteLength(e.linkname) > 100 ? paxRecord("linkpath", e.linkname) : ""), "utf8");
+                await write(ustarHeader({ name: "PaxHeader", type: "x", mode: 0o644, size: recs.length, mtime: e.mtime, linkname: "" }));
+                await write(recs);
+                await write(Buffer.alloc(padOf(recs.length)));
+            }
+            const mode = e.type === "file" ? (e.mode & 0o111 ? 0o755 : 0o644) : e.type === "dir" ? 0o755 : 0o777;
+            const type = e.type === "file" ? "0" : e.type === "dir" ? "5" : "2";
+            await write(ustarHeader({ name: needsPax ? truncateUtf8(name, 100) : name, type, mode, size: e.size, mtime: e.mtime, linkname: needsPax ? truncateUtf8(e.linkname, 100) : e.linkname }));
+            pending = e.size;
+        },
+        async content(part) {
+            await write(part);
+        },
+        async endContent() {
+            await write(Buffer.alloc(padOf(pending)));
+            pending = 0;
+        },
+        async end() {
+            await write(Buffer.alloc(BLOCK * 2));
+            gz.end();
+            await once(gz, "end");
+            return new Uint8Array(Buffer.concat(out));
+        },
+        abort() {
+            gz.destroy();
+        },
+    };
+}
+function paxRecord(key, value) {
+    const body = ` ${key}=${value}\n`;
+    let len = Buffer.byteLength(body) + 1;
+    while (String(len).length + Buffer.byteLength(body) !== len)
+        len = String(len).length + Buffer.byteLength(body);
+    return `${len}${body}`;
+}
+function truncateUtf8(s, max) {
+    let b = Buffer.from(s, "utf8");
+    if (b.length <= max)
+        return s;
+    b = b.subarray(0, max);
+    return b.toString("utf8").replace(/�+$/, "");
+}
+function ustarHeader(f) {
+    const h = Buffer.alloc(BLOCK, 0);
+    Buffer.from(f.name, "utf8").copy(h, 0, 0, 100);
+    h.write(octalField(f.mode, 8), 100, "latin1");
+    h.write(octalField(0, 8), 108, "latin1");
+    h.write(octalField(0, 8), 116, "latin1");
+    h.write(octalField(f.size, 12), 124, "latin1");
+    h.write(octalField(Math.min(f.mtime, 0o77777777777), 12), 136, "latin1");
+    h.write("        ", 148, "latin1");
+    h.write(f.type, 156, "latin1");
+    Buffer.from(f.linkname, "utf8").copy(h, 157, 0, 100);
+    h.write("ustar\0", 257, "latin1");
+    h.write("00", 263, "latin1");
+    h.write(octalField(0, 8), 329, "latin1");
+    h.write(octalField(0, 8), 337, "latin1");
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++)
+        sum += h[i];
+    h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, "latin1");
+    return h;
+}
+function octalField(n, width) {
+    return `${Math.max(0, Math.floor(n)).toString(8).padStart(width - 1, "0")}\0`;
+}
+//# sourceMappingURL=project-bundle.js.map

package/dist/rule-entry-list.d.ts

@@ -2,11 +2,12 @@
  * **规则条目表在本仓受理口的判** —— 一份,四张表同调(core 7.42.0 起「这个调用不用问」只有一个去处:引擎的 allow 层;条目的文法、匹配、
  * 名字、读成空的通告都归引擎,本仓不写第二套):
  *  · 请求自带技能的 `allowedTools` / `disallowedTools`(顶层 `skills[]` 与子代 `agents[].skills[]` 两处受理口,`spec-fields.ts` / `http/admission.ts`);
- *  · 请求的 `settings.permissions.allow`(整份原样投 `TaskSpec.allowedTools`,`task-settings.ts`);
+ *  · 请求的 `settings.permissions.allow`(整份按位置投 `TaskSpec.allowedTools`,`task-settings.ts`;条目也可以是设置层的 `{ rule, layer }`,本文件按它的规则原文读,层只选锚);
  *  · 运维的 `APPROVAL_GRANT`(整份投 `RunnerDeps.allowedTools`,`config.ts` 启动校验)。
  *
  * 本仓在这些表上只剩下面几问(内容形、`*`、写路径形、名字引擎怎么读就怎么算):
- *  ① **形**({@link ruleEntryListShapeOk}):字符串数组。引擎逐条迭代;一个裸字符串会被逐字符读成几条(deny 侧 = 意图静默落空)。
+ *  ① **形**({@link ruleEntryListShapeOk}):字符串数组。引擎逐条迭代;一个裸字符串会被逐字符读成几条(deny 侧 = 意图静默落空)。请求的 allow 桶的形另由桶门判
+ *     (`task-settings.ts` 的 `settingsPermissionBucketIssue`:串或带层条目),它进下面 ③ 时带层条目读成规则原文({@link toolListsOf})。
  *     本谓词不带条数帽(引擎的 `screenAllowedToolsValue` 只判形);条数帽是另一只函数 {@link allowLayerEntryCountIssue}(`MAX_ALLOW_LAYER_ENTRIES`,
  *     请求 allow 桶、技能两只清单、运维表四张表同一只、同一句)。
  *  ② (7.116.0–7.122.x 的「引擎读不到的一形」—— 工具段为空的协议名 `mcp__srv__` 四张表都拒 —— 随 core 7.48.0 [ref] 退役:引擎判官给它判词

package/dist/rule-entry-list.js

@@ -3,6 +3,7 @@ import { displayListEntry } from "./list-entry-display.js";
 import { limitRefusal } from "./limit-refusal.js";
 import { TOOL_NAME_ROSTER } from "./namespaced-rule-name.js";
 import { NOT_IN_ROSTER, entryProblem, entryProblemsFacts } from "./entry-problems.js";
+import { layeredRuleOk } from "./permission-rule-list.js";
 export const ruleEntryListShapeOk = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
 export const MAX_ALLOW_LAYER_ENTRIES = 1_000;
 const ALLOW_LAYER_OVER_CAP_TAIL = "Refused rather than truncated: a truncated list silently drops the entries past the cap. Merge entries into broader ones (mcp__<server>__*, Bash(<prefix>:*), Read(//<dir>/**)) or trim the list";
@@ -162,7 +163,10 @@ function* toolListsOf(body) {
     const settings = body["settings"];
     const permissions = isPlainRecord(settings) ? settings["permissions"] : undefined;
     if (isPlainRecord(permissions))
-        yield { layer: "settings.permissions.allow", field: "settings.permissions.allow", prefix: "", at: "settings.permissions.allow", list: permissions["allow"] };
+        yield { layer: "settings.permissions.allow", field: "settings.permissions.allow", prefix: "", at: "settings.permissions.allow", list: ruleTextsOfBucket(permissions["allow"]) };
+}
+function ruleTextsOfBucket(list) {
+    return Array.isArray(list) ? list.map((x) => (layeredRuleOk(x) ? x.rule : x)) : list;
 }
 function inertReadingOfList(l) {
     const face = TOOL_LIST_FACES[l.layer];