@kabxx/dsh-btw 0.0.0-stage → 0.1.1

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.
@@ -0,0 +1,1013 @@
1
+ import { randomUUID } from 'node:crypto'
2
+ import { realpathSync } from 'node:fs'
3
+ import { createRequire } from 'node:module'
4
+ import { resolve } from 'node:path'
5
+ import { setTimeout as delay } from 'node:timers/promises'
6
+ import { pathToFileURL } from 'node:url'
7
+ import {
8
+ CONTEXT_OVERFLOW, NATIVE_FAILURE_DETAILS, PACKAGE_NAME, TOKEN_FIELDS, contextDescriptor, parseDetail, parseQuestion, parseSessionId, parseSubmissionId, parseThreadId, parseVersion, submitCreateDescriptor, submitFollowupDescriptor, threadDescriptor,
9
+ } from '../shared/wire.js'
10
+ import { sessionThreadStore } from './session-store.js'
11
+
12
+ const requireHere = createRequire(import.meta.url)
13
+ const requireFrom = []
14
+ if (process.env.DSH_INSTALL_DIR) {
15
+ requireFrom.push(createRequire(resolve(process.env.DSH_INSTALL_DIR, 'package.json')))
16
+ }
17
+ if (process.argv[1]) {
18
+ try {
19
+ // The Web Host starts from the CLI entry, even when its shell-tool-only
20
+ // environment variables are absent and the bundle is linked elsewhere.
21
+ requireFrom.push(createRequire(realpathSync(process.argv[1])))
22
+ } catch {
23
+ // Inline or embedded launchers may provide only the package-local resolver.
24
+ }
25
+ }
26
+ requireFrom.push(requireHere)
27
+ function fromDsh(name) {
28
+ for (const locate of requireFrom) {
29
+ let entry
30
+ try {
31
+ entry = locate.resolve(name)
32
+ } catch (error) {
33
+ if (error?.code !== 'MODULE_NOT_FOUND') throw error
34
+ continue
35
+ }
36
+ return import(pathToFileURL(entry).href)
37
+ }
38
+ throw new Error(`BTW could not resolve installed Host package ${name}`)
39
+ }
40
+ const [
41
+ { Service }, { RemoteError, TypertRemoteService }, { z }, { estimateMessage, estimateToolsTokens },
42
+ { BlockAssembler, CONTEXT_WINDOW_EXCEEDED_CODE, isAgentLoopRequest, isTokenDelta },
43
+ { PiAiAdapter },
44
+ ] = await Promise.all([
45
+ fromDsh('@deepseek-ai/cordis'),
46
+ fromDsh('@deepseek-ai/dsh-typert-protocol'),
47
+ fromDsh('zod'),
48
+ fromDsh('@deepseek-ai/dsh-token-meter/estimate'),
49
+ fromDsh('@deepseek-ai/dsh-llm'),
50
+ fromDsh('@deepseek-ai/dsh-llm-pi-ai'),
51
+ ])
52
+
53
+ export const inject = ['agents', 'llm', 'sessionPersistence', 'typert']
54
+
55
+ const CHECKPOINT_INTERVAL_MS = 500
56
+ const PREVIEW_INTERVAL_MS = 45
57
+ const NO_TOOLS = 'Reply in text only. Do not call tools. Treat the preceding conversation as read-only reference context, and state what is missing if answering requires inspecting files or running commands.'
58
+ const INTERRUPTION = '回复已中断。'
59
+ const FAILURE = '回复生成失败。'
60
+ const NO_TEXT = '模型未返回文本内容。'
61
+ const ARCHIVE_ERROR = 'archive-write-failed'
62
+ const tokenCount = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)
63
+ const timestamp = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)
64
+ const providerKey = z.string().min(1)
65
+ const routeSchema = z.strictObject({
66
+ provider: providerKey,
67
+ model: providerKey,
68
+ reasoningEffort: providerKey.optional(),
69
+ })
70
+ const nativeBlock = z.looseObject({ type: z.string().min(1) })
71
+ const nativeMessage = z.looseObject({
72
+ id: z.string().min(1),
73
+ role: z.enum(['system', 'developer', 'user', 'assistant', 'tool']),
74
+ content: z.array(nativeBlock),
75
+ source: z.looseObject({ kind: z.string().min(1) }),
76
+ })
77
+ const toolSchema = z.looseObject({
78
+ name: z.string(), description: z.string(), parameters: z.record(z.string(), z.json()),
79
+ })
80
+ const nativeSnapshot = z.strictObject({
81
+ mode: z.literal('native'),
82
+ anchor: timestamp.nullable(),
83
+ messages: z.array(nativeMessage),
84
+ system: z.string().optional(),
85
+ tools: z.array(toolSchema).optional(),
86
+ toolHistory: z.strictObject({
87
+ tools: z.array(toolSchema),
88
+ updates: z.array(z.strictObject({ messageId: z.string(), additions: z.array(toolSchema) })),
89
+ }).optional(),
90
+ temperature: z.number().optional(),
91
+ maxTokens: z.number().optional(),
92
+ stop: z.array(z.string()).optional(),
93
+ measuredPrefix: tokenCount.optional(),
94
+ })
95
+ const turnSchema = z.strictObject({
96
+ submissionId: z.string().refine(value => {
97
+ try { parseSubmissionId(value); return true } catch { return false }
98
+ }).optional(),
99
+ question: z.string().min(1),
100
+ reply: z.string(),
101
+ status: z.enum(['generating', 'completed', 'failed', 'interrupted']),
102
+ createdAt: timestamp,
103
+ finishedAt: timestamp.optional(),
104
+ error: z.string().optional(),
105
+ saveError: z.string().optional(),
106
+ outputLimitReached: z.literal(true).optional(),
107
+ modelReply: nativeMessage.optional(),
108
+ usage: z.strictObject(Object.fromEntries(TOKEN_FIELDS.map(key => [key, tokenCount.optional()]))).optional(),
109
+ timing: z.strictObject({ requestMs: timestamp, firstTokenMs: timestamp.optional() }).optional(),
110
+ })
111
+ const threadFields = z.strictObject({
112
+ id: z.string(),
113
+ sessionId: z.string(),
114
+ question: z.string().min(1),
115
+ createdAt: timestamp,
116
+ updatedAt: timestamp,
117
+ version: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
118
+ turns: z.array(turnSchema).min(1),
119
+ route: routeSchema,
120
+ })
121
+
122
+ function validateThread(record, context) {
123
+ try {
124
+ parseDetail(toDetailShape(record))
125
+ if (record.question !== record.turns[0].question || record.turns.slice(0, -1).some(turn => turn.status === 'generating')) {
126
+ throw new Error('invalid thread history')
127
+ }
128
+ } catch {
129
+ context.addIssue({ code: 'custom', message: 'Invalid BTW thread record' })
130
+ }
131
+ }
132
+
133
+ const threadRecordSchema = threadFields.superRefine(validateThread)
134
+ export const threadSchema = threadFields.extend({ snapshot: nativeSnapshot }).superRefine(validateThread)
135
+ export const archiveSchemas = { inline: threadSchema, record: threadRecordSchema, snapshot: nativeSnapshot }
136
+
137
+ function fault(code, message) {
138
+ return new RemoteError(`btw/${code}`, message)
139
+ }
140
+
141
+ function newest(record) {
142
+ return record.turns.at(-1)
143
+ }
144
+
145
+ function publicTurn({ modelReply, submissionId, ...fields }) {
146
+ return fields
147
+ }
148
+
149
+ function toDetailShape({ route, snapshot, turns, ...publicFields }) {
150
+ return { ...publicFields, turns: turns.map(publicTurn) }
151
+ }
152
+
153
+ function toDetail(record) {
154
+ return parseDetail(toDetailShape(record))
155
+ }
156
+
157
+ function toSummary({ id, sessionId, question, createdAt, updatedAt, version, turns }) {
158
+ return { id, sessionId, question, createdAt, updatedAt, version, status: turns.at(-1).status }
159
+ }
160
+
161
+ function nextRevision(record, turns, time = Date.now()) {
162
+ return { ...record, turns, updatedAt: Math.max(time, record.updatedAt), version: record.version + 1 }
163
+ }
164
+
165
+ function nextTurn(question, createdAt) {
166
+ return { question, reply: '', status: 'generating', createdAt }
167
+ }
168
+
169
+ function withLatest(record, turn, time) {
170
+ return nextRevision(record, [...record.turns.slice(0, -1), turn], time)
171
+ }
172
+
173
+ function isDone(record) {
174
+ return newest(record).status !== 'generating'
175
+ }
176
+
177
+ // A side request can start while the main loop is executing tools. Only a fully
178
+ // answered tool batch belongs to the frozen prefix. Leave that pending tail in
179
+ // the main loop and retain every preceding committed block unchanged.
180
+ function completeToolBoundary(messages) {
181
+ let complete = 0
182
+ const pending = new Set()
183
+ for (const [index, message] of messages.entries()) {
184
+ if (message.role === 'assistant') {
185
+ if (pending.size) break
186
+ for (const block of message.content) {
187
+ if (block.type === 'tool-call') pending.add(block.id)
188
+ }
189
+ } else if (message.role === 'tool') {
190
+ if (!pending.delete(message.toolCallId)) break
191
+ } else if (message.role === 'user' && pending.size) {
192
+ break
193
+ }
194
+ if (!pending.size) complete = index + 1
195
+ }
196
+ return complete
197
+ }
198
+
199
+ function sameRoute(left, right) {
200
+ return left?.provider === right.provider && left.model === right.model
201
+ }
202
+
203
+ function freezeSnapshot(session, selected, observed, tokenMeter) {
204
+ const derived = session.deriveMessages()
205
+ const end = completeToolBoundary(derived)
206
+ const matchesSurface = observed?.request.messages.length === end &&
207
+ observed.request.messages.every((message, index) => message === derived[index])
208
+ const exact = matchesSurface && sameRoute(observed.request, selected) ? observed : undefined
209
+ const header = session.requestHeader?.()
210
+ const matchingHeader = sameRoute(header?.config, selected) ? header : undefined
211
+ const controls = exact?.request ?? matchingHeader?.config ?? selected
212
+ const usesAdapterDefault = exact ? exact.usesAdapterDefault : matchingHeader?.adapterDefaults?.maxTokens
213
+ const maxTokens = usesAdapterDefault ? undefined : controls.maxTokens
214
+ // The current selection owns reasoning effort. An omitted value means the
215
+ // model default, even when an observed request used an explicit effort.
216
+ const route = selected
217
+ const messages = exact?.request.messages ?? derived.slice(0, end)
218
+ const tools = exact ? exact.request.tools : header?.tools
219
+ let toolHistory = exact ? exact.request.toolHistory : session.toolHistory?.()
220
+ if (!exact && toolHistory && end < derived.length) {
221
+ const messageIds = new Set(messages.map(message => message.id))
222
+ toolHistory = { ...toolHistory, updates: toolHistory.updates.filter(update => messageIds.has(update.messageId)) }
223
+ }
224
+ let measuredPrefix
225
+ if (end === derived.length && tokenMeter) {
226
+ const { temperature, stop, maxTokens } = controls
227
+ const envelope = { config: { ...route, temperature, stop, maxTokens }, ...(tools && { tools }) }
228
+ try { measuredPrefix = tokenMeter.measure(session, envelope).totalTokens } catch { /* Estimate below. */ }
229
+ }
230
+ // Persist only lossless-JSON model inputs; the session identity, call signal,
231
+ // caller, and prepared dispatch belong exclusively to the original request.
232
+ const snapshot = JSON.parse(JSON.stringify({
233
+ mode: 'native',
234
+ anchor: exact?.anchor ?? (end === derived.length ? session.surface?.nodes?.at(-1) ?? null : null),
235
+ messages,
236
+ system: exact?.request.system,
237
+ tools,
238
+ toolHistory,
239
+ temperature: controls.temperature,
240
+ maxTokens,
241
+ stop: controls.stop,
242
+ measuredPrefix: Number.isSafeInteger(measuredPrefix) && measuredPrefix >= 0 ? measuredPrefix : undefined,
243
+ }))
244
+ return { route, snapshot }
245
+ }
246
+
247
+ function userInput(text) {
248
+ return { role: 'user', content: [{ type: 'text', text }] }
249
+ }
250
+
251
+ function assistantInput(id, text, route) {
252
+ return {
253
+ id,
254
+ role: 'assistant',
255
+ content: [{ type: 'text', text }],
256
+ source: { kind: 'model', provider: route.provider, model: route.model },
257
+ }
258
+ }
259
+
260
+ function questionInput(question) {
261
+ return userInput(`${NO_TOOLS}\n\nQuestion:\n${question}`)
262
+ }
263
+
264
+ function requestMessages(record, includeSettledLastReply = false) {
265
+ const { snapshot } = record
266
+ const messages = [...snapshot.messages]
267
+ for (const [index, turn] of record.turns.entries()) {
268
+ messages.push(questionInput(turn.question))
269
+ if (index === record.turns.length - 1 && !includeSettledLastReply) break
270
+ // Native history includes user input and committed assistant messages.
271
+ // Failed provider attempts and recovered checkpoints are UI history only.
272
+ if (turn.modelReply) messages.push(turn.modelReply)
273
+ else if (turn.status === 'completed' && turn.reply.trim()) {
274
+ messages.push(assistantInput(`${record.id}/reply/${index + 1}`, turn.reply, record.route))
275
+ }
276
+ }
277
+ return messages
278
+ }
279
+
280
+ function requestFields(snapshot) {
281
+ const { system, tools, toolHistory, temperature, maxTokens, stop } = snapshot
282
+ return {
283
+ ...(system !== undefined && { system }), ...(tools !== undefined && { tools }),
284
+ ...(toolHistory !== undefined && { toolHistory }), ...(temperature !== undefined && { temperature }),
285
+ ...(maxTokens !== undefined && { maxTokens }), ...(stop !== undefined && { stop }),
286
+ }
287
+ }
288
+
289
+ function responsesRegistration(llm, { provider, model }) {
290
+ // DSH 0.2.2-rc.5 exposes no transport-only cache hint. Qualify the exact
291
+ // registered adapter and model before using its internal prepared dispatch.
292
+ if (typeof llm.registration !== 'function' || typeof llm.normalizeModelInfo !== 'function' ||
293
+ typeof llm.resolveCallWithInfo !== 'function' || typeof llm.streamWithRegistration !== 'function') return
294
+ try {
295
+ const registration = llm.registration(provider)
296
+ const { adapter } = registration
297
+ if (Object.getPrototypeOf(adapter) !== PiAiAdapter.prototype) return
298
+ const descriptor = adapter.modelOf(adapter.current(), provider, model)
299
+ if (descriptor.api === 'openai-responses' && descriptor.compat?.promptCacheKeyMode !== 'disabled') return registration
300
+ } catch {
301
+ // Let the ordinary runtime report errors for unknown routes and models.
302
+ }
303
+ }
304
+
305
+ async function* streamSideQuestion(llm, options, record) {
306
+ const registration = responsesRegistration(llm, options)
307
+ if (!registration) {
308
+ yield* llm.stream(options)
309
+ return
310
+ }
311
+
312
+ // The stock Pi adapter captures the same model snapshot synchronously at
313
+ // prepareCall entry. Late-bind the session ID only to this pinned adapter
314
+ // dispatch. Generic llm/stream listeners must keep seeing the side request
315
+ // without an ID, including listeners that flush or mutate a main session.
316
+ const { provider, model, reasoningEffort, temperature, maxTokens, stop, signal } = options
317
+ const prepared = await registration.adapter.prepareCall(provider, model, signal)
318
+ const modelInfo = llm.normalizeModelInfo(registration, model, prepared.model)
319
+ const { config } = llm.resolveCallWithInfo({ provider, model, reasoningEffort, temperature, maxTokens, stop }, modelInfo)
320
+ yield* llm.streamWithRegistration({ ...options, ...config }, {
321
+ registration, config, modelInfo,
322
+ dispatch: request => prepared.stream({ ...request, sessionId: record.sessionId }),
323
+ })
324
+ }
325
+
326
+ function replyText(blocks) {
327
+ return blocks.filter(block => block.type === 'text').map(block => block.text).join('')
328
+ }
329
+
330
+ function previewReply(assembler) {
331
+ try {
332
+ return replyText(assembler.blocks())
333
+ } catch {
334
+ // An open provider-specific block may not be assemblable until it closes.
335
+ return replyText(assembler.interruptedBlocks())
336
+ }
337
+ }
338
+
339
+ function modelReplyFor(record, assembler, interrupted) {
340
+ const received = interrupted ? assembler.interruptedBlocks() : assembler.blocks()
341
+ const content = received.filter(block => block.type === 'text' || block.type === 'reasoning')
342
+ if (!content.length) return undefined
343
+ const replayState = interrupted || content.length !== received.length ? undefined : assembler.replayState
344
+ return {
345
+ ...assistantInput(`${record.id}/reply/${record.turns.length}`, '', record.route), content,
346
+ ...(replayState !== undefined && { source: { kind: 'model', provider: record.route.provider, model: record.route.model, replayState } }),
347
+ }
348
+ }
349
+
350
+ function readUsage(usage) {
351
+ const counts = {}
352
+ for (const key of TOKEN_FIELDS) {
353
+ const count = usage?.[key]
354
+ if (Number.isSafeInteger(count) && count >= 0) counts[key] = count
355
+ }
356
+ return Object.keys(counts).length > 0 ? counts : undefined
357
+ }
358
+
359
+ function replyDelta(previousText, turn) {
360
+ const offset = previousText !== undefined && turn.reply.startsWith(previousText) ? previousText.length : 0
361
+ const { status, finishedAt, error, saveError, outputLimitReached, usage, timing } = publicTurn(turn)
362
+ return {
363
+ offset, text: turn.reply.slice(offset), status,
364
+ ...(finishedAt !== undefined && { finishedAt }), ...(error !== undefined && { error }),
365
+ ...(saveError !== undefined && { saveError }), ...(usage !== undefined && { usage }),
366
+ ...(outputLimitReached !== undefined && { outputLimitReached }),
367
+ ...(timing !== undefined && { timing }),
368
+ }
369
+ }
370
+
371
+ // Coalesce UI wakeups: each watcher reads the newest immutable revision, so a slow
372
+ // browser does not accumulate a queue of full answers. There is no async gap between
373
+ // checking the version and subscribing to the next pulse.
374
+ function waitForPulse(listeners, id, signal) {
375
+ signal.throwIfAborted()
376
+ return new Promise((resolvePulse, rejectPulse) => {
377
+ const current = listeners.get(id) ?? new Set()
378
+ listeners.set(id, current)
379
+ function cleanup() {
380
+ current.delete(wake)
381
+ if (current.size === 0) listeners.delete(id)
382
+ signal.removeEventListener('abort', onAbort)
383
+ }
384
+ function wake() {
385
+ cleanup()
386
+ resolvePulse()
387
+ }
388
+ function onAbort() {
389
+ cleanup()
390
+ rejectPulse(signal.reason)
391
+ }
392
+ current.add(wake)
393
+ signal.addEventListener('abort', onAbort, { once: true })
394
+ })
395
+ }
396
+
397
+ export class BtwHost {
398
+ constructor({ store, llm, logger, tokenMeter }) {
399
+ this.store = store
400
+ this.llm = llm
401
+ this.logger = logger
402
+ this.tokenMeter = tokenMeter
403
+ this.mainRequests = new WeakMap()
404
+ this.runs = new Map()
405
+ this.listeners = new Map()
406
+ this.sessions = new Map()
407
+ this.opening = new Set()
408
+ this.running = new Set()
409
+ this.admissions = new Set()
410
+ this.archiveRetries = new Set()
411
+ this.lifetime = new AbortController()
412
+ }
413
+
414
+ async prepare(sessionId, signal, owner) {
415
+ signal?.throwIfAborted()
416
+ this.lifetime.signal.throwIfAborted()
417
+ let state = this.sessions.get(sessionId)
418
+ if (state && owner && state.owner !== owner) {
419
+ this.retire(sessionId, state.owner)
420
+ state = undefined
421
+ }
422
+ if (!state) {
423
+ state = { owner, controller: new AbortController(), records: new Map(), terminalWrites: new Map(), creating: new Map() }
424
+ // AgentLoop disposes the agent scope before closing the session write handle.
425
+ state.disposeOwner = owner?.ctx?.effect(() => () => {
426
+ state.disposeOwner = undefined
427
+ if (this.sessions.get(sessionId) === state) this.retire(sessionId, owner)
428
+ }, 'btw.archiveOwner')
429
+ this.sessions.set(sessionId, state)
430
+ const opening = this.openSession(sessionId, state).finally(() => {
431
+ this.opening.delete(opening)
432
+ state.opening = undefined
433
+ if (!state.archive && this.sessions.get(sessionId) === state) {
434
+ this.sessions.delete(sessionId)
435
+ return state.disposeOwner?.()
436
+ }
437
+ })
438
+ state.opening = opening
439
+ this.opening.add(opening)
440
+ }
441
+ await state.opening
442
+ signal?.throwIfAborted()
443
+ this.lifetime.signal.throwIfAborted()
444
+ state.controller.signal.throwIfAborted()
445
+ return !!state.archive
446
+ }
447
+
448
+ retire(sessionId, owner) {
449
+ const state = this.sessions.get(sessionId)
450
+ if (!state || state.owner !== owner) return
451
+ this.sessions.delete(sessionId)
452
+ state.controller.abort()
453
+ for (const id of state.records.keys()) this.notify(id)
454
+ return state.disposeOwner?.()
455
+ }
456
+
457
+ async openSession(sessionId, state) {
458
+ const signal = AbortSignal.any([state.controller.signal, this.lifetime.signal])
459
+ const archive = await this.store.open(sessionId, signal)
460
+ if (!archive) return
461
+ signal.throwIfAborted()
462
+ state.archive = archive
463
+ for (const record of archive.records) {
464
+ this.publish(record, false, state)
465
+ if (isDone(record)) continue
466
+ const time = Math.max(Date.now(), record.updatedAt)
467
+ const terminal = withLatest(record, {
468
+ ...newest(record), status: 'interrupted', finishedAt: time, error: INTERRUPTION,
469
+ }, time)
470
+ this.publish(terminal, false, state)
471
+ try {
472
+ await this.save(terminal, state)
473
+ } catch {
474
+ if (state.controller.signal.aborted) break
475
+ this.logger?.error('BTW could not save a recovered reply')
476
+ this.retryTerminalSave(terminal, state)
477
+ }
478
+ }
479
+ }
480
+
481
+ observeMain(session, request) {
482
+ const header = session.requestHeader?.()
483
+ const usesAdapterDefault = sameRoute(header?.config, request) &&
484
+ header.config.maxTokens === request.maxTokens && header.adapterDefaults?.maxTokens === true
485
+ const anchor = session.surface?.nodes?.at(-1) ?? null
486
+ this.mainRequests.set(session, { request, anchor, usesAdapterDefault })
487
+ }
488
+
489
+ async save(record, state) {
490
+ state.controller.signal.throwIfAborted()
491
+ const turns = record.turns.map(({ saveError, ...turn }) => turn)
492
+ const schema = record.snapshot ? threadSchema : threadRecordSchema
493
+ await state.archive.put(schema.parse({ ...record, turns }), state.controller.signal)
494
+ }
495
+
496
+ retryTerminalSave(terminal, state) {
497
+ const time = terminal.updatedAt
498
+ const failed = withLatest(terminal, { ...newest(terminal), saveError: ARCHIVE_ERROR }, time)
499
+ const recovered = withLatest(failed, newest(terminal), time)
500
+ this.publish(failed, true, state)
501
+ const signal = AbortSignal.any([state.controller.signal, this.lifetime.signal])
502
+ const retry = (async () => {
503
+ while (!signal.aborted && state.records.get(failed.id) === failed) {
504
+ try { await delay(CHECKPOINT_INTERVAL_MS, undefined, { signal, ref: false }) }
505
+ catch { return }
506
+ if (state.records.get(failed.id) !== failed) return
507
+ if (this.runs.get(failed.id)?.state === state) continue
508
+ const write = this.save(recovered, state)
509
+ state.terminalWrites.set(failed.id, write)
510
+ try {
511
+ await write
512
+ if (this.runs.get(failed.id)?.state !== state) {
513
+ this.publish(recovered, true, state)
514
+ return
515
+ }
516
+ } catch {
517
+ // Keep the latest answer eligible for the next archive check.
518
+ } finally {
519
+ state.terminalWrites.delete(failed.id)
520
+ }
521
+ }
522
+ })()
523
+ this.archiveRetries.add(retry)
524
+ retry.then(() => this.archiveRetries.delete(retry), () => this.archiveRetries.delete(retry))
525
+ }
526
+
527
+ read(sessionId, id) {
528
+ parseThreadId(id)
529
+ const record = this.sessions.get(sessionId)?.records.get(id)
530
+ if (!record) throw fault('not-found', '找不到这条侧问。')
531
+ return record
532
+ }
533
+
534
+ list(sessionId) {
535
+ return [...(this.sessions.get(sessionId)?.records.values() ?? [])]
536
+ .map(toSummary)
537
+ .sort((left, right) => right.createdAt - left.createdAt || right.id.localeCompare(left.id))
538
+ }
539
+
540
+ get(sessionId, id) {
541
+ return toDetail(this.read(sessionId, id))
542
+ }
543
+
544
+ async contextWindow(sessionId, id, requestSignal) {
545
+ const initial = this.read(sessionId, id)
546
+ const state = this.sessions.get(sessionId)
547
+ const signal = AbortSignal.any([
548
+ state.controller.signal, this.lifetime.signal, ...(requestSignal ? [requestSignal] : []),
549
+ ])
550
+ signal.throwIfAborted()
551
+ const { provider, model } = initial.route
552
+ let capacity
553
+ try {
554
+ const info = await this.llm.resolveModelInfo(provider, model, signal)
555
+ capacity = info.context?.contextWindow
556
+ } catch {
557
+ // A disconnected provider cannot supply the optional context meter.
558
+ }
559
+ signal.throwIfAborted()
560
+ if (!Number.isSafeInteger(capacity) || capacity <= 0) return { contextWindow: null }
561
+ const snapshot = initial.snapshot ?? await state.archive.loadSnapshot(id)
562
+ signal.throwIfAborted()
563
+ if (!snapshot) return { contextWindow: null }
564
+ const record = { ...this.read(sessionId, id), snapshot }
565
+ const price = messages => messages.reduce((sum, message) => sum + estimateMessage(message), 0)
566
+ const messages = requestMessages(record, true)
567
+ const promptFields = ['inputTokens', 'cacheReadTokens', 'cacheWriteTokens']
568
+ const anchor = record.turns.findLastIndex(({ status, usage }) => {
569
+ // A failed attempt can report zeroed usage without measuring the prompt.
570
+ if (status === 'failed') return promptFields.some(field => usage?.[field] > 0)
571
+ return promptFields.some(field => usage?.[field] !== undefined)
572
+ })
573
+ if (anchor !== -1) {
574
+ // Provider usage describes the input before this turn's assistant reply.
575
+ const usage = record.turns[anchor].usage
576
+ const reported = promptFields.reduce((sum, field) => sum + (usage[field] ?? 0), 0)
577
+ const sampledPrompt = requestMessages({ ...record, turns: record.turns.slice(0, anchor + 1) })
578
+ return { contextWindow: capacity, estimatedTokens: reported + price(messages.slice(sampledPrompt.length)) }
579
+ }
580
+ const schemaTokens = estimateToolsTokens({ tools: snapshot.tools })
581
+ const systemTokens = snapshot.system
582
+ ? estimateMessage({ role: 'system', content: [{ type: 'text', text: snapshot.system }] }) : 0
583
+ const estimatedPrefix = price(snapshot.messages) + schemaTokens + systemTokens
584
+ const prefixTokens = Math.max(estimatedPrefix, snapshot.measuredPrefix ?? 0)
585
+ return { contextWindow: capacity, estimatedTokens: prefixTokens + price(messages.slice(snapshot.messages.length)) }
586
+ }
587
+
588
+ async create(agent, question, signal, submissionId) {
589
+ parseQuestion(question)
590
+ if (submissionId !== undefined) parseSubmissionId(submissionId)
591
+ const sessionId = parseSessionId(agent.session.id)
592
+ if (!await this.prepare(sessionId, signal, agent)) {
593
+ throw fault('session-not-saved', '请先发送一条消息后再发起侧问。')
594
+ }
595
+ const state = this.sessions.get(sessionId)
596
+ if (submissionId !== undefined) {
597
+ const accepted = [...state.records.values()].find(record => record.turns[0].submissionId === submissionId)
598
+ const pending = state.creating.get(submissionId)
599
+ if (accepted || pending) {
600
+ if ((accepted ?? pending).question !== question) throw fault('submission-mismatch', '侧问提交内容不一致。')
601
+ return accepted ? toDetail(accepted) : pending.admission
602
+ }
603
+ }
604
+ const selected = agent.model.current()
605
+ const model = routeSchema.safeParse(selected && {
606
+ provider: selected.provider,
607
+ model: selected.model,
608
+ reasoningEffort: selected.reasoningEffort,
609
+ })
610
+ if (!model.success) throw fault('model-unavailable', '当前会话未配置可用模型。')
611
+ const time = Date.now()
612
+ const { route, snapshot } = freezeSnapshot(agent.session, model.data, this.mainRequests.get(agent.session), this.tokenMeter)
613
+ const turn = nextTurn(question, time)
614
+ if (submissionId !== undefined) turn.submissionId = submissionId
615
+ const admission = this.admit({
616
+ id: `btw-${randomUUID()}`, sessionId, question, createdAt: time, updatedAt: time, version: 1,
617
+ turns: [turn], route, snapshot,
618
+ })
619
+ if (submissionId !== undefined) {
620
+ state.creating.set(submissionId, { question, admission })
621
+ const clear = () => state.creating.delete(submissionId)
622
+ admission.then(clear, clear)
623
+ }
624
+ return admission
625
+ }
626
+
627
+ followup(sessionId, id, question, signal, submissionId) {
628
+ signal?.throwIfAborted()
629
+ this.lifetime.signal.throwIfAborted()
630
+ parseQuestion(question)
631
+ const record = this.read(sessionId, id)
632
+ const active = this.runs.get(id)
633
+ const state = this.sessions.get(sessionId)
634
+ const receipt = (admitted, turnIndex) => {
635
+ const { usage, ...turn } = publicTurn(admitted.turns[turnIndex])
636
+ return { id, sessionId, updatedAt: admitted.updatedAt, version: admitted.version, turnIndex, turn }
637
+ }
638
+ if (submissionId !== undefined) {
639
+ parseSubmissionId(submissionId)
640
+ const turnIndex = record.turns.findIndex(turn => turn.submissionId === submissionId)
641
+ if (turnIndex !== -1) {
642
+ if (record.turns[turnIndex].question !== question) throw fault('submission-mismatch', '侧问提交内容不一致。')
643
+ return Promise.resolve(receipt(record, turnIndex))
644
+ }
645
+ if (active?.state === state && active.submission?.submissionId === submissionId) {
646
+ if (active.submission.question !== question) throw fault('submission-mismatch', '侧问提交内容不一致。')
647
+ return active.admission
648
+ }
649
+ }
650
+ if (active?.state === state || !isDone(record)) throw fault('generating', '上一条回复仍在生成。')
651
+ if (newest(record).error === CONTEXT_OVERFLOW) throw fault('context-overflow', '已达上下文上限。')
652
+ const time = Math.max(Date.now(), record.updatedAt)
653
+ const turns = record.turns.map(({ saveError, ...turn }) => turn)
654
+ const turn = nextTurn(question, time)
655
+ if (submissionId !== undefined) turn.submissionId = submissionId
656
+ return this.admit(nextRevision(record, [...turns, turn], time), admitted => receipt(admitted, turns.length))
657
+ }
658
+
659
+ admit(record, result = toDetail) {
660
+ const controller = new AbortController()
661
+ const state = this.sessions.get(record.sessionId)
662
+ const run = { controller, state, submission: newest(record) }
663
+ this.runs.set(record.id, run)
664
+ const admission = Promise.resolve(state.terminalWrites.get(record.id)).catch(() => {}).then(async () => {
665
+ if (!record.snapshot) {
666
+ const snapshot = await state.archive.loadSnapshot(record.id)
667
+ if (!snapshot) throw fault('snapshot-unavailable', '侧问上下文不可用。')
668
+ record = { ...record, snapshot }
669
+ }
670
+ try {
671
+ await this.save(record, state)
672
+ } catch {
673
+ this.logger?.error('BTW could not admit a question')
674
+ throw fault('save-failed', '保存侧问失败。')
675
+ }
676
+ state.controller.signal.throwIfAborted()
677
+ this.publish(record, true, state)
678
+ // Start only after durable admission. No caller/transport signal is inherited.
679
+ const generation = this.generate(record, controller.signal, () => {
680
+ if (this.runs.get(record.id) === run) this.runs.delete(record.id)
681
+ }, state)
682
+ this.running.add(generation)
683
+ generation.then(() => this.running.delete(generation), () => this.running.delete(generation))
684
+ return result(record)
685
+ }).catch(error => {
686
+ if (this.runs.get(record.id) === run) this.runs.delete(record.id)
687
+ throw error
688
+ })
689
+ run.admission = admission
690
+ this.admissions.add(admission)
691
+ admission.then(() => this.admissions.delete(admission), () => this.admissions.delete(admission))
692
+ return admission
693
+ }
694
+
695
+ publish(record, wake = true, state) {
696
+ if (state.controller.signal.aborted) return
697
+ state.records.set(record.id, record)
698
+ if (wake) this.notify(record.id)
699
+ }
700
+
701
+ notify(id) {
702
+ for (const listener of this.listeners.get(id) ?? []) listener()
703
+ }
704
+
705
+ async generate(record, runSignal, releaseRun, state) {
706
+ const signal = AbortSignal.any([runSignal, this.lifetime.signal, state.controller.signal])
707
+ const assembler = new BlockAssembler()
708
+ let current = record
709
+ let checkpointVersion = record.version
710
+ let pendingSave
711
+ let previewTimer
712
+ let lastNotified = 0
713
+ let finish
714
+ let failureCode
715
+ let firstTokenMs
716
+ const checkpointTimer = setInterval(() => {
717
+ if (pendingSave || checkpointVersion === current.version || signal.aborted) return
718
+ const checkpoint = current
719
+ pendingSave = this.save(checkpoint, state).then(() => {
720
+ checkpointVersion = checkpoint.version
721
+ }).catch(() => {
722
+ this.logger?.error('BTW could not save a reply checkpoint')
723
+ }).finally(() => { pendingSave = undefined })
724
+ }, CHECKPOINT_INTERVAL_MS)
725
+ const sendPreview = () => {
726
+ previewTimer = undefined
727
+ lastNotified = Date.now()
728
+ this.notify(record.id)
729
+ }
730
+ const startedAt = performance.now()
731
+ try {
732
+ signal.throwIfAborted()
733
+ for await (const chunk of streamSideQuestion(this.llm, {
734
+ ...record.route,
735
+ ...requestFields(record.snapshot),
736
+ messages: requestMessages(record),
737
+ purpose: 'btw',
738
+ signal,
739
+ }, record)) {
740
+ signal.throwIfAborted()
741
+ if (firstTokenMs === undefined && isTokenDelta(chunk)) {
742
+ firstTokenMs = Math.round(performance.now() - startedAt)
743
+ }
744
+ assembler.push(chunk)
745
+ if (chunk.type !== 'text-delta' && !(chunk.type === 'block-end' && chunk.block.type === 'text')) continue
746
+ const reply = previewReply(assembler)
747
+ const time = Date.now()
748
+ current = withLatest(current, { ...newest(current), reply }, time)
749
+ this.publish(current, false, state)
750
+ if (time - lastNotified >= PREVIEW_INTERVAL_MS) {
751
+ clearTimeout(previewTimer)
752
+ sendPreview()
753
+ } else if (previewTimer === undefined) {
754
+ previewTimer = setTimeout(sendPreview, PREVIEW_INTERVAL_MS - (time - lastNotified))
755
+ }
756
+ }
757
+ const reason = assembler.finish
758
+ finish = reason.kind
759
+ if (reason.kind === 'error') failureCode = reason.failure?.code
760
+ } catch (error) {
761
+ // Never expose raw provider diagnostics through side-question history.
762
+ failureCode = error?.code
763
+ }
764
+ clearInterval(checkpointTimer)
765
+ clearTimeout(previewTimer)
766
+ const timing = { requestMs: Math.round(performance.now() - startedAt),
767
+ ...(firstTokenMs !== undefined && { firstTokenMs }) }
768
+ await pendingSave
769
+ if (state.controller.signal.aborted) {
770
+ releaseRun()
771
+ return
772
+ }
773
+ const time = Math.max(Date.now(), current.updatedAt)
774
+ const turn = newest(current)
775
+ const interrupted = signal.aborted || finish === 'aborted'
776
+ let error
777
+ if (interrupted) error = INTERRUPTION
778
+ else if (failureCode === CONTEXT_WINDOW_EXCEEDED_CODE) error = CONTEXT_OVERFLOW
779
+ else if (typeof failureCode === 'string' && Object.hasOwn(NATIVE_FAILURE_DETAILS, failureCode)) error = failureCode
780
+ else if (!finish || finish === 'error') error = FAILURE
781
+ else if (finish !== 'max-tokens' && !turn.reply.trim()) error = NO_TEXT
782
+ let modelReply
783
+ if (signal.aborted || !error) {
784
+ try { modelReply = modelReplyFor(record, assembler, signal.aborted) } catch { error = FAILURE }
785
+ }
786
+ const reply = error
787
+ ? replyText(assembler.interruptedBlocks())
788
+ : replyText(modelReply?.content ?? [])
789
+ const usage = readUsage(assembler.usage)
790
+ const terminal = withLatest(current, {
791
+ ...turn,
792
+ reply,
793
+ status: interrupted ? 'interrupted' : error ? 'failed' : 'completed',
794
+ ...(!interrupted && !error && finish === 'max-tokens' && { outputLimitReached: true }),
795
+ finishedAt: time,
796
+ ...(error ? { error } : {}),
797
+ ...(modelReply ? { modelReply } : {}),
798
+ ...(usage ? { usage } : {}),
799
+ timing,
800
+ }, time)
801
+ try {
802
+ await this.save(terminal, state)
803
+ releaseRun()
804
+ this.publish(terminal, true, state)
805
+ } catch {
806
+ this.logger?.error('BTW could not save a terminal reply')
807
+ releaseRun()
808
+ if (!state.controller.signal.aborted) this.retryTerminalSave(terminal, state)
809
+ }
810
+ }
811
+
812
+ async *watch(sessionId, id, version, assertAccess, requestSignal) {
813
+ if (version != null) parseVersion(version)
814
+ const signal = requestSignal
815
+ ? AbortSignal.any([requestSignal, this.lifetime.signal])
816
+ : this.lifetime.signal
817
+ while (!signal.aborted) {
818
+ assertAccess()
819
+ const record = this.read(sessionId, id)
820
+ if (record.version !== version) {
821
+ version = record.version
822
+ yield toDetail(record)
823
+ }
824
+ if (isDone(record) && !record.turns[0].saveError) return
825
+ // If a revision arrived while the generator was yielding, reread promptly.
826
+ if (this.read(sessionId, id).version !== version) continue
827
+ try {
828
+ await waitForPulse(this.listeners, id, signal)
829
+ } catch (error) {
830
+ if (signal.aborted) return
831
+ throw error
832
+ }
833
+ }
834
+ }
835
+
836
+ async *watchThread(sessionId, id, assertAccess, requestSignal) {
837
+ const signal = requestSignal
838
+ ? AbortSignal.any([requestSignal, this.lifetime.signal])
839
+ : this.lifetime.signal
840
+ let previous
841
+ while (!signal.aborted) {
842
+ assertAccess()
843
+ const record = this.read(sessionId, id)
844
+ if (!previous) {
845
+ previous = record
846
+ yield { kind: 'snapshot', detail: toDetail(record) }
847
+ continue
848
+ }
849
+ if (record.version !== previous.version) {
850
+ const firstTurn = previous.turns.length
851
+ const oldTurn = newest(previous)
852
+ const updatedTurn = record.turns[firstTurn - 1]
853
+ const reply = !isDone(previous) || oldTurn.saveError !== updatedTurn.saveError
854
+ ? replyDelta(oldTurn.reply, updatedTurn) : undefined
855
+ previous = record
856
+ yield {
857
+ kind: 'change', version: record.version, updatedAt: record.updatedAt, firstTurn,
858
+ turns: record.turns.slice(firstTurn).map(publicTurn), ...(reply && { reply }),
859
+ }
860
+ continue
861
+ }
862
+ try {
863
+ await waitForPulse(this.listeners, id, signal)
864
+ } catch (error) {
865
+ if (signal.aborted) return
866
+ throw error
867
+ }
868
+ }
869
+ }
870
+
871
+ async *watchReply(sessionId, id, turnIndex, version, assertAccess, requestSignal) {
872
+ const signal = requestSignal
873
+ ? AbortSignal.any([requestSignal, this.lifetime.signal])
874
+ : this.lifetime.signal
875
+ let previousText
876
+ while (!signal.aborted) {
877
+ assertAccess()
878
+ const record = this.read(sessionId, id)
879
+ const turn = record.turns[turnIndex]
880
+ if (!turn) throw fault('not-found', '找不到这轮侧问。')
881
+ if (record.version !== version || turn.status !== 'generating') {
882
+ // A changed baseline may have reordered text blocks before we began watching.
883
+ const delta = replyDelta(previousText, turn)
884
+ version = record.version
885
+ previousText = turn.reply
886
+ yield { version, updatedAt: record.updatedAt, ...delta }
887
+ } else if (previousText === undefined) {
888
+ previousText = turn.reply
889
+ }
890
+ if (turn.status !== 'generating') return
891
+ if (this.read(sessionId, id).version !== version) continue
892
+ try {
893
+ await waitForPulse(this.listeners, id, signal)
894
+ } catch (error) {
895
+ if (signal.aborted) return
896
+ throw error
897
+ }
898
+ }
899
+ }
900
+
901
+ async close() {
902
+ this.lifetime.abort()
903
+ await Promise.allSettled([...this.admissions])
904
+ await Promise.allSettled([...this.running])
905
+ await Promise.allSettled([...this.opening.values()])
906
+ await Promise.allSettled([...this.archiveRetries])
907
+ await Promise.allSettled([...this.sessions].map(([id, state]) => this.retire(id, state.owner)))
908
+ }
909
+ }
910
+
911
+ export default class BtwService extends TypertRemoteService {
912
+ static inject = inject
913
+
914
+ constructor(ctx) {
915
+ super(ctx, 'btw')
916
+ }
917
+
918
+ async [Service.init]() {
919
+ const store = sessionThreadStore(this.ctx.sessionPersistence, archiveSchemas, (file, reason) => {
920
+ this.ctx.logger?.warn('BTW ignored archive %s: %s', file, reason)
921
+ }, (file, error) => {
922
+ this.ctx.logger?.warn('BTW could not clean up unpublished snapshot %s: %s', file, error.code ?? error.message)
923
+ })
924
+ const host = new BtwHost({ store, llm: this.ctx.llm, logger: this.ctx.logger })
925
+ this.ctx.effect(() => () => host.close(), 'btw.close')
926
+ this.ctx.on('agent/disposed', ({ agent }) => host.retire(agent.session.id, agent))
927
+ this.ctx.on('llm/stream', (request, next) => {
928
+ if (isAgentLoopRequest(request) && request.sessionId) {
929
+ const session = this.ctx.agents.get(request.sessionId)?.session
930
+ if (session) host.observeMain(session, request)
931
+ }
932
+ return next()
933
+ })
934
+ this.ctx.inject(['tokenMeter'], scope => {
935
+ host.tokenMeter = scope.tokenMeter
936
+ scope.effect(() => () => { host.tokenMeter = undefined }, 'btw.tokenMeter')
937
+ })
938
+ this.host = host
939
+ // The loader snapshots ./typert once per process. Register this hand-written
940
+ // contribution with the live plugin so an installed update exposes it immediately.
941
+ this.ctx.typert.register({
942
+ package: `${PACKAGE_NAME}-meter`, face: 'host', schemas: [],
943
+ model: { services: [], events: [], objects: [] }, invocations: [contextDescriptor, threadDescriptor, submitFollowupDescriptor, submitCreateDescriptor],
944
+ })
945
+ }
946
+
947
+ sessionFor(agent) {
948
+ const peer = this.ctx.invocation?.peer
949
+ if (peer?.principal.kind !== 'owner' || peer.signal.aborted) throw fault('denied', '无权访问侧问。')
950
+ const sessionId = parseSessionId(agent?.session?.id)
951
+ if (this.ctx.agents.get(sessionId) !== agent) throw fault('denied', '当前会话不可用。')
952
+ return sessionId
953
+ }
954
+
955
+ async prepare(agent, signal) {
956
+ const sessionId = this.sessionFor(agent)
957
+ const available = await this.host.prepare(sessionId, signal, agent)
958
+ this.sessionFor(agent)
959
+ return { sessionId, available }
960
+ }
961
+
962
+ async create(agent, question, signal) {
963
+ const { available } = await this.prepare(agent, signal)
964
+ if (!available) throw fault('session-not-saved', '请先发送一条消息后再发起侧问。')
965
+ return this.host.create(agent, question, signal)
966
+ }
967
+
968
+ async submitCreate(agent, question, submissionId, signal) {
969
+ const { available } = await this.prepare(agent, signal)
970
+ if (!available) throw fault('session-not-saved', '请先发送一条消息后再发起侧问。')
971
+ return this.host.create(agent, question, signal, submissionId)
972
+ }
973
+
974
+ async list(agent, signal) {
975
+ const { sessionId } = await this.prepare(agent, signal)
976
+ return this.host.list(sessionId)
977
+ }
978
+
979
+ async get(agent, id, signal) {
980
+ const { sessionId } = await this.prepare(agent, signal)
981
+ return this.host.get(sessionId, id)
982
+ }
983
+
984
+ async contextCapacity(agent, id, signal) {
985
+ const { sessionId } = await this.prepare(agent, signal)
986
+ return this.host.contextWindow(sessionId, id, signal)
987
+ }
988
+
989
+ async followup(agent, id, question, signal) {
990
+ const { sessionId } = await this.prepare(agent, signal)
991
+ return this.host.followup(sessionId, id, question, signal)
992
+ }
993
+
994
+ async submitFollowup(agent, id, question, submissionId, signal) {
995
+ const { sessionId } = await this.prepare(agent, signal)
996
+ return this.host.followup(sessionId, id, question, signal, submissionId)
997
+ }
998
+
999
+ async *watch(agent, id, version, signal) {
1000
+ const { sessionId } = await this.prepare(agent, signal)
1001
+ yield* this.host.watch(sessionId, id, version, () => this.sessionFor(agent), signal)
1002
+ }
1003
+
1004
+ async *watchThread(agent, id, signal) {
1005
+ const { sessionId } = await this.prepare(agent, signal)
1006
+ yield* this.host.watchThread(sessionId, id, () => this.sessionFor(agent), signal)
1007
+ }
1008
+
1009
+ async *watchReply(agent, id, turnIndex, version, signal) {
1010
+ const { sessionId } = await this.prepare(agent, signal)
1011
+ yield* this.host.watchReply(sessionId, id, turnIndex, version, () => this.sessionFor(agent), signal)
1012
+ }
1013
+ }