@songtonyli/dsh-cli 0.1.22 → 0.1.23

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.
Files changed (44) hide show
  1. package/README.md +1 -1
  2. package/bin/dsh.mjs +1 -1
  3. package/node_modules/@deepseek-ai/dsh-base/cordis.patch.yml +11 -0
  4. package/node_modules/@deepseek-ai/dsh-base/package.json +1 -0
  5. package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
  6. package/node_modules/@deepseek-ai/dsh-compaction-basic/README.i18n.yaml +2 -2
  7. package/node_modules/@deepseek-ai/dsh-compaction-basic/README.md +32 -3
  8. package/node_modules/@deepseek-ai/dsh-compaction-basic/README.zh.md +32 -3
  9. package/node_modules/@deepseek-ai/dsh-compaction-basic/lib/index.js +153 -3
  10. package/node_modules/@deepseek-ai/dsh-goal-round-driver/README.i18n.yaml +2 -2
  11. package/node_modules/@deepseek-ai/dsh-goal-round-driver/README.md +17 -2
  12. package/node_modules/@deepseek-ai/dsh-goal-round-driver/README.zh.md +17 -2
  13. package/node_modules/@deepseek-ai/dsh-goal-round-driver/lib/index.js +153 -2
  14. package/node_modules/@deepseek-ai/dsh-llm-cursor/README.i18n.yaml +2 -2
  15. package/node_modules/@deepseek-ai/dsh-llm-cursor/README.md +1 -1
  16. package/node_modules/@deepseek-ai/dsh-llm-cursor/README.zh.md +1 -1
  17. package/node_modules/@deepseek-ai/dsh-llm-cursor/lib/index.js +48 -24
  18. package/node_modules/@deepseek-ai/dsh-no-progress-reminder/README.i18n.yaml +6 -0
  19. package/node_modules/@deepseek-ai/dsh-no-progress-reminder/README.md +164 -0
  20. package/node_modules/@deepseek-ai/dsh-no-progress-reminder/README.zh.md +164 -0
  21. package/node_modules/@deepseek-ai/dsh-no-progress-reminder/lib/index.js +1516 -0
  22. package/node_modules/@deepseek-ai/dsh-no-progress-reminder/package.json +50 -0
  23. package/node_modules/@deepseek-ai/dsh-repeat-tool-reminder/README.i18n.yaml +2 -2
  24. package/node_modules/@deepseek-ai/dsh-repeat-tool-reminder/README.md +36 -11
  25. package/node_modules/@deepseek-ai/dsh-repeat-tool-reminder/README.zh.md +36 -11
  26. package/node_modules/@deepseek-ai/dsh-repeat-tool-reminder/lib/index.js +54 -7
  27. package/node_modules/@deepseek-ai/dsh-subagent/README.i18n.yaml +2 -2
  28. package/node_modules/@deepseek-ai/dsh-subagent/README.md +2 -2
  29. package/node_modules/@deepseek-ai/dsh-subagent/README.zh.md +2 -2
  30. package/node_modules/@deepseek-ai/dsh-subagent/lib/index.js +93 -32
  31. package/node_modules/@deepseek-ai/dsh-subagent/lib/types/continuation-messages.js +20 -7
  32. package/node_modules/@deepseek-ai/dsh-subagent/lib/types/diagnostic.js +39 -0
  33. package/node_modules/@deepseek-ai/dsh-subagent/lib/types/lifecycle.js +36 -4
  34. package/node_modules/@deepseek-ai/dsh-subagent/lib/types/out-of-process.js +1 -22
  35. package/node_modules/@deepseek-ai/dsh-tool-skill/README.i18n.yaml +2 -2
  36. package/node_modules/@deepseek-ai/dsh-tool-skill/README.md +21 -4
  37. package/node_modules/@deepseek-ai/dsh-tool-skill/README.zh.md +21 -4
  38. package/node_modules/@deepseek-ai/dsh-tool-skill/lib/index.js +194 -16
  39. package/node_modules/@deepseek-ai/dsh-tool-todo/README.i18n.yaml +2 -2
  40. package/node_modules/@deepseek-ai/dsh-tool-todo/README.md +3 -3
  41. package/node_modules/@deepseek-ai/dsh-tool-todo/README.zh.md +3 -3
  42. package/node_modules/@deepseek-ai/dsh-tool-todo/lib/index.js +32 -6
  43. package/node_modules/@deepseek-ai/dsh-tool-todo/lib/types/index.js +31 -5
  44. package/package.json +3 -1
@@ -222,6 +222,40 @@ function finalAssistantOutput(events) {
222
222
  return fold.collect();
223
223
  }
224
224
  //#endregion
225
+ //#region lib/types/diagnostic.js
226
+ /**
227
+ * Byte budget shared by `SubagentResult.diagnostic` and the continuable
228
+ * settlement notice's failure reason.
229
+ *
230
+ * @module @deepseek-ai/dsh-subagent/diagnostic
231
+ */
232
+ /** Maximum UTF-8 size of `SubagentResult.diagnostic`. */
233
+ const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4096;
234
+ const DIAGNOSTIC_TRUNCATION_SUFFIX = "\n[diagnostic truncated]";
235
+ const utf8Encoder = new TextEncoder();
236
+ const utf8Decoder = new TextDecoder();
237
+ /**
238
+ * Limit failure detail without splitting a UTF-8 sequence.
239
+ * @param diagnostic - safe diagnostic text produced by a provider or teardown.
240
+ * @returns the original text, or a visibly truncated value within the limit.
241
+ */
242
+ function limitSubagentDiagnostic(diagnostic) {
243
+ const bytes = utf8Encoder.encode(diagnostic);
244
+ if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES) return diagnostic;
245
+ let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
246
+ while ((bytes[prefixBytes] & 192) === 128) prefixBytes -= 1;
247
+ return utf8Decoder.decode(bytes.subarray(0, prefixBytes)) + DIAGNOSTIC_TRUNCATION_SUFFIX;
248
+ }
249
+ /**
250
+ * Apply the diagnostic byte budget and drop an empty result.
251
+ * @param diagnostic - candidate failure detail, or absent.
252
+ * @returns the limited text, or `undefined` when nothing remains to show.
253
+ */
254
+ function optionalSubagentDiagnostic(diagnostic) {
255
+ if (diagnostic === void 0 || diagnostic.length === 0) return void 0;
256
+ return limitSubagentDiagnostic(diagnostic);
257
+ }
258
+ //#endregion
225
259
  //#region lib/types/types.js
226
260
  /**
227
261
  * The seam's consumer-facing contracts: request, result, and capability types
@@ -334,7 +368,7 @@ function createActivationObserver(emit, provider, childId, parent) {
334
368
  };
335
369
  let boundary = SessionLogOffset(0);
336
370
  let captured = { stopReason: "completed" };
337
- const terminal = (failure) => failure === void 0 ? captured : { stopReason: "error" };
371
+ const terminal = (failure) => resolveActivationTerminal(captured, failure);
338
372
  return {
339
373
  start: (child) => {
340
374
  boundary = child.session.seq;
@@ -343,9 +377,11 @@ function createActivationObserver(emit, provider, childId, parent) {
343
377
  capture: (child) => {
344
378
  const own = child.session.snapshotEvents(boundary);
345
379
  const output = finalAssistantOutput(own);
380
+ const diagnostic = epochDiagnostic(own);
346
381
  captured = {
347
382
  stopReason: epochStopReason(own),
348
- ...output === void 0 ? {} : { output }
383
+ ...output === void 0 ? {} : { output },
384
+ ...diagnostic === void 0 ? {} : { diagnostic }
349
385
  };
350
386
  },
351
387
  terminal,
@@ -360,6 +396,23 @@ function createActivationObserver(emit, provider, childId, parent) {
360
396
  };
361
397
  }
362
398
  /**
399
+ * Resolve this epoch's published terminal facts from the captured child
400
+ * snapshot and any teardown failure. A teardown failure overrides the stop
401
+ * reason and withholds output; a captured diagnostic wins over the thrown
402
+ * value so the parent sees the child's own failure first.
403
+ * @param captured - child-dependent facts snapshotted before handle disposal.
404
+ * @param failure - the teardown or durability failure, or `undefined` on success.
405
+ * @returns this epoch's stop reason, optional output, and optional diagnostic.
406
+ */
407
+ function resolveActivationTerminal(captured, failure) {
408
+ if (failure === void 0) return captured;
409
+ const diagnostic = optionalSubagentDiagnostic(captured.diagnostic) ?? optionalSubagentDiagnostic(errorChain(failure));
410
+ return {
411
+ stopReason: "error",
412
+ ...diagnostic === void 0 ? {} : { diagnostic }
413
+ };
414
+ }
415
+ /**
363
416
  * Why this child's epoch ended, for the terminal lifecycle edge and the
364
417
  * manager's own parent delivery. The child's own log is authoritative:
365
418
  * teardown succeeding says nothing about whether the model errored, hit its
@@ -391,6 +444,16 @@ function epochStopReason(events) {
391
444
  default: return "error";
392
445
  }
393
446
  }
447
+ /**
448
+ * Recorded failure detail for this epoch, when the accounting turn ended
449
+ * as `error`. Other endings have no diagnostic to prefer over teardown.
450
+ * @param events - this epoch's own event suffix.
451
+ * @returns the limited turn-error message, or `undefined` when none exists.
452
+ */
453
+ function epochDiagnostic(events) {
454
+ const { end } = foldConsumedWork(events);
455
+ return end?.data.reason.kind === "error" ? optionalSubagentDiagnostic(end.data.reason.error.message) : void 0;
456
+ }
394
457
  /** Render any listener-thrown value without letting coercion escape containment. */
395
458
  function renderThrown(value) {
396
459
  try {
@@ -642,16 +705,20 @@ function withContinuableReturnGuidance(parentId, prompt) {
642
705
  * the parent's own task vocabulary.
643
706
  * @param childId - the durable child the parent knows by id.
644
707
  * @param stopReason - how the child's last ordinary turn ended.
708
+ * @param diagnostic - sanitized failure reason when `stopReason` is `error`.
645
709
  * @returns the model-facing opening line of the settlement notice.
646
710
  */
647
- function settlementSummary(childId, stopReason) {
711
+ function settlementSummary(childId, stopReason, diagnostic) {
648
712
  const subject = `Background subagent ${childId}`;
649
713
  switch (stopReason) {
650
714
  case "completed": return `${subject} finished and will do no further work unless you send it more.`;
651
715
  case "aborted": return `${subject} was stopped before it finished.`;
652
716
  case "max-tokens": return `${subject} ran out of room before it finished.`;
653
717
  case "refusal": return `${subject} declined the task.`;
654
- case "error": return `${subject} failed before it finished.`;
718
+ case "error": {
719
+ const reason = optionalSubagentDiagnostic(diagnostic);
720
+ return reason === void 0 ? `${subject} failed before it finished.` : `${subject} failed before it finished: ${reason}`;
721
+ }
655
722
  /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
656
723
  * needs a backend that adds a variant; an unnameable ending is reported as unfinished
657
724
  * rather than silently as success. */
@@ -660,24 +727,35 @@ function settlementSummary(childId, stopReason) {
660
727
  }
661
728
  /**
662
729
  * Build the runtime-owned settlement notice from the child's nonempty closing text.
730
+ * A `stopReason: 'error'` notice appends the stable retry instruction after the
731
+ * closing-message block.
663
732
  * @param childId - durable child session id named in the notice.
664
733
  * @param terminal - recorded terminal state for the settled Activation.
665
734
  * @returns the durable user-message representation delivered to the parent.
666
735
  */
667
736
  function createSettlementMessage(childId, terminal) {
668
- const summary = settlementSummary(childId, terminal.stopReason);
737
+ const summary = settlementSummary(childId, terminal.stopReason, terminal.diagnostic);
669
738
  const closingText = (terminal.output ?? []).flatMap((block) => block.type === "text" && block.text.length > 0 ? [block] : []);
739
+ const closing = closingText.length === 0 ? [{
740
+ type: "text",
741
+ text: "It left no closing message."
742
+ }] : [{
743
+ type: "text",
744
+ text: "Its closing message:"
745
+ }, ...closingText];
746
+ const retry = terminal.stopReason === "error" ? [{
747
+ type: "text",
748
+ text: "Do the work directly or retry."
749
+ }] : [];
670
750
  return createUserMessage({
671
- content: [{
672
- type: "text",
673
- text: summary
674
- }, ...closingText.length === 0 ? [{
675
- type: "text",
676
- text: "It left no closing message."
677
- }] : [{
678
- type: "text",
679
- text: "Its closing message:"
680
- }, ...closingText]],
751
+ content: [
752
+ {
753
+ type: "text",
754
+ text: summary
755
+ },
756
+ ...closing,
757
+ ...retry
758
+ ],
681
759
  source: {
682
760
  kind: "subagent-settled",
683
761
  form: "notice",
@@ -2514,23 +2592,6 @@ const subagentIdentityProjectionDefinition = {
2514
2592
  *
2515
2593
  * @module @deepseek-ai/dsh-subagent/out-of-process
2516
2594
  */
2517
- /** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
2518
- const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4096;
2519
- const DIAGNOSTIC_TRUNCATION_SUFFIX = "\n[diagnostic truncated]";
2520
- const utf8Encoder = new TextEncoder();
2521
- const utf8Decoder = new TextDecoder();
2522
- /**
2523
- * Limit provider-authored failure detail without splitting a UTF-8 sequence.
2524
- * @param diagnostic - safe diagnostic text produced by the provider.
2525
- * @returns the original text, or a visibly truncated value within the limit.
2526
- */
2527
- function limitSubagentDiagnostic(diagnostic) {
2528
- const bytes = utf8Encoder.encode(diagnostic);
2529
- if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES) return diagnostic;
2530
- let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
2531
- while ((bytes[prefixBytes] & 192) === 128) prefixBytes -= 1;
2532
- return utf8Decoder.decode(bytes.subarray(0, prefixBytes)) + DIAGNOSTIC_TRUNCATION_SUFFIX;
2533
- }
2534
2595
  /** Enforce the byte limit on a provider-returned diagnostic. */
2535
2596
  function normalizeSubagentDiagnostic(result) {
2536
2597
  return result.diagnostic === void 0 ? result : {
@@ -4,6 +4,7 @@
4
4
  * @module @deepseek-ai/dsh-subagent/continuation-messages
5
5
  */
6
6
  import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
7
+ import { optionalSubagentDiagnostic } from "./diagnostic.js";
7
8
  /** Build durable attribution for one adjacent-Agent message. */
8
9
  function agentMessageSource(sender) {
9
10
  return {
@@ -52,9 +53,10 @@ export function withContinuableReturnGuidance(parentId, prompt) {
52
53
  * the parent's own task vocabulary.
53
54
  * @param childId - the durable child the parent knows by id.
54
55
  * @param stopReason - how the child's last ordinary turn ended.
56
+ * @param diagnostic - sanitized failure reason when `stopReason` is `error`.
55
57
  * @returns the model-facing opening line of the settlement notice.
56
58
  */
57
- function settlementSummary(childId, stopReason) {
59
+ function settlementSummary(childId, stopReason, diagnostic) {
58
60
  const subject = `Background subagent ${childId}`;
59
61
  switch (stopReason) {
60
62
  case 'completed':
@@ -67,8 +69,12 @@ function settlementSummary(childId, stopReason) {
67
69
  // the child had claimed, so the parent must not treat the task as done.
68
70
  case 'refusal':
69
71
  return `${subject} declined the task.`;
70
- case 'error':
71
- return `${subject} failed before it finished.`;
72
+ case 'error': {
73
+ const reason = optionalSubagentDiagnostic(diagnostic);
74
+ return reason === undefined
75
+ ? `${subject} failed before it finished.`
76
+ : `${subject} failed before it finished: ${reason}`;
77
+ }
72
78
  /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
73
79
  * needs a backend that adds a variant; an unnameable ending is reported as unfinished
74
80
  * rather than silently as success. */
@@ -78,22 +84,29 @@ function settlementSummary(childId, stopReason) {
78
84
  }
79
85
  /**
80
86
  * Build the runtime-owned settlement notice from the child's nonempty closing text.
87
+ * A `stopReason: 'error'` notice appends the stable retry instruction after the
88
+ * closing-message block.
81
89
  * @param childId - durable child session id named in the notice.
82
90
  * @param terminal - recorded terminal state for the settled Activation.
83
91
  * @returns the durable user-message representation delivered to the parent.
84
92
  */
85
93
  export function createSettlementMessage(childId, terminal) {
86
- const summary = settlementSummary(childId, terminal.stopReason);
94
+ const summary = settlementSummary(childId, terminal.stopReason, terminal.diagnostic);
87
95
  // Parent providers receive this notice as a user message and may reject
88
96
  // nontext assistant blocks. Keep this conversion local so SDK/UI consumers
89
97
  // retain the complete child output.
90
98
  const closingText = (terminal.output ?? []).flatMap(block => block.type === 'text' && block.text.length > 0 ? [block] : []);
99
+ const closing = closingText.length === 0
100
+ ? [{ type: 'text', text: 'It left no closing message.' }]
101
+ : [{ type: 'text', text: 'Its closing message:' }, ...closingText];
102
+ const retry = terminal.stopReason === 'error'
103
+ ? [{ type: 'text', text: 'Do the work directly or retry.' }]
104
+ : [];
91
105
  return createUserMessage({
92
106
  content: [
93
107
  { type: 'text', text: summary },
94
- ...closingText.length === 0
95
- ? [{ type: 'text', text: 'It left no closing message.' }]
96
- : [{ type: 'text', text: 'Its closing message:' }, ...closingText],
108
+ ...closing,
109
+ ...retry,
97
110
  ],
98
111
  source: {
99
112
  kind: 'subagent-settled',
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Byte budget shared by `SubagentResult.diagnostic` and the continuable
3
+ * settlement notice's failure reason.
4
+ *
5
+ * @module @deepseek-ai/dsh-subagent/diagnostic
6
+ */
7
+ /** Maximum UTF-8 size of `SubagentResult.diagnostic`. */
8
+ const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096;
9
+ const DIAGNOSTIC_TRUNCATION_SUFFIX = '\n[diagnostic truncated]';
10
+ const utf8Encoder = new TextEncoder();
11
+ const utf8Decoder = new TextDecoder();
12
+ /**
13
+ * Limit failure detail without splitting a UTF-8 sequence.
14
+ * @param diagnostic - safe diagnostic text produced by a provider or teardown.
15
+ * @returns the original text, or a visibly truncated value within the limit.
16
+ */
17
+ export function limitSubagentDiagnostic(diagnostic) {
18
+ const bytes = utf8Encoder.encode(diagnostic);
19
+ if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES)
20
+ return diagnostic;
21
+ const suffixBytes = utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
22
+ let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - suffixBytes;
23
+ while ((bytes[prefixBytes] & 0b1100_0000) === 0b1000_0000) {
24
+ prefixBytes -= 1;
25
+ }
26
+ return utf8Decoder.decode(bytes.subarray(0, prefixBytes))
27
+ + DIAGNOSTIC_TRUNCATION_SUFFIX;
28
+ }
29
+ /**
30
+ * Apply the diagnostic byte budget and drop an empty result.
31
+ * @param diagnostic - candidate failure detail, or absent.
32
+ * @returns the limited text, or `undefined` when nothing remains to show.
33
+ */
34
+ export function optionalSubagentDiagnostic(diagnostic) {
35
+ if (diagnostic === undefined || diagnostic.length === 0)
36
+ return undefined;
37
+ return limitSubagentDiagnostic(diagnostic);
38
+ }
39
+ //# sourceMappingURL=diagnostic.js.map
@@ -15,8 +15,10 @@
15
15
  */
16
16
  import { randomUUID } from 'node:crypto';
17
17
  import { foldConsumedWork } from '@deepseek-ai/dsh-agent';
18
+ import { errorChain } from '@deepseek-ai/dsh-llm';
18
19
  import { SessionLogOffset } from '@deepseek-ai/dsh-session';
19
20
  import { finalAssistantOutput } from "./assistant-output.js";
21
+ import { optionalSubagentDiagnostic } from "./diagnostic.js";
20
22
  import { SubagentRunId } from "./types.js";
21
23
  /**
22
24
  * Build the contained lifecycle emitter this seam publishes every edge through.
@@ -97,21 +99,20 @@ export function createActivationObserver(emit, provider, childId, parent) {
97
99
  let captured = { stopReason: 'completed' };
98
100
  // Teardown failure overrides the epoch's own outcome and withholds its
99
101
  // output: an answer this harness could not durably release is not a result.
100
- const terminal = (failure) => failure === undefined
101
- ? captured
102
- : { stopReason: 'error' };
102
+ const terminal = (failure) => resolveActivationTerminal(captured, failure);
103
103
  return {
104
104
  start: (child) => {
105
105
  boundary = child.session.seq;
106
106
  emit('subagent/start', identity, parent);
107
107
  },
108
108
  capture: (child) => {
109
- // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
110
109
  const own = child.session.snapshotEvents(boundary);
111
110
  const output = finalAssistantOutput(own);
111
+ const diagnostic = epochDiagnostic(own);
112
112
  captured = {
113
113
  stopReason: epochStopReason(own),
114
114
  ...output === undefined ? {} : { output },
115
+ ...diagnostic === undefined ? {} : { diagnostic },
115
116
  };
116
117
  },
117
118
  terminal,
@@ -125,6 +126,25 @@ export function createActivationObserver(emit, provider, childId, parent) {
125
126
  },
126
127
  };
127
128
  }
129
+ /**
130
+ * Resolve this epoch's published terminal facts from the captured child
131
+ * snapshot and any teardown failure. A teardown failure overrides the stop
132
+ * reason and withholds output; a captured diagnostic wins over the thrown
133
+ * value so the parent sees the child's own failure first.
134
+ * @param captured - child-dependent facts snapshotted before handle disposal.
135
+ * @param failure - the teardown or durability failure, or `undefined` on success.
136
+ * @returns this epoch's stop reason, optional output, and optional diagnostic.
137
+ */
138
+ export function resolveActivationTerminal(captured, failure) {
139
+ if (failure === undefined)
140
+ return captured;
141
+ const diagnostic = optionalSubagentDiagnostic(captured.diagnostic)
142
+ ?? optionalSubagentDiagnostic(errorChain(failure));
143
+ return {
144
+ stopReason: 'error',
145
+ ...diagnostic === undefined ? {} : { diagnostic },
146
+ };
147
+ }
128
148
  /**
129
149
  * Why this child's epoch ended, for the terminal lifecycle edge and the
130
150
  * manager's own parent delivery. The child's own log is authoritative:
@@ -167,6 +187,18 @@ function epochStopReason(events) {
167
187
  return 'error';
168
188
  }
169
189
  }
190
+ /**
191
+ * Recorded failure detail for this epoch, when the accounting turn ended
192
+ * as `error`. Other endings have no diagnostic to prefer over teardown.
193
+ * @param events - this epoch's own event suffix.
194
+ * @returns the limited turn-error message, or `undefined` when none exists.
195
+ */
196
+ function epochDiagnostic(events) {
197
+ const { end } = foldConsumedWork(events);
198
+ return end?.data.reason.kind === 'error'
199
+ ? optionalSubagentDiagnostic(end.data.reason.error.message)
200
+ : undefined;
201
+ }
170
202
  /** Render any listener-thrown value without letting coercion escape containment. */
171
203
  function renderThrown(value) {
172
204
  try {
@@ -12,28 +12,7 @@
12
12
  */
13
13
  import { accessSync, constants, statSync } from 'node:fs';
14
14
  import { isAbsolute, resolve } from 'node:path';
15
- /** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
16
- const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096;
17
- const DIAGNOSTIC_TRUNCATION_SUFFIX = '\n[diagnostic truncated]';
18
- const utf8Encoder = new TextEncoder();
19
- const utf8Decoder = new TextDecoder();
20
- /**
21
- * Limit provider-authored failure detail without splitting a UTF-8 sequence.
22
- * @param diagnostic - safe diagnostic text produced by the provider.
23
- * @returns the original text, or a visibly truncated value within the limit.
24
- */
25
- function limitSubagentDiagnostic(diagnostic) {
26
- const bytes = utf8Encoder.encode(diagnostic);
27
- if (bytes.byteLength <= MAX_SUBAGENT_DIAGNOSTIC_BYTES)
28
- return diagnostic;
29
- const suffixBytes = utf8Encoder.encode(DIAGNOSTIC_TRUNCATION_SUFFIX).byteLength;
30
- let prefixBytes = MAX_SUBAGENT_DIAGNOSTIC_BYTES - suffixBytes;
31
- while ((bytes[prefixBytes] & 0b1100_0000) === 0b1000_0000) {
32
- prefixBytes -= 1;
33
- }
34
- return utf8Decoder.decode(bytes.subarray(0, prefixBytes))
35
- + DIAGNOSTIC_TRUNCATION_SUFFIX;
36
- }
15
+ import { limitSubagentDiagnostic } from "./diagnostic.js";
37
16
  /** Enforce the byte limit on a provider-returned diagnostic. */
38
17
  function normalizeSubagentDiagnostic(result) {
39
18
  return result.diagnostic === undefined
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
5
- README.md: eeee637c25bc38138deaf907e6bf73202f408b96
6
- README.zh.md: f2c1adf49a838e84fd488f0cb803d3aa30f8b8ca
5
+ README.md: e1615cf19a63771d6d20666df478a79a21ddda88
6
+ README.zh.md: 9d30ecce0eaa0a56b64279444a45b1087596a776
@@ -33,7 +33,7 @@ Use it when agents should discover and load skills during a session. Skip it whe
33
33
 
34
34
  ### Mount and configure
35
35
 
36
- Load the plugin together with the skill registry and at least one provider. The only configuration caps the normalized description length rendered in the catalog.
36
+ Load the plugin together with the skill registry and at least one provider. Configuration caps the catalog description length and names the provider routes that receive the unknown-skill hard-stop.
37
37
 
38
38
  ```yaml
39
39
  - name: '@deepseek-ai/dsh-skill'
@@ -44,6 +44,7 @@ Load the plugin together with the skill registry and at least one provider. The
44
44
  | Field | Default | Meaning |
45
45
  |---|---|---|
46
46
  | `catalogDescriptionMaxLength` | `500` | Maximum normalized description length rendered in the session catalog; minimum 3 |
47
+ | `closedCatalogProviders` | `['cursor']` | Provider routes that receive the per-turn unknown-skill hard-stop; empty disables the stop. Suggestions still run for every provider. |
47
48
 
48
49
  The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-skill) is the exhaustive source for every accepted field.
49
50
 
@@ -56,7 +57,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
56
57
 
57
58
  ### Observable success and failures
58
59
 
59
- Loading a listed skill returns its full instructions; the model sees one canonical shape whether the load came from the tool or from a user's explicit invocation. An invalid name reports `Error: invalid skill name "<name>"`, an unknown name reports the skill is unknown or no longer available, and a skill disabled for model invocation reports it is not available for model invocation. The catalog is omitted entirely when no catalog was ever published and either no model-invocable skills exist or the `skill` tool is hidden or shadowed; after a catalog has been published, either visibility loss — the `skill` tool hidden or shadowed by a same-name scoped tool — or removal of every skill instead appends an empty catalog that retires older names.
60
+ Loading a listed skill returns its full instructions; the model sees one canonical shape whether the load came from the tool or from a user's explicit invocation. An invalid name reports `Error: invalid skill name "<name>"`, an unknown or vanished name reports `Error: skill "<name>" is unknown or no longer available` plus closest catalog names, a capped list of model-invocable names, and the closed-catalog rule, and a skill disabled for model invocation reports it is not available for model invocation. After three consecutive unknown loads on the same live agent in the same turn, further `skill` calls in that turn — including valid names — report that the catalog is closed this turn and the next action must be a task tool when the agent's current or selected provider is in `closedCatalogProviders` (default the Cursor subscription route `cursor`); an invalid name, a model-disabled skill, a successful load, a new turn, a provider outside that list, or direct execution without an agent never applies it. The catalog is omitted entirely when no catalog was ever published and either no model-invocable skills exist or the `skill` tool is hidden or shadowed; after a catalog has been published, either visibility loss — the `skill` tool hidden or shadowed by a same-name scoped tool — or removal of every skill instead appends an empty catalog that retires older names.
60
61
 
61
62
  -----
62
63
 
@@ -77,6 +78,7 @@ The package is built on two ideas. First, the catalog is a durable projection, d
77
78
  | File | Role |
78
79
  |---|---|
79
80
  | [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, catalog and gesture pre-step listeners, rendering and digest |
81
+ | [`src/unknown-skill.ts`](src/unknown-skill.ts) | Closest-name ranker and unknown-skill error text |
80
82
  | — | No runtime invariant companion is published; this model-facing adapter has no independent lifecycle stream; execution relations are owned by the capability seam it calls. |
81
83
 
82
84
  ### Catalog lifecycle
@@ -209,11 +211,26 @@ Append-only; newly visible content follows the reusable request prefix and does
209
211
 
210
212
  #### What the model sees
211
213
 
212
- Invalid or stale selections return exactly `Error: invalid skill name "<name>"`, `Error: skill "<name>" is unknown or no longer available`, or `Error: skill "<name>" is not available for model invocation`. Provider-thrown lookup text is data-dependent and receives the same `Error: <message>` wrapper.
214
+ Invalid names return `Error: invalid skill name "<name>"`. A skill disabled for model invocation returns `Error: skill "<name>" is not available for model invocation`. An unknown or vanished name keeps the first line `Error: skill "<name>" is unknown or no longer available` and appends closest catalog names, the model-invocable name list, and the closed-catalog rule. When no catalog name is close enough, the second line is `No close catalog name matches.` When the catalog is empty, the third line is `The skill catalog is empty.` instead of a `Valid skill names:` list. A list longer than 40 names ends with `(+N more)`. After three consecutive unknown loads on the same live agent in the same turn, further `skill` calls in that turn — including valid names — return the closed-catalog refusal. Provider-thrown lookup text is data-dependent and receives the same `Error: <message>` wrapper. An invalid name or a model-disabled skill does not count toward the per-turn stop. Direct `skill` execution without an agent never applies that stop.
215
+
216
+ ##### Unknown skill error
217
+
218
+ ```markdown
219
+ Error: skill "<name>" is unknown or no longer available
220
+ Closest catalog names: `<near-1>`, `<near-2>`
221
+ Valid skill names: `<name-1>`, `<name-2>`
222
+ The skill catalog is closed: use only listed names. Do not invent names.
223
+ ```
224
+
225
+ ##### Closed catalog this turn
226
+
227
+ ```markdown
228
+ Error: The skill catalog is closed this turn. The next action must be a task tool (read/edit/write/bash), not another skill load.
229
+ ```
213
230
 
214
231
  #### Token effect
215
232
 
216
- Only a failing call adds these retained tokens.
233
+ Only a failing call adds these retained tokens. An unknown-skill error includes a catalog list capped at 40 names; the per-turn refusal is one fixed sentence.
217
234
 
218
235
  #### KV Cache effect
219
236
 
@@ -33,7 +33,7 @@ agent 可以在会话期间发现并加载 skill。在首次请求前,如果
33
33
 
34
34
  ### 挂载与配置
35
35
 
36
- 与 skill 注册表和至少一个提供方一起加载该插件。唯一配置项限制目录中渲染的规范化描述长度。
36
+ 与 skill 注册表和至少一个提供方一起加载该插件。配置项限制目录描述长度,并指定会收到未知 skill 硬停止的提供方路由。
37
37
 
38
38
  ```yaml
39
39
  - name: '@deepseek-ai/dsh-skill'
@@ -44,6 +44,7 @@ agent 可以在会话期间发现并加载 skill。在首次请求前,如果
44
44
  | 字段 | 默认值 | 含义 |
45
45
  |---|---|---|
46
46
  | `catalogDescriptionMaxLength` | `500` | 会话目录中渲染的规范化描述最大长度;最小为 3 |
47
+ | `closedCatalogProviders` | `['cursor']` | 会收到每轮未知 skill 硬停止的提供方路由;空列表禁用该停止。建议仍对每个提供方生效。 |
47
48
 
48
49
  生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-skill)是每个受支持字段的穷尽式真源。
49
50
 
@@ -56,7 +57,7 @@ agent 可以在会话期间发现并加载 skill。在首次请求前,如果
56
57
 
57
58
  ### 可观察的成功与失败
58
59
 
59
- 加载列出的 skill 会返回其完整指令;无论加载来自工具还是用户的显式调用,模型看到的都是同一种规范形态。无效名称会报告 `Error: invalid skill name "<name>"`,未知名称会报告该 skill 未知或已不可用,被禁用模型调用的 skill 会报告其不可用于模型调用。如果从未发布过目录,并且不存在模型可调用 skill,或 `skill` 工具被隐藏或遮蔽,则会整体省略目录;目录发布后,无论可见性丧失——`skill` 工具被隐藏或被同名作用域工具遮蔽——还是删除全部 skill,都会改为追加空目录来停用旧名称。
60
+ 加载列出的 skill 会返回其完整指令;无论加载来自工具还是用户的显式调用,模型看到的都是同一种规范形态。无效名称会报告 `Error: invalid skill name "<name>"`,未知或已消失的名称会报告 `Error: skill "<name>" is unknown or no longer available`,并附上最接近的目录名称、有上限的模型可调用名称列表以及目录已封闭规则,被禁用模型调用的 skill 会报告其不可用于模型调用。同一存活 agent 在同一轮次连续三次未知加载之后,该轮后续 `skill` 调用——包括有效名称——会在该 agent 当前或已选提供方属于 `closedCatalogProviders`(默认是 Cursor 订阅路由 `cursor`)时报告本轮目录已封闭,下一步必须是任务工具;无效名称、模型禁用的 skill、一次成功加载、新的一轮、该列表之外的提供方,或没有 agent 的直接执行,都不会应用该停止。如果从未发布过目录,并且不存在模型可调用 skill,或 `skill` 工具被隐藏或遮蔽,则会整体省略目录;目录发布后,无论可见性丧失——`skill` 工具被隐藏或被同名作用域工具遮蔽——还是删除全部 skill,都会改为追加空目录来停用旧名称。
60
61
 
61
62
  -----
62
63
 
@@ -77,6 +78,7 @@ agent 可以在会话期间发现并加载 skill。在首次请求前,如果
77
78
  | 文件 | 职责 |
78
79
  |---|---|
79
80
  | [`src/index.ts`](src/index.ts) | 插件入口:工具注册、目录与手势 pre-step 监听器、渲染与 digest |
81
+ | [`src/unknown-skill.ts`](src/unknown-skill.ts) | 最近名称排序与未知 skill 错误文本 |
80
82
  | — | 不发布运行时不变式伴生入口;这个面向模型的适配器没有独立的生命周期流;执行关系由它调用的能力 seam 负责。 |
81
83
 
82
84
  ### 目录生命周期
@@ -209,11 +211,26 @@ Load referenced resources only as needed.
209
211
 
210
212
  #### 模型看到什么
211
213
 
212
- 无效或陈旧选择会精确返回 `Error: invalid skill name "<name>"`、`Error: skill "<name>" is unknown or no longer available` 或 `Error: skill "<name>" is not available for model invocation`。提供方抛出的查找文本取决于数据,并套用同一个 `Error: <message>` 包装层。
214
+ 无效名称会返回 `Error: invalid skill name "<name>"`。被禁用模型调用的 skill 会返回 `Error: skill "<name>" is not available for model invocation`。未知或已消失的名称会保留首行 `Error: skill "<name>" is unknown or no longer available`,并追加最接近的目录名称、模型可调用名称列表以及目录已封闭规则。当没有足够接近的目录名称时,第二行是 `No close catalog name matches.`。目录为空时,第三行是 `The skill catalog is empty.`,而不是 `Valid skill names:` 列表。超过 40 个名称的列表以 `(+N more)` 结尾。同一存活 agent 在同一轮次连续三次未知加载之后,该轮后续 `skill` 调用——包括有效名称——会返回关闭目录的拒绝。提供方抛出的查找文本取决于数据,并套用同一个 `Error: <message>` 包装层。无效名称或模型禁用的 skill 不计入该轮停止次数。没有 agent 的直接 `skill` 执行从不应用该停止。
215
+
216
+ ##### 未知 skill 错误
217
+
218
+ ```markdown
219
+ Error: skill "<name>" is unknown or no longer available
220
+ Closest catalog names: `<near-1>`, `<near-2>`
221
+ Valid skill names: `<name-1>`, `<name-2>`
222
+ The skill catalog is closed: use only listed names. Do not invent names.
223
+ ```
224
+
225
+ ##### 本轮关闭的目录
226
+
227
+ ```markdown
228
+ Error: The skill catalog is closed this turn. The next action must be a task tool (read/edit/write/bash), not another skill load.
229
+ ```
213
230
 
214
231
  #### Token 影响
215
232
 
216
- 只有失败调用会添加这些已保留 token。
233
+ 只有失败调用会添加这些已保留 token。未知 skill 错误包含最多 40 个名称的目录列表;该轮拒绝是一句固定句子。
217
234
 
218
235
  #### KV Cache 影响
219
236