@kabxx/dsh-btw 0.1.0 → 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.
package/src/host/index.js CHANGED
@@ -2,9 +2,10 @@ import { randomUUID } from 'node:crypto'
2
2
  import { realpathSync } from 'node:fs'
3
3
  import { createRequire } from 'node:module'
4
4
  import { resolve } from 'node:path'
5
+ import { setTimeout as delay } from 'node:timers/promises'
5
6
  import { pathToFileURL } from 'node:url'
6
7
  import {
7
- CONTEXT_OVERFLOW, PACKAGE_NAME, TOKEN_FIELDS, contextDescriptor, parseDetail, parseQuestion, parseSessionId, parseThreadId, parseVersion,
8
+ CONTEXT_OVERFLOW, NATIVE_FAILURE_DETAILS, PACKAGE_NAME, TOKEN_FIELDS, contextDescriptor, parseDetail, parseQuestion, parseSessionId, parseSubmissionId, parseThreadId, parseVersion, submitCreateDescriptor, submitFollowupDescriptor, threadDescriptor,
8
9
  } from '../shared/wire.js'
9
10
  import { sessionThreadStore } from './session-store.js'
10
11
 
@@ -87,10 +88,14 @@ const nativeSnapshot = z.strictObject({
87
88
  updates: z.array(z.strictObject({ messageId: z.string(), additions: z.array(toolSchema) })),
88
89
  }).optional(),
89
90
  temperature: z.number().optional(),
91
+ maxTokens: z.number().optional(),
90
92
  stop: z.array(z.string()).optional(),
91
93
  measuredPrefix: tokenCount.optional(),
92
94
  })
93
95
  const turnSchema = z.strictObject({
96
+ submissionId: z.string().refine(value => {
97
+ try { parseSubmissionId(value); return true } catch { return false }
98
+ }).optional(),
94
99
  question: z.string().min(1),
95
100
  reply: z.string(),
96
101
  status: z.enum(['generating', 'completed', 'failed', 'interrupted']),
@@ -98,11 +103,12 @@ const turnSchema = z.strictObject({
98
103
  finishedAt: timestamp.optional(),
99
104
  error: z.string().optional(),
100
105
  saveError: z.string().optional(),
106
+ outputLimitReached: z.literal(true).optional(),
101
107
  modelReply: nativeMessage.optional(),
102
108
  usage: z.strictObject(Object.fromEntries(TOKEN_FIELDS.map(key => [key, tokenCount.optional()]))).optional(),
103
109
  timing: z.strictObject({ requestMs: timestamp, firstTokenMs: timestamp.optional() }).optional(),
104
110
  })
105
- export const threadSchema = z.strictObject({
111
+ const threadFields = z.strictObject({
106
112
  id: z.string(),
107
113
  sessionId: z.string(),
108
114
  question: z.string().min(1),
@@ -111,8 +117,9 @@ export const threadSchema = z.strictObject({
111
117
  version: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
112
118
  turns: z.array(turnSchema).min(1),
113
119
  route: routeSchema,
114
- snapshot: nativeSnapshot,
115
- }).superRefine((record, context) => {
120
+ })
121
+
122
+ function validateThread(record, context) {
116
123
  try {
117
124
  parseDetail(toDetailShape(record))
118
125
  if (record.question !== record.turns[0].question || record.turns.slice(0, -1).some(turn => turn.status === 'generating')) {
@@ -121,7 +128,11 @@ export const threadSchema = z.strictObject({
121
128
  } catch {
122
129
  context.addIssue({ code: 'custom', message: 'Invalid BTW thread record' })
123
130
  }
124
- })
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 }
125
136
 
126
137
  function fault(code, message) {
127
138
  return new RemoteError(`btw/${code}`, message)
@@ -131,7 +142,7 @@ function newest(record) {
131
142
  return record.turns.at(-1)
132
143
  }
133
144
 
134
- function publicTurn({ modelReply, ...fields }) {
145
+ function publicTurn({ modelReply, submissionId, ...fields }) {
135
146
  return fields
136
147
  }
137
148
 
@@ -196,8 +207,13 @@ function freezeSnapshot(session, selected, observed, tokenMeter) {
196
207
  observed.request.messages.every((message, index) => message === derived[index])
197
208
  const exact = matchesSurface && sameRoute(observed.request, selected) ? observed : undefined
198
209
  const header = session.requestHeader?.()
199
- const controls = exact?.request ?? (sameRoute(header?.config, selected) ? header.config : selected)
200
- const route = { ...selected, reasoningEffort: selected.reasoningEffort ?? controls.reasoningEffort }
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
201
217
  const messages = exact?.request.messages ?? derived.slice(0, end)
202
218
  const tools = exact ? exact.request.tools : header?.tools
203
219
  let toolHistory = exact ? exact.request.toolHistory : session.toolHistory?.()
@@ -221,6 +237,7 @@ function freezeSnapshot(session, selected, observed, tokenMeter) {
221
237
  tools,
222
238
  toolHistory,
223
239
  temperature: controls.temperature,
240
+ maxTokens,
224
241
  stop: controls.stop,
225
242
  measuredPrefix: Number.isSafeInteger(measuredPrefix) && measuredPrefix >= 0 ? measuredPrefix : undefined,
226
243
  }))
@@ -261,11 +278,11 @@ function requestMessages(record, includeSettledLastReply = false) {
261
278
  }
262
279
 
263
280
  function requestFields(snapshot) {
264
- const { system, tools, toolHistory, temperature, stop } = snapshot
281
+ const { system, tools, toolHistory, temperature, maxTokens, stop } = snapshot
265
282
  return {
266
283
  ...(system !== undefined && { system }), ...(tools !== undefined && { tools }),
267
284
  ...(toolHistory !== undefined && { toolHistory }), ...(temperature !== undefined && { temperature }),
268
- ...(stop !== undefined && { stop }),
285
+ ...(maxTokens !== undefined && { maxTokens }), ...(stop !== undefined && { stop }),
269
286
  }
270
287
  }
271
288
 
@@ -306,6 +323,19 @@ async function* streamSideQuestion(llm, options, record) {
306
323
  })
307
324
  }
308
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
+
309
339
  function modelReplyFor(record, assembler, interrupted) {
310
340
  const received = interrupted ? assembler.interruptedBlocks() : assembler.blocks()
311
341
  const content = received.filter(block => block.type === 'text' || block.type === 'reasoning')
@@ -326,6 +356,18 @@ function readUsage(usage) {
326
356
  return Object.keys(counts).length > 0 ? counts : undefined
327
357
  }
328
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
+
329
371
  // Coalesce UI wakeups: each watcher reads the newest immutable revision, so a slow
330
372
  // browser does not accumulate a queue of full answers. There is no async gap between
331
373
  // checking the version and subscribing to the next pulse.
@@ -362,55 +404,124 @@ export class BtwHost {
362
404
  this.runs = new Map()
363
405
  this.listeners = new Map()
364
406
  this.sessions = new Map()
365
- this.opening = new Map()
407
+ this.opening = new Set()
408
+ this.running = new Set()
366
409
  this.admissions = new Set()
410
+ this.archiveRetries = new Set()
367
411
  this.lifetime = new AbortController()
368
412
  }
369
413
 
370
- async prepare(sessionId, signal) {
414
+ async prepare(sessionId, signal, owner) {
371
415
  signal?.throwIfAborted()
372
416
  this.lifetime.signal.throwIfAborted()
373
- if (this.opening.has(sessionId) || !this.sessions.has(sessionId)) {
374
- let opening = this.opening.get(sessionId)
375
- if (!opening) {
376
- opening = this.openSession(sessionId).finally(() => this.opening.delete(sessionId))
377
- this.opening.set(sessionId, opening)
378
- }
379
- await opening
417
+ let state = this.sessions.get(sessionId)
418
+ if (state && owner && state.owner !== owner) {
419
+ this.retire(sessionId, state.owner)
420
+ state = undefined
380
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
381
442
  signal?.throwIfAborted()
382
443
  this.lifetime.signal.throwIfAborted()
383
- return this.sessions.has(sessionId)
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?.()
384
455
  }
385
456
 
386
- async openSession(sessionId) {
387
- const archive = await this.store.open(sessionId, this.lifetime.signal)
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)
388
460
  if (!archive) return
389
- this.sessions.set(sessionId, { archive, records: new Map() })
461
+ signal.throwIfAborted()
462
+ state.archive = archive
390
463
  for (const record of archive.records) {
391
- this.publish(record, false)
464
+ this.publish(record, false, state)
392
465
  if (isDone(record)) continue
393
466
  const time = Math.max(Date.now(), record.updatedAt)
394
467
  const terminal = withLatest(record, {
395
468
  ...newest(record), status: 'interrupted', finishedAt: time, error: INTERRUPTION,
396
469
  }, time)
397
- this.publish(terminal, false)
470
+ this.publish(terminal, false, state)
398
471
  try {
399
- await this.save(terminal)
472
+ await this.save(terminal, state)
400
473
  } catch {
474
+ if (state.controller.signal.aborted) break
401
475
  this.logger?.error('BTW could not save a recovered reply')
402
- this.publish(withLatest(terminal, { ...newest(terminal), saveError: ARCHIVE_ERROR }, time), false)
476
+ this.retryTerminalSave(terminal, state)
403
477
  }
404
478
  }
405
479
  }
406
480
 
407
481
  observeMain(session, request) {
408
- this.mainRequests.set(session, { request, anchor: session.surface?.nodes?.at(-1) ?? null })
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 })
409
487
  }
410
488
 
411
- async save(record) {
489
+ async save(record, state) {
490
+ state.controller.signal.throwIfAborted()
412
491
  const turns = record.turns.map(({ saveError, ...turn }) => turn)
413
- await this.sessions.get(record.sessionId).archive.put(threadSchema.parse({ ...record, turns }))
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))
414
525
  }
415
526
 
416
527
  read(sessionId, id) {
@@ -431,11 +542,13 @@ export class BtwHost {
431
542
  }
432
543
 
433
544
  async contextWindow(sessionId, id, requestSignal) {
434
- const signal = requestSignal
435
- ? AbortSignal.any([requestSignal, this.lifetime.signal])
436
- : this.lifetime.signal
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
+ ])
437
550
  signal.throwIfAborted()
438
- const { provider, model } = this.read(sessionId, id).route
551
+ const { provider, model } = initial.route
439
552
  let capacity
440
553
  try {
441
554
  const info = await this.llm.resolveModelInfo(provider, model, signal)
@@ -445,34 +558,48 @@ export class BtwHost {
445
558
  }
446
559
  signal.throwIfAborted()
447
560
  if (!Number.isSafeInteger(capacity) || capacity <= 0) return { contextWindow: null }
448
- const record = this.read(sessionId, id)
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 }
449
565
  const price = messages => messages.reduce((sum, message) => sum + estimateMessage(message), 0)
450
- const snapshot = record.snapshot
451
- const schemaTokens = estimateToolsTokens({ tools: snapshot.tools })
452
- const systemTokens = snapshot.system
453
- ? estimateMessage({ role: 'system', content: [{ type: 'text', text: snapshot.system }] }) : 0
454
- const overhead = schemaTokens + systemTokens
455
- const fullEstimate = price(requestMessages(record, true)) + overhead
566
+ const messages = requestMessages(record, true)
456
567
  const promptFields = ['inputTokens', 'cacheReadTokens', 'cacheWriteTokens']
457
- const anchor = record.turns.findIndex(({ usage }) => promptFields.some(field => usage?.[field] !== undefined))
458
- const nativeAdjustment = snapshot.measuredPrefix !== undefined
459
- ? snapshot.measuredPrefix - (price(snapshot.messages) + overhead) : 0
460
- let usageAdjustment = 0
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
+ })
461
573
  if (anchor !== -1) {
462
- const reported = promptFields.reduce((sum, field) => sum + (record.turns[anchor].usage[field] ?? 0), 0)
463
- const promptEstimate = price(requestMessages({ ...record, turns: record.turns.slice(0, anchor + 1) })) + overhead
464
- usageAdjustment = reported - promptEstimate
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)) }
465
579
  }
466
- // Fixed native measurements and assistant-context deltas coexist with the
467
- // first side-request sample. Newer billing reports do not reset the meter.
468
- return { contextWindow: capacity, estimatedTokens: fullEstimate + Math.max(0, nativeAdjustment, usageAdjustment) }
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)) }
469
586
  }
470
587
 
471
- async create(agent, question, signal) {
588
+ async create(agent, question, signal, submissionId) {
472
589
  parseQuestion(question)
590
+ if (submissionId !== undefined) parseSubmissionId(submissionId)
473
591
  const sessionId = parseSessionId(agent.session.id)
474
- if (!await this.prepare(sessionId, signal)) {
475
- throw fault('session-not-saved', '请先发送一条消息开始侧问')
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
+ }
476
603
  }
477
604
  const selected = agent.model.current()
478
605
  const model = routeSchema.safeParse(selected && {
@@ -483,49 +610,91 @@ export class BtwHost {
483
610
  if (!model.success) throw fault('model-unavailable', '当前会话未配置可用模型。')
484
611
  const time = Date.now()
485
612
  const { route, snapshot } = freezeSnapshot(agent.session, model.data, this.mainRequests.get(agent.session), this.tokenMeter)
486
- return this.admit({
613
+ const turn = nextTurn(question, time)
614
+ if (submissionId !== undefined) turn.submissionId = submissionId
615
+ const admission = this.admit({
487
616
  id: `btw-${randomUUID()}`, sessionId, question, createdAt: time, updatedAt: time, version: 1,
488
- turns: [nextTurn(question, time)], route, snapshot,
617
+ turns: [turn], route, snapshot,
489
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
490
625
  }
491
626
 
492
- followup(sessionId, id, question, signal) {
627
+ followup(sessionId, id, question, signal, submissionId) {
493
628
  signal?.throwIfAborted()
494
629
  this.lifetime.signal.throwIfAborted()
495
630
  parseQuestion(question)
496
631
  const record = this.read(sessionId, id)
497
- if (this.runs.has(id) || !isDone(record)) throw fault('generating', '上一条回复仍在生成。')
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', '上一条回复仍在生成。')
498
651
  if (newest(record).error === CONTEXT_OVERFLOW) throw fault('context-overflow', '已达上下文上限。')
499
652
  const time = Math.max(Date.now(), record.updatedAt)
500
- return this.admit(nextRevision(record, [...record.turns, nextTurn(question, time)], time), admitted => {
501
- const { usage, ...turn } = publicTurn(newest(admitted))
502
- return { id, sessionId, updatedAt: admitted.updatedAt, version: admitted.version, turnIndex: admitted.turns.length - 1, turn }
503
- })
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))
504
657
  }
505
658
 
506
659
  admit(record, result = toDetail) {
507
660
  const controller = new AbortController()
508
- const run = { controller, promise: undefined }
661
+ const state = this.sessions.get(record.sessionId)
662
+ const run = { controller, state, submission: newest(record) }
509
663
  this.runs.set(record.id, run)
510
- const admission = this.save(record).then(() => {
511
- this.publish(record)
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)
512
678
  // Start only after durable admission. No caller/transport signal is inherited.
513
- run.promise = this.generate(record, controller.signal, () => {
679
+ const generation = this.generate(record, controller.signal, () => {
514
680
  if (this.runs.get(record.id) === run) this.runs.delete(record.id)
515
- })
681
+ }, state)
682
+ this.running.add(generation)
683
+ generation.then(() => this.running.delete(generation), () => this.running.delete(generation))
516
684
  return result(record)
517
685
  }).catch(error => {
518
- this.runs.delete(record.id)
519
- this.logger?.error('BTW could not admit a question')
520
- throw fault('save-failed', '保存侧问失败。')
686
+ if (this.runs.get(record.id) === run) this.runs.delete(record.id)
687
+ throw error
521
688
  })
689
+ run.admission = admission
522
690
  this.admissions.add(admission)
523
691
  admission.then(() => this.admissions.delete(admission), () => this.admissions.delete(admission))
524
692
  return admission
525
693
  }
526
694
 
527
- publish(record, wake = true) {
528
- this.sessions.get(record.sessionId).records.set(record.id, record)
695
+ publish(record, wake = true, state) {
696
+ if (state.controller.signal.aborted) return
697
+ state.records.set(record.id, record)
529
698
  if (wake) this.notify(record.id)
530
699
  }
531
700
 
@@ -533,8 +702,8 @@ export class BtwHost {
533
702
  for (const listener of this.listeners.get(id) ?? []) listener()
534
703
  }
535
704
 
536
- async generate(record, runSignal, releaseRun) {
537
- const signal = AbortSignal.any([runSignal, this.lifetime.signal])
705
+ async generate(record, runSignal, releaseRun, state) {
706
+ const signal = AbortSignal.any([runSignal, this.lifetime.signal, state.controller.signal])
538
707
  const assembler = new BlockAssembler()
539
708
  let current = record
540
709
  let checkpointVersion = record.version
@@ -547,8 +716,9 @@ export class BtwHost {
547
716
  const checkpointTimer = setInterval(() => {
548
717
  if (pendingSave || checkpointVersion === current.version || signal.aborted) return
549
718
  const checkpoint = current
550
- checkpointVersion = checkpoint.version
551
- pendingSave = this.save(checkpoint).catch(() => {
719
+ pendingSave = this.save(checkpoint, state).then(() => {
720
+ checkpointVersion = checkpoint.version
721
+ }).catch(() => {
552
722
  this.logger?.error('BTW could not save a reply checkpoint')
553
723
  }).finally(() => { pendingSave = undefined })
554
724
  }, CHECKPOINT_INTERVAL_MS)
@@ -572,16 +742,11 @@ export class BtwHost {
572
742
  firstTokenMs = Math.round(performance.now() - startedAt)
573
743
  }
574
744
  assembler.push(chunk)
575
- if (chunk.type === 'finish') {
576
- finish = chunk.reason.kind
577
- if (finish === 'error') failureCode = chunk.reason.failure?.code
578
- break
579
- }
580
745
  if (chunk.type !== 'text-delta' && !(chunk.type === 'block-end' && chunk.block.type === 'text')) continue
581
- const reply = assembler.interruptedBlocks().filter(block => block.type === 'text').map(block => block.text).join('')
746
+ const reply = previewReply(assembler)
582
747
  const time = Date.now()
583
748
  current = withLatest(current, { ...newest(current), reply }, time)
584
- this.publish(current, false)
749
+ this.publish(current, false, state)
585
750
  if (time - lastNotified >= PREVIEW_INTERVAL_MS) {
586
751
  clearTimeout(previewTimer)
587
752
  sendPreview()
@@ -589,8 +754,11 @@ export class BtwHost {
589
754
  previewTimer = setTimeout(sendPreview, PREVIEW_INTERVAL_MS - (time - lastNotified))
590
755
  }
591
756
  }
757
+ const reason = assembler.finish
758
+ finish = reason.kind
759
+ if (reason.kind === 'error') failureCode = reason.failure?.code
592
760
  } catch (error) {
593
- // Only the canonical overflow code crosses the wire, never provider details.
761
+ // Never expose raw provider diagnostics through side-question history.
594
762
  failureCode = error?.code
595
763
  }
596
764
  clearInterval(checkpointTimer)
@@ -598,22 +766,32 @@ export class BtwHost {
598
766
  const timing = { requestMs: Math.round(performance.now() - startedAt),
599
767
  ...(firstTokenMs !== undefined && { firstTokenMs }) }
600
768
  await pendingSave
769
+ if (state.controller.signal.aborted) {
770
+ releaseRun()
771
+ return
772
+ }
601
773
  const time = Math.max(Date.now(), current.updatedAt)
602
774
  const turn = newest(current)
603
775
  const interrupted = signal.aborted || finish === 'aborted'
604
776
  let error
605
777
  if (interrupted) error = INTERRUPTION
606
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
607
780
  else if (!finish || finish === 'error') error = FAILURE
608
- else if (!turn.reply.trim()) error = NO_TEXT
781
+ else if (finish !== 'max-tokens' && !turn.reply.trim()) error = NO_TEXT
609
782
  let modelReply
610
783
  if (signal.aborted || !error) {
611
784
  try { modelReply = modelReplyFor(record, assembler, signal.aborted) } catch { error = FAILURE }
612
785
  }
786
+ const reply = error
787
+ ? replyText(assembler.interruptedBlocks())
788
+ : replyText(modelReply?.content ?? [])
613
789
  const usage = readUsage(assembler.usage)
614
790
  const terminal = withLatest(current, {
615
791
  ...turn,
792
+ reply,
616
793
  status: interrupted ? 'interrupted' : error ? 'failed' : 'completed',
794
+ ...(!interrupted && !error && finish === 'max-tokens' && { outputLimitReached: true }),
617
795
  finishedAt: time,
618
796
  ...(error ? { error } : {}),
619
797
  ...(modelReply ? { modelReply } : {}),
@@ -621,13 +799,13 @@ export class BtwHost {
621
799
  timing,
622
800
  }, time)
623
801
  try {
624
- await this.save(terminal)
802
+ await this.save(terminal, state)
625
803
  releaseRun()
626
- this.publish(terminal)
804
+ this.publish(terminal, true, state)
627
805
  } catch {
628
806
  this.logger?.error('BTW could not save a terminal reply')
629
807
  releaseRun()
630
- this.publish(withLatest(terminal, { ...newest(terminal), saveError: ARCHIVE_ERROR }, time))
808
+ if (!state.controller.signal.aborted) this.retryTerminalSave(terminal, state)
631
809
  }
632
810
  }
633
811
 
@@ -643,7 +821,7 @@ export class BtwHost {
643
821
  version = record.version
644
822
  yield toDetail(record)
645
823
  }
646
- if (isDone(record)) return
824
+ if (isDone(record) && !record.turns[0].saveError) return
647
825
  // If a revision arrived while the generator was yielding, reread promptly.
648
826
  if (this.read(sessionId, id).version !== version) continue
649
827
  try {
@@ -655,6 +833,41 @@ export class BtwHost {
655
833
  }
656
834
  }
657
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
+
658
871
  async *watchReply(sessionId, id, turnIndex, version, assertAccess, requestSignal) {
659
872
  const signal = requestSignal
660
873
  ? AbortSignal.any([requestSignal, this.lifetime.signal])
@@ -667,16 +880,10 @@ export class BtwHost {
667
880
  if (!turn) throw fault('not-found', '找不到这轮侧问。')
668
881
  if (record.version !== version || turn.status !== 'generating') {
669
882
  // A changed baseline may have reordered text blocks before we began watching.
670
- const start = previousText !== undefined && turn.reply.startsWith(previousText) ? previousText.length : 0
671
- const { status, finishedAt, error, saveError, usage, timing } = turn
883
+ const delta = replyDelta(previousText, turn)
672
884
  version = record.version
673
885
  previousText = turn.reply
674
- yield {
675
- version, updatedAt: record.updatedAt, offset: start, text: turn.reply.slice(start), status,
676
- ...(finishedAt !== undefined && { finishedAt }), ...(error !== undefined && { error }),
677
- ...(saveError !== undefined && { saveError }), ...(usage !== undefined && { usage }),
678
- ...(timing !== undefined && { timing }),
679
- }
886
+ yield { version, updatedAt: record.updatedAt, ...delta }
680
887
  } else if (previousText === undefined) {
681
888
  previousText = turn.reply
682
889
  }
@@ -694,8 +901,10 @@ export class BtwHost {
694
901
  async close() {
695
902
  this.lifetime.abort()
696
903
  await Promise.allSettled([...this.admissions])
697
- await Promise.allSettled([...this.runs.values()].map(run => run.promise))
904
+ await Promise.allSettled([...this.running])
698
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)))
699
908
  }
700
909
  }
701
910
 
@@ -707,9 +916,14 @@ export default class BtwService extends TypertRemoteService {
707
916
  }
708
917
 
709
918
  async [Service.init]() {
710
- const store = sessionThreadStore(this.ctx.sessionPersistence, record => threadSchema.parse(record))
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
+ })
711
924
  const host = new BtwHost({ store, llm: this.ctx.llm, logger: this.ctx.logger })
712
925
  this.ctx.effect(() => () => host.close(), 'btw.close')
926
+ this.ctx.on('agent/disposed', ({ agent }) => host.retire(agent.session.id, agent))
713
927
  this.ctx.on('llm/stream', (request, next) => {
714
928
  if (isAgentLoopRequest(request) && request.sessionId) {
715
929
  const session = this.ctx.agents.get(request.sessionId)?.session
@@ -726,7 +940,7 @@ export default class BtwService extends TypertRemoteService {
726
940
  // contribution with the live plugin so an installed update exposes it immediately.
727
941
  this.ctx.typert.register({
728
942
  package: `${PACKAGE_NAME}-meter`, face: 'host', schemas: [],
729
- model: { services: [], events: [], objects: [] }, invocations: [contextDescriptor],
943
+ model: { services: [], events: [], objects: [] }, invocations: [contextDescriptor, threadDescriptor, submitFollowupDescriptor, submitCreateDescriptor],
730
944
  })
731
945
  }
732
946
 
@@ -740,17 +954,23 @@ export default class BtwService extends TypertRemoteService {
740
954
 
741
955
  async prepare(agent, signal) {
742
956
  const sessionId = this.sessionFor(agent)
743
- const available = await this.host.prepare(sessionId, signal)
957
+ const available = await this.host.prepare(sessionId, signal, agent)
744
958
  this.sessionFor(agent)
745
959
  return { sessionId, available }
746
960
  }
747
961
 
748
962
  async create(agent, question, signal) {
749
963
  const { available } = await this.prepare(agent, signal)
750
- if (!available) throw fault('session-not-saved', '请先发送一条消息开始侧问')
964
+ if (!available) throw fault('session-not-saved', '请先发送一条消息后再发起侧问。')
751
965
  return this.host.create(agent, question, signal)
752
966
  }
753
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
+
754
974
  async list(agent, signal) {
755
975
  const { sessionId } = await this.prepare(agent, signal)
756
976
  return this.host.list(sessionId)
@@ -771,11 +991,21 @@ export default class BtwService extends TypertRemoteService {
771
991
  return this.host.followup(sessionId, id, question, signal)
772
992
  }
773
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
+
774
999
  async *watch(agent, id, version, signal) {
775
1000
  const { sessionId } = await this.prepare(agent, signal)
776
1001
  yield* this.host.watch(sessionId, id, version, () => this.sessionFor(agent), signal)
777
1002
  }
778
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
+
779
1009
  async *watchReply(agent, id, turnIndex, version, signal) {
780
1010
  const { sessionId } = await this.prepare(agent, signal)
781
1011
  yield* this.host.watchReply(sessionId, id, turnIndex, version, () => this.sessionFor(agent), signal)