@lmzhen/dsh-tool-skill-manage 0.11.3 → 0.13.0

package/README.md

@@ -34,12 +34,25 @@ write whose target the session never read is refused with `E-318`, and only a re
 counts. A session log the tool cannot read proceeds with one warning rather than blocking every
 autonomous write.
 
-A foreground `create`, or a bare foreground `delete`, asks the operator once before it writes and is
-refused with `E-317` when the answer is not the confirm label; a `delete` carrying `absorbed_into` is the
-merge protocol and does not ask. This gate is UX, not a security door: it is admission-only (a
-replayed record already carries the human release that staged it), and an unmounted question
-service, a caller that is not the registry's exact live root agent, or a failing ask all PROCEED
-with one warning — the operator's own session stays the authority that asked for the write.
+A foreground `create`, or a bare foreground `delete`, is the ONE write this tool puts to a human
+before writing; a `delete` carrying `absorbed_into` is the merge protocol and does not ask. WHAT
+that confirmation does is the `skillWriteConfirm` parameter (`/evolution params`, and the
+技能写入规则 card):
+
+| Mode | What happens |
+|---|---|
+| `auto` (**the default**) | the write proceeds with no prompt — an unattended run (a background pass, a scheduled review, a headless session) must not park a tool call on a question nobody will answer |
+| `ask` | the question waits for as long as it takes; the answer is `Create`/`Delete` to proceed, `Cancel` (or a dismissed card) to refuse with `E-317` |
+| `timeout` | the question is asked with a deadline of `skillWriteConfirmTimeoutSeconds` (default 120 s); an unanswered prompt cancels the write with `E-319`, which names the three knobs |
+
+The deadline is enforced by the gate itself, not only by the abort signal it hands the question
+service: a prompt that outlives it returns anyway, and the timer is unref'd and cleared, so an
+answered prompt leaves neither a parked call nor a live timer behind. This gate is UX, not a
+security door: it is admission-only (a replayed record already carries the human release that staged
+it), and — in the two modes that ask at all — an unmounted question service, a caller that is not
+the registry's exact live root agent, or a failing ask all PROCEED with one warning. The shipped
+`auto` mode asks nothing, so it never reaches those fallbacks; the operator's own session stays the
+authority that asked for the write.
 
 ### Approval seam
 

package/lib/index.js

@@ -32,6 +32,16 @@ import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_REFE
 const CONFIRM_QUESTION_ID = "evolution-skill-write";
 /** The cancel label every confirm question offers. */
 const CANCEL_LABEL = "Cancel";
+/** What a `timeout`-mode deadline settles with: comparable by identity against the seam's
+* boolean, so the two outcomes stay distinguishable without a mutable flag (which a linter
+* cannot follow through a timer callback, and a reader cannot either). */
+const CONFIRM_TIMED_OUT = "confirm-timed-out";
+/** The mode a deployment that configures nothing gets. */
+const DEFAULT_WRITE_CONFIRM_MODE = "auto";
+/** A usable deadline: the configured value when it is a positive finite number, else the default. */
+function timeoutSecondsOf(configured) {
+	return configured !== void 0 && Number.isFinite(configured) && configured >= 1 ? Math.floor(configured) : 120;
+}
 /** The scalar fields the tool schema types as strings; the replay channel has no schema.
 * `action` is one of them: a non-string action used to fall through to the library as "Unknown
 * action" while the read gate re-defaulted it to `patch` and refused with E-318 (review
@@ -120,26 +130,54 @@ const GATES = [
 	{
 		id: "human-confirm",
 		appliesTo: ["admission"],
-		run: async ({ view, origin, confirm, warn }) => {
+		run: async ({ view, origin, confirm, warn, confirmMode, confirmTimeoutSeconds, describeTarget }) => {
 			const action = view.action;
 			if (action === void 0 || origin !== "foreground" || view.name === "") return null;
 			if (!(action === "create" || action === "delete" && view.absorbedInto === void 0)) return null;
+			const mode = confirmMode ?? "auto";
+			if (mode === "auto") return null;
 			if (confirm === void 0) {
 				warn("skill_manage: no confirmation channel is mounted, so the write proceeds unconfirmed.");
 				return null;
 			}
 			const confirmLabel = action === "create" ? "Create" : "Delete";
-			if (await confirm({
+			const seconds = timeoutSecondsOf(confirmTimeoutSeconds);
+			const cancel = new AbortController();
+			let timer;
+			const deadline = mode === "timeout" ? new Promise((resolve) => {
+				timer = setTimeout(() => {
+					cancel.abort();
+					resolve(CONFIRM_TIMED_OUT);
+				}, seconds * 1e3);
+				timer.unref();
+			}) : void 0;
+			const context = await describeTarget?.();
+			const details = [context?.description === void 0 || context.description === "" ? null : "What it does: " + context.description, context?.versions === void 0 ? null : "Content versions recorded: " + String(context.versions)].filter((line) => line !== null);
+			const consequence = action === "create" ? `Create skill "${view.name}"? A new skill directory is written into the family tree.` : `Delete skill "${view.name}"? It is archived under .archive and leaves the catalog.`;
+			const asked = confirm({
 				action,
 				name: view.name,
 				confirmLabel,
 				question: {
 					id: CONFIRM_QUESTION_ID,
 					header: "Confirm",
-					question: action === "create" ? `Create skill "${view.name}"? A new skill directory is written into the family tree.` : `Delete skill "${view.name}"? It is archived under .archive and leaves the catalog.`,
+					question: details.length === 0 ? consequence : consequence + " " + details.join(" · "),
 					options: [{ label: confirmLabel }, { label: CANCEL_LABEL }]
-				}
-			})) return null;
+				},
+				...mode === "timeout" ? { signal: cancel.signal } : {}
+			});
+			let outcome;
+			try {
+				outcome = deadline === void 0 ? await asked : await Promise.race([asked, deadline]);
+			} finally {
+				if (timer !== void 0) clearTimeout(timer);
+			}
+			if (outcome === true) return null;
+			if (outcome === CONFIRM_TIMED_OUT || cancel.signal.aborted) return errorText("e-319-skill-write-confirm-timed-out", {
+				a1: view.name,
+				a2: action === "create" ? "created" : "deleted",
+				a3: String(seconds)
+			});
 			return errorText("e-317-skill-write-not-confirmed", {
 				a1: view.name,
 				a2: action === "create" ? "created" : "deleted"
@@ -214,7 +252,13 @@ const Config = z.object({
 	descriptionStrict: z.boolean().default(false),
 	threatExemptLabels: z.array(z.string()).default([]),
 	strictCrossSource: z.boolean().default(false),
-	skillVersionKeep: z.number().min(1).default(DEFAULT_SKILL_LIMITS.versionKeep ?? DEFAULT_SKILL_VERSION_KEEP)
+	skillVersionKeep: z.number().min(1).default(DEFAULT_SKILL_LIMITS.versionKeep ?? DEFAULT_SKILL_VERSION_KEEP),
+	skillWriteConfirm: z.union([
+		z.const("auto"),
+		z.const("ask"),
+		z.const("timeout")
+	]).default(DEFAULT_WRITE_CONFIRM_MODE),
+	skillWriteConfirmTimeoutSeconds: z.number().min(1).default(120)
 });
 /** Schema the platform validates the user layer against; defaults mirror the core
 * constants and the row schema, so an empty document resolves to today's behaviour. */
@@ -226,7 +270,13 @@ const SKILLS_SETTINGS_SCHEMA = z.object({
 	descriptionStrict: z.boolean().default(false),
 	strictCrossSource: z.boolean().default(false),
 	citationPolicy: z.union([z.const("verify"), z.const("refuse")]).default(DEFAULT_CITATION_POLICY),
-	supportFileCharPolicy: z.union([z.const("report"), z.const("enforce")]).default(DEFAULT_SUPPORT_FILE_CHAR_POLICY)
+	supportFileCharPolicy: z.union([z.const("report"), z.const("enforce")]).default(DEFAULT_SUPPORT_FILE_CHAR_POLICY),
+	skillWriteConfirm: z.union([
+		z.const("auto"),
+		z.const("ask"),
+		z.const("timeout")
+	]).default(DEFAULT_WRITE_CONFIRM_MODE),
+	skillWriteConfirmTimeoutSeconds: z.number().min(1).default(120)
 });
 /** The four caps a user may only tighten, in schema order (the sentry reads it). */
 const SKILL_SETTINGS_CAPS = [
@@ -245,6 +295,18 @@ const SKILL_SETTINGS_CAPS = [
 function validateSkillSettings(value, ceilings) {
 	for (const key of SKILL_SETTINGS_CAPS) if (value[key] > ceilings[key]) throw new Error(`${key} may only be tightened: ${value[key]} exceeds the deployment value ${ceilings[key]}`);
 }
+/** One abort signal that carries BOTH cancellations: the call's own (the operator cancelled the
+* turn) and the gate's deadline (`skillWriteConfirm: 'timeout'`). `undefined` when neither exists —
+* the platform's `ask()` then waits without a signal, which is the `ask` mode.
+* @param call - this call's cancellation signal, when the exec context carries one.
+* @param deadline - the gate's own deadline signal, when the mode imposes one.
+* @returns the request field to spread, or undefined when neither signal exists.
+*/
+function combinedSignal(call, deadline) {
+	if (call === void 0) return deadline === void 0 ? void 0 : { signal: deadline };
+	if (deadline === void 0) return { signal: call };
+	return { signal: AbortSignal.any([call, deadline]) };
+}
 /** The platform error code a question-service failure carries, when it carries one. */
 function questionErrorCode(error) {
 	const code = error?.code;
@@ -348,7 +410,7 @@ function apply(ctx, rawConfig = {}) {
 				options: request.question.options.map((option) => ({ label: option.label }))
 			}],
 			agent,
-			...exec.signal !== void 0 ? { signal: exec.signal } : {}
+			...combinedSignal(exec.signal, request.signal) ?? {}
 		});
 		const declared = exec.agent;
 		if (declared !== void 0) try {
@@ -396,7 +458,9 @@ function apply(ctx, rawConfig = {}) {
 		descriptionStrict: rawConfig.descriptionStrict ?? false,
 		strictCrossSource: rawConfig.strictCrossSource ?? false,
 		citationPolicy: libraryLimits.citationPolicy ?? DEFAULT_CITATION_POLICY,
-		supportFileCharPolicy: libraryLimits.supportFileCharPolicy ?? DEFAULT_SUPPORT_FILE_CHAR_POLICY
+		supportFileCharPolicy: libraryLimits.supportFileCharPolicy ?? DEFAULT_SUPPORT_FILE_CHAR_POLICY,
+		skillWriteConfirm: rawConfig.skillWriteConfirm ?? "auto",
+		skillWriteConfirmTimeoutSeconds: rawConfig.skillWriteConfirmTimeoutSeconds ?? 120
 	};
 	const section = {};
 	const settings = () => {
@@ -412,7 +476,9 @@ function apply(ctx, rawConfig = {}) {
 			descriptionStrict: pick("descriptionStrict"),
 			strictCrossSource: pick("strictCrossSource"),
 			citationPolicy: overridden("citationPolicy") ?? stages.citationPolicy ?? settingsBase.citationPolicy,
-			supportFileCharPolicy: overridden("supportFileCharPolicy") ?? stages.supportFileCharPolicy ?? settingsBase.supportFileCharPolicy
+			supportFileCharPolicy: overridden("supportFileCharPolicy") ?? stages.supportFileCharPolicy ?? settingsBase.supportFileCharPolicy,
+			skillWriteConfirm: pick("skillWriteConfirm"),
+			skillWriteConfirmTimeoutSeconds: pick("skillWriteConfirmTimeoutSeconds")
 		};
 	};
 	const applyLimits = () => {
@@ -748,6 +814,19 @@ function apply(ctx, rawConfig = {}) {
 				protectedNames: protectedSkillNamesOf(),
 				readNames: sessionReadSkillNames(exec.agent?.session),
 				confirm: async (request) => confirmSkillWrite(request, exec),
+				confirmMode: settings().skillWriteConfirm,
+				confirmTimeoutSeconds: settings().skillWriteConfirmTimeoutSeconds,
+				describeTarget: async () => {
+					const versions = typeof args.name === "string" && args.name !== "" ? (await library.listVersions(args.name).catch(() => [])).length : 0;
+					const body = typeof args.content === "string" && args.content !== "" ? args.content : typeof args.name === "string" && args.name !== "" ? await library.read(args.name).catch(() => null) : null;
+					const frontmatter = body === null ? null : parseFrontmatter(body)?.frontmatter ?? null;
+					const parsedDescription = frontmatter === null ? void 0 : frontmatter.description;
+					const description = typeof parsedDescription === "string" ? parsedDescription : "";
+					return {
+						...description === "" ? {} : { description },
+						...versions === 0 ? {} : { versions }
+					};
+				},
 				warn: warnWriteGateOnce
 			});
 			if (refusal !== null) return {
@@ -786,7 +865,7 @@ function apply(ctx, rawConfig = {}) {
 				});
 				if (decision.action === "staged") return {
 					ok: true,
-					message: decision.message,
+					message: decision.pendingId === void 0 ? decision.message : decision.message + " (staged id: " + decision.pendingId + " — /evolution pending lists it)",
 					skills: [],
 					...decision.pendingId !== void 0 ? { pending_id: decision.pendingId } : {}
 				};

package/lib/types/index.d.ts

@@ -20,6 +20,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { CitationPolicy, SupportFileCharPolicy } from '@lmzhen/dsh-evolution-core';
+import { type WriteConfirmMode } from './write-gates.ts';
 export declare const name = "tool-skill-manage";
 export declare const inject: string[];
 export interface Config {
@@ -50,6 +51,11 @@ export interface Config {
      * like the four caps above — the settings layer deliberately has no card for it (retention is
      * storage policy, not an authoring knob). */
     skillVersionKeep?: number;
+    /** What the ONE confirmation before a create or a bare delete does (registry `skillWriteConfirm`).
+     * Default `auto`: an unattended run must not park a tool call on a question nobody will answer. */
+    skillWriteConfirm?: WriteConfirmMode;
+    /** Seconds a `timeout`-mode prompt waits for an answer before the write is cancelled. */
+    skillWriteConfirmTimeoutSeconds?: number;
 }
 export declare const Config: z<Config>;
 /** Write behaviour a user may change (G3/S3.4). Field names are the CANONICAL
@@ -73,6 +79,10 @@ export interface SkillSettings {
     citationPolicy: CitationPolicy;
     /** Warn about an oversize support file, or refuse the write. */
     supportFileCharPolicy: SupportFileCharPolicy;
+    /** What the confirmation before a create or a bare delete does (0.12.0). */
+    skillWriteConfirm: WriteConfirmMode;
+    /** Seconds a `timeout`-mode confirmation waits before the write is cancelled. */
+    skillWriteConfirmTimeoutSeconds: number;
 }
 /** Schema the platform validates the user layer against; defaults mirror the core
  * constants and the row schema, so an empty document resolves to today's behaviour. */

package/lib/types/write-gates.d.ts

@@ -25,6 +25,25 @@
 import { type WriteOrigin } from '@lmzhen/dsh-evolution-core';
 /** The point whose verdict is being taken. */
 export type WriteGatePoint = 'admission' | 'execution';
+/**
+ * How the ONE confirmation behaves (registry `skillWriteConfirm`).
+ *
+ * `auto` writes without asking — the default, because an unattended run (a background pass, a
+ * scheduled review, a headless session) must not park a tool call on a question nobody will answer.
+ * `ask` waits for as long as it takes, which is the deployment that wants the gate in the loop.
+ * `timeout` asks and cancels the write on its own deadline.
+ */
+export type WriteConfirmMode = 'auto' | 'ask' | 'timeout';
+/** The mode a deployment that configures nothing gets. */
+export declare const DEFAULT_WRITE_CONFIRM_MODE: WriteConfirmMode;
+/** Seconds a `timeout`-mode prompt waits before the write is cancelled. */
+export declare const DEFAULT_WRITE_CONFIRM_TIMEOUT_SECONDS = 120;
+/** What the operator is told about the target before answering. Every field is optional: a target
+ * with no frontmatter, or one the library cannot read, simply carries less. */
+export interface ConfirmContext {
+    readonly description?: string | undefined;
+    readonly versions?: number | undefined;
+}
 /** One confirm question, as the gate writes it and the seam asks it. */
 export interface WriteConfirmRequest {
     /** The action being confirmed (`create` or `delete`). */
@@ -42,6 +61,9 @@ export interface WriteConfirmRequest {
     };
     /** The option label that means "proceed". */
     readonly confirmLabel: string;
+    /** A deadline the gate imposes on itself (`timeout` mode); the seam combines it with the call's
+     * own cancellation. An abort is a dismissal, never a consent. */
+    readonly signal?: AbortSignal;
 }
 /**
  * Ask the human to confirm one irreversible skill write.
@@ -68,6 +90,13 @@ export interface WriteGateContext {
     readonly readNames: ReadonlySet<string> | undefined;
     /** The human confirm seam — read only by the gates that apply to `'admission'`. */
     readonly confirm: WriteConfirm | undefined;
+    /** The registry's `skillWriteConfirm`: `auto` (the default) skips the question entirely. */
+    readonly confirmMode?: WriteConfirmMode;
+    /** The registry's `skillWriteConfirmTimeoutSeconds`, read only in `timeout` mode. */
+    readonly confirmTimeoutSeconds?: number;
+    /** Read the target's own words for the confirmation card. LAZY on purpose: a write that is not
+     * asked about must not pay a read for a question nobody sees. Absent means "say nothing extra". */
+    readonly describeTarget?: (() => Promise<ConfirmContext | undefined>) | undefined;
     /** Report a degraded gate; must not throw. The implementation decides how often it speaks — the
      * shipped seam latches once per PROCESS, because the conditions it reports (no question service,
      * an unreadable session log) belong to the deployment, not to one write. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-tool-skill-manage",
   "description": "Model-facing skill_manage tool (community build)",
-  "version": "0.11.3",
+  "version": "0.13.0",
   "publishConfig": {
     "access": "public"
   },
@@ -27,24 +27,24 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1",
-    "@lmzhen/dsh-evolution-approval": "^0.11.3",
-    "@lmzhen/dsh-evolution-core": "^0.11.3"
+    "@lmzhen/dsh-evolution-approval": "^0.13.0",
+    "@lmzhen/dsh-evolution-core": "^0.13.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-skill": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-io": "^0.11.3",
-    "@lmzhen/dsh-skill-usage": "^0.11.3"
+    "@lmzhen/dsh-evolution-io": "^0.13.0",
+    "@lmzhen/dsh-skill-usage": "^0.13.0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-skill": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@lmzhen/dsh-evolution-core": "^0.11.3",
-    "@lmzhen/dsh-evolution-io": "^0.11.3",
-    "@lmzhen/dsh-skill-usage": "^0.11.3"
+    "@lmzhen/dsh-evolution-core": "^0.13.0",
+    "@lmzhen/dsh-evolution-io": "^0.13.0",
+    "@lmzhen/dsh-skill-usage": "^0.13.0"
   }
 }