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

package/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-evolution-review
+
+Background review orchestration
+
+## Model Experience
+
+### Indirect model surface
+
+#### What the model sees
+
+`@deepseek-ai/dsh-evolution-review` 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
+
+
+- - Review subagents inherit the host preset; Anchored Standard deployments rely on the default `skill_search`/`skill_load` allow-list.

package/lib/index.js

@@ -0,0 +1,239 @@
+import { createHash, randomUUID } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+import { CallId, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { PROMPT_BUNDLE, advanceReview, foldTurn, reviewPrompt, verifyPromptBundle } from "@lmzhen/dsh-evolution-core";
+import { validateEvolutionPlan } from "@lmzhen/dsh-evolution-plan-validator";
+//#region lib/types/index.js
+/**
+* Background review orchestration: signal gate → one-shot subagent → trusted plan execution.
+* @module @lmzhen/dsh-evolution-review
+*/
+const name = "evolution-review";
+const inject = ["agents", "tools"];
+const Config = z.object({
+	reviewEnabled: z.boolean().default(true),
+	reviewMode: z.string().default("subagent"),
+	memoryInterval: z.number().default(10),
+	skillInterval: z.number().default(10),
+	reviewToolAllow: z.array(z.string()).default([
+		"skill",
+		"skill_search",
+		"skill_load"
+	]),
+	reviewTimeoutMs: z.number().default(12e4),
+	executionTimeoutMs: z.number().default(3e4),
+	reviewContextMessages: z.number().default(60),
+	reviewMessageChars: z.number().default(2e3),
+	reviewMaxDepth: z.number().default(0)
+});
+function apply(ctx, rawConfig) {
+	if (!verifyPromptBundle(PROMPT_BUNDLE)) throw new Error("dsh-evolution prompt bundle integrity check failed; refusing to schedule review work");
+	const config = rawConfig;
+	const turnStarts = /* @__PURE__ */ new Map();
+	const policy = () => ctx.get("evolutionPolicy")?.get();
+	ctx.on("session/event", (session, event) => {
+		if (event.type === "turn/start") turnStarts.set(session.id, session.seq - 1);
+		if (event.type !== "turn/end") return;
+		onTurnEnd(session, event);
+	});
+	async function onTurnEnd(session, event) {
+		if (!config.reviewEnabled) return;
+		if (session.header.origin === "subagent") return;
+		const agent = ctx.agents.get(session.id);
+		if (!agent) return;
+		const signal = foldTurn(session, turnStarts.get(session.id) ?? Math.max(0, session.seq - 1));
+		turnStarts.delete(session.id);
+		const stateService = ctx.get("evolutionState");
+		const state = await stateService?.loadReviewState(session.id) ?? {
+			turnsSinceMemory: 0,
+			turnsSinceSkill: 0,
+			lastTurn: -1
+		};
+		const snapshot = policy();
+		const kind = advanceReview(state, event.data.turn, signal, {
+			memoryInterval: snapshot?.reviewMemoryInterval ?? config.memoryInterval,
+			skillInterval: snapshot?.reviewSkillInterval ?? config.skillInterval,
+			substantiveMinToolCalls: snapshot?.substantiveMinToolCalls ?? 3,
+			substantiveMinUserChars: snapshot?.substantiveMinUserChars ?? 200,
+			substantiveMinAgentChars: snapshot?.substantiveMinAgentChars ?? 500
+		});
+		await stateService?.saveReviewState(session.id, state);
+		if (!kind) return;
+		if (!await trySubagentReview(session, agent, kind, signal)) agent.inject(createUserMessage({
+			content: [{
+				type: "text",
+				text: reviewPrompt(kind)
+			}],
+			source: {
+				kind: "plugin",
+				plugin: "dsh-evolution-review",
+				form: "notice",
+				summary: "auto-review"
+			}
+		}));
+	}
+	async function trySubagentReview(session, agent, kind, signal) {
+		if ((policy()?.reviewMode ?? config.reviewMode) === "inject") return false;
+		const subagents = ctx.get("subagents");
+		if (!subagents) return false;
+		try {
+			const routingPolicy = ctx.get("evolutionPolicy");
+			const model = kind === "memory" ? routingPolicy?.get().memoryReviewModel ?? "deepseek-v4-flash" : routingPolicy?.get().skillReviewModel ?? "deepseek-v4-pro";
+			const reviewText = buildReviewRequest(session, kind, signal, config.reviewContextMessages, config.reviewMessageChars);
+			const run = await subagents.start("spawn", {
+				label: "dsh-evolution-review",
+				prompt: [{
+					type: "text",
+					text: reviewText
+				}],
+				parent: agent,
+				signal: AbortSignal.timeout(config.reviewTimeoutMs),
+				maxDepth: config.reviewMaxDepth,
+				agentOptions: {
+					provider: "deepseek-official",
+					model
+				},
+				persona: reviewPrompt(kind),
+				toolFilter: { allow: [...config.reviewToolAllow] },
+				outputSchema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						memoryOps: {
+							type: "array",
+							items: { type: "json" }
+						},
+						skillOps: {
+							type: "array",
+							items: { type: "json" }
+						},
+						summary: { type: "string" }
+					}
+				}
+			});
+			const result = await run.result;
+			await run.dispose();
+			if (!result.structured) return true;
+			const snapshot = policy();
+			const plan = result.structured;
+			const policyFingerprint = fingerprintPolicy(snapshot);
+			const validation = validateEvolutionPlan(plan, {
+				sessionSeq: session.seq - 1,
+				maxOpsPerPlan: snapshot?.maxOpsPerPlan ?? 32,
+				protectedSkillNames: new Set(snapshot?.protectedSkillNames ?? []),
+				maxMemoryChars: snapshot?.memoryChars ?? 2200,
+				maxUserChars: snapshot?.userChars ?? 1375,
+				maxSkillContentChars: snapshot?.skillContentChars ?? 1e5
+			});
+			const actions = await executePlan(validation.accepted, agent);
+			const evidenceQuotes = [...validation.accepted.memoryOps ?? [], ...validation.accepted.skillOps ?? []].reduce((total, op) => total + (Array.isArray(op.evidence) ? op.evidence.length : 0), 0);
+			session.append("evolution/plan-applied", {
+				planId: randomUUID(),
+				policyFingerprint,
+				memoryApplied: actions.filter((action) => action.startsWith("Memory")).length,
+				skillApplied: actions.filter((action) => action.startsWith("Skill ")).length,
+				rejectedOps: validation.rejected.length,
+				evidenceQuotes,
+				estimatedInputChars: reviewText.length
+			});
+			if (actions.length > 0) agent.inject(createUserMessage({
+				content: [{
+					type: "text",
+					text: `💾 Self-improvement review: ${actions.join(" · ")}`
+				}],
+				source: {
+					kind: "plugin",
+					plugin: "dsh-evolution-review",
+					form: "notice",
+					summary: "self-improvement review"
+				}
+			}));
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async function executePlan(plan, parent) {
+		const memory = ctx.get("memory");
+		const approval = ctx.get("evolutionApproval");
+		const actions = [];
+		for (const op of plan.memoryOps ?? []) {
+			if (!Array.isArray(op.evidence) || op.evidence.length === 0) continue;
+			const normalized = {
+				target: op.target === "user" ? "user" : "memory",
+				action: op.action ?? "add",
+				facts: op.facts ?? op.content,
+				old_text: op.old_text
+			};
+			if ((approval ? await runApproved("memory", `memory ${normalized.target} ${normalized.action}`, normalized, normalized) : await memory?.applyBatch(normalized.target, [normalized]))?.ok) actions.push("Memory updated");
+		}
+		for (const op of plan.skillOps ?? []) {
+			if (!Array.isArray(op.evidence) || op.evidence.length === 0 || !op.name) continue;
+			const args = {
+				...op,
+				evidence: op.evidence
+			};
+			if ((approval ? await runApproved("skill", `skill ${op.action ?? "patch"} ${op.name}`, {
+				operation: args,
+				origin: "background_review"
+			}, args) : await executeSkillTool(parent, args))?.ok) actions.push(`Skill ${op.name} ${op.action ?? "patch"}`);
+		}
+		return actions;
+		async function runApproved(kind, summary, stored, runnerArgs) {
+			if (!approval) return void 0;
+			const decision = await approval.request({
+				kind,
+				summary,
+				args: stored,
+				origin: "background_review"
+			});
+			if (decision.action === "staged") return {
+				ok: false,
+				message: decision.message
+			};
+			return await approval.run(kind, runnerArgs);
+		}
+		async function executeSkillTool(agent, args) {
+			return (await ctx.tools.execute({
+				callId: CallId(`evolution-${randomUUID()}`),
+				name: "skill_manage",
+				arguments: args,
+				agent,
+				signal: AbortSignal.timeout(config.executionTimeoutMs)
+			})).isError ? {
+				ok: false,
+				message: "skill_manage execution failed"
+			} : {
+				ok: true,
+				message: "skill_manage executed"
+			};
+		}
+	}
+	ctx.effect(() => () => {
+		turnStarts.clear();
+	}, "dsh-evolution-review.cleanup");
+}
+function fingerprintPolicy(snapshot) {
+	try {
+		return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex").slice(0, 12);
+	} catch {
+		return;
+	}
+}
+function buildReviewRequest(session, kind, signal, maxMessages, maxMessageChars) {
+	const messages = [];
+	const surface = session.deriveMessages();
+	for (const message of surface.slice(-maxMessages)) if (message.role === "user" || message.role === "assistant") {
+		const text = message.content.map((block) => block.type === "text" ? block.text : "").join(" ").trim();
+		if (text) messages.push(`${message.role.toUpperCase()}: ${text.slice(0, maxMessageChars)}`);
+	}
+	return [
+		`Review kind: ${kind}`,
+		`Signals: ${signal.toolCalls} tool calls, ${signal.userChars} user chars, ${signal.assistantChars} assistant chars.`,
+		"Return ONLY the structured JSON plan. Evidence is mandatory for every op.",
+		"",
+		...messages
+	].join("\n");
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-review";
+const name = "evolution-review-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,24 @@
+/**
+ * Background review orchestration: signal gate → one-shot subagent → trusted plan execution.
+ * @module @deepseek-ai/dsh-evolution-review
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "evolution-review";
+export declare const inject: string[];
+export interface Config {
+    reviewEnabled?: boolean;
+    reviewMode?: string;
+    memoryInterval?: number;
+    skillInterval?: number;
+    /** Tools the one-shot review subagent may use. Defaults include the Anchored Standard discovery pair. */
+    reviewToolAllow?: string[];
+    reviewTimeoutMs?: number;
+    executionTimeoutMs?: number;
+    reviewContextMessages?: number;
+    reviewMessageChars?: number;
+    reviewMaxDepth?: number;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, rawConfig: Config): void;
+//# 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-review-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,59 @@
+{
+  "name": "@lmzhen/dsh-evolution-review",
+  "description": "Background review orchestration (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-review"
+  },
+  "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-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-core": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-plan-validator": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.1"
+  }
+}