@deepseek-ai/dsh-session-title-llm 0.1.1-rc.2 → 0.1.2-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-title-llm/README.md
-README.md: db03205cabf9f723ee9bf6ad122026d75cb92113
-README.zh.md: 7e3a7d30022cd2dec4b59d98b90b9f02e5d6e9b3
+README.md: d17c4962a3cc1f4f369013990c27ff1e5eea5588
+README.zh.md: 156600335eb8e72e39e7441039b6e69bc34528e4

package/README.md

@@ -1,30 +1,97 @@
+---
+description: "Shared model-backed title generation policy for users and maintainers configuring title providers or debugging auxiliary LLM requests."
+kind: "package-library"
+---
+
 # @deepseek-ai/dsh-session-title-llm
 
 English | [中文](README.zh.md)
 
-Shared implementation policy for model-backed session-title providers. It resolves the auxiliary route, frames exact selected human messages as JSON, records the exact dispatchable request, applies a language-aware title instruction, enforces input and output budgets, composes timeout and caller cancellation, assembles the stream, and returns normalized text with exact source seqs plus the provider/model route used to generate it.
+## Summary
+
+`dsh-session-title-llm` runs model-backed title generation through one shared policy: it resolves the auxiliary route, frames the exact selected human messages as JSON, enforces input and output budgets, composes timeout and caller cancellation, and validates the model's output before a title is accepted. It is a library, not a Cordis plugin — the shipped provider plugins call `registerSessionTitleLlmProvider()` with their cadence and message selector, and the helper validates shared config and delegates every revision to one generation path, so registration, route, prompt, cancellation, and validation behavior cannot drift between them. Deployments configure it through the provider plugins, which require every limit. The route, failure, and configuration contracts come first; the request internals live in a collapsible developer section below.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+As a deployment, configure this policy through the [first-prompt](../session-title-first-prompt-llm/README.md) or [all-prompts](../session-title-all-prompts-llm/README.md) provider plugin. As a provider author, register through the shared helper instead of hand-rolling generation.
+
+### Registering a provider
 
-This package is a library, not a Cordis plugin. The provider plugins call `registerSessionTitleLlmProvider()` with their cadence and message selector; it validates shared config and delegates each revision to `generateSessionTitleWithLlm()`, so registration, route, prompt, cancellation, and validation behavior cannot drift between them.
+A provider plugin calls `registerSessionTitleLlmProvider(ctx, config, id, automatic, selectMessages)`; the helper validates the shared config, registers the provider on `ctx.sessionTitle`, and runs every generation through the shared policy. The two shipped plugins register the `first-prompt` and `all-prompts` cadences with their message selectors, and a second registration on the service throws.
 
-## Route and failure contract
+### Route and failure contract
 
-`provider` and `model` overrides are optional but must be supplied together as non-empty strings. Without that pair, the helper uses the exact provider/model route captured from the current session's logged `request/header`; an explicit refresh before any route exists therefore needs overrides. The helper measures the final JSON-framed user prompt, including seq fields, wrappers, and JSON escaping, against `maxInputBytes` before logging or dispatch instead of truncating it. Timeout and caller cancellation are rechecked while consuming the stream and after it completes, so a late successful result cannot be accepted even if an interceptor or adapter ignores abort. Malformed or empty output, tool calls, and non-stop finish reasons also reject; the session-title service decides whether that rejection is an automatic warning or an explicit caller failure.
+`provider` and `model` overrides are optional but must be supplied together as non-empty strings. Without that pair, the helper uses the exact provider/model route captured from the current session's logged `request/header`, so an explicit refresh before any route exists needs overrides. The helper measures the final JSON-framed user prompt against `maxInputBytes` before logging or dispatch instead of truncating it, and rechecks timeout and caller cancellation while consuming the stream and after it completes, so a late successful result cannot be accepted even if an interceptor or adapter ignores abort. Malformed or empty output, tool calls, and non-stop finish reasons reject; the session-title service decides whether that rejection is an automatic warning or an explicit caller failure.
 
-After route and input validation, the helper appends a log-only `session/title-llm-request` event directly through `Session` before model dispatch. It contains the title-provider id, exact source seqs, route, system prompt, message list, and output-token cap used by the call. Persistence observes the record eagerly; the append does not need a title-specific marker, cast, settlement queue, or flush. The dispatched envelope is deep-frozen, carries `purpose: 'session-title'`, and deliberately lacks dsh-agent-loop's process-local request identity. Interceptors stay aligned with the record while loop-only reconstruction observers do not compare it with the conversation header. The DeepSeek adapter maps that purpose to thinking-disabled so the small output budget is reserved for visible title text; other adapters own their purpose-specific behavior. A later model failure leaves the request record intact; validation failures that never become dispatchable requests do not create one. The event stays outside derived model history.
+### Configuration
 
-## Configuration
+<a id="configuration"></a>
 
 Every field is required except the paired route override; there are no library defaults.
 
-| Key | Contract |
+| Key | Default | Meaning |
+|---|---|---|
+| `targetWords` | required | Target word count for non-CJK titles |
+| `targetCjkCharacters` | required | Target character count for Chinese, Japanese, or Korean titles |
+| `maxInputBytes` | required | UTF-8 byte ceiling for the final JSON-framed user prompt |
+| `maxOutputTokens` | required | Auxiliary generation token cap |
+| `timeoutMs` | required | End-to-end deadline within the runtime timer limit |
+| `provider`, `model` | optional | Explicit route; both or neither |
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the generation path; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+One shared policy so provider plugins cannot drift: config validation, route resolution, prompt framing, budget enforcement, cancellation, and output validation all live here, parameterized only by the provider's cadence and message selector.
+
+### Source map
+
+| File | Role |
 |---|---|
-| `targetWords` | Positive target word count for non-CJK titles. |
-| `targetCjkCharacters` | Positive target character count for Chinese, Japanese, or Korean titles. |
-| `maxInputBytes` | Positive UTF-8 byte ceiling for the final JSON-framed user prompt. |
-| `maxOutputTokens` | Positive auxiliary generation token cap. |
-| `timeoutMs` | Positive end-to-end deadline within the runtime timer limit. |
-| `provider`, `model` | Optional explicit route; both or neither. |
+| [`src/index.ts`](src/index.ts) | Config schema and validation, provider registration helper, request framing, dispatch, and output validation |
 
+### Request flow
+
+A generation validates the config once at registration; each revision frames the selected messages as JSON, measures the framed prompt's UTF-8 bytes against `maxInputBytes`, resolves the route (the explicit pair or the logged `request/header`), appends a log-only `session/title-llm-request` event carrying the exact dispatchable request, then streams through `ctx.llm` under a composed timeout and cancellation deadline. The dispatched envelope carries `purpose: 'session-title'` and deliberately lacks the agent loop's process-local request identity; the DeepSeek adapter maps that purpose to thinking-disabled so the small output budget is reserved for visible title text, and other adapters own their purpose-specific behavior. Output assembles into text blocks only; tool calls, malformed or empty output, and non-stop finish reasons reject, and a later model failure leaves the request record intact.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the generation policy is not enough. They move from the service it plugs into to the provider plugins that consume it.
+
+- [Session title service](../session-title/README.md) — the title service, fallback behavior, and provider registration contract.
+- [Session title subsystem](../../../docs/subsystems/session-title.md) — durable title state and the auxiliary request record.
+- [First-message title provider](../session-title-first-prompt-llm/README.md) — titles from the first eligible human message.
+- [All-messages title provider](../session-title-all-prompts-llm/README.md) — titles from every eligible human message.
+- [Session package map](../README.md) — adjacent persistence, projection, title, and telemetry packages.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
 ### Auxiliary title request
@@ -43,5 +110,20 @@ No main-request invalidation. Auxiliary cache reuse is provider-specific; the fi
 
 ## Known Limitations and Deferred Work
 
-- The helper accepts text output only and rejects tool calls; structured-output adapters and provider-specific prompt variants are not exposed.
-- It enforces a byte ceiling for the whole framed user prompt rather than clipping individual messages or applying a retention policy.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define the accepted generation shapes. They are current package constraints.
+
+- **Text output only** — the helper accepts text output and rejects tool calls; structured-output adapters and provider-specific prompt variants are not exposed.
+- **Whole-prompt byte ceiling** — it enforces a byte ceiling for the whole framed user prompt rather than clipping individual messages or applying a retention policy.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,49 +1,129 @@
+---
+description: "面向用户与维护者的共享模型标题生成策略说明，用于配置标题提供方或排查辅助 LLM 请求。"
+kind: "package-library"
+---
+
 # @deepseek-ai/dsh-session-title-llm
 
 [English](README.md) | 中文
 
-由模型支持的会话标题提供方的共享实现策略。它解析辅助路由，将精确选中的用户消息封装为 JSON，记录可分发的确切请求，应用语言感知的标题指令，强制执行输入和输出预算，组合超时与调用方取消，组装流，并返回规范化文本，同时给出确切来源 seq 以及生成该文本时使用的提供方／模型路由。
+## 概述
 
-此包是普通库，不是 Cordis 插件。提供方插件调用 `registerSessionTitleLlmProvider()`，传入各自节奏与消息选择器；该函数验证共享配置，并将每次修订委派给 `generateSessionTitleWithLlm()`，使各插件的注册、路由、提示词、取消与验证行为不会漂移。
+`dsh-session-title-llm` 让模型支持的标题生成都经过同一份共享策略：它解析辅助路由，把精确选中的用户消息封装为 JSON，强制执行输入与输出预算，组合超时与调用方取消，并在标题被接受前校验模型输出。它是普通库而非 Cordis 插件——随附提供方插件以各自的节奏与消息选择器调用 `registerSessionTitleLlmProvider()`，该辅助函数验证共享配置并把每次修订委托给同一条生成路径，因此注册、路由、提示词、取消与校验行为不会在它们之间漂移。部署方通过要求所有上限的提供方插件来配置它。路由、失败与配置约定在前；请求内部细节放在下方可折叠的开发者章节中。
 
-## 路由与失败约定
+## 目录
 
-`provider` 和 `model` 覆盖项都是可选的，但必须同时作为非空字符串提供。如果没有这一对取值，辅助模块会使用当前会话已记录 `request/header` 中捕获的确切提供方／模型路由；因此，在任何路由出现前显式刷新时必须提供覆盖项。辅助模块在记录或分发前，依据 `maxInputBytes` 检查最终 JSON 封装用户提示词的大小，包括 seq 字段、包装层与 JSON 转义，而不是将其截断。消费流期间和流完成后都会重新检查超时与调用方取消，因此即使拦截器或适配器忽略 abort，也不能接受迟到的成功结果。格式错误或空输出、工具调用和非 stop 结束原因同样会导致调用被拒绝；会话标题服务决定该拒绝属于自动警告还是显式调用方失败。
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
 
-路由与输入验证完成后，辅助模块会在模型分发前直接通过 `Session` 追加仅写入日志的 `session/title-llm-request` 事件。它包含标题提供方 id、确切来源 seq、路由、系统提示词、消息列表，以及该调用使用的输出 token 上限。持久化会立即观察到该记录；追加不需要标题专属标记、类型断言、结算队列或刷写。分发的请求封套会深度冻结，携带 `purpose: 'session-title'`，且有意不包含 dsh-agent-loop 的进程本地请求身份。拦截器会与记录保持一致，而循环专用重建观察者不会把它与对话请求头比较。DeepSeek 适配器会根据该用途禁用思考，使少量输出预算全部用于可见标题文本；其他适配器负责自身用途专用行为。后续模型失败会保留请求记录；从未成为可分发请求的验证失败不会创建记录。该事件始终位于派生模型历史之外。
+-----
 
-<a id="configuration"></a>
+<a id="use-this-package"></a>
+## 使用本包
+
+作为部署方，通过[首消息](../session-title-first-prompt-llm/README.zh.md)或[全消息](../session-title-all-prompts-llm/README.zh.md)提供方插件配置此策略。作为提供方作者，通过共享辅助函数注册，而不是手写生成逻辑。
+
+### 注册提供方
+
+提供方插件调用 `registerSessionTitleLlmProvider(ctx, config, id, automatic, selectMessages)`；辅助函数验证共享配置、在 `ctx.sessionTitle` 上注册提供方，并让每次生成都经过共享策略。两个随附插件以各自的 `first-prompt` 与 `all-prompts` 节奏和消息选择器注册；服务上的第二次注册会立即抛出。
+
+### 路由与失败约定
+
+`provider` 与 `model` 覆盖项都是可选的，但必须同时作为非空字符串提供。如果没有这一对取值，辅助函数使用当前会话已记录 `request/header` 中捕获的确切提供方／模型路由，因此在任何路由出现前显式刷新时必须提供覆盖项。辅助函数在记录或分发前，依据 `maxInputBytes` 检查最终 JSON 封装用户提示词的大小，而不是将其截断，并在消费流期间与完成后重新检查超时与调用方取消，因此即使拦截器或适配器忽略 abort，也不能接受迟到的成功结果。格式错误或空输出、工具调用与非 stop 结束原因都会拒绝；会话标题服务决定该拒绝属于自动警告还是显式调用方失败。
+
+### 配置
 
-## 配置
+<a id="configuration"></a>
 
 除成对的路由覆盖项外，每个字段都必填；库不提供默认值。
 
-| 键 | 约定 |
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `targetWords` | 必填 | 非 CJK 标题的目标词数 |
+| `targetCjkCharacters` | 必填 | 中文、日文或韩文标题的目标字符数 |
+| `maxInputBytes` | 必填 | 最终 JSON 封装用户提示词的 UTF-8 字节上限 |
+| `maxOutputTokens` | 必填 | 辅助生成的 token 上限 |
+| `timeoutMs` | 必填 | 运行时定时器限制内的端到端时限 |
+| `provider`, `model` | 可选 | 显式路由；二者同时提供或同时省略 |
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释生成路径；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+一份共享策略让提供方插件无法漂移：配置校验、路由解析、提示词封装、预算执行、取消与输出校验都在这里，只以提供方的节奏与消息选择器为参数。
+
+### 源码地图
+
+| 文件 | 职责 |
 |---|---|
-| `targetWords` | 非 CJK 标题的正整数目标词数。 |
-| `targetCjkCharacters` | 中文、日文或韩文标题的正整数目标字符数。 |
-| `maxInputBytes` | 最终 JSON 封装用户提示词的正整数 UTF-8 字节上限。 |
-| `maxOutputTokens` | 辅助生成的正整数 token 上限。 |
-| `timeoutMs` | 运行时定时器限制内的正数端到端时限。 |
-| `provider`, `model` | 可选显式路由；二者同时提供或同时省略。 |
+| [`src/index.ts`](src/index.ts) | 配置 schema 与校验、提供方注册辅助、请求封装、分发与输出校验 |
+
+### 请求流程
+
+生成在注册时校验一次配置；每次修订把选中的消息封装为 JSON，依据 `maxInputBytes` 检查封装提示词的 UTF-8 字节数，解析路由（显式对或已记录 `request/header`），追加一条携带确切可分发请求的仅日志 `session/title-llm-request` 事件，然后在组合的超时与取消截止时间内通过 `ctx.llm` 流式生成。分发的封套携带 `purpose: 'session-title'`，且有意不包含 agent loop 的进程本地请求身份；DeepSeek 适配器根据该用途禁用思考，使少量输出预算全部用于可见标题文本，其他适配器负责自身用途专用行为。输出只组装为文本块；工具调用、格式错误或空输出与非 stop 结束原因都会拒绝，后续模型失败会保留请求记录。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当生成策略不够用时阅读以下页面。它们从它所插入的服务逐步进入消费它的提供方插件。
+
+- [会话标题服务](../session-title/README.zh.md)——标题服务、回退行为与提供方注册约定。
+- [会话标题子系统](../../../docs/subsystems/session-title.zh.md)——持久标题状态与辅助请求记录。
+- [首消息标题提供方](../session-title-first-prompt-llm/README.zh.md)——根据第一条符合条件的用户消息生成标题。
+- [全消息标题提供方](../session-title-all-prompts-llm/README.zh.md)——根据所有符合条件的用户消息生成标题。
+- [会话包映射](../README.zh.md)——相邻的持久化、投影、标题与遥测包。
 
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
 ### 辅助标题请求
 
-#### 模型看到的内容
+#### 模型看到什么
 
 标题模型会收到固定系统指令，要求以输入语言返回一个简洁且无装饰的标题；该指令包含所配置的词数与 CJK 字符数目标。它唯一的用户消息包含一个 JSON 数组，其中是精确选中的用户消息及其 seq。
 
 #### Token 影响
 
-辅助请求根据所选输入大小和 `maxOutputTokens` 消耗 token。它与主 agent（智能体）请求相互独立，不会向 agent 历史增加标题文本或封装内容。DeepSeek 标题调用会关闭思考；主对话保留自身配置的思考模式。
+辅助请求根据所选输入大小与 `maxOutputTokens` 消耗 token。它与主 agent 请求相互独立，不会向 agent 历史增加标题文本或封装内容。DeepSeek 标题调用会关闭思考；主对话保留自身配置的思考模式。
 
 #### KV Cache 影响
 
 不会使主请求的 KV Cache 失效。辅助缓存复用由提供方决定；固定指令可复用，而 JSON 消息数组会随每次修订变化。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制定义被接受的生成形态。它们是当前包约束。
+
+- **仅文本输出**——辅助函数只接受文本输出并拒绝工具调用；不公开结构化输出适配器或提供方专用提示词变体。
+- **整体提示词字节上限**——它对整个封装用户提示词强制执行字节上限，而不是剪裁单条消息或应用保留策略。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
 
-- 辅助模块只接受文本输出，并拒绝工具调用；不公开结构化输出适配器或提供方专用提示词变体。
-- 它对整个封装用户提示词强制执行字节上限，不会剪裁单条消息或应用保留策略。
+</details>

package/lib/index.js

@@ -1,6 +1,7 @@
 import z from "@deepseek-ai/schemastery";
-import { BlockAssembler, createUserMessage, deepFreeze } from "@deepseek-ai/dsh-llm";
+import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { MAX_TIMER_DELAY_MS, deadline } from "@deepseek-ai/dsh-timeout";
+import { deepFreeze } from "@deepseek-ai/dsh-util-values";
 import { SessionTitleProviderId, normalizeSessionTitle } from "@deepseek-ai/dsh-session-title";
 //#region lib/types/index.js
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-title-llm",
   "description": "Shared LLM generation policy for DeepSeek Harness session-title providers",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,22 +32,23 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-title": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-title": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-title": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-session-title": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2"
   }
 }