@lmzhen/dsh-evolution-core 0.26.26 → 0.27.1

package/lib/restrictor.js

@@ -0,0 +1,37 @@
+import { n as errorText } from "./errors-Br2-uUSK.js";
+//#region lib/types/restrictor.js
+const name = "evolution-restrictor";
+const inject = ["agentPresets"];
+function normalize(names) {
+	return [...new Set((names ?? []).map((value) => value.trim()).filter((value) => value !== ""))].sort();
+}
+function failure(detail) {
+	return new Error(errorText("e-324-restricted-preset-unavailable", { a1: "evolution restrictor " + detail }));
+}
+function apply(ctx, config = {}) {
+	const allow = normalize(config.allow);
+	const deny = normalize(config.deny);
+	if (allow.length === 0 && deny.length === 0) throw failure("needs a non-empty allow or deny set");
+	const filter = {
+		...allow.length > 0 ? { allow } : {},
+		...deny.length > 0 ? { deny } : {}
+	};
+	const presetId = typeof config.presetId === "string" && config.presetId.trim() !== "" ? config.presetId : void 0;
+	if (presetId === void 0) throw failure("requires the restricted presetId in its row config");
+	const on = ctx.on;
+	if (typeof on !== "function") throw failure("requires a context that owns on()");
+	const presets = ctx.agentPresets;
+	if (presets === void 0 || typeof presets.composedPreset !== "function") throw failure("requires the agentPresets service (inject: agentPresets)");
+	on.call(ctx, "agent/created", (payload) => {
+		const agent = payload.agent;
+		if (agent === void 0) return;
+		if (presets.composedPreset(agent.ctx) !== presetId) return;
+		const tools = agent.ctx.tools;
+		if (tools === void 0 || typeof tools.restrict !== "function") throw failure("child scope exposes no tools.restrict()");
+		const effect = agent.ctx.effect;
+		if (effect === void 0) throw failure("child scope owns no effect() to release the restriction");
+		effect.call(agent.ctx, () => tools.restrict(filter), "evolution-restrictor:child");
+	});
+}
+//#endregion
+export { apply, inject, name };

package/lib/subagent/index.js

@@ -0,0 +1,186 @@
+import { h as restrictedPresetId, n as ensureRestrictedPreset, r as restrictedPresetState } from "../ensure-MEYMj9jn.js";
+//#region lib/types/subagent/readiness.js
+function serviceOf$1(ctx, name) {
+	return ctx.get(name);
+}
+function kindOf(kind) {
+	return kind === "reviewer" ? "reviewer" : "maintainer";
+}
+/** Pure derivation (no side effects): the doctor reads this, the channel re-probes on every run. */
+function probeChannelState(ctx, kind) {
+	const subagents = serviceOf$1(ctx, "subagents");
+	if (subagents === void 0 || typeof subagents.getProvider !== "function") return {
+		kind: "unavailable",
+		code: "E-323",
+		reason: "subagents service unavailable"
+	};
+	const provider = subagents.getProvider("spawn");
+	if (provider === void 0) return {
+		kind: "unavailable",
+		code: "E-323",
+		reason: "spawn provider unavailable"
+	};
+	if (provider.capabilities?.agentPreset !== true) return {
+		kind: "unavailable",
+		code: "E-323",
+		reason: "spawn provider lacks the agentPreset capability"
+	};
+	if (provider.inheritsParentContext === true) return {
+		kind: "unavailable",
+		code: "E-323",
+		reason: "spawn provider inherits the parent context (independent preset required)"
+	};
+	const agentPresets = serviceOf$1(ctx, "agentPresets");
+	if (agentPresets === void 0 || typeof agentPresets.readDocument !== "function" || typeof agentPresets.register !== "function") return {
+		kind: "unavailable",
+		code: "E-323",
+		reason: "agentPresets service unavailable or incomplete"
+	};
+	return {
+		kind: "available",
+		provider: "spawn",
+		preset: {
+			id: restrictedPresetId(kindOf(kind)),
+			registered: restrictedPresetState(ctx, kindOf(kind))?.kind === "ready"
+		}
+	};
+}
+function subagentChannelState(ctx, kind) {
+	return probeChannelState(ctx, kind);
+}
+//#endregion
+//#region lib/types/subagent/channel.js
+function serviceOf(ctx, name) {
+	return ctx.get(name);
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function createSubagentChannel(ctx) {
+	let lastKind = "reviewer";
+	return {
+		get state() {
+			return probeChannelState(ctx, lastKind);
+		},
+		prepare(spec) {
+			lastKind = spec.kind;
+			const state = probeChannelState(ctx, spec.kind);
+			if (state.kind === "unavailable") return Promise.resolve(state);
+			if (spec.allow.length === 0) return Promise.resolve({
+				kind: "unavailable",
+				code: "E-324",
+				reason: "allow set is empty"
+			});
+			return Promise.resolve(state);
+		},
+		async run(spec) {
+			lastKind = spec.kind;
+			const probe = probeChannelState(ctx, spec.kind);
+			if (probe.kind === "unavailable") return probe;
+			const subagents = serviceOf(ctx, "subagents");
+			const presets = serviceOf(ctx, "agentPresets");
+			if (subagents === void 0 || presets === void 0) return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: "subagents/agentPresets service unavailable"
+			};
+			const parentPresetId = presets.composedPreset(spec.parent.ctx);
+			if (parentPresetId === void 0) return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: "parent preset could not be resolved"
+			};
+			const ensured = await ensureRestrictedPreset(ctx, {
+				kind: spec.kind,
+				parentPresetId,
+				allow: spec.allow
+			});
+			if (ensured.kind === "failed") return {
+				kind: "unavailable",
+				code: "E-324",
+				reason: ensured.reason
+			};
+			const controller = new AbortController();
+			const timer = setTimeout(() => {
+				controller.abort(/* @__PURE__ */ new Error("subagent timeout"));
+			}, spec.timeoutMs);
+			const onAbort = () => {
+				controller.abort(spec.signal?.reason);
+			};
+			spec.signal?.addEventListener("abort", onAbort, { once: true });
+			let activation;
+			try {
+				activation = await subagents.startActivation({
+					provider: "spawn",
+					label: spec.label,
+					delivery: "caller",
+					request: {
+						parent: spec.parent,
+						prompt: [{
+							type: "text",
+							text: spec.promptText
+						}],
+						agentPreset: ensured.presetId,
+						...spec.outputSchema !== void 0 ? { outputSchema: spec.outputSchema } : {},
+						...spec.maxDepth !== void 0 ? { maxDepth: spec.maxDepth } : {},
+						...spec.agentOptions !== void 0 ? { agentOptions: spec.agentOptions } : {}
+					},
+					signal: controller.signal
+				});
+				let result;
+				try {
+					result = await activation.result;
+				} catch (error) {
+					if (controller.signal.aborted) return { kind: "aborted" };
+					return {
+						kind: "unavailable",
+						code: "E-323",
+						reason: messageOf(error)
+					};
+				}
+				let evidence;
+				if (spec.afterResult !== void 0) try {
+					const child = serviceOf(ctx, "agents")?.get(activation.childId);
+					if (child !== void 0) evidence = spec.afterResult(child);
+				} catch {
+					evidence = void 0;
+				}
+				const stopReason = result.stopReason;
+				if (stopReason === "completed" && result.structured !== void 0 && result.structured !== null) return {
+					kind: "ok",
+					structured: result.structured,
+					childId: activation.childId,
+					stopReason: "completed",
+					...evidence !== void 0 ? { evidence } : {}
+				};
+				if (stopReason === "aborted") return { kind: "aborted" };
+				return {
+					kind: "no-structured",
+					childId: activation.childId,
+					stopReason,
+					...result.diagnostic !== void 0 ? { diagnostic: result.diagnostic } : {},
+					...evidence !== void 0 ? { evidence } : {}
+				};
+			} catch (error) {
+				if (controller.signal.aborted) return { kind: "aborted" };
+				return {
+					kind: "unavailable",
+					code: "E-323",
+					reason: messageOf(error)
+				};
+			} finally {
+				clearTimeout(timer);
+				spec.signal?.removeEventListener("abort", onAbort);
+				if (activation !== void 0) try {
+					await activation.dispose();
+				} catch (error) {
+					try {
+						ctx.logger.warn("subagent channel: activation dispose failed: " + messageOf(error));
+					} catch {}
+				}
+			}
+		}
+	};
+}
+//#endregion
+export { createSubagentChannel, probeChannelState, subagentChannelState };

package/lib/types/citations.js

@@ -0,0 +1,192 @@
+/**
+ * Citation resolution for skill bodies and support files (design §5.2).
+ *
+ * WHY this exists beside `supportRefs` (skill-store.ts): that scanner answers
+ * "does this text contain a path-shaped token", which is the right question
+ * when a package is being ARCHIVED — every such path may dangle — and the wrong
+ * one when a section is only being MOVED, where nothing leaves and the only
+ * thing that changes is the directory a citation is read from. Measured false
+ * positives of the token scan: a URL tail (`https://host/references/x.md`), a
+ * category path the original Hermes documents as legitimate
+ * (`skills/scripts/foo.py`), and a prose command line
+ * (`npm run scripts/build.mjs`).
+ *
+ * CONTRACT: a token whose path STARTS WITH a support directory is a citation of
+ * this skill and is resolved from the SKILL ROOT, in whichever file it is
+ * written. A token that merely contains a support directory further along its
+ * path belongs to something else: it is reported as `foreign` and never
+ * resolved.
+ *
+ * PURE: existence is decided against the caller's file list, so identical
+ * inputs always answer the same report.
+ */
+/** Support directories that make a path a citation of the owning skill. */
+export const CITATION_SUPPORT_DIRS = ['references', 'templates', 'scripts', 'assets'];
+/** Scan budget: bounded so a pathological body cannot stall a maintenance run. */
+export const DEFAULT_CITATION_REF_BUDGET = 500;
+/** Words that introduce an executable command rather than a citation. */
+const PROSE_COMMAND_PREFIXES = ['npm', 'pnpm', 'yarn', 'npx', 'node', 'python', 'python3', 'bash', 'sh', 'git', 'gh', 'run'];
+const TOKEN_RE = /(?:references|templates|scripts|assets)\/[A-Za-z0-9._/-]+/g;
+const TOKEN_CHAR_RE = /[A-Za-z0-9._/-]/;
+const FENCE_RE = /^\s*(`{3,}|~{3,})/;
+const TRAILING_PUNCT_RE = /[.,;:]+$/;
+/** A citation's final segment must look like \u0060name.ext\u0060: a bare \u0060.\u0060 or a dotless
+ * segment is a directory mention, not a file. */
+const FILE_SEGMENT_RE = /^[^.].*\.[^.]+$/;
+const FRAGMENT_RE = /^#([A-Za-z0-9._-]+)/;
+/** Whether the token starting at `start` is the argument of a shell command. */
+function isProseCommand(line, start) {
+    const head = line.slice(0, start).trimEnd();
+    if (head === '')
+        return false;
+    const word = head.split(/\s+/).pop() ?? '';
+    return PROSE_COMMAND_PREFIXES.includes(word);
+}
+/** The token's final path segment (`references/a/b.md` -> `b.md`). */
+function lastSegmentOf(target) {
+    return target.slice(target.lastIndexOf('/') + 1);
+}
+/** The token's parent directory within the skill (`references/a/b.md` -> `references/a`). */
+function parentDirOf(target) {
+    const cut = target.lastIndexOf('/');
+    return cut <= 0 ? '' : target.slice(0, cut);
+}
+/** Classify one token by its first path segment. */
+function classifyToken(token) {
+    const head = token.split('/')[0] ?? '';
+    return CITATION_SUPPORT_DIRS.includes(head) ? 'citation' : 'foreign';
+}
+/**
+ * Resolve every path-shaped token in `content`.
+ * @param input - content, the skill-root-relative path of its owner, the skill's
+ *   file list, and an optional scan budget.
+ * @returns the refs plus the dangling and foreign subsets; `truncated` marks a
+ *   report that stopped at the budget.
+ */
+export function resolveCitations(input) {
+    const budget = input.budget ?? DEFAULT_CITATION_REF_BUDGET;
+    const files = new Set(input.files.map(path => path.replace(/\\/g, '/')));
+    const refs = [];
+    const seen = new Set();
+    let truncated = false;
+    let fence = null;
+    const lines = input.content.split('\n');
+    for (let index = 0; index < lines.length && !truncated; index += 1) {
+        const rawLine = lines[index] ?? '';
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        const fenceMark = FENCE_RE.exec(line);
+        if (fenceMark) {
+            const marker = fenceMark[1] ?? '';
+            fence = fence === null ? marker.slice(0, 1) : null;
+            continue;
+        }
+        for (const match of line.matchAll(TOKEN_RE)) {
+            const matched = match[0];
+            const matchedAt = match.index;
+            let start = matchedAt;
+            while (start > 0 && TOKEN_CHAR_RE.test(line[start - 1] ?? ''))
+                start -= 1;
+            const prefix = line.slice(0, start);
+            const tail = line.slice(matchedAt + matched.length);
+            const fragment = FRAGMENT_RE.exec(tail)?.[1];
+            const token = matched.replace(TRAILING_PUNCT_RE, '');
+            const scanned = line.slice(start, matchedAt + matched.length);
+            const classified = fence !== null
+                ? 'fence'
+                : prefix.endsWith(':') && line.slice(start, start + 2) === '//'
+                    ? 'url'
+                    : isProseCommand(line, start)
+                        ? 'prose'
+                        : classifyToken(scanned);
+            // A citation names a FILE: a dotless last segment is a directory mention
+            // (`references/templates/scripts` in prose), and a `..` segment is a
+            // traversal — a different defect class the old scanner also skipped. Both
+            // are prose unless the listing proves the path is a real entry.
+            const traversal = scanned.split('/').includes('..');
+            const namesFile = !traversal && (FILE_SEGMENT_RE.test(lastSegmentOf(scanned)) || files.has(token));
+            const kind = classified === 'citation' && !namesFile ? 'prose' : classified;
+            const target = kind === 'citation' ? token : null;
+            const key = `${index}|${kind}|${target ?? token}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            refs.push({
+                raw: token,
+                line: index + 1,
+                target,
+                base: 'root',
+                kind,
+                exists: target !== null && files.has(target),
+                ...(fragment === undefined ? {} : { fragment }),
+            });
+            if (refs.length >= budget) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    const citations = refs.filter(ref => ref.kind === 'citation');
+    const undecidable = (ref) => {
+        const target = ref.target;
+        return target !== null && !ref.exists && files.has(parentDirOf(target));
+    };
+    return {
+        refs,
+        dangling: citations.filter(ref => !ref.exists && !undecidable(ref)),
+        unverified: citations.filter(undecidable),
+        foreign: refs.filter(ref => ref.kind !== 'citation'),
+        truncated,
+    };
+}
+/** The sanctioned body hook (design §5.6): a list item whose payload is
+ * exactly one support-file path, so the file stays discoverable in the body. */
+export const HOOK_LINE_RE = /^- [^\n]{1,60} → ((?:references|templates|scripts|assets)\/[a-z0-9][a-z0-9._/-]*)$/;
+/** The retirement escape hatch (design §5.6): a standalone body comment that
+ * names the support file it exempts and the reason it must survive. The path
+ * is part of the marker because the proposal list is per FILE, and a reason is
+ * required — an unexplained exemption is what this hook exists to prevent. */
+export const KEEP_LINE_RE = /^<!--\s*keep:\s*((?:references|templates|scripts|assets)\/[a-z0-9][a-z0-9._/-]*)\s+(\S[^>]*?)\s*-->$/;
+/** Whether a skill-relative path names a FILE rather than a directory: the same
+ * rule the scanner applies to a token's final segment (`name.ext`). The support
+ * listing is one level deep and includes directory entries (a real library has
+ * `references/archive`), which no pointer or retirement list may treat as a file.
+ * @param path - a skill-root-relative support path.
+ * @returns true when the final segment is file-shaped.
+ */
+export function isFileShapedPath(path) {
+    return FILE_SEGMENT_RE.test(path.slice(path.lastIndexOf('/') + 1));
+}
+/**
+ * Scan a body for sanctioned hooks and `keep` markers.
+ * @param content - the SKILL.md body (frontmatter included).
+ * @returns hook targets plus the `keep` reasons keyed by target.
+ */
+export function scanBodyHooks(content) {
+    const targets = [];
+    const seen = new Set();
+    const kept = new Map();
+    // A hook-shaped line inside a fenced block is sample text, not a pointer.
+    let fence = null;
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine;
+        const fenceMark = FENCE_RE.exec(line);
+        if (fenceMark) {
+            fence = fence === null ? (fenceMark[1] ?? '').slice(0, 1) : null;
+            continue;
+        }
+        if (fence !== null)
+            continue;
+        const keep = KEEP_LINE_RE.exec(line);
+        if (keep?.[1] !== undefined) {
+            kept.set(keep[1], (keep[2] ?? '').trim());
+            continue;
+        }
+        const target = HOOK_LINE_RE.exec(line)?.[1];
+        if (target === undefined || seen.has(target))
+            continue;
+        seen.add(target);
+        targets.push(target);
+    }
+    return { targets, kept };
+}
+//# sourceMappingURL=citations.js.map

package/lib/types/{preset-composition.d.ts → composition/composer.d.ts}

@@ -304,4 +304,4 @@ export declare function trimTrailingBlankLines(lines: string[]): string[];
  */
 export declare function presetPatchText(patchText: string): string;
 export {};
-//# sourceMappingURL=preset-composition.d.ts.map
+//# sourceMappingURL=composer.d.ts.map