@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.
@@ -1,11 +1,13 @@
1
1
  import { randomUUID } from 'node:crypto'
2
- import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises'
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 SCHEMA_VERSION = 1
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
- export function sessionThreadStore(persistence, parseRecord) {
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
- const envelope = JSON.parse(await readFile(file, { encoding: 'utf8', signal }))
43
- if (envelope.schemaVersion !== SCHEMA_VERSION) continue
44
- const record = parseRecord(envelope.record)
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)) throw new Error('Invalid BTW thread archive')
47
- files.set(record.id, file)
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 put(record) {
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 file = files.get(id) ?? join(root, `v${version}`, 'threads', `${id}.json`)
57
- let directory = sessionDirectory
58
- for (const part of relative(sessionDirectory, dirname(file)).split(sep)) {
59
- directory = join(directory, part)
60
- // Start below the session root so a removed session cannot be recreated here.
61
- await mkdir(directory, { mode: 0o700 }).catch(error => {
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
- const envelope = { schemaVersion: SCHEMA_VERSION, record }
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
- await unlink(temporary).catch(() => {})
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
  },
@@ -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
- checked(update.offset <= turn.reply.length, 'reply offset')
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
- ...turn, reply: turn.reply.slice(0, update.offset) + update.text, status: update.status,
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
- function parseReplyUpdate(value) {
147
- object(value, ['version', 'updatedAt', 'offset', 'text', 'status', 'finishedAt', 'error', 'saveError', 'usage', 'timing'])
160
+ const replyFields = ['offset', 'text', 'status', 'finishedAt', 'error', 'saveError', 'outputLimitReached', 'usage', 'timing']
161
+
162
+ function parseReply(value) {
148
163
  const update = {
149
- version: parseVersion(value.version), updatedAt: timestamp(value.updatedAt), offset: parsePosition(value.offset),
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 TYPERT_REMOTE = Object.freeze({ package: PACKAGE_NAME, descriptors: Object.freeze([...descriptors, contextDescriptor]) })
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