@lmzhen/dsh-evolution-approval 0.32.5 → 0.32.6

package/README.md

@@ -1,19 +1,27 @@
 # @lmzhen/dsh-evolution-approval
 
-> 审批窗口：让记忆/技能写入等你批准。
+Staged approval service for memory and skill writes. It records a proposed mutation, then replays the registered runner only after an operator approves it.
 
-## 你会看到
+## Operator surface
 
-`/evolution pending`、`approve`、`reject`，以及设置页待批卡。
+Use `/evolution pending`, `approve <id>`, and `reject <id>`. The settings UI can show the pending queue and, when the owning tool registered a preview, a before/after diff without executing the write.
 
-## 什么时候会用到
+`/evolution release <id>` is different from approval. It returns an orphaned `executing` record to `pending` after a crashed approval. A live foreign process or an in-flight local decision blocks release.
 
-你打开审批后，每次可暂存的写入。
+## Defaults
 
-## 默认 / 前提
+| Setting | Default | Effect |
+|---|---|---|
+| `enabled` | `false` | Writes proceed without this staged queue. |
+| `stageForeground` | `true` | Once enabled, foreground writes also stage unless the effective session policy is `never`. |
+| `pendingTtlMs` | `0` | Pending records never expire automatically. |
+| `approvalConfirm` | `auto` | Approving does not add a second confirmation by default. |
 
-默认关闭；打开后生效。
+A positive `pendingTtlMs` closes expired records as `rejected` and never executes them. Expiry is evaluated on queue reads and decisions, not by a background timer.
 
-## 边界
+## Boundaries
 
-批准/拒绝是人工决定；`release` 不是批准。
+- Background-review writes require a registered replay runner. Staging a record without one is not a usable approval flow.
+- Curator and merge writes have their own controls; they do not pass through this ordinary memory/skill approval queue.
+- Before using `release`, verify whether the original runner already landed the write and what effect it had. Approving the returned record replays that operation, which may be non-idempotent.
+- Resolved history is bounded by the state provider. The JSON provider archives older resolved records; the domain provider does not create that JSON archive sidecar.

package/lib/index.js

@@ -1,6 +1,6 @@
+import { clampOnce, elapsedSince, registerOwnerSettings, textDiffFacts, unwrapLive } from "@lmzhen/dsh-evolution-core";
 import { Service } from "@deepseek-ai/cordis";
 import { randomUUID } from "node:crypto";
-import { clampOnce, elapsedSince, textDiffFacts, unwrapLive } from "@lmzhen/dsh-evolution-core";
 import z from "@deepseek-ai/schemastery";
 import { PENDING_STATUSES } from "@lmzhen/dsh-evolution-state-storage";
 import { HOST_ROUTES, json, methodNotAllowed, readJsonObject, registerHostRoutes } from "@lmzhen/dsh-evolution-core/http-routes";
@@ -31,6 +31,26 @@ const APPROVAL_ROUTES = HOST_ROUTES.approval;
 * reported the same way rather than escaping as an empty 500, because the operator's next step
 * ("reject it", "retry") is only actionable if the reason is visible.
 */
+function structuredOf(record) {
+	const args = record.args;
+	if (record.kind === "memory") {
+		const operations = Array.isArray(args?.operations) ? args.operations : [];
+		const first = operations[0];
+		return {
+			verb: typeof first?.action === "string" ? first.action : typeof args?.action === "string" ? args.action : "update",
+			target: typeof args?.target === "string" ? args.target : "memory",
+			operationCount: operations.length === 0 ? 1 : operations.length,
+			actions: record.status === "executing" ? ["release"] : ["approve", "reject"]
+		};
+	}
+	const operation = args?.operation;
+	return {
+		verb: typeof operation?.action === "string" ? operation.action : "update",
+		target: typeof operation?.name === "string" ? operation.name : record.summary,
+		operationCount: 1,
+		actions: record.status === "executing" ? ["release"] : ["approve", "reject"]
+	};
+}
 async function decide(run, id) {
 	try {
 		const result = await run(id);
@@ -85,7 +105,8 @@ function makeApprovalRoutes(approval, audit) {
 							createdAt: record.createdAt,
 							age: elapsedSince(record.createdAt, Date.now()),
 							status: record.status,
-							...record.claimedBy === void 0 ? {} : { claimedBy: record.claimedBy }
+							...record.claimedBy === void 0 ? {} : { claimedBy: record.claimedBy },
+							...structuredOf(record)
 						}))
 					});
 				} catch (error) {
@@ -165,6 +186,26 @@ function makeApprovalRoutes(approval, audit) {
 				return await decide((current) => approval.approve(current, audit), id);
 			}
 		},
+		{
+			path: APPROVAL_ROUTES.release,
+			methods: ["POST"],
+			requestBody: "buffered",
+			fetch: async (request) => {
+				if (request.method !== "POST") return methodNotAllowed(["POST"]);
+				const id = idOf(await readJsonObject(request));
+				if (id === "") return json(400, {
+					ok: false,
+					code: "bad-request",
+					message: "缺少 id"
+				});
+				if (approval.release === void 0) return json(200, {
+					ok: false,
+					code: "approval-refused",
+					message: "这个部署没有提供 release"
+				});
+				return await decide((current) => approval.release(current), id);
+			}
+		},
 		{
 			path: APPROVAL_ROUTES.reject,
 			methods: ["POST"],
@@ -235,7 +276,7 @@ function effectiveSessionPolicy(ctx, session) {
 	if (!approval || session === void 0) return void 0;
 	return approval.overrideOf(session) ?? approval.config?.policy ?? "ask";
 }
-var EvolutionApproval = class extends Service {
+var EvolutionApproval = class EvolutionApproval extends Service {
 	static inject = ["evolutionState"];
 	static Config = z.object({
 		enabled: z.boolean().default(false).volatile(),
@@ -265,6 +306,7 @@ var EvolutionApproval = class extends Service {
 	inFlight = /* @__PURE__ */ new Map();
 	constructor(ctx, config = {}) {
 		super(ctx, "evolutionApproval");
+		registerOwnerSettings(this.ctx, "evolution-approval", EvolutionApproval.Config);
 		this.enabledConfig = config.enabled;
 		this.stageForegroundConfig = config.stageForeground ?? true;
 		this.pendingTtlMsConfig = config.pendingTtlMs;

package/lib/types/routes.d.ts

@@ -24,6 +24,7 @@ export declare const APPROVAL_ROUTES: {
     readonly preview: "/api/dsh-evolution/approval/preview";
     readonly approve: "/api/dsh-evolution/approval/approve";
     readonly reject: "/api/dsh-evolution/approval/reject";
+    readonly release: "/api/dsh-evolution/approval/release";
 };
 /** What one row of the pending list carries to the browser half. */
 export interface PendingRow {
@@ -36,6 +37,11 @@ export interface PendingRow {
     readonly status: PendingStatus;
     /** Present on a claimed-but-unfinished approve: the operator clears it by rejecting (doctor says so too). */
     readonly claimedBy?: string | undefined;
+    /** Structured summary derived from the staged args; the raw summary stays for details. */
+    readonly verb: string;
+    readonly target: string;
+    readonly operationCount: number;
+    readonly actions: readonly string[];
 }
 /**
  * The slice of the approval service these routes read.
@@ -54,6 +60,11 @@ export interface ApprovalFace {
         ok: boolean;
         message: string;
     }>;
+    /** Release an executing claim; absent on fixtures that only model approve/reject. */
+    release?(id: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
     /** The preview the replayer of that kind registered, when it registered one. */
     previewOf(kind: PendingKind): WritePreview | undefined;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-approval",
   "description": "Stage/pending approval service for Hermes-style self-evolution writes (community build)",
-  "version": "0.32.5",
+  "version": "0.32.6",
   "publishConfig": {
     "access": "public"
   },
@@ -27,18 +27,18 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.32.5"
+    "@lmzhen/dsh-evolution-core": "^0.32.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
-    "@lmzhen/dsh-evolution-core": "^0.32.5",
-    "@lmzhen/dsh-evolution-state": "^0.32.5",
-    "@lmzhen/dsh-evolution-state-storage": "^0.32.5"
+    "@lmzhen/dsh-evolution-core": "^0.32.6",
+    "@lmzhen/dsh-evolution-state": "^0.32.6",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.6"
   },
   "devDependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.32.5",
-    "@lmzhen/dsh-evolution-state": "^0.32.5",
-    "@lmzhen/dsh-evolution-state-storage": "^0.32.5"
+    "@lmzhen/dsh-evolution-core": "^0.32.6",
+    "@lmzhen/dsh-evolution-state": "^0.32.6",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.6"
   },
   "engines": {
     "dsh": ">=0.2.1-rc.2 <0.2.2-0"