@lmzhen/dsh-evolution-curator 0.1.0-rc.1

package/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-evolution-curator
+
+Deterministic skill lifecycle and recovery
+
+## Model Experience
+
+### Indirect model surface
+
+#### What the model sees
+
+`@deepseek-ai/dsh-evolution-curator` registers no direct prompt or tool schema itself. Model-visible effects are owned by the packages that consume this service.
+
+#### Token effect
+
+Zero direct token effect from this package; consumers add any model-visible tokens.
+
+#### KV Cache effect
+
+Independent of request-prefix construction. This package does not alter the assembled prompt or tool list.
+
+## Known Limitations and Deferred Work
+
+
+- - LLM nomination pass is advisory and disabled by default; deterministic lifecycle remains authoritative.

package/lib/index.js

@@ -0,0 +1,252 @@
+import { Service } from "@deepseek-ai/cordis";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
+import z from "@deepseek-ai/schemastery";
+import { CURATOR_PROMPT, SkillLibrary, buildCuratorRunReport, computeLifecycleTransitions, evolutionHome, evolutionIoAdapter, loadUsage, saveUsage } from "@lmzhen/dsh-evolution-core";
+//#region lib/types/index.js
+/**
+* Deterministic skill lifecycle curator with interval gate and archive.
+* @module @lmzhen/dsh-evolution-curator
+*/
+var EvolutionCurator = class extends Service {
+	static inject = ["evolutionIo"];
+	static Config = z.object({
+		enabled: z.boolean().default(true),
+		intervalHours: z.number().default(168),
+		staleAfterDays: z.number().default(30),
+		archiveAfterDays: z.number().default(90),
+		llmReview: z.boolean().default(false),
+		curatorProvider: z.string().default("deepseek-official"),
+		qualityWarnStaleAfterDays: z.number().default(7),
+		minIdleHours: z.number().default(0),
+		excludeSkillNames: z.array(z.string()).default([]),
+		manageUnmanaged: z.boolean().default(false),
+		curatorReviewMaxTokens: z.number().default(2048)
+	});
+	skills;
+	io;
+	enabled;
+	intervalHours;
+	staleAfterDays;
+	archiveAfterDays;
+	llmReview;
+	curatorProvider;
+	qualityWarnStaleAfterDays;
+	minIdleHours;
+	excludeSkillNames;
+	manageUnmanaged;
+	curatorReviewMaxTokens;
+	lastRun = 0;
+	timer;
+	constructor(ctx, config = {}) {
+		super(ctx, "evolutionCurator");
+		this.io = evolutionIoAdapter(() => ctx.evolutionIo.provider());
+		this.skills = new SkillLibrary(void 0, this.io);
+		this.enabled = config.enabled ?? true;
+		this.intervalHours = config.intervalHours ?? 168;
+		this.staleAfterDays = config.staleAfterDays ?? 30;
+		this.archiveAfterDays = config.archiveAfterDays ?? 90;
+		this.llmReview = config.llmReview ?? false;
+		this.curatorProvider = config.curatorProvider ?? "deepseek-official";
+		this.qualityWarnStaleAfterDays = config.qualityWarnStaleAfterDays ?? 7;
+		this.minIdleHours = config.minIdleHours ?? 0;
+		this.excludeSkillNames = new Set(config.excludeSkillNames ?? []);
+		this.manageUnmanaged = config.manageUnmanaged ?? false;
+		this.curatorReviewMaxTokens = config.curatorReviewMaxTokens ?? 2048;
+		this.lastRun = Date.now();
+		this.ctx.effect(() => {
+			return () => {
+				this.stop();
+			};
+		}, "evolution-curator.stop");
+	}
+	lifecycle() {
+		const snapshot = this.ctx.get("evolutionPolicy")?.get();
+		return {
+			intervalHours: snapshot?.curatorIntervalHours ?? this.intervalHours,
+			staleAfterDays: snapshot?.staleAfterDays ?? this.staleAfterDays,
+			archiveAfterDays: snapshot?.archiveAfterDays ?? this.archiveAfterDays
+		};
+	}
+	start() {
+		if (!this.enabled || this.timer) return;
+		this.timer = setInterval(() => {
+			if (Date.now() - this.lastRun >= this.lifecycle().intervalHours * 36e5) this.run();
+		}, 3600 * 1e3);
+		this.timer.unref();
+	}
+	stop() {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = void 0;
+	}
+	/**
+	* Optional Hermes-curator LLM pass. The model may only NOMINATE pruning
+	* candidates; archive/restore remains a control-plane operation and every
+	* nominated name is still checked against lifecycle thresholds and
+	* protected markers before any file move.
+	*/
+	async recommend(candidates) {
+		if (candidates.length === 0) return [];
+		const llm = this.ctx.get("llm");
+		if (!llm) return [];
+		const model = this.ctx.get("evolutionPolicy")?.get().curatorModel ?? "deepseek-v4-pro";
+		const prompt = [
+			CURATOR_PROMPT,
+			"",
+			"Stale candidates observed by the deterministic lifecycle scanner:",
+			...candidates.map((name) => `- ${name}`),
+			"",
+			"Return a YAML summary with a prunings list. Nominate only candidates whose archival is clearly safe."
+		].join("\n");
+		try {
+			const assembler = new BlockAssembler();
+			for await (const chunk of llm.stream({
+				provider: this.curatorProvider,
+				model,
+				messages: [createUserMessage({
+					content: [{
+						type: "text",
+						text: prompt
+					}],
+					source: {
+						kind: "plugin",
+						plugin: "dsh-evolution-curator",
+						form: "notice",
+						summary: "curator review"
+					}
+				})],
+				maxTokens: this.curatorReviewMaxTokens,
+				purpose: "evolution-curator"
+			})) assembler.push(chunk);
+			const text = assembler.blocks().filter((block) => block.type === "text").map((block) => block.text).join("\n");
+			const names = /* @__PURE__ */ new Set();
+			const section = text.slice(text.indexOf("prunings:"));
+			for (const [, name] of section.matchAll(/^\s*-\s*name:\s*([a-z0-9][a-z0-9-]*)\s*$/gm)) if (name) names.add(name);
+			return [...names].filter((name) => candidates.includes(name));
+		} catch {
+			return [];
+		}
+	}
+	skippedReport(runId, startedAt) {
+		return buildCuratorRunReport({
+			runId,
+			startedAt,
+			finishedAt: startedAt,
+			staleCandidates: [],
+			llmNominations: [],
+			archiveCandidates: [],
+			archived: [],
+			failed: []
+		});
+	}
+	async run() {
+		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const runId = randomUUID();
+		const stateService = this.ctx.get("evolutionState");
+		const lifecycle = this.lifecycle();
+		const persisted = await stateService?.loadCuratorState();
+		if (persisted && Date.now() - persisted.lastRunAt < lifecycle.intervalHours * 36e5) return {
+			stale: [],
+			archived: [],
+			errors: [],
+			report: this.skippedReport(runId, startedAt),
+			skipped: "interval"
+		};
+		if (this.minIdleHours > 0 && this.recentSessionActive()) return {
+			stale: [],
+			archived: [],
+			errors: [],
+			report: this.skippedReport(runId, startedAt),
+			skipped: "active-session"
+		};
+		const root = this.skills.root;
+		const snapshotPath = await this.skills.snapshotAll("pre-curator-run");
+		const usage = await loadUsage(root, this.io);
+		const result = computeLifecycleTransitions(usage, {
+			staleAfterDays: lifecycle.staleAfterDays,
+			archiveAfterDays: lifecycle.archiveAfterDays,
+			qualityWarnStaleAfterDays: this.qualityWarnStaleAfterDays,
+			excludeSkillNames: this.excludeSkillNames,
+			manageUnmanaged: this.manageUnmanaged
+		});
+		const errors = [];
+		const archivedSkills = [];
+		const llmNominations = this.llmReview ? await this.recommend(result.markStale) : [];
+		const archiveCandidates = [...new Set([...result.archive, ...llmNominations])];
+		for (const name of archiveCandidates) {
+			const archived = await this.skills.archive(name, "Lifecycle: reached archive threshold");
+			if (!archived.ok) {
+				const record = usage.get(name);
+				if (record) record.state = "active";
+				errors.push(`${name}: ${archived.message}`);
+			} else archivedSkills.push({
+				name,
+				path: archived.path ?? "",
+				reason: "Lifecycle: reached archive threshold"
+			});
+		}
+		await saveUsage(root, usage, this.io);
+		this.lastRun = Date.now();
+		const report = buildCuratorRunReport({
+			runId,
+			startedAt,
+			finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			staleCandidates: result.markStale,
+			llmNominations,
+			archiveCandidates,
+			archived: archivedSkills,
+			failed: archiveCandidates.filter((name) => errors.some((error) => error.startsWith(`${name}:`))).map((name) => {
+				return {
+					name,
+					reason: errors.find((item) => item.startsWith(`${name}:`))?.slice(name.length + 2) ?? "unknown"
+				};
+			}),
+			snapshotPath
+		});
+		const reportsRoot = join(evolutionHome(), "reports");
+		try {
+			await this.io.writeText(join(reportsRoot, `curator-${runId}.json`), JSON.stringify(report, null, 2));
+		} catch (error) {
+			this.ctx.logger.warn(`evolution-curator: failed to persist report ${runId}`);
+			this.ctx.logger.warn(error);
+		}
+		await stateService?.saveCuratorState({
+			lastRunAt: this.lastRun,
+			runCount: (persisted?.runCount ?? 0) + 1,
+			lastSummary: `stale:${result.markStale.length} archived:${archivedSkills.length}`,
+			paused: false
+		});
+		return {
+			stale: result.markStale,
+			archived: archivedSkills.map((item) => item.name),
+			errors,
+			report
+		};
+	}
+	recentSessionActive() {
+		const agents = this.ctx.get("agents");
+		if (!agents) return false;
+		let latest = 0;
+		for (const agent of agents.list()) {
+			const events = agent.session.events;
+			const last = events.length === 0 ? 0 : events[events.length - 1]?.time ?? 0;
+			latest = Math.max(latest, last);
+		}
+		return latest > 0 && Date.now() - latest < this.minIdleHours * 36e5;
+	}
+	async latestReport() {
+		const reportsRoot = join(evolutionHome(), "reports");
+		const latest = (await this.io.list(reportsRoot)).filter((name) => name.startsWith("curator-") && name.endsWith(".json")).sort().reverse()[0];
+		if (!latest) return null;
+		const raw = await this.io.readText(join(reportsRoot, latest));
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw);
+		} catch {
+			return null;
+		}
+	}
+};
+//#endregion
+export { EvolutionCurator, EvolutionCurator as default };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-curator";
+const name = "evolution-curator-invariant";
+const inject = ["invariants"];
+const install = () => {};
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Deterministic skill lifecycle curator with interval gate and archive.
+ * @module @deepseek-ai/dsh-evolution-curator
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type Schema from '@deepseek-ai/schemastery';
+import { SkillLibrary } from '@deepseek-ai/dsh-evolution-core';
+import { type CuratorRunReport } from '@deepseek-ai/dsh-evolution-core';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        evolutionCurator: EvolutionCurator;
+    }
+}
+export interface Config {
+    enabled?: boolean;
+    intervalHours?: number;
+    staleAfterDays?: number;
+    archiveAfterDays?: number;
+    /** Spend one LLM review pass on stale candidates before the deterministic archive step. */
+    llmReview?: boolean;
+    curatorProvider?: string;
+    /** Quality-warned skills may turn stale after this many idle days. */
+    qualityWarnStaleAfterDays?: number;
+    /** Skip automatic runs while any session was active within this many hours (0 disables). */
+    minIdleHours?: number;
+    /** Skill names excluded from the automated lifecycle. */
+    excludeSkillNames?: string[];
+    /** Include usage records whose created_by is not 'agent' in lifecycle decisions. */
+    manageUnmanaged?: boolean;
+    /** Max tokens for the optional LLM nomination pass. */
+    curatorReviewMaxTokens?: number;
+}
+export declare class EvolutionCurator extends Service {
+    static inject: string[];
+    static Config: Schema<Config>;
+    readonly skills: SkillLibrary;
+    private readonly io;
+    private readonly enabled;
+    private readonly intervalHours;
+    private readonly staleAfterDays;
+    private readonly archiveAfterDays;
+    private readonly llmReview;
+    private readonly curatorProvider;
+    private readonly qualityWarnStaleAfterDays;
+    private readonly minIdleHours;
+    private readonly excludeSkillNames;
+    private readonly manageUnmanaged;
+    private readonly curatorReviewMaxTokens;
+    private lastRun;
+    private timer;
+    constructor(ctx: Context, config?: Config);
+    private lifecycle;
+    start(): void;
+    stop(): void;
+    /**
+     * Optional Hermes-curator LLM pass. The model may only NOMINATE pruning
+     * candidates; archive/restore remains a control-plane operation and every
+     * nominated name is still checked against lifecycle thresholds and
+     * protected markers before any file move.
+     */
+    recommend(candidates: string[]): Promise<string[]>;
+    private skippedReport;
+    run(): Promise<{
+        stale: string[];
+        archived: string[];
+        errors: string[];
+        report: CuratorRunReport;
+        skipped?: string;
+    }>;
+    private recentSessionActive;
+    latestReport(): Promise<CuratorRunReport | null>;
+}
+export default EvolutionCurator;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "evolution-curator-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@lmzhen/dsh-evolution-curator",
+  "description": "Deterministic skill lifecycle and recovery (community build)",
+  "version": "0.1.0-rc.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/dsh-evolution-curator"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/invariant.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.1"
+  }
+}