@lmzhen/dsh-tool-skill-manage 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -45,6 +45,14 @@ that confirmation does is the `skillWriteConfirm` parameter (`/evolution params`
45
45
  | `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` |
46
46
  | `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 |
47
47
 
48
+ **One human gate per write (T2-10/A25).** When the approval seam is mounted, enabled and will stage
49
+ this write (a background-origin write, or a deployment with `stageForeground`), the confirmation is
50
+ SKIPPED — the approval window is the stronger gate (it holds the bytes until someone decides and replays
51
+ them), and asking first as well asked the same question twice for one foreground write. The confirmation
52
+ still fires exactly once when there is no such seam. A session whose approval policy is `never` has
53
+ opted out of interrupts altogether; the seam allows the write outright there, which is that instruction
54
+ rather than two gates collapsing into none.
55
+
48
56
  The deadline is enforced by the gate itself, not only by the abort signal it hands the question
49
57
  service: a prompt that outlives it returns anyway, and the timer is unref'd and cleared, so an
50
58
  answered prompt leaves neither a parked call nor a live timer behind. This gate is UX, not a
package/lib/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { effectiveSessionPolicy } from "@lmzhen/dsh-evolution-approval";
2
2
  import z from "@deepseek-ai/schemastery";
3
3
  import { defineTool } from "@deepseek-ai/dsh-tools";
4
- import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DSH_AUTHORING_STANDARDS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, anchorVerdict, authoringFeedback, callingScope, clampedNumber, computeDedupGroups, contentHash, errorText, evolutionIoAdapter, fuzzyPatch, isPresent, isUnknown, isUnreadWrite, nearDuplicateSummaries, newSkillLibrary, normalizeFrontmatter, paramRowId, parseFrontmatter, policyStageLimits, probePresent, probeUnknown, resolveExecOrigins, sessionReadSkillNames } from "@lmzhen/dsh-evolution-core";
4
+ import { DEFAULT_ARCHIVE_RETENTION_POLICY, DEFAULT_CITATION_POLICY, DEFAULT_REFERENCE_REWRITE_POLICY, DEFAULT_SKILL_LIMITS, DEFAULT_SKILL_VERSION_KEEP, DEFAULT_SUPPORT_FILE_CHAR_POLICY, DSH_AUTHORING_STANDARDS, SKILLS_GUIDANCE, SKILLS_GUIDANCE_SECTION_ORDER, SKILL_ACTION_REQUIRED_FIELDS, anchorVerdict, authoringFeedback, callingScope, clampedNumber, computeDedupGroups, contentHash, errorText, evolutionIoAdapter, fuzzyPatch, isPresent, isUnknown, isUnreadWrite, nearDuplicateSummaries, newSkillLibrary, normalizeFrontmatter, paramRowId, parseFrontmatter, policyStageLimits, probePresent, probeUnknown, resolveExecOrigins, sessionReadSkillNames, userSetKeys } from "@lmzhen/dsh-evolution-core";
5
5
  //#region lib/types/write-gates.js
6
6
  /**
7
7
  * The write-admission sequence: ONE ordered table of the reasons a skill write is refused.
@@ -56,6 +56,12 @@ const SCALAR_ARG_FIELDS = [
56
56
  "file_content",
57
57
  "absorbed_into"
58
58
  ];
59
+ /** The scalar fields the tool schema types as BOOLEANS; the replay channel has no schema either.
60
+ * T2-V3/A28: `args.replace_all === true` answered "false" for anything else, so a staged
61
+ * `replace_all: 'yes'` silently patched only the FIRST occurrence — a wrong count with no signal.
62
+ * The plan channel already refuses a non-boolean `replace_all` by name (S1-C1); this is the same
63
+ * rule on the replay channel, so the two channels cannot disagree about one flag. */
64
+ const FLAG_ARG_FIELDS = ["replace_all"];
59
65
  /**
60
66
  * Narrow the arguments once for every gate.
61
67
  *
@@ -88,6 +94,11 @@ const GATES = [
88
94
  if (value === void 0 || value === null || typeof value === "string") continue;
89
95
  return `skill_manage: "${field}" must be a string (got ${typeof value}); refusing the write.`;
90
96
  }
97
+ for (const field of FLAG_ARG_FIELDS) {
98
+ const value = view.scalars[field];
99
+ if (value === void 0 || value === null || typeof value === "boolean") continue;
100
+ return `skill_manage: "${field}" must be a boolean (got ${typeof value}); refusing the write.`;
101
+ }
91
102
  return null;
92
103
  }
93
104
  },
@@ -315,8 +326,24 @@ async function previewSkillWrite(library, args) {
315
326
  reason: "the target changed after this write was staged — approving it would be refused"
316
327
  };
317
328
  const action = typeof operation.action === "string" ? operation.action : "";
318
- /** The bytes the write path commits for a body: frontmatter normalized, one trailing newline. */
329
+ /**
330
+ * The bytes the write path commits for a body.
331
+ *
332
+ * T2-04/A19: the library normalizes frontmatter ONLY for SKILL.md (skill-store's `target === skillMd`
333
+ * branch); a support-file write commits the bytes with the trailing-newline rule and nothing else. The
334
+ * preview used to run the SKILL.md pass on EVERY target, so a support file whose body opens with a
335
+ * `---` fence (routine in reference docs) was shown with quoted YAML values — or refused outright with
336
+ * "frontmatter cannot be auto-fixed" — while the approve path stored the untouched bytes: the operator
337
+ * decided on a diff the write path never produces. `filePath === null` is exactly "the target is
338
+ * SKILL.md", the same discrimination the library makes.
339
+ */
319
340
  const bodyOnDisk = (content) => {
341
+ if (filePath !== null) return {
342
+ available: true,
343
+ path,
344
+ before,
345
+ after: content.trimEnd() + "\n"
346
+ };
320
347
  const norm = normalizeFrontmatter(content);
321
348
  if (norm.issues.length > 0) return {
322
349
  available: false,
@@ -394,9 +421,9 @@ function reasonOfError(error) {
394
421
  /**
395
422
  * The registry's live ROOT agent for this call's session, or `undefined`.
396
423
  *
397
- * The registry keys agents by their shared agent/session id (platform `agent/src/index.ts:567`), and
398
- * the platform's `ask()` accepts only an agent that is BOTH its exact live instance and a root
399
- * (platform `user-questions/src/index.ts:96-106`). An id that resolves to an agent owned by another
424
+ * The registry keys agents by their shared agent/session id (platform `agent`), and the
425
+ * platform's `ask()` accepts only an agent that is BOTH its exact live instance and a root —
426
+ * that check is `user-questions`'s own private `assertLiveRoot`. An id that resolves to an agent owned by another
400
427
  * agent is not a root: the caller then proceeds unconfirmed rather than blocking a human question on
401
428
  * an agent no human is watching.
402
429
  * @param probe - the context, read through the optional-service probe.
@@ -424,7 +451,7 @@ function apply(ctx, rawConfig = {}) {
424
451
  ctx.inject(["settings"], (injected) => {
425
452
  const settings = injected.settings;
426
453
  if (typeof settings?.configure !== "function") return;
427
- const disposer = settings.configure({ auto: false });
454
+ const disposer = settings.configure({ auto: false }, ctx.fiber);
428
455
  if (typeof disposer === "function") ctx.effect(() => disposer, "tool-skill-manage: settings presentation");
429
456
  });
430
457
  const systemPrompt = ctx.get("systemPrompt");
@@ -539,17 +566,6 @@ function apply(ctx, rawConfig = {}) {
539
566
  skillWriteConfirmTimeoutSeconds: limit("skillWriteConfirmTimeoutSeconds", rawConfig.skillWriteConfirmTimeoutSeconds, 120)
540
567
  });
541
568
  /**
542
- * The keys the user set in this row's namespace (G1 §8.4-A). This is the ONLY
543
- * remaining read of the settings user layer, and it reads KEY NAMES, never values:
544
- * the platform resolves the user layer into the row's live fields, so the value
545
- * comes from `rowSettings()`.
546
- * @returns the keys present in this row's user layer.
547
- */
548
- const userSetKeys = () => {
549
- const entry = ctx.get("settings")?.describe?.({ redactSecrets: false }).find((item) => item.ns === paramRowId("tool-skill-manage"));
550
- return new Set(Object.keys(entry?.user ?? {}));
551
- };
552
- /**
553
569
  * G3/S3.4 + G1: the USER layer sits above the deployment carriers. `settings()` is
554
570
  * the one reader of this group's knobs — a key the user set (whose value arrived
555
571
  * through the row's live field), then the policy STAGES, then this row. Consumers
@@ -560,7 +576,7 @@ function apply(ctx, rawConfig = {}) {
560
576
  const settings = () => {
561
577
  const row = rowSettings();
562
578
  const stages = policyStageLimits(policySnapshotOf(ctx.get("evolutionPolicy")));
563
- const userSet = userSetKeys();
579
+ const userSet = userSetKeys(ctx, paramRowId("tool-skill-manage"));
564
580
  return {
565
581
  ...row,
566
582
  citationPolicy: userSet.has("citationPolicy") ? row.citationPolicy : stages.citationPolicy ?? row.citationPolicy,
@@ -615,23 +631,42 @@ function apply(ctx, rawConfig = {}) {
615
631
  let crossSourceViewWarned = false;
616
632
  const crossSourceRefusal = async (rawName, phase = "stage") => {
617
633
  const replay = phase === "replay";
618
- if (typeof rawName !== "string" || rawName === "") return null;
634
+ if (typeof rawName !== "string" || rawName === "") return {
635
+ refusal: null,
636
+ view: null
637
+ };
619
638
  const probe = await catalogWinner(rawName);
620
639
  if (isUnknown(probe)) {
621
- if (settings().strictCrossSource) return replay ? `Refused: the cross-source check could not be performed — ${probe.reason}. Reject this staged write, fix the catalog view, and re-stage "${rawName}".` : `Refused: the cross-source check could not be performed — ${probe.reason}. Fix the catalog view (or drop strictCrossSource) before writing "${rawName}".`;
640
+ if (settings().strictCrossSource) return {
641
+ refusal: replay ? `Refused: the cross-source check could not be performed — ${probe.reason}. Reject this staged write, fix the catalog view, and re-stage "${rawName}".` : `Refused: the cross-source check could not be performed — ${probe.reason}. Fix the catalog view (or drop strictCrossSource) before writing "${rawName}".`,
642
+ view: null
643
+ };
622
644
  if (!crossSourceViewWarned) {
623
645
  crossSourceViewWarned = true;
624
646
  ctx.logger.warn(`skill_manage: cross-source check skipped for this session — ${probe.reason}`);
625
647
  }
626
- return null;
648
+ return {
649
+ refusal: null,
650
+ view: null
651
+ };
627
652
  }
628
- if (isPresent(probe) && probe.value !== void 0 && probe.value.provider !== "dsh-evolution") {
629
- const winner = probe.value;
653
+ if (!isPresent(probe)) return {
654
+ refusal: null,
655
+ view: null
656
+ };
657
+ const { view, winner } = probe.value;
658
+ if (winner !== void 0 && winner.provider !== "dsh-evolution") {
630
659
  const message = `skill "${rawName}" resolves to a higher-priority "${winner.source}" skill (provider "${winner.provider}"); this write lands on the family copy, which the catalog does NOT serve — edit the "${winner.source}" copy or rename.`;
631
- if (settings().strictCrossSource) return `Refused: ${message}`;
660
+ if (settings().strictCrossSource) return {
661
+ refusal: `Refused: ${message}`,
662
+ view
663
+ };
632
664
  ctx.logger.warn(`skill_manage: ${message}`);
633
665
  }
634
- return null;
666
+ return {
667
+ refusal: null,
668
+ view
669
+ };
635
670
  };
636
671
  const catalogWinner = async (name) => {
637
672
  const catalog = ctx.get("skills");
@@ -640,12 +675,16 @@ function apply(ctx, rawConfig = {}) {
640
675
  try {
641
676
  const summaries = await catalog.list(scope === void 0 ? void 0 : { scope });
642
677
  if (summaries.length === 0) return probeUnknown(`the catalog view is empty in the ${scope === void 0 ? "global" : "calling"} scope`);
643
- return probePresent(summaries.find((summary) => summary.name === name));
678
+ return probePresent({
679
+ winner: summaries.find((summary) => summary.name === name),
680
+ view: summaries
681
+ });
644
682
  } catch (error) {
645
683
  return probeUnknown(`the catalog lookup failed (${error instanceof Error ? error.message : String(error)})`);
646
684
  }
647
685
  };
648
- async function executeCore(args, origin = "foreground") {
686
+ async function executeCore(args, origin = "foreground", crossSourceView) {
687
+ applyLimits();
649
688
  const action = args.action;
650
689
  const name = args.name ?? "";
651
690
  if (action === "review") try {
@@ -707,7 +746,7 @@ function apply(ctx, rawConfig = {}) {
707
746
  }
708
747
  let result;
709
748
  if (action === "create") {
710
- feedbackLines.push(...await duplicateHintLines(name, candidateDescription));
749
+ feedbackLines.push(...await duplicateHintLines(name, candidateDescription, crossSourceView));
711
750
  result = await library.create(name, args.content ?? "", origin);
712
751
  } else if (action === "edit" || action === "update") result = await library.update(name, args.content ?? "", origin, stagedAnchor);
713
752
  else if (action === "patch") result = await library.patch(name, args.old_string ?? "", args.new_string ?? "", args.file_path ?? "", args.replace_all === true, origin);
@@ -756,10 +795,11 @@ function apply(ctx, rawConfig = {}) {
756
795
  * core's `summary` projection (name + description). Three properties are the
757
796
  * design's, not stylistic choices:
758
797
  *
759
- * - It adds NO read of its own. `library.list()` reads each SKILL.md to parse its
760
- * frontmatter — that listing is what publishes `description` — and the hint never
761
- * calls `library.read`, never holds a body and never compares content, so a create
762
- * pays no SECOND whole-tree pass for it.
798
+ * - It adds NO whole-tree pass of its own. `existing` is the listing the cross-source gate ALREADY
799
+ * read for this operation (T2-05/A20); only when there is none (the gate did not run, or its view
800
+ * was empty/unreadable) does the hint list the tree itself. The earlier wording claimed the listing
801
+ * "reads each SKILL.md anyway", which held only when nothing else in the operation had read the
802
+ * tree — on the create path the gate reads it first, so the hint WAS the second pass.
763
803
  * - It is a HINT: the write proceeds either way (G4 — create's foreground
764
804
  * behavior is unchanged). The model gets the news, not a refusal.
765
805
  * - A failed listing degrades to a NAMED line, never to silence: "nothing
@@ -768,7 +808,7 @@ function apply(ctx, rawConfig = {}) {
768
808
  *
769
809
  * The level and the math live in core (`nearDuplicateSummaries`,
770
810
  * `SUMMARY_DUPLICATE_HINT_THRESHOLD`) — this function owns the wording only. */
771
- async function duplicateHintLines(name, description) {
811
+ async function duplicateHintLines(name, description, existing) {
772
812
  let matches;
773
813
  try {
774
814
  matches = nearDuplicateSummaries({
@@ -776,7 +816,7 @@ function apply(ctx, rawConfig = {}) {
776
816
  name,
777
817
  description
778
818
  },
779
- existing: await library.list()
819
+ existing: existing ?? await library.list()
780
820
  });
781
821
  } catch (error) {
782
822
  return [`Duplicate check skipped: the skill listing failed (${error instanceof Error ? error.message : String(error)}).`];
@@ -900,13 +940,17 @@ function apply(ctx, rawConfig = {}) {
900
940
  const reviewOrigin = origins.approval;
901
941
  const libraryOrigin = origins.library;
902
942
  const sessionPolicy = effectiveSessionPolicy(ctx, exec.agent?.session);
943
+ /** The approval seam this write would go through (T2-10/A25: the gate decision below reads it). */
944
+ const approvalSeam = ctx.get("evolutionApproval");
945
+ let crossSourceView = null;
903
946
  if (typeof args.name === "string" && args.name !== "" && args.action !== "list" && args.action !== "review" && args.action !== "pin" && args.action !== "unpin") {
904
- const refusal = await crossSourceRefusal(args.name);
905
- if (refusal !== null) return {
947
+ const gate = await crossSourceRefusal(args.name);
948
+ if (gate.refusal !== null) return {
906
949
  ok: false,
907
- message: refusal,
950
+ message: gate.refusal,
908
951
  skills: []
909
952
  };
953
+ crossSourceView = gate.view;
910
954
  }
911
955
  const refusal = await runWriteGates({
912
956
  point: "admission",
@@ -915,7 +959,7 @@ function apply(ctx, rawConfig = {}) {
915
959
  protectedNames: protectedSkillNamesOf(),
916
960
  readNames: sessionReadSkillNames(ctx, exec.agent?.session),
917
961
  confirm: async (request) => confirmSkillWrite(request, exec),
918
- confirmMode: settings().skillWriteConfirm,
962
+ confirmMode: approvalSeam !== void 0 && approvalSeam.isEnabled !== false && sessionPolicy !== "never" && (libraryOrigin === "background_review" || approvalSeam.stageForeground !== false) ? "auto" : settings().skillWriteConfirm,
919
963
  confirmTimeoutSeconds: settings().skillWriteConfirmTimeoutSeconds,
920
964
  describeTarget: async () => {
921
965
  const versions = typeof args.name === "string" && args.name !== "" ? (await library.listVersions(args.name).catch(() => [])).length : 0;
@@ -935,7 +979,7 @@ function apply(ctx, rawConfig = {}) {
935
979
  message: refusal,
936
980
  skills: []
937
981
  };
938
- const approval = ctx.get("evolutionApproval");
982
+ const approval = approvalSeam;
939
983
  if (approval && args.action !== "list" && args.action !== "review" && args.action !== "pin" && args.action !== "unpin") {
940
984
  if ((args.action === "update" || args.action === "edit") && typeof args.name === "string" && args.name !== "") {
941
985
  const stageCurrent = await library.read(args.name).catch(() => null);
@@ -971,7 +1015,7 @@ function apply(ctx, rawConfig = {}) {
971
1015
  ...decision.pendingId !== void 0 ? { pending_id: decision.pendingId } : {}
972
1016
  };
973
1017
  }
974
- return await executeCore(operation, libraryOrigin);
1018
+ return await executeCore(operation, libraryOrigin, crossSourceView ?? void 0);
975
1019
  }
976
1020
  }));
977
1021
  ctx.inject(["evolutionApproval"], (approvalCtx) => {
@@ -981,13 +1025,13 @@ function apply(ctx, rawConfig = {}) {
981
1025
  const wrapped = args ?? {};
982
1026
  const operation = wrapped.operation ?? {};
983
1027
  const replayAction = operation.action;
984
- if (replayAction !== "list" && replayAction !== "review" && replayAction !== "pin" && replayAction !== "unpin") return crossSourceRefusal(operation.name, "replay").then((refusal) => {
985
- if (refusal !== null) return {
1028
+ if (replayAction !== "list" && replayAction !== "review" && replayAction !== "pin" && replayAction !== "unpin") return crossSourceRefusal(operation.name, "replay").then((gate) => {
1029
+ if (gate.refusal !== null) return {
986
1030
  ok: false,
987
- message: `${refusal} (re-checked at approve time: the catalog ranking changed while the write was staged)`,
1031
+ message: `${gate.refusal} (re-checked at approve time: the catalog ranking changed while the write was staged)`,
988
1032
  skills: []
989
1033
  };
990
- return executeCore(operation, wrapped.libraryOrigin ?? wrapped.origin ?? "background_review");
1034
+ return executeCore(operation, wrapped.libraryOrigin ?? wrapped.origin ?? "background_review", gate.view ?? void 0);
991
1035
  });
992
1036
  return executeCore(operation, wrapped.libraryOrigin ?? wrapped.origin ?? "background_review");
993
1037
  }, preview);
@@ -41,7 +41,8 @@ export interface Config {
41
41
  * registry id (G1). */
42
42
  supportFileCharPolicy?: Volatile<SupportFileCharPolicy | undefined>;
43
43
  /** Deprecated alias of `skillContentChars` (G0/S0.3): still readable, refused
44
- * by writes; removed in 0.7.0. */
44
+ * by writes; removal was planned for 0.7.0 and is deferred (the alias still
45
+ * ships — see the package README). */
45
46
  maxSkillContentChars?: number;
46
47
  maxSkillFileBytes?: Volatile<number>;
47
48
  /** When true, create/update refuse a description over the 60-char authoring bar (default: advisory feedback only). */
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lmzhen/dsh-tool-skill-manage",
3
3
  "description": "Model-facing skill_manage tool (community build)",
4
- "version": "0.17.0",
4
+ "version": "0.18.0",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -26,25 +26,25 @@
26
26
  ],
27
27
  "license": "MIT",
28
28
  "dependencies": {
29
- "@deepseek-ai/schemastery": "^3.18.1",
30
- "@lmzhen/dsh-evolution-approval": "^0.17.0",
31
- "@lmzhen/dsh-evolution-core": "^0.17.0"
29
+ "@deepseek-ai/schemastery": "^3.18.4",
30
+ "@lmzhen/dsh-evolution-approval": "^0.18.0",
31
+ "@lmzhen/dsh-evolution-core": "^0.18.0"
32
32
  },
33
33
  "peerDependencies": {
34
34
  "@deepseek-ai/cordis": "^4.0.1",
35
35
  "@deepseek-ai/dsh-skill": "^0.2.0-rc.1",
36
36
  "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.1",
37
37
  "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
38
- "@lmzhen/dsh-evolution-io": "^0.17.0",
39
- "@lmzhen/dsh-skill-usage": "^0.17.0"
38
+ "@lmzhen/dsh-evolution-io": "^0.18.0",
39
+ "@lmzhen/dsh-skill-usage": "^0.18.0"
40
40
  },
41
41
  "devDependencies": {
42
42
  "@deepseek-ai/dsh-agent-loop-testkit": "^0.2.0-rc.1",
43
43
  "@deepseek-ai/dsh-skill": "^0.2.0-rc.1",
44
44
  "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.1",
45
45
  "@deepseek-ai/dsh-tools": "^0.2.0-rc.1",
46
- "@lmzhen/dsh-evolution-core": "^0.17.0",
47
- "@lmzhen/dsh-evolution-io": "^0.17.0",
48
- "@lmzhen/dsh-skill-usage": "^0.17.0"
46
+ "@lmzhen/dsh-evolution-core": "^0.18.0",
47
+ "@lmzhen/dsh-evolution-io": "^0.18.0",
48
+ "@lmzhen/dsh-skill-usage": "^0.18.0"
49
49
  }
50
50
  }