Skip to content

feat: configurable text limits for advice notes and next-prompt suggestions (#155) - #156

Closed
triagmas wants to merge 1 commit into
omdsh-dev:mainfrom
triagmas:feat/configurable-text-limits
Closed

triagmas wants to merge 1 commit into
omdsh-dev:mainfrom
triagmas:feat/configurable-text-limits

Conversation

@triagmas

Copy link
Copy Markdown
Contributor

Closes #155.

Both user-visible text caps were hardcoded, applied silently, and cut mid-word without a marker for the suggestion (120 characters) / with a mid-word marker for the note (768). This PR makes both bounds configurable and gives the cuts a single, documented shape.

New config keys

key default meaning
nextPromptMaxChars 120 Bound on the stored next-prompt suggestion, in code points. 0 = unbounded. Read live per prediction attempt; one snapshot feeds both the prompt budget and the shaping step.
noteMaxChars 768 Bound on the delivered advice note, in code points. 0 = unbounded. A runtime construction constant, folded into runtimeSignature (an edit rebuilds the session runtime once, exactly like proseFallback).

Both are .volatile() live fields, join CONFIG_KEYS (strict unknown-key rejection unchanged), ride the settings wire (/api/advisor/get + set), appear in the /advisor config readback, and are editable on the web card (two number inputs with hints; an empty input is treated as 0).

Truncation shape

One shared helper — src/text-limit.ts limitText:

  • counts code points, so a surrogate pair is never split;
  • cuts on a word boundary and appends …, with the marker counting toward the bound;
  • accepts the word boundary only when it keeps ≥ 60 % of the budget — a single huge "word" (URL, hash, filler run) would otherwise collapse a near-full note to a few characters;
  • maxChars <= 0 returns the text unchanged (the opt-out).

Defaults keep the historical limits, so an absent key changes only the cut shape: the next-prompt suggestion still lands within 120 code points, but now on a word boundary and marked with …, and the predictor system prompt now states the char budget it enforces.

Evidence

Reproduced on the pre-PR build: a 187-char prediction was stored as exactly 120 characters with endsWith('…') === false and a mid-word tail ("…адержке, потом добав"), while the predictor system prompt carried no budget at all; a 900-char note became 768 + … mid-word. After the change the same inputs are cut on a word boundary and marked.

Tests

pnpm test — pass: 28 files, 767 tests.
pnpm typecheck — pass (main + client + spec configs).
pnpm build — pass.

New coverage: tests/text-limit.test.ts (bounds, 0/negative opt-out, word boundary, 60 % fallback, maxChars = 1, code points, idempotence), plus per-surface cases in tests/config.test.ts (schema defaults/bounds/null/unknown near-miss), tests/next-prompt.test.ts (custom bound, live per-attempt read, prompt budget, 0 = whole text), tests/advisor-runtime.test.ts (runtime option + extraction functions), tests/advisor-store.test.ts (draft seeding, patch, clamping) and tests/gateway.test.ts (wire round-trip).

Docs: README.md / README.zh.md (YAML example, bounds paragraph, surface notes), docs/configuration.md (field table, example YAML, defaults paragraph, card fields, KD-2 notes), docs/consumer-api.md, CONCEPTS.md, docs/verification.md.

…mdsh-dev#155)

Both user-visible text caps were hardcoded and cut the text silently:
the stored next-prompt suggestion at 120 characters (no marker, mid-word)
and the delivered advice note at 768 (marker, mid-word). Add two config
keys and one shared bound helper:

- `nextPromptMaxChars` (default 120, 0 = unbounded): read live per
  prediction attempt; one snapshot feeds both the prompt budget (a
  "keep the reply within N characters" line in the predictor system
  prompt) and the shaping step, so an attempt can never mix two bounds.
- `noteMaxChars` (default 768, 0 = unbounded): a runtime construction
  constant threaded into the runtime options and folded into
  `runtimeSignature`, so an edit rebuilds the session runtime once,
  like `proseFallback`.

The shared `limitText` helper (`src/text-limit.ts`) counts CODE POINTS
(never splitting a surrogate pair), cuts on a word boundary when the
boundary keeps at least 60% of the budget, and appends a `…` marker
that counts toward the bound. Defaults keep the historical limits, so
an absent key behaves exactly as before — except that an over-long text
now lands on a word boundary and carries the marker.

Surfaces: schema + strict key set, `/advisor config` readback, the
settings wire (get/set), the web card (two number inputs) and both
locales. Docs, READMEs and the example YAMLs updated.

Closes omdsh-dev#155
@m-inspector

m-inspector Bot commented Nov 17, 2026

Copy link
Copy Markdown

✅ Verdict: ship it · Score 88% (good)

Findings Count
🔴 must-fix 0
🟠 should-fix 0
🟡 may-fix 2
🔵 nit 1

📋 Review

What this PR does: This PR replaces the two hardcoded advisor text caps — a silent, mid-word 120-code-point slice on the stored next-prompt suggestion and a 768-code-point slice on the delivered advice note — with two config keys, nextPromptMaxChars (default 120, range 0–2000) and noteMaxChars (default 768, range 0–20000), both .volatile(), added to CONFIG_KEYS, the resolved snapshot, the gateway wire, the /advisor config readback, the web card and the en/zh locales. One shared helper, limitText in src/text-limit.ts, now performs every cut: code-point counted, word boundary preferred with a … marker that counts toward the bound, hard cut when a single token exceeds the budget, and maxChars <= 0 meaning unbounded. The suggestion bound is read once per prediction attempt (one snapshot feeding both the predictor prompt budget and the shaping step), while noteMaxChars is a runtime construction constant folded into runtimeSignature, so an edit rebuilds the session runtime exactly like proseFallback; defaults keep the historical limits and only the cut shape changes at defaults, by design.

Findings

🔵 Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants

  • Evidence:

    [DEBT-01] Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants

    • Evidence: src/gateway.ts:748-749 — the S1 containment arm of readConfig() seeds the two bounds with raw literals: nextPromptMaxChars: raw?.nextPromptMaxChars ?? 120, / noteMaxChars: raw?.noteMaxChars ?? 768,; gateway.ts imports nothing from ./text-limit.js.
      src/index.ts:281-282 — the sibling containment arm introduced by the same diff does the identical fallback through the constants: raw?.nextPromptMaxChars ?? DEFAULT_NEXT_PROMPT_MAX_CHARS / raw?.noteMaxChars ?? DEFAULT_ADVISOR_NOTE_MAX_CHARS (imported at src/index.ts:72).
      src/config.ts:266-269 — the schema is the declared default SSOT (.default(DEFAULT_NEXT_PROMPT_MAX_CHARS) / .default(DEFAULT_ADVISOR_NOTE_MAX_CHARS)).
    • Impact: No behavioral difference today (the literals equal the constants). The cost is drift: there are now three places that must agree on the historical defaults, and the two containment arms in the same feature answer the same question two different ways. A future default change edits text-limit.ts + config.ts + index.ts and silently misses gateway.ts, so /api/advisor/get and the settings card would report a bound the resolver never used for the disabled-with-reason arm — exactly the misreport class the S1 seeding exists to prevent.
    • Effort: XS — two lines plus one import.
    • Risk: LOW — pure substitution of equal values; the ?? nullish test (0 stays 0, absent → default) is unchanged.
    • Confidence: HIGH — read both fallback arms and the schema defaults; the values currently match.
    • Merge class: nit
    • Fix sketch: Import DEFAULT_NEXT_PROMPT_MAX_CHARS / DEFAULT_ADVISOR_NOTE_MAX_CHARS from ./text-limit.js in gateway.ts and use them in the readConfig() fallback, matching src/index.ts:281-282. Judgement-class fix (cross-file consistency), not machinery-detectable: the pattern is two ?? <number> exp…
  • Location: src/gateway.ts:748-749

  • Category: tech-debt

  • Merge class: nit

🟡 Live-reapply doc omits noteMaxChars from the runtime-signature list it presents as exhaustive

  • Evidence:

    [DOCS-01] Live-reapply section omits noteMaxChars from the runtime-signature list

    • Evidence: docs/configuration.md:173 — 「每个会话 runtime 仅在其「运行影响签名」(provider / model / systemPrompt / proseFallback / reasoningEffort)变化时重建 —— 只改免疫/窗口的编辑不会中断在途调用或丢弃 backlog。」 The list is presented as the complete set.
    • Evidence: docs/configuration.md:31 — the same change's field-table row for noteMaxChars: 「它是运行期构造常量,因此进 runtime 签名——修改会重建会话 runtime(与 proseFallback 同一路径)。」
    • Evidence: src/index.ts:487-489 — runtimeSignature inserts globalResolved.noteMaxChars ?? DEFAULT_ADVISOR_NOTE_MAX_CHARS, and the inline comment on line 487-488 says nextPromptMaxChars is deliberately ABSENT because it is read live. So the code's signature set contains noteMaxChars and excludes nextPromptMaxChars; the doc at :173 has it the other way round for noteMaxChars (silently absent).
    • Evidence: src/index.ts:792-794 — a signature change calls disposeRuntime + ensureRuntime, so the consequence the section describes (in-flight call abort, backlog drop) is exactly what a noteMaxChars edit now triggers.
    • Impact: a reader who edits noteMaxChars and consults this section (the section that owns "what does a live config edit do to a running session") is told the edit re-applies without a runtime rebuild, i.e. that it does not interrupt in-flight review calls — the opposite of the shipped behavior. The same document asserts both answers, so the reader cannot resolve which one governs.
    • Effort: XS
    • Risk: LOW — adding one item to a prose list; no code touched.
    • Confidence: HIGH — cited both sides of the contradiction (doc row :31, code :487-489) and the rebuild path (:792-794).
    • Merge class: may-fix
    • Fix sketch: add noteMaxChars to the parenthesized signature list at docs/configuration.md:173 (and keep nextPromptMaxChars out, matching the code comment), so the section agrees with the :31 row.
  • Location: docs/configuration.md:173

  • Category: docs

  • Merge class: may-fix

🟡 nextPromptMaxChars row promises an unconditional word-boundary cut; the code hard-cuts mid-word on a long token

  • Evidence:

    [DOCS-02] nextPromptMaxChars row states a word-boundary guarantee the helper only honors conditionally

    • Evidence: docs/configuration.md:30 — 「截断落在词边界并追加 … 标记(标记计入上限)」, stated unconditionally for the new field.
    • Evidence: src/text-limit.ts:33-36 — the helper's own contract: 「A single word longer than the bound falls back to a hard cut: there is no word boundary to land on」; and the body at src/text-limit.ts:49-52 only accepts the boundary when lastSpace >= Math.ceil(budget * 0.6), otherwise cut stays the full budget body. A note whose tail is a URL/hash/long token is cut inside that token.
    • Evidence: tests/text-limit.test.ts:55-61 — this change pins the mid-word path as intended behavior: limitText('a'.repeat(130), 120) === 'a'.repeat(119) + '…', and prefix + 1000×x at bound 120 ends mid-word.
    • Impact: the field row is the reader's contract for user-visible suggestion text. A reader who relies on 「截断落在词边界」 to know that a suggested prompt containing a long identifier never gets split gets a mid-word cut in exactly the case the code documents as routine (long single token, or a trailing token holding < 60 % of the budget). The doc and the helper state different rules for the same bound.
    • Effort: XS
    • Risk: LOW — prose-only change.
    • Confidence: HIGH — implementation, its docstring, and the new tests all read directly.
    • Merge class: may-fix
    • Fix sketch: qualify the row at docs/configuration.md:30 the way src/text-limit.ts:30-36 does — word boundary when it keeps most of the budget, otherwise a code-point hard cut (and mention the 60 % rule if the doc intends to state it).

    Seat coverage declaration (not a finding). Soft cap reached; scope declared truncated. Read in full: docs/configuration.md, docs/consumer-api.md, tests/text-limit.test.ts, plus the new feat: configurable text limits for advice notes and next-prompt suggestions (0 = no truncation) #155 sections of tests/next-prompt.test.ts:755-843, tests/advisor-runtime.test.ts:1601-1650, `tests/advisor-store.test.ts:16…

  • Location: docs/configuration.md:30

  • Category: docs

  • Merge class: may-fix

Revalidated findings

none

Linked-issue AC

- Configurable nextPromptMaxChars (integer, 0–2000, default 120): met — src/config.ts:266-267 declares z.number().step(1).min(0).max(MAX_NEXT_PROMPT_MAX_CHARS).default(DEFAULT_NEXT_PROMPT_MAX_CHARS).
- Configurable noteMaxChars (integer, 0–20000, default 768): met — src/config.ts:268-269 declares the matching schema default/bounds via MAX_ADVISOR_NOTE_MAX_CHARS / DEFAULT_ADVISOR_NOTE_MAX_CHARS.
- Both fields .volatile(), added to CONFIG_KEYS, the resolved snapshot, the gateway write payload, the settings card and the en/zh locales: met — .volatile() at src/config.ts:267,269, CONFIG_KEYS at :191-192, resolved defaults at :421-422, wire round-trip at src/gateway.ts:787-788, card inputs at src/client/advisor-card.tsx:463-496, locale keys at src/client/locales.ts:35-38 (en) and :134-137 (zh).
- One snapshot per attempt, used for both the prompt budget and the shaping step (no mixed limits inside one attempt): met — src/next-prompt.ts:413-415 reads config.nextPromptMaxChars once into attemptMaxChars and passes that same value to callOnce(...) and shapeNextPrompt(raw, attemptMaxChars).
- Word-boundary cut appending … with the marker counting toward the cap, result <= cap, hard cut for a single over-long word: met — src/text-limit.ts:37-59 reserves one code point for the marker and only accepts a boundary at lastSpace >= Math.ceil(budget * 0.6); the hard-cut path is pinned by tests/text-limit.test.ts:55-61.
- 0 = keep the full text: met — src/text-limit.ts:38 returns the text unchanged for maxChars <= 0, and the schema allows 0 on both keys.
- Pass the budget into the predictor system prompt ("keep the reply under N characters"): met — src/prompts.ts:53-56 documents the advisory budget and the prompt is built from the same attemptMaxChars snapshot; enforcement remains the shaping step.
- Config schema bounds and settings round-trip covered by tests: met — tests/config.test.ts:452-495 (defaults/bounds/null/unknown) and the tests/gateway.test.ts bound-field fixtures exercise the wire; the field row at docs/configuration.md:31 already states the noteMaxChars signature consequence.

✅ Verified

- src/text-limit.ts read in full: code-point counting via Array.from, maxChars <= 0 opt-out, one-code-point marker reserve so body + … <= maxChars, and the Math.ceil(budget * 0.6) acceptance rule for a word boundary all match the PR's stated cut shape.
- src/config.ts:190-194,263-269,305-308,362-376,420-422 read: both keys are in CONFIG_KEYS, .volatile(), bounded by the shared MAX constants, unwrapped through unwrapReference, and defaulted on the resolved arm.
- src/index.ts:281-282,487-489,537,1070-1071 read: noteMaxChars is inserted into runtimeSignature and threaded into the runtime options while nextPromptMaxChars is deliberately absent (read live per attempt); the S1 containment arm falls back through the shared constants.
- src/next-prompt.ts:33,167,193,413-415 read: shapeNextPrompt ends in limitText(text, maxChars) and the per-attempt snapshot feeds both the prediction call and the shaping step.
- src/gateway.ts:747-749,786-788 read: both keys ride every resolved get (0 is a real value, never absent) and the S1 containment fallback uses raw 120 / 768 literals.
- src/client/advisor-card.tsx:463-496, src/client/advisor-store.ts:324-354,877-884,1013 and src/client/locales.ts:35-38,134-137 read: two number inputs with min=0 step=1, empty input mapped to 0, draft seeded/clamped/patch-listed on both keys, en+zh label and hint present.
- tests/text-limit.test.ts:55-61 read: the mid-word hard-cut path ('a'.repeat(130) at bound 120) is asserted as intended behavior.
- docs/configuration.md:30,31,173 read: the field rows match the code, while :173's runtime-signature list omits noteMaxChars (DOCS-01) and :30 states the word-boundary rule unconditionally (DOCS-02).
- ❓ PR body reports pnpm test (28 files, 767 tests), pnpm typecheck and pnpm build all passing; the review document shows no command output, so none of those runs are claimed here.
- ❓ PR body promises a truncation debug log carrying only rawLength and a truncated flag; a search of src/ finds no rawLength/truncated logging (only unrelated truncated doc comments), and the review raised no finding on it — confirm whether that detail was dropped from #155's scope.

🗑️ Considered & rejected

- docs/configuration.md:182 (empty number input treated as 0) — rejected as a doc defect: src/client/advisor-card.tsx:475,492 maps an empty input to 0, so the card matches the doc.
- tests/next-prompt.test.ts:767,791 assertions that rebuild the expectation via nextPromptSystemPrompt(...) — rejected: src/prompts.ts:67-70 returns the plain prompt for maxChars <= 0, so no wrong behavior is pinned.
- tests/config.test.ts:476-478 "null treated as absent" — dropped as a candidate: settling it would require execution, so it was excluded under the evidence rules rather than raised.
- nextPromptMaxChars being absent from runtimeSignature — rejected as a defect: the inline comment at src/index.ts:487-488 states the predictor reads it live per attempt, exactly like nextPrompt; only the doc's signature list (DOCS-01) is wrong.
- noteMaxChars in the runtime signature aborting in-flight calls on edit — rejected as a defect: src/index.ts:792-794 (disposeRuntime + ensureRuntime) is the intended proseFallback-style path documented at docs/configuration.md:31.

🛠️ Plan to fix

Expand fix plan
Nothing here blocks merge (0 must-fix); the two doc items and the nit are consistency cleanups. Ordered smallest-first:

1. DEBT-01 (nit) — kill the duplicated bound literals in the containment fallback.
   - src/gateway.ts: add an import of DEFAULT_NEXT_PROMPT_MAX_CHARS / DEFAULT_ADVISOR_NOTE_MAX_CHARS from ./text-limit.js.
   - src/gateway.ts:748-749: replace raw?.nextPromptMaxChars ?? 120 / raw?.noteMaxChars ?? 768 with the imported constants, mirroring the sibling arm at src/index.ts:281-282.
   - Keep the ?? nullish test untouched (0 still stays 0; absent still means the default).
   - Gate: pnpm typecheck; a repo search for ?? 120 / ?? 768 under src/ returns no remaining bound defaults.

2. DOCS-01 (may-fix) — make the live-reapply signature list exhaustive.
   - docs/configuration.md:173: add noteMaxChars to the parenthesized runtime-signature list and leave nextPromptMaxChars out, matching the code comment at src/index.ts:487-489 and the field row at docs/configuration.md:31 (which already says an edit rebuilds the session runtime via the proseFallback path).
   - Re-read the surrounding paragraph so the consequence sentence still reads correctly with the added item (an edit to noteMaxChars aborts in-flight calls and drops backlog, per src/index.ts:792-794).
   - Gate: cross-check the list against src/index.ts:487-537; search the doc for other signature enumerations so none is left stale.

3. DOCS-02 (may-fix) — qualify the word-boundary guarantee in the field row.
   - docs/configuration.md:30: state the rule the helper actually enforces — a word boundary is used when it keeps at least 60% of the budget (lastSpace >= Math.ceil(budget * 0.6)), otherwise the cut is a code-point hard cut inside the trailing token; the … marker counts toward the bound.
   - Keep the row's existing statements (0 = unbounded, code-point counting, one snapshot per attempt, not in the runtime signature) as-is.
   - Gate: read docs/configuration.md:30 against src/text-limit.ts:30-59 and tests/text-limit.test.ts:55-61; the doc must no longer promise an unconditional boundary cut.

4. Regression gate for the whole change set.
   - pnpm typecheck (main + client + spec configs) and pnpm test — expected green: steps 1-3 touch one import pair and two prose lines, and the substituted constants equal the literals, so no test expectation changes.
   - Optional final read: git diff limited to src/gateway.ts and docs/configuration.md to confirm no other file moved.

Review 1 · commit d371965

@m-inspector m-inspector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mstar-inspector line comments · round 1 · d371965

Comment thread src/gateway.ts
// an absent raw key keeps the schema default (120 / 768), so the S1
// fallback never invents an unbounded read.
nextPromptMaxChars: raw?.nextPromptMaxChars ?? 120,
noteMaxChars: raw?.noteMaxChars ?? 768,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants · 🔵 nit

[DEBT-01] Containment fallback duplicates the 120/768 bound defaults as literals instead of the shared constants

  • Evidence: src/gateway.ts:748-749 — the S1 containment arm of readConfig() seeds the two bounds with raw literals: nextPromptMaxChars: raw?.nextPromptMaxChars ?? 120, / noteMaxChars: raw?.noteMaxChars ?? 768,; gateway.ts imports nothing from ./text-limit.js.
    src/index.ts:281-282 — the sibling containment arm introduced by the same diff does the identical fallback through the constants: raw?.nextPromptMaxChars ?? DEFAULT_NEXT_PROMPT_MAX_CHARS / raw?.noteMaxChars ?? DEFAULT_ADVISOR_NOTE_MAX_CHARS (imported at src/index.ts:72).
    src/config.ts:266-269 — the schema is the declared default SSOT (.default(DEFAULT_NEXT_PROMPT_MAX_CHARS) / .default(DEFAULT_ADVISOR_NOTE_MAX_CHARS)).
  • Impact: No behavioral difference today (the literals equal the constants). The cost is drift: there are now three places that must agree on the historical defaults, and the two containment arms in the same feature answer the same question two different ways. A future default change edits text-limit.ts + config.ts + index.ts and silently misses gateway.ts, so /api/advisor/get and the settings card would report a bound the resolver never used for the disabled-with-reason arm — exactly the misreport class the S1 seeding exists to prevent.
  • Effort: XS — two lines plus one import.
  • Risk: LOW — pure substitution of equal values; the ?? nullish test (0 stays 0, absent → default) is unchanged.
  • Confidence: HIGH — read both fallback arms and the schema defaults; the values currently match.
  • Merge class: nit
  • Fix sketch: Import DEFAULT_NEXT_PROMPT_MAX_CHARS / DEFAULT_ADVISOR_NOTE_MAX_CHARS from ./text-limit.js in gateway.ts and use them in the readConfig() fallback, matching `src/index.ts:2…

Comment thread docs/configuration.md
| `proseFallback` | boolean | `false` | Opt-in 散文容错(issue #102):开启后,未产出有效 note(无可解析 JSON 帧,或帧的 note 为空/非法)但正文非空的回复经清理(trim → 剥外围 markdown 围栏 → 768 字符截断)作为 `severity: 'nit'` 的 note 走正常 guard/投递管线。可用的帧 note 始终优先;默认关闭时同样回复仍被丢弃。 |
| `proseFallback` | boolean | `false` | Opt-in 散文容错(issue #102):开启后,未产出有效 note(无可解析 JSON 帧,或帧的 note 为空/非法)但正文非空的回复经清理(trim → 剥外围 markdown 围栏 → `noteMaxChars` 截断,默认 768 码点)作为 `severity: 'nit'` 的 note 走正常 guard/投递管线。可用的帧 note 始终优先;默认关闭时同样回复仍被丢弃。 |
| `nextPrompt` | boolean | `true` | 下一提示预测开关(plan dsh-advisor-next-prompt-n12):每个完成的 turn 后预测用户可能的下一提示,作为 composer 下方提示条显示。**仅 web 配置面**(web 卡片可编辑;`/advisor config` 回读与 TUI 分节不包含该键)。 |
| `nextPromptMaxChars` | number(整数 ≥ 0,≤ 2000) | `120` | 存储的下一提示建议的字数上限(**码点**计数,GitHub issue #155):`0` = 无上限。截断落在词边界并追加 `…` 标记(标记计入上限);同一快照同时喂给该次预测的 prompt 预算(系统提示追加「Keep the reply within N characters」)与塑形步骤,一次预测内不会混用两个上限。该键**不**进 runtime 签名——每次预测实时读取。**仅 web 配置面**(web 卡片可编辑;`/advisor config` 回读,TUI 分节不含)。 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nextPromptMaxChars row promises an unconditional word-boundary cut; the code hard-cuts mid-word on a long token · 🟡 may-fix

[DOCS-02] nextPromptMaxChars row states a word-boundary guarantee the helper only honors conditionally

  • Evidence: docs/configuration.md:30 — 「截断落在词边界并追加 … 标记(标记计入上限)」, stated unconditionally for the new field.
  • Evidence: src/text-limit.ts:33-36 — the helper's own contract: 「A single word longer than the bound falls back to a hard cut: there is no word boundary to land on」; and the body at src/text-limit.ts:49-52 only accepts the boundary when lastSpace >= Math.ceil(budget * 0.6), otherwise cut stays the full budget body. A note whose tail is a URL/hash/long token is cut inside that token.
  • Evidence: tests/text-limit.test.ts:55-61 — this change pins the mid-word path as intended behavior: limitText('a'.repeat(130), 120) === 'a'.repeat(119) + '…', and prefix + 1000×x at bound 120 ends mid-word.
  • Impact: the field row is the reader's contract for user-visible suggestion text. A reader who relies on 「截断落在词边界」 to know that a suggested prompt containing a long identifier never gets split gets a mid-word cut in exactly the case the code documents as routine (long single token, or a trailing token holding < 60 % of the budget). The doc and the helper state different rules for the same bound.
  • Effort: XS
  • Risk: LOW — prose-only change.
  • Confidence: HIGH — implementation, its docstring, and the new tests all read directly.
  • Merge class: may-fix
  • Fix sketch: qualify the row at docs/configuration.md:30 the way src/text-limit.ts:30-36 does — word boundary when it keeps most of the budget, otherwise a code-point hard cut (and mention the 60 % rule if the doc intends to state it).

Seat coverage declaration (not a finding). Soft cap reached; scope declared truncated. Read in full: docs/configuration.md, docs/consumer-api.md, tests/text-limit.test.ts, plus the ne…

@triagmas

Copy link
Copy Markdown
Contributor Author

CI run https://github.com/omdsh-dev/dsh-advisor/actions/runs/44010247313 currently reports action_required with no jobs created for it (the pull_request run from the fork did not execute). That pattern usually means the workflow is waiting for a maintainer to approve it for this fork PR — could a maintainer approve that run (or re-run it) when convenient?

Local verification on this branch (d371965): pnpm typecheck pass, pnpm test pass (28 files, 767 tests), pnpm build pass.

@btspoony

Copy link
Copy Markdown
Member

Superseding this PR with #157, which keeps your work and credits you as co-author (Co-authored-by: triagmas <[email protected]> on the commit).

What we kept, essentially unchanged

  • src/text-limit.ts limitText — code-point counting, word boundary, … counting toward the bound, the 60% acceptance rule, the hard-cut fallback.
  • Both config keys end to end: schema + CONFIG_KEYS + resolved snapshot + gateway get/set + /advisor config readback + web card + en/zh locales.
  • Live per-attempt read for nextPromptMaxChars; noteMaxChars in runtimeSignature.
  • The predictor system prompt budget line.

What we changed

  • No 0 / unbounded setting. The note bound is the only output bound left since the 2026-10-18 maxTokens removal, and a steer-ed note wakes the primary agent, so both keys carry a schema floor. Each key gets its own range: nextPromptMaxChars 50–2000 (default 120), noteMaxChars 128–4096 (default 768).
  • limitText loses the maxChars <= 0 branch; the card treats an empty input as "leave unchanged" instead of 0.

Everything else you touched — docs, tests and surfaces — carried over with those bounds adjusted. pnpm typecheck, pnpm build and pnpm test (28 files, 765 tests) pass on #157.

Thanks for the diagnosis, the helper and the test coverage — the word-boundary shaping was the right call.

@btspoony

Copy link
Copy Markdown
Member

Shipped as #157 (merged in 97c12eb), with your work credited as co-author on the commit. Closing this PR as superseded — thanks again for the diagnosis, the helper and the test coverage; the word-boundary shaping was the right call.

@btspoony btspoony closed this Nov 17, 2026
@m-inspector m-inspector Bot mentioned this pull request Nov 17, 2026
@triagmas
triagmas deleted the feat/configurable-text-limits branch November 17, 2026 07:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: configurable text limits for advice notes and next-prompt suggestions (0 = no truncation)

2 participants