dsh-bailinghub 0.5.0 → 0.7.0
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/CHANGELOG.md +79 -0
- package/PRIVACY.md +16 -5
- package/README.md +21 -3
- package/SECURITY.md +10 -2
- package/docs/AGENT_CLIENT_CONTRACT.md +27 -7
- package/docs/CAPABILITY_FEEDBACK.md +199 -0
- package/docs/COMPATIBILITY.md +19 -6
- package/docs/CROSS_SYSTEM_CONVERSATIONS.md +4 -2
- package/docs/GENERATED_ARTIFACTS.md +77 -0
- package/docs/GETTING_STARTED.md +5 -5
- package/docs/GETTING_STARTED.zh-CN.md +5 -5
- package/docs/INVOCATION_RECOVERY.md +182 -0
- package/docs/MIGRATION_VNEXT.md +8 -0
- package/docs/README.zh-CN.md +37 -3
- package/docs/RELEASE_NOTES_v0.6.0.en.md +39 -0
- package/docs/RELEASE_NOTES_v0.6.0.md +39 -0
- package/docs/RELEASE_NOTES_v0.7.0.en.md +15 -0
- package/docs/RELEASE_NOTES_v0.7.0.md +15 -0
- package/docs/SESSION_TOOL_REUSE.md +213 -0
- package/docs/TASK_CONTROL.md +183 -0
- package/docs/UPGRADE_v0.6.0.en.md +71 -0
- package/docs/UPGRADE_v0.6.0.md +73 -0
- package/docs/UPGRADE_v0.7.0.en.md +15 -0
- package/docs/UPGRADE_v0.7.0.md +15 -0
- package/docs/USAGE_SERVICE.md +96 -0
- package/lib/artifact-store.js +56 -0
- package/lib/artifacts.js +132 -0
- package/lib/capability-feedback.js +138 -0
- package/lib/conversation-outbox.js +24 -0
- package/lib/index.js +16 -1
- package/lib/invocation-journal.js +228 -0
- package/lib/invocation-store.js +275 -0
- package/lib/model-gateway-transport.js +246 -0
- package/lib/runtime.js +951 -146
- package/lib/session-scope.js +47 -5
- package/lib/session-task-store.js +275 -0
- package/lib/session-task.js +237 -0
- package/lib/session-tool-cache.js +168 -0
- package/lib/session-tools.js +240 -0
- package/lib/session-usage-store.js +280 -0
- package/lib/tool-catalog.js +38 -0
- package/lib/transport.js +19 -0
- package/lib/usage-llm-stream.js +157 -0
- package/lib/usage-model-transport.js +206 -0
- package/lib/usage-provider-stream.js +82 -0
- package/package.json +18 -3
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto'
|
|
2
|
+
|
|
3
|
+
export const MODEL_REQUEST_EVENT = 'bailinghub/model-request'
|
|
4
|
+
const CLOSED_EVENT = 'bailinghub/model-request-group-ended'
|
|
5
|
+
const SCHEMA = 'bailing.usage-session.v1'
|
|
6
|
+
const META_SCHEMA = 'bailing.model-request.v1'
|
|
7
|
+
const REQUIRED = ['modelModels', 'modelSummary', 'modelComplete', 'modelStream', 'inspectModelRequest', 'cancelModelRequest']
|
|
8
|
+
const clone = value => structuredClone(value)
|
|
9
|
+
|
|
10
|
+
/** Request-sized sidecars prevent a long task from consuming a session-wide metadata budget.
|
|
11
|
+
* The real durable Session is the original request index. No transcript or credential is copied.
|
|
12
|
+
*/
|
|
13
|
+
export class ModelGatewayTransport {
|
|
14
|
+
constructor(host, helpers) { this.host = host; Object.assign(this, helpers) }
|
|
15
|
+
assertSupported() {
|
|
16
|
+
if (REQUIRED.some(name => typeof this.host.client?.[name] !== 'function')) throw this.failure('USAGE_UNSUPPORTED')
|
|
17
|
+
}
|
|
18
|
+
markers(session) { return session.events.filter(e => e.type === MODEL_REQUEST_EVENT) }
|
|
19
|
+
locate(session, id) {
|
|
20
|
+
const found = this.markers(session).filter(e => e.data?.operationId === id)
|
|
21
|
+
if (found.length !== 1) throw this.failure('USAGE_RECOVERY_GAP')
|
|
22
|
+
return found[0].data
|
|
23
|
+
}
|
|
24
|
+
key(session, id) { return `model:${this.hash(session.id)}:${id}` }
|
|
25
|
+
async load(session, meta) {
|
|
26
|
+
const owner = this.eventFor(session, meta.turnId)
|
|
27
|
+
if (meta.schema !== META_SCHEMA || meta.conversationId !== session.id || meta.eventSeq !== owner.seq
|
|
28
|
+
|| meta.eventHash !== this.hash(owner.data) || this.hash(meta.binding) !== this.hash(this.host.assertSupported())) throw this.failure('USAGE_RECOVERY_GAP')
|
|
29
|
+
let record
|
|
30
|
+
try { record = await this.host.store.load(this.key(session, meta.operationId)) } catch { throw this.failure('USAGE_STORAGE_ERROR') }
|
|
31
|
+
if (!record || record.schema !== SCHEMA || record.entries?.length !== 1
|
|
32
|
+
|| this.hash(record.entries[0].request?.metadata) !== this.hash(meta)) throw this.failure('USAGE_RECOVERY_GAP')
|
|
33
|
+
return record
|
|
34
|
+
}
|
|
35
|
+
async save(session, record) {
|
|
36
|
+
const previous = record.revision; record.revision++
|
|
37
|
+
try { await this.host.store.save(record.sessionId, clone(record), previous || null) }
|
|
38
|
+
catch { this.host.storageFailures.add(session.id); throw this.failure('USAGE_STORAGE_ERROR') }
|
|
39
|
+
}
|
|
40
|
+
closed(session, meta) {
|
|
41
|
+
return this.host.cancelled.has(`${session.id}:${meta.turnId}`) || this.host.ended.has(`${session.id}:${meta.turnId}`)
|
|
42
|
+
|| session.events.some(e => e.type === CLOSED_EVENT && e.data?.id === meta.turnId)
|
|
43
|
+
|| !this.isLiveMessage(session, this.eventFor(session, meta.turnId))
|
|
44
|
+
}
|
|
45
|
+
async model(options = {}) {
|
|
46
|
+
this.assertSupported()
|
|
47
|
+
const key = options.serviceId ?? this.host.client.binding.serviceId
|
|
48
|
+
const cached = this.host.modelModelsCache
|
|
49
|
+
const hit = !options.refresh && cached?.until > Date.now()
|
|
50
|
+
const models = hit ? cached.value : await this.host.client.modelModels(options)
|
|
51
|
+
// Cache hits do not extend the freshness deadline; live plan edits must become visible.
|
|
52
|
+
if (!hit) this.host.modelModelsCache = { value: clone(models), until: Date.now() + 60_000 }
|
|
53
|
+
const model = models.items.find(item => item.service_id === key)
|
|
54
|
+
if (!model) throw this.failure('SERVICE_NOT_ENTITLED', { feedback: { schema: 'bailing.usage-feedback.v1', code: 'SERVICE_NOT_ENTITLED', dispatch: 'not_dispatched', next_action: 'select_model', retryable: false } })
|
|
55
|
+
return clone(model)
|
|
56
|
+
}
|
|
57
|
+
async complete(session, input, options = {}, modelTool = false) {
|
|
58
|
+
this.assertSupported()
|
|
59
|
+
let copied
|
|
60
|
+
try { copied = clone(input) } catch { throw this.failure('USAGE_INPUT_INVALID') }
|
|
61
|
+
if (!copied || typeof copied !== 'object' || Array.isArray(copied)
|
|
62
|
+
|| Object.keys(copied).some(key => !['userMessageId', 'modelRequestId', 'serviceId', 'requestGroupId', 'requestKind',
|
|
63
|
+
...(modelTool ? ['arguments'] : ['messages', 'tools', 'tool_choice', 'temperature', 'provider_options'])].includes(key))) throw this.failure('USAGE_INPUT_INVALID')
|
|
64
|
+
const prepared = await this.host.serial(session, async () => {
|
|
65
|
+
await this.host.durable(session)
|
|
66
|
+
const binding = this.host.assertSupported()
|
|
67
|
+
if (this.markers(session).some(marker => this.hash(marker.data?.binding) !== this.hash(binding))) throw this.failure('USAGE_BINDING_MISMATCH')
|
|
68
|
+
const event = this.eventFor(session, copied.userMessageId), requestKey = this.exact(copied.modelRequestId)
|
|
69
|
+
const serviceId = this.exact(copied.serviceId ?? this.host.client.binding.serviceId)
|
|
70
|
+
const request = Object.fromEntries((modelTool ? ['arguments'] : ['messages', 'tools', 'tool_choice', 'temperature', 'provider_options'])
|
|
71
|
+
.filter(key => copied[key] !== undefined).map(key => [key, copied[key]]))
|
|
72
|
+
if (modelTool ? !request.arguments || typeof request.arguments !== 'object' || Array.isArray(request.arguments)
|
|
73
|
+
: !Array.isArray(request.messages) || !request.messages.length) throw this.failure('USAGE_INPUT_INVALID')
|
|
74
|
+
const requestHash = this.hash({ serviceId, kind: modelTool ? 'tool' : 'chat', ...request })
|
|
75
|
+
const existing = this.markers(session).filter(item => item.data?.turnId === copied.userMessageId && item.data?.requestKey === requestKey)
|
|
76
|
+
if (existing.length > 1) throw this.failure('USAGE_RECOVERY_GAP')
|
|
77
|
+
if (existing.length) {
|
|
78
|
+
const meta = existing[0].data
|
|
79
|
+
if (meta.requestHash !== requestHash || meta.serviceId !== serviceId) throw this.failure('USAGE_IDEMPOTENCY_CONFLICT')
|
|
80
|
+
return { receipt: await this.inspect(session, meta, options) }
|
|
81
|
+
}
|
|
82
|
+
if (this.host.cancelled.has(`${session.id}:${copied.userMessageId}`)) throw this.failure('USAGE_CANCELLED')
|
|
83
|
+
this.signalActive(options.signal)
|
|
84
|
+
if (this.host.ended.has(`${session.id}:${copied.userMessageId}`) || !this.isLiveMessage(session, event) || session.events.some(e => e.type === CLOSED_EVENT && e.data?.id === copied.userMessageId)) throw this.failure('USAGE_TURN_ENDED')
|
|
85
|
+
// Preserve the original user/account/service credential binding alongside the selected model.
|
|
86
|
+
// The server remains authoritative for its current plan and credential scope.
|
|
87
|
+
if (modelTool) {
|
|
88
|
+
const directory = await this.host.client.modelTools(options)
|
|
89
|
+
const tool = directory.items.find(item => item.service_id === serviceId)
|
|
90
|
+
if (!tool) throw this.failure('SERVICE_NOT_ENTITLED')
|
|
91
|
+
if (!tool.callable) throw this.failure('USAGE_MODEL_TOOL_UNAVAILABLE')
|
|
92
|
+
}
|
|
93
|
+
const meta = { schema: META_SCHEMA, kind: modelTool ? 'tool' : 'chat', operationId: randomUUID(), requestKey, requestHash,
|
|
94
|
+
binding: clone(this.host.assertSupported()), serviceId, conversationId: this.exact(session.id),
|
|
95
|
+
turnId: copied.userMessageId, eventSeq: event.seq, eventHash: this.hash(event.data) }
|
|
96
|
+
const record = { schema: SCHEMA, sessionId: this.key(session, meta.operationId), revision: 0,
|
|
97
|
+
entries: [{ request: { metadata: meta, state: 'prepared' } }] }
|
|
98
|
+
await this.save(session, record)
|
|
99
|
+
if (typeof session.append !== 'function') throw this.failure('USAGE_RECOVERY_GAP')
|
|
100
|
+
session.append(MODEL_REQUEST_EVENT, meta)
|
|
101
|
+
await this.host.durable(session)
|
|
102
|
+
if (options.signal?.aborted || this.closed(session, meta)) {
|
|
103
|
+
record.entries[0].request.state = 'rejected'
|
|
104
|
+
await this.save(session, record)
|
|
105
|
+
throw this.afterFailure(this.failure(options.signal?.aborted ? 'USAGE_CANCELLED' : 'USAGE_TURN_ENDED'), meta, 'not_dispatched')
|
|
106
|
+
}
|
|
107
|
+
return { meta, request }
|
|
108
|
+
})
|
|
109
|
+
if (prepared.receipt) return prepared.receipt
|
|
110
|
+
const { meta, request } = prepared
|
|
111
|
+
const wire = { ...request, operation_id: meta.operationId, service_id: meta.serviceId,
|
|
112
|
+
conversation_id: meta.conversationId, turn_id: meta.turnId }
|
|
113
|
+
let result, receivedFrame = false
|
|
114
|
+
try {
|
|
115
|
+
await this.host.primary(session); this.signalActive(options.signal)
|
|
116
|
+
if (this.closed(session, meta)) throw this.failure('USAGE_TURN_ENDED')
|
|
117
|
+
if (modelTool) result = await this.host.client.runModelTool(wire, options)
|
|
118
|
+
else if (options.onDelta) {
|
|
119
|
+
for await (const frame of this.host.client.modelStream(wire, options)) {
|
|
120
|
+
receivedFrame = true
|
|
121
|
+
if (frame.type === 'operation') result = frame.operation
|
|
122
|
+
else if (['delta', 'provider'].includes(frame.type) && !options.signal?.aborted && !this.closed(session, meta)) {
|
|
123
|
+
await this.host.primary(session)
|
|
124
|
+
await options.onDelta({ ...frame, preview: true, executable: false })
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
if (!result) throw this.failure('USAGE_STREAM_INCOMPLETE', { feedback: { schema: 'bailing.usage-feedback.v1', code: 'USAGE_STREAM_INCOMPLETE', dispatch: 'unknown', next_action: 'inspect_original', retryable: true } })
|
|
128
|
+
} else result = await this.host.client.modelComplete(wire, options)
|
|
129
|
+
} catch (error) {
|
|
130
|
+
if (receivedFrame && error?.feedback) error.feedback = { ...error.feedback, dispatch: 'unknown', next_action: 'inspect_original' }
|
|
131
|
+
if (['USAGE_INPUT_LIMIT', 'USAGE_UNSUPPORTED', 'SERVICE_NOT_ENTITLED'].includes(error?.code)) this.host.modelModelsCache = null
|
|
132
|
+
try {
|
|
133
|
+
await this.update(session, meta, item => { item.state = error?.feedback?.dispatch === 'not_dispatched' ? 'rejected' : 'unknown' })
|
|
134
|
+
await this.host.primary(session)
|
|
135
|
+
} catch (primary) { throw this.afterFailure(primary, meta) }
|
|
136
|
+
throw this.afterFailure(error?.feedback ? error : this.failure('USAGE_TRANSPORT_UNAVAILABLE'), meta, error?.feedback?.dispatch)
|
|
137
|
+
}
|
|
138
|
+
try {
|
|
139
|
+
this.check(result, meta)
|
|
140
|
+
await this.update(session, meta, item => { item.state = this.state(result) })
|
|
141
|
+
await this.host.primary(session)
|
|
142
|
+
} catch (error) { throw this.afterFailure(error, meta) }
|
|
143
|
+
return this.delivery(session, meta, result, Boolean(options.signal?.aborted))
|
|
144
|
+
}
|
|
145
|
+
afterFailure(error, meta, dispatch = 'unknown') {
|
|
146
|
+
return Object.assign(error, { operationId: meta.operationId, turnId: meta.turnId,
|
|
147
|
+
feedback: { ...error.feedback, dispatch, ...(dispatch === 'unknown' ? { next_action: 'inspect_original' } : {}) } })
|
|
148
|
+
}
|
|
149
|
+
check(result, meta) {
|
|
150
|
+
if (result?.schema !== 'bailing.model-operation.v1' || result.operation_id !== meta.operationId
|
|
151
|
+
|| result.account_id !== meta.binding.accountId || result.user_id !== meta.binding.userId
|
|
152
|
+
|| result.service_id !== meta.serviceId || result.conversation_id !== meta.conversationId || result.turn_id !== meta.turnId
|
|
153
|
+
|| !['pending', 'complete', 'unknown', 'cancelled', 'failed'].includes(result.result_state)
|
|
154
|
+
|| !['pending', 'settled'].includes(result.billing_state)) throw this.failure('USAGE_RECOVERY_GAP')
|
|
155
|
+
}
|
|
156
|
+
state(result) { return result.response_expired === true ? 'closed_unresolved' : result.result_state === 'complete' ? 'completed' : result.result_state === 'cancelled' ? 'cancelled' : result.result_state === 'failed' ? 'rejected' : 'unknown' }
|
|
157
|
+
delivery(session, meta, result, aborted = false) {
|
|
158
|
+
const closed = aborted || this.closed(session, meta), ready = result.result_state === 'complete' && result.response && typeof result.response === 'object'
|
|
159
|
+
return { ...result, host_turn_active: Boolean(!closed && ready),
|
|
160
|
+
delivery_state: closed ? 'cancelled_late_result' : ready ? 'response_ready' : result.result_state === 'failed' ? 'request_failed' : result.response_expired === true || result.result_state === 'unknown' ? 'unresolved_original' : 'pending_original',
|
|
161
|
+
...(closed ? { next_action: 'inspect_original' } : result.response_expired === true ? { next_action: 'contact_operator' } : {}) }
|
|
162
|
+
}
|
|
163
|
+
async update(session, meta, update) {
|
|
164
|
+
return this.host.serial(session, async () => {
|
|
165
|
+
await this.host.primary(session)
|
|
166
|
+
const record = await this.load(session, meta)
|
|
167
|
+
update(record.entries[0].request)
|
|
168
|
+
await this.save(session, record)
|
|
169
|
+
})
|
|
170
|
+
}
|
|
171
|
+
async inspect(session, meta, options = {}) {
|
|
172
|
+
const record = await this.load(session, meta)
|
|
173
|
+
const result = await this.host.client.inspectModelRequest(meta.operationId, { ...options, serviceId: meta.serviceId, conversationId: meta.conversationId, turnId: meta.turnId })
|
|
174
|
+
this.check(result, meta)
|
|
175
|
+
record.entries[0].request.state = this.state(result)
|
|
176
|
+
await this.save(session, record)
|
|
177
|
+
await this.host.primary(session)
|
|
178
|
+
return { ...this.delivery(session, meta, result), recovered_original: true }
|
|
179
|
+
}
|
|
180
|
+
async recover(session, operationId, options = {}) {
|
|
181
|
+
this.assertSupported()
|
|
182
|
+
return this.host.serial(session, async () => {
|
|
183
|
+
await this.host.durable(session)
|
|
184
|
+
return this.inspect(session, this.locate(session, operationId), options)
|
|
185
|
+
})
|
|
186
|
+
}
|
|
187
|
+
async close(session, userMessageId, cancelled, options = {}) {
|
|
188
|
+
const id = this.exact(userMessageId)
|
|
189
|
+
;(cancelled ? this.host.cancelled : this.host.ended).add(`${session.id}:${id}`)
|
|
190
|
+
return this.host.serial(session, async () => {
|
|
191
|
+
await this.host.primary(session)
|
|
192
|
+
this.eventFor(session, id)
|
|
193
|
+
if (!session.events.some(e => e.type === CLOSED_EVENT && e.data?.id === id)) {
|
|
194
|
+
session.append(CLOSED_EVENT, { id, cancelled: Boolean(cancelled) })
|
|
195
|
+
await this.host.durable(session)
|
|
196
|
+
}
|
|
197
|
+
const results = []
|
|
198
|
+
for (const marker of this.markers(session).filter(e => e.data?.turnId === id)) {
|
|
199
|
+
const meta = marker.data, record = await this.load(session, meta)
|
|
200
|
+
if (cancelled && !['completed', 'rejected', 'cancelled'].includes(record.entries[0].request.state)) {
|
|
201
|
+
// Original request cancellation only. No turn exists and no model operation is replayed.
|
|
202
|
+
const result = await this.host.client.cancelModelRequest(meta.operationId,
|
|
203
|
+
{ ...options, serviceId: meta.serviceId, conversationId: meta.conversationId, turnId: meta.turnId })
|
|
204
|
+
this.check(result, meta); results.push(result)
|
|
205
|
+
record.entries[0].request.state = this.state(result)
|
|
206
|
+
await this.save(session, record)
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
return { state: cancelled ? 'cancelled' : 'ended', requests: results, model_operation_performed: false }
|
|
210
|
+
})
|
|
211
|
+
}
|
|
212
|
+
async status(session, options = {}) {
|
|
213
|
+
const pending = []
|
|
214
|
+
for (const marker of this.markers(session)) {
|
|
215
|
+
const record = await this.load(session, marker.data)
|
|
216
|
+
if (['prepared', 'unknown'].includes(record.entries[0].request.state)) pending.push(marker.data.operationId)
|
|
217
|
+
}
|
|
218
|
+
let summary
|
|
219
|
+
try { summary = await this.host.client.modelSummary(options) }
|
|
220
|
+
catch (error) { await this.host.primary(session); throw error }
|
|
221
|
+
await this.host.primary(session)
|
|
222
|
+
const presentation = summary?.presentation
|
|
223
|
+
// Hosts may provide a custom client. Never hand an old/raw summary to a customer UI.
|
|
224
|
+
if (presentation?.schema !== 'bailing.usage-presentation.v1'
|
|
225
|
+
|| !['credits', 'percentage', 'none'].includes(presentation.kind)
|
|
226
|
+
|| !['active', 'depleted', 'not_started', 'expired', 'suspended', 'unavailable'].includes(presentation.state)
|
|
227
|
+
|| !['remaining', 'total'].every(key => presentation[key] === null || typeof presentation[key] === 'number' && Number.isFinite(presentation[key]) && presentation[key] >= 0)
|
|
228
|
+
|| !(presentation.displayValue === null || typeof presentation.displayValue === 'string' && /^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,2})?$|^<(?:1|0\.01)$/.test(presentation.displayValue))) throw this.failure('USAGE_RESPONSE_INVALID')
|
|
229
|
+
const usable = ['active', 'depleted'].includes(presentation.state)
|
|
230
|
+
if (presentation.kind === 'none') {
|
|
231
|
+
if (presentation.state !== 'unavailable' || presentation.remaining !== null || presentation.total !== null || presentation.displayValue !== null) throw this.failure('USAGE_RESPONSE_INVALID')
|
|
232
|
+
} else if (!usable) {
|
|
233
|
+
if (!['not_started', 'expired', 'suspended'].includes(presentation.state) || presentation.remaining !== null || presentation.displayValue !== null) throw this.failure('USAGE_RESPONSE_INVALID')
|
|
234
|
+
} else {
|
|
235
|
+
if (presentation.remaining === null || presentation.total === null || presentation.displayValue === null
|
|
236
|
+
|| presentation.state === 'active' && presentation.remaining <= 0
|
|
237
|
+
|| presentation.state === 'depleted' && (presentation.remaining !== 0 || presentation.displayValue !== '0')) throw this.failure('USAGE_RESPONSE_INVALID')
|
|
238
|
+
if (presentation.kind === 'percentage') {
|
|
239
|
+
if (presentation.total !== 100 || presentation.remaining > 100 || !/^(?:0|[1-9][0-9]?|100|<1)$/.test(presentation.displayValue)) throw this.failure('USAGE_RESPONSE_INVALID')
|
|
240
|
+
} else if (presentation.displayValue === '<1') throw this.failure('USAGE_RESPONSE_INVALID')
|
|
241
|
+
}
|
|
242
|
+
return { schema: 'bailing.usage-host-status.v1', state: 'ready', binding: clone(this.host.assertSupported()),
|
|
243
|
+
mode: 'model_gateway', summary: clone(summary), pendingOperations: pending,
|
|
244
|
+
model_transport_required: true, byok_metered: false, turn_required: false }
|
|
245
|
+
}
|
|
246
|
+
}
|