@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,180 @@
1
+ import { randomUUID } from 'node:crypto'
2
+ import { renameSync, unlinkSync } from 'node:fs'
3
+ import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
4
+ import { createRequire } from 'node:module'
5
+ import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
6
+ import { PACKAGE_NAME, parseThreadId } from '../shared/wire.js'
7
+
8
+ const { version } = createRequire(import.meta.url)('../../package.json')
9
+ const INLINE_SCHEMA_VERSION = 1
10
+ const SCHEMA_VERSION = 2
11
+ const releaseDirectory = /^v\d+\.\d+\.\d+$/u
12
+
13
+ async function listDirectory(directory) {
14
+ try {
15
+ return await readdir(directory, { withFileTypes: true })
16
+ } catch (error) {
17
+ if (error?.code !== 'ENOENT') throw error
18
+ return []
19
+ }
20
+ }
21
+
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) {
73
+ return {
74
+ async open(sessionId, signal) {
75
+ const snapshot = await persistence.stat(sessionId, { signal })
76
+ signal.throwIfAborted()
77
+ const location = snapshot?.location
78
+ if (location?.kind !== 'jsonl' || !location.path || !isAbsolute(location.path)) return undefined
79
+
80
+ const sessionDirectory = dirname(location.path)
81
+ const directoryInfo = await stat(sessionDirectory).catch(error => {
82
+ if (error.code !== 'ENOENT') throw error
83
+ })
84
+ if (!directoryInfo?.isDirectory()) return undefined
85
+ const root = join(sessionDirectory, 'plugins', PACKAGE_NAME)
86
+ const records = []
87
+ const files = new Map()
88
+ for (const release of await listDirectory(root)) {
89
+ if (!release.isDirectory() || !releaseDirectory.test(release.name)) continue
90
+ const directory = join(root, release.name, 'threads')
91
+ for (const entry of await listDirectory(directory)) {
92
+ if (!entry.isFile() || !entry.name.endsWith('.json')) continue
93
+ const file = join(directory, entry.name)
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
+ }
124
+ if (record.sessionId !== sessionId) continue
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 })
130
+ records.push(record)
131
+ }
132
+ }
133
+ signal.throwIfAborted()
134
+ return {
135
+ records,
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()
153
+ const id = parseThreadId(record.id)
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)
160
+ }
161
+ try {
162
+ await replaceArchiveFile(sessionDirectory, file, { schemaVersion: SCHEMA_VERSION, record }, ownerSignal)
163
+ } catch (error) {
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
+ }
173
+ throw error
174
+ }
175
+ if (!existing?.hasSnapshot) files.set(id, { file, hasSnapshot: true })
176
+ },
177
+ }
178
+ },
179
+ }
180
+ }
@@ -0,0 +1,9 @@
1
+ import { PACKAGE_NAME, descriptors } from '../shared/wire.js'
2
+
3
+ export const TYPERT = Object.freeze({
4
+ package: PACKAGE_NAME,
5
+ face: 'host',
6
+ schemas: [],
7
+ model: { services: [], events: [], objects: [] },
8
+ invocations: descriptors,
9
+ })
@@ -0,0 +1,268 @@
1
+ export const PACKAGE_NAME = '@kabxx/dsh-btw'
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
+ })
12
+ const STATUSES = new Set(['generating', 'completed', 'failed', 'interrupted'])
13
+ export const TOKEN_FIELDS = ['inputTokens', 'outputTokens', 'totalTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']
14
+ const THREAD_ID = /^btw-[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/u
15
+
16
+ function checked(value, condition, field) {
17
+ if (!condition) throw new TypeError(`Invalid BTW ${field}`)
18
+ return value
19
+ }
20
+
21
+ export function parseSessionId(value) {
22
+ return checked(value, typeof value === 'string' && value.length > 0, 'sessionId')
23
+ }
24
+
25
+ export function parseThreadId(value) {
26
+ return checked(value, typeof value === 'string' && THREAD_ID.test(value), 'id')
27
+ }
28
+
29
+ export function parseQuestion(value) {
30
+ return checked(value, typeof value === 'string' && value.trim() !== '', 'question')
31
+ }
32
+
33
+ export function parseSubmissionId(value) {
34
+ return checked(value, typeof value === 'string' && /^[\da-f]{32}$/u.test(value), 'submissionId')
35
+ }
36
+
37
+ export function parseVersion(value) {
38
+ return checked(value, Number.isSafeInteger(value) && value >= 1, 'version')
39
+ }
40
+
41
+ function timestamp(value) {
42
+ return checked(value, Number.isSafeInteger(value) && value >= 0, 'timestamp')
43
+ }
44
+
45
+ function object(value, fields) {
46
+ return checked(value, value !== null && typeof value === 'object' && !Array.isArray(value)
47
+ && [null, Object.prototype].includes(Object.getPrototypeOf(value))
48
+ && Object.keys(value).every(key => fields.includes(key)), 'record shape')
49
+ }
50
+
51
+ function common(value) {
52
+ return {
53
+ id: parseThreadId(value.id),
54
+ sessionId: parseSessionId(value.sessionId),
55
+ question: parseQuestion(value.question),
56
+ createdAt: timestamp(value.createdAt),
57
+ updatedAt: timestamp(value.updatedAt),
58
+ version: parseVersion(value.version),
59
+ }
60
+ }
61
+
62
+ const commonFields = ['id', 'sessionId', 'question', 'createdAt', 'updatedAt', 'version']
63
+
64
+ function status(value) {
65
+ return checked(value, STATUSES.has(value), 'status')
66
+ }
67
+
68
+ function parseUsage(usage) {
69
+ object(usage, TOKEN_FIELDS)
70
+ return Object.fromEntries(Object.entries(usage).map(([key, value]) => [key, parsePosition(value)]))
71
+ }
72
+
73
+ function parseTiming(value) {
74
+ object(value, ['requestMs', 'firstTokenMs'])
75
+ const requestMs = timestamp(value.requestMs)
76
+ if (value.firstTokenMs === undefined) return { requestMs }
77
+ const firstTokenMs = timestamp(value.firstTokenMs)
78
+ return checked({ requestMs, firstTokenMs }, firstTokenMs <= requestMs, 'first token timing')
79
+ }
80
+
81
+ function parseOutputLimit(value) {
82
+ return checked(value.outputLimitReached, value.outputLimitReached === true && value.status === 'completed', 'output limit')
83
+ }
84
+
85
+ export function parseTurn(value) {
86
+ object(value, ['question', 'reply', 'status', 'createdAt', 'finishedAt', 'error', 'saveError', 'outputLimitReached', 'usage', 'timing'])
87
+ const turn = {
88
+ question: parseQuestion(value.question),
89
+ reply: checked(value.reply, typeof value.reply === 'string', 'reply'),
90
+ status: status(value.status),
91
+ createdAt: timestamp(value.createdAt),
92
+ }
93
+ if (turn.status !== 'generating') turn.finishedAt = timestamp(value.finishedAt)
94
+ else checked(value.finishedAt, value.finishedAt === undefined, 'finishedAt')
95
+ if (value.error !== undefined) turn.error = checked(value.error, typeof value.error === 'string', 'error')
96
+ if (value.saveError !== undefined) turn.saveError = checked(value.saveError, typeof value.saveError === 'string', 'saveError')
97
+ if (value.outputLimitReached !== undefined) turn.outputLimitReached = parseOutputLimit(value)
98
+ if (value.usage !== undefined) turn.usage = parseUsage(value.usage)
99
+ if (value.timing !== undefined) turn.timing = parseTiming(value.timing)
100
+ return turn
101
+ }
102
+
103
+ export function parseDetail(value) {
104
+ object(value, [...commonFields, 'turns'])
105
+ checked(value.turns, Array.isArray(value.turns) && value.turns.length > 0, 'turns')
106
+ return { ...common(value), turns: value.turns.map(parseTurn) }
107
+ }
108
+
109
+ function parseContext(value) {
110
+ object(value, ['contextWindow', 'estimatedTokens'])
111
+ const capacity = value.contextWindow
112
+ const contextWindow = checked(capacity, capacity === null || (Number.isSafeInteger(capacity) && capacity > 0), 'contextWindow')
113
+ return { contextWindow,
114
+ ...(value.estimatedTokens !== undefined && { estimatedTokens: parsePosition(value.estimatedTokens) }),
115
+ }
116
+ }
117
+
118
+ function parseSummaries(values) {
119
+ checked(values, Array.isArray(values), 'summaries')
120
+ return values.map(value => {
121
+ object(value, [...commonFields, 'status'])
122
+ return { ...common(value), status: status(value.status) }
123
+ })
124
+ }
125
+
126
+ function codec(typeSymbol, parse) {
127
+ return Object.freeze({ mode: 'strict', typeSymbol, create: () => ({ parse }) })
128
+ }
129
+
130
+ function parsePosition(value) {
131
+ return checked(value, Number.isSafeInteger(value) && value >= 0, 'position')
132
+ }
133
+
134
+ export function applyReply(detail, turnIndex, update) {
135
+ const turn = detail.turns[turnIndex]
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')
139
+ const turns = [...detail.turns]
140
+ turns[turnIndex] = {
141
+ ...previous, reply: turn.reply.slice(0, update.offset) + update.text, status: update.status,
142
+ ...(update.finishedAt !== undefined && { finishedAt: update.finishedAt }),
143
+ ...(update.error !== undefined && { error: update.error }),
144
+ ...(update.outputLimitReached !== undefined && { outputLimitReached: update.outputLimitReached }),
145
+ ...(update.saveError !== undefined && { saveError: update.saveError }),
146
+ ...(update.usage !== undefined && { usage: update.usage }),
147
+ ...(update.timing !== undefined && { timing: update.timing }),
148
+ }
149
+ return { ...detail, updatedAt: update.updatedAt, version: update.version, turns }
150
+ }
151
+
152
+ function parseReceipt(value) {
153
+ object(value, ['id', 'sessionId', 'updatedAt', 'version', 'turnIndex', 'turn'])
154
+ return {
155
+ id: parseThreadId(value.id), sessionId: parseSessionId(value.sessionId), updatedAt: timestamp(value.updatedAt),
156
+ version: parseVersion(value.version), turnIndex: parsePosition(value.turnIndex), turn: parseTurn(value.turn),
157
+ }
158
+ }
159
+
160
+ const replyFields = ['offset', 'text', 'status', 'finishedAt', 'error', 'saveError', 'outputLimitReached', 'usage', 'timing']
161
+
162
+ function parseReply(value) {
163
+ const update = {
164
+ offset: parsePosition(value.offset),
165
+ text: checked(value.text, typeof value.text === 'string', 'text'), status: status(value.status),
166
+ }
167
+ if (update.status !== 'generating') update.finishedAt = timestamp(value.finishedAt)
168
+ else checked(value.finishedAt, value.finishedAt === undefined, 'finishedAt')
169
+ if (value.error !== undefined) update.error = checked(value.error, typeof value.error === 'string', 'error')
170
+ if (value.outputLimitReached !== undefined) update.outputLimitReached = parseOutputLimit(value)
171
+ if (value.saveError !== undefined) update.saveError = checked(value.saveError, typeof value.saveError === 'string', 'saveError')
172
+ if (value.usage !== undefined) update.usage = parseUsage(value.usage)
173
+ if (value.timing !== undefined) update.timing = parseTiming(value.timing)
174
+ return update
175
+ }
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
+
195
+ const detail = codec(`${PACKAGE_NAME}#Detail`, parseDetail)
196
+ const receipt = codec(`${PACKAGE_NAME}#FollowupReceipt`, parseReceipt)
197
+ const replyUpdate = codec(`${PACKAGE_NAME}#ReplyUpdate`, parseReplyUpdate)
198
+ const summaryList = codec(`${PACKAGE_NAME}#SummaryList`, parseSummaries)
199
+ const agent = Object.freeze({
200
+ name: 'agent',
201
+ wire: 'agentId',
202
+ source: 'lookup',
203
+ lookup: 'agent',
204
+ codec: codec('@deepseek-ai/dsh-session/types#SessionId', parseSessionId),
205
+ })
206
+
207
+ function parameter(name, parse, acceptsUndefined) {
208
+ return Object.freeze({
209
+ name,
210
+ wire: name,
211
+ source: 'json',
212
+ codec: codec(`${PACKAGE_NAME}#${name}`, parse),
213
+ ...(acceptsUndefined ? { acceptsUndefined: true } : {}),
214
+ })
215
+ }
216
+
217
+ const id = parameter('id', parseThreadId)
218
+ const question = parameter('question', parseQuestion)
219
+ const version = parameter('version', value => value == null ? undefined : parseVersion(value), true)
220
+
221
+ function descriptor(method, parameters, result, stream = false) {
222
+ return Object.freeze({
223
+ id: `${PACKAGE_NAME}#btw/${method}`,
224
+ service: 'btw',
225
+ namespace: 'btw',
226
+ method,
227
+ invocation: { kind: 'direct' },
228
+ parameters: Object.freeze([agent, ...parameters]),
229
+ cancellation: { parameter: 'signal' },
230
+ result,
231
+ ...(stream ? { mode: 'stream' } : {}),
232
+ })
233
+ }
234
+
235
+ export const descriptors = Object.freeze([
236
+ descriptor('create', [question], detail),
237
+ descriptor('list', [], summaryList),
238
+ descriptor('get', [id], detail),
239
+ descriptor('followup', [id, question], receipt),
240
+ descriptor('watch', [id, version], detail, true),
241
+ descriptor('watchReply', [id, parameter('turnIndex', parsePosition), version], replyUpdate, true),
242
+ ])
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
+
263
+ export const contextDescriptor = descriptor('contextCapacity', [id], codec(`${PACKAGE_NAME}#ContextWindow`, parseContext))
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]) })
268
+ export const createBtwContribution = () => TYPERT_REMOTE