mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
feat(session-title): add fallback and model providers
This commit is contained in:
Tianyi Cui
245
packages/session-title/session-title-llm/src/index.ts
Normal file
245
packages/session-title/session-title-llm/src/index.ts
Normal file
@@ -0,0 +1,245 @@
|
||||
/**
|
||||
* Shared route, framing, timeout, assembly, and validation policy for
|
||||
* model-backed session-title providers.
|
||||
* @module @deepseek-ai/dsh-session-title-llm
|
||||
*/
|
||||
|
||||
import type { Context } from 'cordis'
|
||||
import z from 'schemastery'
|
||||
import { BlockAssembler, deepFreeze } from '@deepseek-ai/dsh-llm'
|
||||
import type { FinishReason, GenerateOptions } from '@deepseek-ai/dsh-llm'
|
||||
import { deadline, MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
|
||||
import { normalizeSessionTitle, SessionTitleProviderId } from '@deepseek-ai/dsh-session-title'
|
||||
import type {
|
||||
SessionTitleAutomaticMode,
|
||||
SessionTitleModelProvenance,
|
||||
SessionTitleProviderRequest,
|
||||
SessionTitleProviderResult,
|
||||
SessionTitleUserMessage,
|
||||
} from '@deepseek-ai/dsh-session-title'
|
||||
|
||||
/** Capability-owned timeout reason code for auxiliary title requests. */
|
||||
export const SESSION_TITLE_TIMEOUT_CODE = 'SESSION_TITLE_TIMEOUT'
|
||||
|
||||
/** Required deployment policy for one model-backed title plugin. */
|
||||
export interface SessionTitleLlmConfig {
|
||||
/** Target word count for non-CJK titles. */
|
||||
readonly targetWords: number
|
||||
/** Target character count for Chinese, Japanese, or Korean titles. */
|
||||
readonly targetCjkCharacters: number
|
||||
/** Maximum total UTF-8 bytes across selected source-message text. */
|
||||
readonly maxInputBytes: number
|
||||
/** Auxiliary generation output-token cap. */
|
||||
readonly maxOutputTokens: number
|
||||
/** End-to-end auxiliary request deadline in milliseconds. */
|
||||
readonly timeoutMs: number
|
||||
/** Optional explicit provider route; must be paired with `model`. */
|
||||
readonly provider?: string
|
||||
/** Optional explicit model id; must be paired with `provider`. */
|
||||
readonly model?: string
|
||||
}
|
||||
|
||||
/** Validated immutable model-provider policy. */
|
||||
export interface ResolvedSessionTitleLlmConfig extends SessionTitleLlmConfig {}
|
||||
|
||||
/** Shared Loader field schemas with no library defaults. */
|
||||
export const SessionTitleLlmConfigFields = {
|
||||
targetWords: z.number().step(1).min(1).required(),
|
||||
targetCjkCharacters: z.number().step(1).min(1).required(),
|
||||
maxInputBytes: z.number().step(1).min(1).required(),
|
||||
maxOutputTokens: z.number().step(1).min(1).required(),
|
||||
timeoutMs: z.number().step(1).min(1).max(MAX_TIMER_DELAY_MS).required(),
|
||||
provider: z.string(),
|
||||
model: z.string(),
|
||||
}
|
||||
|
||||
/** Shared Loader schema with no library defaults. */
|
||||
export const SessionTitleLlmConfigSchema: z<SessionTitleLlmConfig> = z.object(SessionTitleLlmConfigFields)
|
||||
|
||||
/** Complete configuration key set for direct construction validation. */
|
||||
const CONFIG_KEYS: ReadonlySet<string> = new Set([
|
||||
'targetWords',
|
||||
'targetCjkCharacters',
|
||||
'maxInputBytes',
|
||||
'maxOutputTokens',
|
||||
'timeoutMs',
|
||||
'provider',
|
||||
'model',
|
||||
])
|
||||
|
||||
/** Validate one positive integer limit. */
|
||||
function assertPositiveInteger(name: string, value: number): void {
|
||||
if (!Number.isInteger(value) || value <= 0) {
|
||||
throw new Error(`session-title-llm: ${name} must be a positive integer`)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate and detach required model-provider configuration.
|
||||
* @param config - untrusted plugin configuration.
|
||||
* @returns immutable policy with optional route absence preserved.
|
||||
*/
|
||||
export function resolveSessionTitleLlmConfig(
|
||||
config: SessionTitleLlmConfig,
|
||||
): ResolvedSessionTitleLlmConfig {
|
||||
const candidate: unknown = config
|
||||
if (candidate === null || typeof candidate !== 'object') {
|
||||
throw new Error('session-title-llm: configuration is required')
|
||||
}
|
||||
const value = candidate as SessionTitleLlmConfig
|
||||
for (const key of Object.keys(value)) {
|
||||
if (!CONFIG_KEYS.has(key)) throw new Error(`session-title-llm: unknown config key "${key}"`)
|
||||
}
|
||||
assertPositiveInteger('targetWords', value.targetWords)
|
||||
assertPositiveInteger('targetCjkCharacters', value.targetCjkCharacters)
|
||||
assertPositiveInteger('maxInputBytes', value.maxInputBytes)
|
||||
assertPositiveInteger('maxOutputTokens', value.maxOutputTokens)
|
||||
assertPositiveInteger('timeoutMs', value.timeoutMs)
|
||||
if (value.timeoutMs > MAX_TIMER_DELAY_MS) {
|
||||
throw new Error(`session-title-llm: timeoutMs must not exceed ${MAX_TIMER_DELAY_MS}`)
|
||||
}
|
||||
const hasProvider = value.provider !== undefined
|
||||
const hasModel = value.model !== undefined
|
||||
if (hasProvider !== hasModel) {
|
||||
throw new Error('session-title-llm: provider and model must be supplied together')
|
||||
}
|
||||
if (hasProvider
|
||||
&& (typeof value.provider !== 'string' || value.provider.length === 0
|
||||
|| typeof value.model !== 'string' || value.model.length === 0)) {
|
||||
throw new Error('session-title-llm: provider and model overrides must be non-empty strings')
|
||||
}
|
||||
return deepFreeze({ ...value })
|
||||
}
|
||||
|
||||
/** Select the provider-owned message subset from one fixed service revision. */
|
||||
export type SessionTitleLlmMessageSelector = (
|
||||
messages: readonly SessionTitleUserMessage[],
|
||||
) => readonly SessionTitleUserMessage[]
|
||||
|
||||
/**
|
||||
* Register one model-backed provider through the shared configuration and call policy.
|
||||
* @param ctx - context exposing the title and LLM services.
|
||||
* @param config - untrusted required deployment policy.
|
||||
* @param id - stable plugin identity recorded in title provenance.
|
||||
* @param automatic - provider-owned automatic generation cadence.
|
||||
* @param selectMessages - exact source-message selection for one revision.
|
||||
*/
|
||||
export function registerSessionTitleLlmProvider(
|
||||
ctx: Context,
|
||||
config: SessionTitleLlmConfig,
|
||||
id: string,
|
||||
automatic: SessionTitleAutomaticMode,
|
||||
selectMessages: SessionTitleLlmMessageSelector,
|
||||
): void {
|
||||
const resolved = resolveSessionTitleLlmConfig(config)
|
||||
ctx.sessionTitle.register({
|
||||
id: SessionTitleProviderId(id),
|
||||
automatic,
|
||||
async generate(request) {
|
||||
return generateSessionTitleWithLlm(ctx, resolved, request, selectMessages(request.messages))
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
/** Resolve the explicit pair or the exact route captured from `request/header`. */
|
||||
function resolveRoute(
|
||||
config: ResolvedSessionTitleLlmConfig,
|
||||
request: SessionTitleProviderRequest,
|
||||
): SessionTitleModelProvenance {
|
||||
if (config.provider !== undefined && config.model !== undefined) {
|
||||
return { provider: config.provider, model: config.model }
|
||||
}
|
||||
if (request.route === undefined) {
|
||||
throw new Error('session-title-llm: no logged request route is available; configure provider and model together')
|
||||
}
|
||||
return request.route
|
||||
}
|
||||
|
||||
/** Stable language-aware system instruction shared by both provider plugins. */
|
||||
function systemPrompt(config: ResolvedSessionTitleLlmConfig): string {
|
||||
return [
|
||||
'Create a concise title for an AI coding-assistant session from the supplied human messages.',
|
||||
'Return only the title on one line, with no quotes, prefix, explanation, Markdown, or terminal control codes.',
|
||||
'Use the language of the messages.',
|
||||
`Aim for about ${config.targetWords} words in non-CJK languages or ${config.targetCjkCharacters} CJK characters.`,
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
/** Frame exact messages as JSON so user text cannot break structural delimiters. */
|
||||
function frameMessages(messages: readonly SessionTitleUserMessage[]): string {
|
||||
return `Generate the session title from this JSON array of human messages:\n${JSON.stringify(messages)}`
|
||||
}
|
||||
|
||||
/** Translate terminal finish reasons into an auxiliary-call failure. */
|
||||
function finishError(finish: FinishReason): Error | undefined {
|
||||
switch (finish.kind) {
|
||||
case 'stop':
|
||||
return undefined
|
||||
case 'error':
|
||||
case 'aborted': {
|
||||
const error = new Error(finish.failure.message) as Error & { code?: string }
|
||||
error.code = finish.failure.code
|
||||
return error
|
||||
}
|
||||
case 'max-tokens':
|
||||
return new Error('session-title-llm: title output reached maxOutputTokens')
|
||||
case 'tool-calls':
|
||||
return new Error('session-title-llm: title model unexpectedly requested a tool')
|
||||
default:
|
||||
return new Error(`session-title-llm: unsupported finish reason "${String((finish as { kind?: unknown }).kind)}"`)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate one title through the shared auxiliary LLM call.
|
||||
* @param ctx - context exposing the registered LLM service.
|
||||
* @param config - validated model-provider policy.
|
||||
* @param request - service-owned session, route, message snapshot, and cancellation.
|
||||
* @param selectedMessages - exact provider-selected subset to frame and attribute.
|
||||
* @returns normalized non-empty title, exact source seqs, and used model route.
|
||||
*/
|
||||
export async function generateSessionTitleWithLlm(
|
||||
ctx: Context,
|
||||
config: ResolvedSessionTitleLlmConfig,
|
||||
request: SessionTitleProviderRequest,
|
||||
selectedMessages: readonly SessionTitleUserMessage[],
|
||||
): Promise<SessionTitleProviderResult> {
|
||||
request.signal.throwIfAborted()
|
||||
if (selectedMessages.length === 0) {
|
||||
throw new Error('session-title-llm: at least one source message is required')
|
||||
}
|
||||
const inputBytes = selectedMessages.reduce((total, message) => total + Buffer.byteLength(message.text, 'utf8'), 0)
|
||||
if (inputBytes > config.maxInputBytes) {
|
||||
throw new Error(`session-title-llm: input is ${inputBytes} bytes, exceeding maxInputBytes ${config.maxInputBytes}`)
|
||||
}
|
||||
const route = resolveRoute(config, request)
|
||||
using callDeadline = deadline(request.signal, config.timeoutMs, SESSION_TITLE_TIMEOUT_CODE)
|
||||
const options: GenerateOptions = {
|
||||
provider: route.provider,
|
||||
model: route.model,
|
||||
messages: [{ role: 'user', content: [{ type: 'text', text: frameMessages(selectedMessages) }] }],
|
||||
system: systemPrompt(config),
|
||||
maxTokens: config.maxOutputTokens,
|
||||
sessionId: request.session.id,
|
||||
signal: callDeadline.signal,
|
||||
}
|
||||
const assembler = new BlockAssembler()
|
||||
for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
|
||||
const terminalError = finishError(assembler.finish)
|
||||
if (terminalError !== undefined) throw terminalError
|
||||
const blocks = assembler.message().content
|
||||
if (blocks.some(block => block.type === 'tool-call')) {
|
||||
throw new Error('session-title-llm: title output must contain text only')
|
||||
}
|
||||
const text = blocks
|
||||
.filter((block): block is Extract<(typeof blocks)[number], { type: 'text' }> => block.type === 'text')
|
||||
.map(block => block.text)
|
||||
.join(' ')
|
||||
const title = normalizeSessionTitle(text, Number.MAX_SAFE_INTEGER)
|
||||
if (title.length === 0) throw new Error('session-title-llm: title model produced no text')
|
||||
return {
|
||||
title,
|
||||
messageSeqs: selectedMessages.map(message => message.seq),
|
||||
model: route,
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user