@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/README.md +7 -9
- package/dist/client.js +575 -247
- package/locale/en.json +18 -5
- package/locale/zh.json +20 -7
- package/package.json +2 -1
- package/src/host/index.js +332 -102
- package/src/host/session-store.js +125 -24
- package/src/shared/wire.js +70 -14
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto'
|
|
2
|
-
import {
|
|
2
|
+
import { renameSync, unlinkSync } from 'node:fs'
|
|
3
|
+
import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
|
|
3
4
|
import { createRequire } from 'node:module'
|
|
4
|
-
import { dirname, isAbsolute, join, relative, sep } from 'node:path'
|
|
5
|
+
import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
|
|
5
6
|
import { PACKAGE_NAME, parseThreadId } from '../shared/wire.js'
|
|
6
7
|
|
|
7
8
|
const { version } = createRequire(import.meta.url)('../../package.json')
|
|
8
|
-
const
|
|
9
|
+
const INLINE_SCHEMA_VERSION = 1
|
|
10
|
+
const SCHEMA_VERSION = 2
|
|
9
11
|
const releaseDirectory = /^v\d+\.\d+\.\d+$/u
|
|
10
12
|
|
|
11
13
|
async function listDirectory(directory) {
|
|
@@ -17,7 +19,57 @@ async function listDirectory(directory) {
|
|
|
17
19
|
}
|
|
18
20
|
}
|
|
19
21
|
|
|
20
|
-
|
|
22
|
+
async function replaceArchiveFile(sessionDirectory, file, value, ownerSignal) {
|
|
23
|
+
ownerSignal.throwIfAborted()
|
|
24
|
+
let directory = sessionDirectory
|
|
25
|
+
for (const part of relative(sessionDirectory, dirname(file)).split(sep)) {
|
|
26
|
+
directory = join(directory, part)
|
|
27
|
+
// Start below the session root so a removed session cannot be recreated here.
|
|
28
|
+
await mkdir(directory, { mode: 0o700 }).catch(error => {
|
|
29
|
+
if (error.code !== 'EEXIST') throw error
|
|
30
|
+
})
|
|
31
|
+
}
|
|
32
|
+
const temporary = `${file}.${randomUUID()}.tmp`
|
|
33
|
+
try {
|
|
34
|
+
await writeFile(temporary, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 })
|
|
35
|
+
// Agent scope teardown revokes writes before the main session lease closes.
|
|
36
|
+
// Keep the ownership check and final replacement in the same JS turn.
|
|
37
|
+
ownerSignal.throwIfAborted()
|
|
38
|
+
renameSync(temporary, file)
|
|
39
|
+
} catch (error) {
|
|
40
|
+
await unlink(temporary).catch(() => {})
|
|
41
|
+
throw error
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function snapshotFileFor(file) {
|
|
46
|
+
return join(dirname(dirname(file)), 'snapshots', basename(file))
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
async function readSnapshot(file, signal, schema, onMalformedRecord) {
|
|
50
|
+
const contents = await readFile(snapshotFileFor(file), { encoding: 'utf8', signal }).catch(error => {
|
|
51
|
+
if (error.code !== 'ENOENT') throw error
|
|
52
|
+
})
|
|
53
|
+
if (contents === undefined) {
|
|
54
|
+
onMalformedRecord?.(file, 'missing thread snapshot')
|
|
55
|
+
return
|
|
56
|
+
}
|
|
57
|
+
let snapshot
|
|
58
|
+
try {
|
|
59
|
+
snapshot = JSON.parse(contents)
|
|
60
|
+
} catch {
|
|
61
|
+
onMalformedRecord?.(file, 'invalid thread snapshot JSON')
|
|
62
|
+
return
|
|
63
|
+
}
|
|
64
|
+
const parsed = schema.safeParse(snapshot)
|
|
65
|
+
if (!parsed.success) {
|
|
66
|
+
onMalformedRecord?.(file, 'invalid thread snapshot')
|
|
67
|
+
return
|
|
68
|
+
}
|
|
69
|
+
return parsed.data
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function sessionThreadStore(persistence, schemas, onMalformedRecord, onSnapshotCleanupError) {
|
|
21
73
|
return {
|
|
22
74
|
async open(sessionId, signal) {
|
|
23
75
|
const snapshot = await persistence.stat(sessionId, { signal })
|
|
@@ -39,39 +91,88 @@ export function sessionThreadStore(persistence, parseRecord) {
|
|
|
39
91
|
for (const entry of await listDirectory(directory)) {
|
|
40
92
|
if (!entry.isFile() || !entry.name.endsWith('.json')) continue
|
|
41
93
|
const file = join(directory, entry.name)
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
94
|
+
let contents
|
|
95
|
+
try {
|
|
96
|
+
contents = await readFile(file, { encoding: 'utf8', signal })
|
|
97
|
+
} catch (error) {
|
|
98
|
+
if (error?.code !== 'EACCES' && error?.code !== 'EPERM') throw error
|
|
99
|
+
signal.throwIfAborted()
|
|
100
|
+
onMalformedRecord?.(file, `cannot read thread record (${error.code})`)
|
|
101
|
+
continue
|
|
102
|
+
}
|
|
103
|
+
let envelope
|
|
104
|
+
try {
|
|
105
|
+
envelope = JSON.parse(contents)
|
|
106
|
+
} catch {
|
|
107
|
+
onMalformedRecord?.(file, 'invalid JSON')
|
|
108
|
+
continue
|
|
109
|
+
}
|
|
110
|
+
if (typeof envelope?.schemaVersion !== 'number') {
|
|
111
|
+
onMalformedRecord?.(file, 'invalid archive envelope')
|
|
112
|
+
continue
|
|
113
|
+
}
|
|
114
|
+
const { schemaVersion } = envelope
|
|
115
|
+
if (schemaVersion !== INLINE_SCHEMA_VERSION && schemaVersion !== SCHEMA_VERSION) continue
|
|
116
|
+
const hasSnapshot = schemaVersion === SCHEMA_VERSION
|
|
117
|
+
let record
|
|
118
|
+
try {
|
|
119
|
+
record = (hasSnapshot ? schemas.record : schemas.inline).parse(envelope.record)
|
|
120
|
+
} catch {
|
|
121
|
+
onMalformedRecord?.(file, 'invalid thread record')
|
|
122
|
+
continue
|
|
123
|
+
}
|
|
45
124
|
if (record.sessionId !== sessionId) continue
|
|
46
|
-
if (entry.name !== `${record.id}.json` || files.has(record.id))
|
|
47
|
-
|
|
125
|
+
if (entry.name !== `${record.id}.json` || files.has(record.id)) {
|
|
126
|
+
onMalformedRecord?.(file, 'invalid or duplicate thread filename')
|
|
127
|
+
continue
|
|
128
|
+
}
|
|
129
|
+
files.set(record.id, { file, hasSnapshot })
|
|
48
130
|
records.push(record)
|
|
49
131
|
}
|
|
50
132
|
}
|
|
51
133
|
signal.throwIfAborted()
|
|
52
134
|
return {
|
|
53
135
|
records,
|
|
54
|
-
async
|
|
136
|
+
async loadSnapshot(id) {
|
|
137
|
+
signal.throwIfAborted()
|
|
138
|
+
const entry = files.get(parseThreadId(id))
|
|
139
|
+
if (!entry?.hasSnapshot) return
|
|
140
|
+
const loading = entry.loading ??= readSnapshot(entry.file, signal, schemas.snapshot, onMalformedRecord)
|
|
141
|
+
let snapshot
|
|
142
|
+
try {
|
|
143
|
+
snapshot = await loading
|
|
144
|
+
signal.throwIfAborted()
|
|
145
|
+
return snapshot
|
|
146
|
+
} finally {
|
|
147
|
+
// Keep successful reads for this owner, and allow repaired files to be read again.
|
|
148
|
+
if (snapshot === undefined && entry.loading === loading) delete entry.loading
|
|
149
|
+
}
|
|
150
|
+
},
|
|
151
|
+
async put({ snapshot, ...record }, ownerSignal = signal) {
|
|
152
|
+
ownerSignal.throwIfAborted()
|
|
55
153
|
const id = parseThreadId(record.id)
|
|
56
|
-
const
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
//
|
|
61
|
-
await
|
|
62
|
-
if (error.code !== 'EEXIST') throw error
|
|
63
|
-
})
|
|
154
|
+
const existing = files.get(id)
|
|
155
|
+
const file = existing?.file ?? join(root, `v${version}`, 'threads', `${id}.json`)
|
|
156
|
+
const snapshotFile = snapshotFileFor(file)
|
|
157
|
+
if (!existing?.hasSnapshot) {
|
|
158
|
+
// Publish the frozen prefix first so either archive format stays readable.
|
|
159
|
+
await replaceArchiveFile(sessionDirectory, snapshotFile, schemas.snapshot.parse(snapshot), ownerSignal)
|
|
64
160
|
}
|
|
65
|
-
const temporary = `${file}.${randomUUID()}.tmp`
|
|
66
161
|
try {
|
|
67
|
-
|
|
68
|
-
await writeFile(temporary, `${JSON.stringify(envelope)}\n`, { flag: 'wx', mode: 0o600 })
|
|
69
|
-
await rename(temporary, file)
|
|
162
|
+
await replaceArchiveFile(sessionDirectory, file, { schemaVersion: SCHEMA_VERSION, record }, ownerSignal)
|
|
70
163
|
} catch (error) {
|
|
71
|
-
|
|
164
|
+
// A failed first admission has no thread referencing this snapshot.
|
|
165
|
+
// Keep the ownership check and cleanup in the same JS turn.
|
|
166
|
+
if (!existing && !ownerSignal.aborted) {
|
|
167
|
+
try {
|
|
168
|
+
unlinkSync(snapshotFile)
|
|
169
|
+
} catch (cleanupError) {
|
|
170
|
+
if (cleanupError.code !== 'ENOENT') onSnapshotCleanupError?.(snapshotFile, cleanupError)
|
|
171
|
+
}
|
|
172
|
+
}
|
|
72
173
|
throw error
|
|
73
174
|
}
|
|
74
|
-
files.set(id, file)
|
|
175
|
+
if (!existing?.hasSnapshot) files.set(id, { file, hasSnapshot: true })
|
|
75
176
|
},
|
|
76
177
|
}
|
|
77
178
|
},
|
package/src/shared/wire.js
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
1
|
export const PACKAGE_NAME = '@kabxx/dsh-btw'
|
|
2
2
|
export const CONTEXT_OVERFLOW = 'context-window-exceeded'
|
|
3
|
+
export const NATIVE_FAILURE_DETAILS = Object.freeze({
|
|
4
|
+
ACCOUNT_SIGNED_OUT: 'accountSignedOut',
|
|
5
|
+
ACCOUNT_SIGN_IN_REQUIRED: 'accountSignInRequired',
|
|
6
|
+
AUTH: 'invalidApiKey',
|
|
7
|
+
QUOTA: 'quotaExhausted',
|
|
8
|
+
ACCOUNT_QUOTA: 'quotaExhausted',
|
|
9
|
+
RATE_LIMIT: 'rateLimited',
|
|
10
|
+
CONTENT_REFUSED: 'contentRefused',
|
|
11
|
+
})
|
|
3
12
|
const STATUSES = new Set(['generating', 'completed', 'failed', 'interrupted'])
|
|
4
13
|
export const TOKEN_FIELDS = ['inputTokens', 'outputTokens', 'totalTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']
|
|
5
14
|
const THREAD_ID = /^btw-[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/u
|
|
@@ -21,6 +30,10 @@ export function parseQuestion(value) {
|
|
|
21
30
|
return checked(value, typeof value === 'string' && value.trim() !== '', 'question')
|
|
22
31
|
}
|
|
23
32
|
|
|
33
|
+
export function parseSubmissionId(value) {
|
|
34
|
+
return checked(value, typeof value === 'string' && /^[\da-f]{32}$/u.test(value), 'submissionId')
|
|
35
|
+
}
|
|
36
|
+
|
|
24
37
|
export function parseVersion(value) {
|
|
25
38
|
return checked(value, Number.isSafeInteger(value) && value >= 1, 'version')
|
|
26
39
|
}
|
|
@@ -65,8 +78,12 @@ function parseTiming(value) {
|
|
|
65
78
|
return checked({ requestMs, firstTokenMs }, firstTokenMs <= requestMs, 'first token timing')
|
|
66
79
|
}
|
|
67
80
|
|
|
81
|
+
function parseOutputLimit(value) {
|
|
82
|
+
return checked(value.outputLimitReached, value.outputLimitReached === true && value.status === 'completed', 'output limit')
|
|
83
|
+
}
|
|
84
|
+
|
|
68
85
|
export function parseTurn(value) {
|
|
69
|
-
object(value, ['question', 'reply', 'status', 'createdAt', 'finishedAt', 'error', 'saveError', 'usage', 'timing'])
|
|
86
|
+
object(value, ['question', 'reply', 'status', 'createdAt', 'finishedAt', 'error', 'saveError', 'outputLimitReached', 'usage', 'timing'])
|
|
70
87
|
const turn = {
|
|
71
88
|
question: parseQuestion(value.question),
|
|
72
89
|
reply: checked(value.reply, typeof value.reply === 'string', 'reply'),
|
|
@@ -77,6 +94,7 @@ export function parseTurn(value) {
|
|
|
77
94
|
else checked(value.finishedAt, value.finishedAt === undefined, 'finishedAt')
|
|
78
95
|
if (value.error !== undefined) turn.error = checked(value.error, typeof value.error === 'string', 'error')
|
|
79
96
|
if (value.saveError !== undefined) turn.saveError = checked(value.saveError, typeof value.saveError === 'string', 'saveError')
|
|
97
|
+
if (value.outputLimitReached !== undefined) turn.outputLimitReached = parseOutputLimit(value)
|
|
80
98
|
if (value.usage !== undefined) turn.usage = parseUsage(value.usage)
|
|
81
99
|
if (value.timing !== undefined) turn.timing = parseTiming(value.timing)
|
|
82
100
|
return turn
|
|
@@ -113,21 +131,17 @@ function parsePosition(value) {
|
|
|
113
131
|
return checked(value, Number.isSafeInteger(value) && value >= 0, 'position')
|
|
114
132
|
}
|
|
115
133
|
|
|
116
|
-
export function appendTurn(detail, receipt) {
|
|
117
|
-
if (detail.id !== receipt.id || detail.sessionId !== receipt.sessionId
|
|
118
|
-
|| receipt.turnIndex !== detail.turns.length || receipt.version <= detail.version) return detail
|
|
119
|
-
return { ...detail, updatedAt: receipt.updatedAt, version: receipt.version, turns: [...detail.turns, receipt.turn] }
|
|
120
|
-
}
|
|
121
|
-
|
|
122
134
|
export function applyReply(detail, turnIndex, update) {
|
|
123
135
|
const turn = detail.turns[turnIndex]
|
|
124
|
-
if (!turn || turn.status !== 'generating' || update.version <= detail.version) return detail
|
|
125
|
-
|
|
136
|
+
if (!turn || (turn.status !== 'generating' && !turn.saveError) || update.version <= detail.version) return detail
|
|
137
|
+
const { saveError, ...previous } = turn
|
|
138
|
+
checked(update.offset, update.offset <= turn.reply.length, 'reply offset')
|
|
126
139
|
const turns = [...detail.turns]
|
|
127
140
|
turns[turnIndex] = {
|
|
128
|
-
...
|
|
141
|
+
...previous, reply: turn.reply.slice(0, update.offset) + update.text, status: update.status,
|
|
129
142
|
...(update.finishedAt !== undefined && { finishedAt: update.finishedAt }),
|
|
130
143
|
...(update.error !== undefined && { error: update.error }),
|
|
144
|
+
...(update.outputLimitReached !== undefined && { outputLimitReached: update.outputLimitReached }),
|
|
131
145
|
...(update.saveError !== undefined && { saveError: update.saveError }),
|
|
132
146
|
...(update.usage !== undefined && { usage: update.usage }),
|
|
133
147
|
...(update.timing !== undefined && { timing: update.timing }),
|
|
@@ -143,21 +157,41 @@ function parseReceipt(value) {
|
|
|
143
157
|
}
|
|
144
158
|
}
|
|
145
159
|
|
|
146
|
-
|
|
147
|
-
|
|
160
|
+
const replyFields = ['offset', 'text', 'status', 'finishedAt', 'error', 'saveError', 'outputLimitReached', 'usage', 'timing']
|
|
161
|
+
|
|
162
|
+
function parseReply(value) {
|
|
148
163
|
const update = {
|
|
149
|
-
|
|
164
|
+
offset: parsePosition(value.offset),
|
|
150
165
|
text: checked(value.text, typeof value.text === 'string', 'text'), status: status(value.status),
|
|
151
166
|
}
|
|
152
167
|
if (update.status !== 'generating') update.finishedAt = timestamp(value.finishedAt)
|
|
153
168
|
else checked(value.finishedAt, value.finishedAt === undefined, 'finishedAt')
|
|
154
169
|
if (value.error !== undefined) update.error = checked(value.error, typeof value.error === 'string', 'error')
|
|
170
|
+
if (value.outputLimitReached !== undefined) update.outputLimitReached = parseOutputLimit(value)
|
|
155
171
|
if (value.saveError !== undefined) update.saveError = checked(value.saveError, typeof value.saveError === 'string', 'saveError')
|
|
156
172
|
if (value.usage !== undefined) update.usage = parseUsage(value.usage)
|
|
157
173
|
if (value.timing !== undefined) update.timing = parseTiming(value.timing)
|
|
158
174
|
return update
|
|
159
175
|
}
|
|
160
176
|
|
|
177
|
+
function parseReplyUpdate(value) {
|
|
178
|
+
object(value, ['version', 'updatedAt', ...replyFields])
|
|
179
|
+
return { version: parseVersion(value.version), updatedAt: timestamp(value.updatedAt), ...parseReply(value) }
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function applyThreadEvent(detail, event) {
|
|
183
|
+
if (event.kind === 'snapshot') return event.detail
|
|
184
|
+
if (event.version <= detail.version) return detail
|
|
185
|
+
checked(event.firstTurn, event.firstTurn === detail.turns.length, 'thread turn position')
|
|
186
|
+
const changed = event.reply ? applyReply(detail, event.firstTurn - 1, {
|
|
187
|
+
...event.reply, version: event.version, updatedAt: event.updatedAt,
|
|
188
|
+
}) : detail
|
|
189
|
+
return {
|
|
190
|
+
...changed, version: event.version, updatedAt: event.updatedAt,
|
|
191
|
+
turns: event.turns.length ? [...changed.turns, ...event.turns] : changed.turns,
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
|
|
161
195
|
const detail = codec(`${PACKAGE_NAME}#Detail`, parseDetail)
|
|
162
196
|
const receipt = codec(`${PACKAGE_NAME}#FollowupReceipt`, parseReceipt)
|
|
163
197
|
const replyUpdate = codec(`${PACKAGE_NAME}#ReplyUpdate`, parseReplyUpdate)
|
|
@@ -207,6 +241,28 @@ export const descriptors = Object.freeze([
|
|
|
207
241
|
descriptor('watchReply', [id, parameter('turnIndex', parsePosition), version], replyUpdate, true),
|
|
208
242
|
])
|
|
209
243
|
|
|
244
|
+
function parseThreadEvent(value) {
|
|
245
|
+
if (value?.kind === 'snapshot') {
|
|
246
|
+
object(value, ['kind', 'detail'])
|
|
247
|
+
return { kind: 'snapshot', detail: parseDetail(value.detail) }
|
|
248
|
+
}
|
|
249
|
+
object(value, ['kind', 'version', 'updatedAt', 'firstTurn', 'reply', 'turns'])
|
|
250
|
+
checked(value.kind, value.kind === 'change', 'thread event kind')
|
|
251
|
+
checked(value.turns, Array.isArray(value.turns), 'added turns')
|
|
252
|
+
const version = parseVersion(value.version)
|
|
253
|
+
const updatedAt = timestamp(value.updatedAt)
|
|
254
|
+
const firstTurn = parsePosition(value.firstTurn)
|
|
255
|
+
const event = { kind: 'change', version, updatedAt, firstTurn, turns: value.turns.map(parseTurn) }
|
|
256
|
+
if (value.reply !== undefined) {
|
|
257
|
+
object(value.reply, replyFields)
|
|
258
|
+
event.reply = parseReply(value.reply)
|
|
259
|
+
}
|
|
260
|
+
return event
|
|
261
|
+
}
|
|
262
|
+
|
|
210
263
|
export const contextDescriptor = descriptor('contextCapacity', [id], codec(`${PACKAGE_NAME}#ContextWindow`, parseContext))
|
|
211
|
-
export const
|
|
264
|
+
export const threadDescriptor = descriptor('watchThread', [id], codec(`${PACKAGE_NAME}#ThreadEvent`, parseThreadEvent), true)
|
|
265
|
+
export const submitCreateDescriptor = descriptor('submitCreate', [question, parameter('submissionId', parseSubmissionId)], detail)
|
|
266
|
+
export const submitFollowupDescriptor = descriptor('submitFollowup', [id, question, parameter('submissionId', parseSubmissionId)], receipt)
|
|
267
|
+
export const TYPERT_REMOTE = Object.freeze({ package: PACKAGE_NAME, descriptors: Object.freeze([...descriptors, contextDescriptor, threadDescriptor, submitFollowupDescriptor, submitCreateDescriptor]) })
|
|
212
268
|
export const createBtwContribution = () => TYPERT_REMOTE
|