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

package/README.md

@@ -0,0 +1,35 @@
+# @deepseek-ai/dsh-evolution-approval
+
+Stage/pending approval service for Hermes-style self-evolution writes.
+
+DSH native approval is one-shot; this service adds the Hermes staged queue:
+`request()` stores background writes, `approve()` replays them through a runner,
+and `reject()` discards them. The core evolution plugin registers memory/skill
+runners when both plugins are composed.
+
+Run the companion invariant and tests:
+
+```sh
+node node_modules/vitest/vitest.mjs run packages/evolution/evolution-approval/tests
+```
+
+## Model Experience
+
+### Indirect model surface
+
+#### What the model sees
+
+`@deepseek-ai/dsh-evolution-approval` 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
+
+
+- `approve()` deduplicates concurrent approvals inside one process, and state providers resolve the pending record atomically. However, the replay runner executes **before** that atomic resolution, so two OS processes approving the same id can each perform the write once while only one process wins the audit transition. Run approvals from a single writer process, or make replay runners idempotent when multi-process approval is required.

package/lib/index.js

@@ -0,0 +1,161 @@
+import { Service } from "@deepseek-ai/cordis";
+import { randomUUID } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/index.js
+/**
+* Stage/pending write approval for self-evolution mutations.
+*
+* DSH's native approval seam is one-shot only. This service adds the
+* Hermes-style staged queue: background review/curator writes are stored in
+* `ctx.evolutionState`, and a human approves or rejects them later. A runner
+* registry replays the exact mutation without passing through the gate a
+* second time. Resolved records are KEPT as audit history.
+*
+* @module @lmzhen/dsh-evolution-approval
+*/
+var EvolutionApproval = class extends Service {
+	static inject = ["evolutionState"];
+	static Config = z.object({
+		enabled: z.boolean().default(false),
+		stageForeground: z.boolean().default(true)
+	});
+	enabled;
+	stageForeground;
+	runners = /* @__PURE__ */ new Map();
+	inFlight = /* @__PURE__ */ new Map();
+	constructor(ctx, config = {}) {
+		super(ctx, "evolutionApproval");
+		this.enabled = config.enabled ?? false;
+		this.stageForeground = config.stageForeground ?? true;
+	}
+	state() {
+		return this.ctx.evolutionState;
+	}
+	/** Fail-closed capability adapters need to distinguish "allowed" from "enabled". */
+	get isEnabled() {
+		return this.enabled;
+	}
+	registerRunner(kind, runner) {
+		this.runners.set(kind, runner);
+		return () => {
+			if (this.runners.get(kind) === runner) this.runners.delete(kind);
+		};
+	}
+	/** Trusted plan-executor entry point: replay a write through the registered runner exactly once. */
+	async run(kind, args) {
+		const runner = this.runners.get(kind);
+		if (!runner) return {
+			ok: false,
+			message: `No replay runner registered for kind "${kind}".`
+		};
+		return await runner(args);
+	}
+	/** Evaluate one mutation. Returns allow, or stores the write and returns staged. */
+	async request(input) {
+		if (!this.enabled) return {
+			action: "allow",
+			message: "Approval disabled."
+		};
+		if (input.origin === "background_review" || this.stageForeground) {
+			const record = {
+				id: randomUUID(),
+				kind: input.kind,
+				summary: input.summary,
+				args: input.args,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+				status: "pending"
+			};
+			await this.state().savePending(record);
+			return {
+				action: "staged",
+				pendingId: record.id,
+				message: `Write staged for approval. Review with /evolution pending and approve ${record.id}.`
+			};
+		}
+		return {
+			action: "allow",
+			message: "Foreground write allowed."
+		};
+	}
+	async list(status = "pending") {
+		return await this.state().listPending(status);
+	}
+	async approve(id) {
+		return await this.dedupe(id, () => this.doApprove(id));
+	}
+	async reject(id) {
+		return await this.dedupe(id, async () => {
+			const resolution = await this.state().tryResolvePending(id, "rejected");
+			if (!resolution.applied || !resolution.record) return {
+				ok: false,
+				message: `Pending write "${id}" is not pending (already resolved or missing).`
+			};
+			return {
+				ok: true,
+				message: `Rejected ${resolution.record.kind} write "${id}".`
+			};
+		});
+	}
+	dedupe(id, task) {
+		const existing = this.inFlight.get(id);
+		if (existing) return existing;
+		const run = task().finally(() => {
+			this.inFlight.delete(id);
+		});
+		this.inFlight.set(id, run);
+		return run;
+	}
+	async doApprove(id) {
+		const claimId = randomUUID();
+		const record = await this.state().claimPending(id, claimId);
+		if (!record) return {
+			ok: false,
+			message: `Pending write "${id}" is already being resolved by another writer.`
+		};
+		const runner = this.runners.get(record.kind);
+		if (!runner) {
+			if (record.kind === "capability") {
+				if (!(await this.state().tryResolvePending(id, "approved")).applied) return {
+					ok: false,
+					message: `Pending write "${id}" was already resolved.`
+				};
+				return {
+					ok: true,
+					message: "Capability approved for manual activation in Creator mode (no code was executed)."
+				};
+			}
+			await this.state().releasePendingClaim(id, claimId);
+			return {
+				ok: false,
+				message: `No replay runner registered for kind "${record.kind}".`
+			};
+		}
+		try {
+			const result = await runner(record.args);
+			if (!result.ok) {
+				await this.state().releasePendingClaim(id, claimId);
+				return {
+					ok: false,
+					message: result.message
+				};
+			}
+		} catch (error) {
+			await this.state().releasePendingClaim(id, claimId);
+			this.ctx.logger.warn(error);
+			return {
+				ok: false,
+				message: "Replay runner failed; the pending write remains pending."
+			};
+		}
+		if (!(await this.state().tryResolvePending(id, "approved")).applied) return {
+			ok: false,
+			message: `Pending write "${id}" was already resolved by another writer.`
+		};
+		return {
+			ok: true,
+			message: `Approved ${record.kind}`
+		};
+	}
+};
+//#endregion
+export { EvolutionApproval, EvolutionApproval as default };

package/lib/invariant.js

@@ -0,0 +1,8 @@
+//#region lib/types/invariant.js
+const PACKAGE_NAME = "@deepseek-ai/dsh-evolution-approval";
+const name = "evolution-approval-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 @@
+/**
+ * Stage/pending write approval for self-evolution mutations.
+ *
+ * DSH's native approval seam is one-shot only. This service adds the
+ * Hermes-style staged queue: background review/curator writes are stored in
+ * `ctx.evolutionState`, and a human approves or rejects them later. A runner
+ * registry replays the exact mutation without passing through the gate a
+ * second time. Resolved records are KEPT as audit history.
+ *
+ * @module @deepseek-ai/dsh-evolution-approval
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type Schema from '@deepseek-ai/schemastery';
+import type { PendingKind, PendingRecord, PendingStatus } from '@deepseek-ai/dsh-evolution-state-storage';
+export type { PendingKind, PendingRecord, PendingStatus };
+export type WriteRunner = (args: unknown) => Promise<{
+    ok: boolean;
+    message: string;
+}>;
+export interface ApprovalRequest {
+    kind: PendingKind;
+    summary: string;
+    args: unknown;
+    origin: 'foreground' | 'background_review';
+}
+export interface ApprovalDecision {
+    action: 'allow' | 'staged';
+    pendingId?: string;
+    message: string;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        evolutionApproval: EvolutionApproval;
+    }
+}
+export interface Config {
+    /** Master switch. Default false matches Hermes write_approval default. */
+    enabled?: boolean;
+    /** Require approval for foreground writes as well. */
+    stageForeground?: boolean;
+}
+export declare class EvolutionApproval extends Service {
+    static inject: string[];
+    static Config: Schema<Config>;
+    private readonly enabled;
+    private readonly stageForeground;
+    private readonly runners;
+    private readonly inFlight;
+    constructor(ctx: Context, config?: Config);
+    private state;
+    /** Fail-closed capability adapters need to distinguish "allowed" from "enabled". */
+    get isEnabled(): boolean;
+    registerRunner(kind: PendingKind, runner: WriteRunner): () => void;
+    /** Trusted plan-executor entry point: replay a write through the registered runner exactly once. */
+    run(kind: PendingKind, args: unknown): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Evaluate one mutation. Returns allow, or stores the write and returns staged. */
+    request(input: ApprovalRequest): Promise<ApprovalDecision>;
+    list(status?: PendingStatus): Promise<PendingRecord[]>;
+    approve(id: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    reject(id: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    private dedupe;
+    private doApprove;
+}
+export default EvolutionApproval;
+//# 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-approval-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/pending-store.d.ts

@@ -0,0 +1,23 @@
+export type PendingKind = 'memory' | 'skill' | 'skill_batch';
+export interface PendingRecord {
+    id: string;
+    kind: PendingKind;
+    summary: string;
+    args: unknown;
+    createdAt: string;
+    status: 'pending' | 'approved' | 'rejected';
+    resolvedAt?: string;
+}
+export declare class PendingStore {
+    private records;
+    private readonly path;
+    constructor(env?: NodeJS.ProcessEnv);
+    private loadSync;
+    private save;
+    list(status?: 'pending' | 'approved' | 'rejected'): PendingRecord[];
+    stage(kind: PendingKind, summary: string, args: unknown): Promise<PendingRecord>;
+    resolve(id: string, status: 'approved' | 'rejected'): Promise<PendingRecord | null>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=pending-store.d.ts.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@lmzhen/dsh-evolution-approval",
+  "description": "Stage/pending approval service for Hermes-style self-evolution writes (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-approval"
+  },
+  "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"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@lmzhen/dsh-evolution-state-storage": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
+    "@lmzhen/dsh-evolution-state-storage": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-io": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-io-node": "^0.1.0-rc.1",
+    "@lmzhen/dsh-evolution-state-json": "^0.1.0-rc.1"
+  }
+}