@qvac/core 1.0.0-rc.5 → 1.0.0-rc.6

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.
Files changed (108) hide show
  1. package/CHANGELOG.md +43 -2
  2. package/README.md +55 -4
  3. package/dist-lib/lib/api/agents.d.ts +2 -1
  4. package/dist-lib/lib/api/agents.js +5 -1
  5. package/dist-lib/lib/api/app-config.d.ts +3 -0
  6. package/dist-lib/lib/api/app-config.js +20 -0
  7. package/dist-lib/lib/api/device-routes.d.ts +1 -1
  8. package/dist-lib/lib/api/device-routes.js +3 -1
  9. package/dist-lib/lib/api/index.js +2 -1
  10. package/dist-lib/lib/api/projects.js +3 -4
  11. package/dist-lib/lib/api/served.d.ts +2 -2
  12. package/dist-lib/lib/api/served.js +24 -1
  13. package/dist-lib/lib/assistant/harness.d.ts +3 -0
  14. package/dist-lib/lib/assistant/history.js +14 -2
  15. package/dist-lib/lib/assistant/message.d.ts +1 -0
  16. package/dist-lib/lib/assistant/model-round.d.ts +3 -0
  17. package/dist-lib/lib/assistant/model-round.js +16 -2
  18. package/dist-lib/lib/assistant/round-host.d.ts +2 -0
  19. package/dist-lib/lib/assistant/round-host.js +8 -0
  20. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  21. package/dist-lib/lib/assistant-tree.js +4 -2
  22. package/dist-lib/lib/assistant.d.ts +11 -1
  23. package/dist-lib/lib/assistant.js +115 -8
  24. package/dist-lib/lib/client.js +4 -1
  25. package/dist-lib/lib/core/agent-copies.js +2 -1
  26. package/dist-lib/lib/core/agent-hosting.js +9 -4
  27. package/dist-lib/lib/core/agent.js +2 -1
  28. package/dist-lib/lib/core/chat-copy.d.ts +1 -0
  29. package/dist-lib/lib/core/chat-copy.js +13 -2
  30. package/dist-lib/lib/core/chat.d.ts +0 -1
  31. package/dist-lib/lib/core/chat.js +0 -3
  32. package/dist-lib/lib/core/collections.d.ts +7 -7
  33. package/dist-lib/lib/core/collections.js +7 -7
  34. package/dist-lib/lib/core/contract/project-device-keys.d.ts +4 -2
  35. package/dist-lib/lib/core/contract/project-device-keys.js +12 -12
  36. package/dist-lib/lib/core/contract/project-host-keys.d.ts +5 -3
  37. package/dist-lib/lib/core/contract/project-host-keys.js +22 -11
  38. package/dist-lib/lib/core/contract/projects.d.ts +4 -2
  39. package/dist-lib/lib/core/contract/projects.js +29 -17
  40. package/dist-lib/lib/core/deleted-agent-runs.d.ts +1 -0
  41. package/dist-lib/lib/core/deleted-agent-runs.js +22 -11
  42. package/dist-lib/lib/core/helpers/index.d.ts +1 -1
  43. package/dist-lib/lib/core/helpers/index.js +2 -2
  44. package/dist-lib/lib/core/mesh.d.ts +1 -0
  45. package/dist-lib/lib/core/mesh.js +4 -4
  46. package/dist-lib/lib/core/project-keys.d.ts +5 -2
  47. package/dist-lib/lib/core/project-keys.js +15 -6
  48. package/dist-lib/lib/core/sync/index.js +5 -5
  49. package/dist-lib/lib/core.d.ts +2 -0
  50. package/dist-lib/lib/core.js +102 -25
  51. package/dist-lib/lib/kv-cache-ledger.d.ts +22 -0
  52. package/dist-lib/lib/kv-cache-ledger.js +72 -0
  53. package/dist-lib/lib/kv-cache-retention.d.ts +1 -0
  54. package/dist-lib/lib/kv-cache-retention.js +5 -2
  55. package/dist-lib/lib/model-memory-cap.d.ts +3 -0
  56. package/dist-lib/lib/model-memory-cap.js +15 -6
  57. package/dist-lib/lib/run-replay.d.ts +3 -2
  58. package/dist-lib/lib/run-replay.js +16 -5
  59. package/dist-lib/lib/run-transcript.js +1 -1
  60. package/dist-lib/schema/engine.js +54 -1
  61. package/dist-lib/schema/qvac.js +62 -1
  62. package/dist-lib/spec/bind.js +3 -0
  63. package/dist-lib/spec/calls.js +1 -0
  64. package/dist-lib/spec/capabilities.d.ts +2 -0
  65. package/dist-lib/spec/hrpc/hrpc.json +13 -0
  66. package/dist-lib/spec/hrpc/index.js +15 -3
  67. package/dist-lib/spec/hrpc/messages.js +253 -3
  68. package/dist-lib/spec/hyperschema/index.js +253 -3
  69. package/dist-lib/spec/hyperschema/schema.json +187 -0
  70. package/dist-lib/spec/hyperschema/types.d.ts +33 -0
  71. package/dist-lib/spec/mesh/hyperdb/db.json +110 -0
  72. package/dist-lib/spec/mesh/hyperdb/index.js +498 -2
  73. package/dist-lib/spec/mesh/hyperdb/messages.js +865 -410
  74. package/dist-lib/spec/mesh/hyperdispatch/messages.js +244 -3
  75. package/dist-lib/spec/mesh/hyperschema/index.js +244 -3
  76. package/dist-lib/spec/mesh/hyperschema/schema.json +155 -0
  77. package/dist-lib/spec/mesh/hyperschema/types.d.ts +37 -0
  78. package/package.json +27 -11
  79. package/tui/README.md +190 -0
  80. package/tui/app.mjs +8247 -0
  81. package/tui/boot.mjs +159 -0
  82. package/tui/index.mjs +89 -0
  83. package/tui/lib/boot-timing.mjs +41 -0
  84. package/tui/lib/busy-words.mjs +116 -0
  85. package/tui/lib/connect-sheet.mjs +350 -0
  86. package/tui/lib/device-target.mjs +64 -0
  87. package/tui/lib/export.mjs +194 -0
  88. package/tui/lib/folders-command.mjs +84 -0
  89. package/tui/lib/fork-command.mjs +43 -0
  90. package/tui/lib/knowledge-command.mjs +190 -0
  91. package/tui/lib/knowledge-import.mjs +153 -0
  92. package/tui/lib/local-path.mjs +21 -0
  93. package/tui/lib/move-command.mjs +17 -0
  94. package/tui/lib/render.mjs +225 -0
  95. package/tui/lib/save-file.mjs +88 -0
  96. package/tui/lib/select.mjs +81 -0
  97. package/tui/lib/selection.mjs +18 -0
  98. package/tui/lib/setup.mjs +135 -0
  99. package/tui/lib/sidebar.mjs +63 -0
  100. package/tui/lib/skill-connect.mjs +145 -0
  101. package/tui/lib/splash-art.mjs +107 -0
  102. package/tui/lib/splash.mjs +18 -0
  103. package/tui/lib/upload-frames.mjs +9 -0
  104. package/tui/lib/usage.mjs +59 -0
  105. package/tui/lib/wrap.mjs +143 -0
  106. package/tui/main.mjs +279 -0
  107. package/tui/plugins.mjs +158 -0
  108. package/worker/assistant-sidecar.mjs +1 -0
@@ -0,0 +1,43 @@
1
+ export const FORK_USAGE = 'usage: /chat fork [turn] [before] · /mesh fork <n|id> [turn] [before]'
2
+
3
+ // `[turn] [before]` to a forkChat cut: turn n is the n-th message, through its answer or before it
4
+ export function forkCut(chunks, args) {
5
+ const [turn, mode, ...extra] = args
6
+ if (!turn) {
7
+ return { request: {}, label: 'every finished turn' }
8
+ }
9
+
10
+ const n = Number(turn)
11
+ if (!Number.isInteger(n) || n < 1 || (mode && mode !== 'before') || extra.length > 0) {
12
+ return { miss: FORK_USAGE }
13
+ }
14
+
15
+ const before = mode === 'before'
16
+ const runId = turnRunId(chunks, { n, before })
17
+ if (!runId) {
18
+ return { miss: `turn ${n} has no answer to fork at` }
19
+ }
20
+
21
+ return {
22
+ request: { runId, exclusive: before },
23
+ label: before ? `everything before turn ${n}` : `through turn ${n}`
24
+ }
25
+ }
26
+
27
+ // a retry answers the same message again, so `through` takes its last answer and `before` its first
28
+ function turnRunId(chunks, { n, before }) {
29
+ const messages = chunks.filter((chunk) => chunk.type === 'user-message' && !chunk.runId)
30
+ const message = messages[n - 1]
31
+ if (!message) {
32
+ return null
33
+ }
34
+
35
+ const next = messages[n]?.seq ?? Infinity
36
+ const answers = chunks.filter(
37
+ (chunk) =>
38
+ chunk.type === 'run-request' && chunk.seq > message.seq && chunk.seq < next && chunk.runId
39
+ )
40
+ const answer = before ? answers[0] : answers.at(-1)
41
+
42
+ return answer?.runId ?? null
43
+ }
@@ -0,0 +1,190 @@
1
+ import b4a from 'b4a'
2
+ import { importKnowledgeDirectory, importKnowledgeFile } from './knowledge-import.mjs'
3
+ import { saveUniqueStream } from './save-file.mjs'
4
+
5
+ const USAGE =
6
+ 'usage: /knowledge [list] · /knowledge add <file> · /knowledge add-dir <directory> · /knowledge download <n|id> · /knowledge remove <n|id>'
7
+
8
+ export async function knowledgeCommand(engine, { chatId, meshId, saveDir }, input) {
9
+ try {
10
+ return { type: 'notice', text: await execute(engine, { chatId, meshId, saveDir }, input) }
11
+ } catch (error) {
12
+ return { type: 'run.error', error }
13
+ }
14
+ }
15
+
16
+ async function execute(engine, { saveDir, ...scope }, input) {
17
+ const { chatId, meshId } = scope
18
+ const { action, argument } = parseInput(input)
19
+ if ((!action || action === 'list') && !argument) {
20
+ const [{ knowledge }, { statuses }] = await Promise.all([
21
+ engine.listKnowledge({ chatId, meshId }),
22
+ engine.listIndexing({ chatId, meshId })
23
+ ])
24
+ return formatKnowledge(sortKnowledge(knowledge ?? []), statuses ?? [])
25
+ }
26
+
27
+ if (action === 'add' || action === 'add-dir') {
28
+ if (!argument) {
29
+ return USAGE
30
+ }
31
+
32
+ if (action === 'add') {
33
+ const added = await importKnowledgeFile(engine, scope, argument)
34
+ return `uploaded ${singleLine(added.fileName)} (${added.byteLength}B) · run /knowledge to track indexing`
35
+ }
36
+
37
+ return formatDirectoryImport(await importKnowledgeDirectory(engine, scope, argument))
38
+ }
39
+
40
+ const [selector, ...extra] = argument.split(/\s+/)
41
+ if ((action !== 'download' && action !== 'remove') || !selector || extra.length) {
42
+ return USAGE
43
+ }
44
+
45
+ const { knowledge } = await engine.listKnowledge({ chatId, meshId })
46
+ const selected = resolveKnowledge(sortKnowledge(knowledge ?? []), selector)
47
+ if (selected.error) {
48
+ return selected.error
49
+ }
50
+
51
+ const row = selected.knowledge
52
+ if (action === 'remove') {
53
+ await engine.removeKnowledge({ knowledgeId: row.id, at: Date.now(), meshId })
54
+ return `removed ${singleLine(row.fileName)} (${row.id.slice(0, 8)})`
55
+ }
56
+
57
+ const saved = await saveUniqueStream(
58
+ frameData(engine.downloadKnowledge({ blobId: row.blobId, meshId })),
59
+ { dir: saveDir, fileName: row.fileName }
60
+ )
61
+ if (saved) {
62
+ return `saved ${singleLine(row.fileName)} (${saved.bytesWritten}B) to ${saved.file}`
63
+ }
64
+
65
+ return `not saved: 100 files named ${singleLine(row.fileName)} already exist in ${saveDir}`
66
+ }
67
+
68
+ function parseInput(input) {
69
+ const value = input.trim()
70
+ const separator = value.search(/\s/)
71
+ if (separator === -1) {
72
+ return { action: value, argument: '' }
73
+ }
74
+
75
+ return {
76
+ action: value.slice(0, separator),
77
+ argument: value.slice(separator).trimStart()
78
+ }
79
+ }
80
+
81
+ function formatDirectoryImport(result) {
82
+ if (!result.added.length && !result.failed.length) {
83
+ return `no supported knowledge files in ${result.directory}`
84
+ }
85
+
86
+ const lines = [
87
+ `uploaded ${result.added.length} knowledge file${result.added.length === 1 ? '' : 's'}`
88
+ ]
89
+ for (const row of result.added) {
90
+ lines.push(` + ${singleLine(row.fileName)} (${row.byteLength}B)`)
91
+ }
92
+
93
+ for (const row of result.failed) {
94
+ lines.push(` ! ${singleLine(row.fileName)} · ${singleLine(row.error)}`)
95
+ }
96
+
97
+ if (result.skipped.length) {
98
+ lines.push(
99
+ ` - skipped ${result.skipped.length} unsupported ${result.skipped.length === 1 ? 'entry' : 'entries'}`
100
+ )
101
+ }
102
+
103
+ if (result.added.length) {
104
+ lines.push('run /knowledge to track indexing')
105
+ }
106
+
107
+ return lines.join('\n')
108
+ }
109
+
110
+ function formatKnowledge(knowledge, statuses) {
111
+ if (!knowledge.length) return 'no knowledge in this chat'
112
+ const byKnowledge = new Map()
113
+ for (const row of statuses) {
114
+ const rows = byKnowledge.get(row.knowledgeId) ?? []
115
+ rows.push(row)
116
+ byKnowledge.set(row.knowledgeId, rows)
117
+ }
118
+
119
+ return knowledge
120
+ .map((row, index) => formatKnowledgeRow(row, index, byKnowledge.get(row.id) ?? []))
121
+ .join('\n')
122
+ }
123
+
124
+ function formatKnowledgeRow(knowledge, index, statuses) {
125
+ const name = singleLine(knowledge.fileName) || '(unnamed)'
126
+ const lines = [`${index + 1}. ${name} (${knowledge.byteLength}B) · ${knowledge.id.slice(0, 8)}`]
127
+ const sorted = [...statuses].sort((a, b) => a.id.localeCompare(b.id))
128
+ if (!sorted.length) {
129
+ lines.push(' - not indexed')
130
+ }
131
+
132
+ for (const row of sorted) {
133
+ lines.push(` - ${formatStatus(row)}`)
134
+ }
135
+
136
+ return lines.join('\n')
137
+ }
138
+
139
+ function formatStatus(row) {
140
+ const status = row.status === 'indexing' && !row.claimLive ? 'expired' : row.status
141
+ let detail = `${status} · artifact ${row.id.slice(0, 8)}`
142
+ if (row.status === 'indexing' && row.claimLive) {
143
+ detail += ` · claimed by ${b4a.toHex(row.claimedBy).slice(0, 8)}`
144
+ }
145
+
146
+ if (row.status === 'failed' && row.error) {
147
+ detail += ` · ${singleLine(row.error)}`
148
+ }
149
+
150
+ return detail
151
+ }
152
+
153
+ function sortKnowledge(rows) {
154
+ return [...rows].sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id))
155
+ }
156
+
157
+ function resolveKnowledge(rows, selector) {
158
+ const exact = rows.find((row) => row.id === selector)
159
+ if (exact) {
160
+ return { knowledge: exact }
161
+ }
162
+
163
+ if (/^\d+$/.test(selector)) {
164
+ const index = Number(selector) - 1
165
+ return rows[index] ? { knowledge: rows[index] } : { error: `no knowledge #${selector}` }
166
+ }
167
+
168
+ const matches = rows.filter((row) => row.id.startsWith(selector))
169
+ if (matches.length === 1) {
170
+ return { knowledge: matches[0] }
171
+ }
172
+
173
+ if (matches.length > 1) {
174
+ return { error: `ambiguous knowledge id: ${selector}` }
175
+ }
176
+
177
+ return { error: `no knowledge matching: ${selector}` }
178
+ }
179
+
180
+ function singleLine(value) {
181
+ return String(value).replace(/\s+/g, ' ').trim()
182
+ }
183
+
184
+ async function* frameData(frames) {
185
+ for await (const frame of frames) {
186
+ if (frame.data) {
187
+ yield frame.data
188
+ }
189
+ }
190
+ }
@@ -0,0 +1,153 @@
1
+ import fs from 'fs'
2
+ import path from 'path'
3
+ import { RAG_ACCEPT_EXTENSIONS } from 'rag-extract'
4
+ import { resolveLocalPath } from './local-path.mjs'
5
+ import { UPLOAD_FRAME_BYTES, writeFrame } from './upload-frames.mjs'
6
+ import { errorMessage } from '../../dist-lib/lib/guards.js'
7
+ const ACCEPTED = new Set(RAG_ACCEPT_EXTENSIONS)
8
+ const MIME_TYPES = new Map([
9
+ ['.pdf', 'application/pdf'],
10
+ ['.txt', 'text/plain'],
11
+ ['.md', 'text/markdown'],
12
+ ['.markdown', 'text/markdown'],
13
+ ['.rtf', 'application/rtf'],
14
+ ['.html', 'text/html'],
15
+ ['.htm', 'text/html'],
16
+ ['.xhtml', 'application/xhtml+xml'],
17
+ ['.log', 'text/plain'],
18
+ ['.json', 'application/json'],
19
+ ['.jsonl', 'application/x-ndjson'],
20
+ ['.csv', 'text/csv'],
21
+ ['.tsv', 'text/tab-separated-values'],
22
+ ['.xml', 'application/xml'],
23
+ ['.yaml', 'application/yaml'],
24
+ ['.yml', 'application/yaml'],
25
+ // accepted everywhere: a device without the engine waits for a peer to publish the index
26
+ ['.docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
27
+ ['.doc', 'application/msword'],
28
+ ['.odt', 'application/vnd.oasis.opendocument.text']
29
+ ])
30
+
31
+ export async function importKnowledgeFile(engine, scope, inputPath) {
32
+ const file = resolveLocalPath(inputPath)
33
+ const stat = await fs.promises.stat(file)
34
+ if (!stat.isFile()) {
35
+ throw new Error(`not a file: ${file}`)
36
+ }
37
+
38
+ if (!supported(file)) {
39
+ throw new Error(`unsupported knowledge file: ${path.basename(file)}`)
40
+ }
41
+
42
+ return upload(engine, file, { ...scope, byteLength: stat.size })
43
+ }
44
+
45
+ export async function importKnowledgeDirectory(engine, scope, inputPath) {
46
+ const directory = resolveLocalPath(inputPath)
47
+ const stat = await fs.promises.stat(directory)
48
+ if (!stat.isDirectory()) {
49
+ throw new Error(`not a directory: ${directory}`)
50
+ }
51
+
52
+ const added = []
53
+ const failed = []
54
+ const skipped = []
55
+ const names = (await fs.promises.readdir(directory)).sort()
56
+ for (const name of names) {
57
+ const file = path.join(directory, name)
58
+ let fileStat
59
+ try {
60
+ fileStat = await fs.promises.lstat(file)
61
+ } catch (error) {
62
+ failed.push({ fileName: name, error: errorMessage(error) })
63
+ continue
64
+ }
65
+
66
+ if (!fileStat.isFile() || !supported(file)) {
67
+ skipped.push(name)
68
+ continue
69
+ }
70
+
71
+ try {
72
+ added.push(await upload(engine, file, { ...scope, byteLength: fileStat.size }))
73
+ } catch (error) {
74
+ failed.push({ fileName: name, error: errorMessage(error) })
75
+ }
76
+ }
77
+
78
+ return { directory, added, failed, skipped }
79
+ }
80
+
81
+ function supported(file) {
82
+ return ACCEPTED.has(path.extname(file).toLowerCase())
83
+ }
84
+
85
+ async function upload(engine, file, { chatId, meshId, byteLength }) {
86
+ const fileName = path.basename(file)
87
+ const extension = path.extname(file).toLowerCase()
88
+ const stream = engine.uploadKnowledge()
89
+ let responseError = null
90
+ const response = readFinal(stream).catch((error) => {
91
+ responseError = error
92
+ safeDestroy(stream)
93
+
94
+ return null
95
+ })
96
+ const source = fs.createReadStream(file, { highWaterMark: UPLOAD_FRAME_BYTES })
97
+
98
+ try {
99
+ // the first frame names the mesh; the rest carry bytes
100
+ const metadataWritten = await writeFrame(stream, {
101
+ meshId,
102
+ chatId,
103
+ fileName,
104
+ mimeType: MIME_TYPES.get(extension) ?? 'application/octet-stream',
105
+ totalBytes: byteLength
106
+ })
107
+ if (!metadataWritten) {
108
+ throw responseError ?? new Error('knowledge upload closed while writing')
109
+ }
110
+
111
+ for await (const data of source) {
112
+ if (responseError) throw responseError
113
+ const dataWritten = await writeFrame(stream, { data })
114
+ if (!dataWritten) {
115
+ throw responseError ?? new Error('knowledge upload closed while writing')
116
+ }
117
+ }
118
+
119
+ stream.end()
120
+ const final = await response
121
+ if (responseError) {
122
+ throw responseError
123
+ }
124
+
125
+ if (!final?.knowledge) {
126
+ throw new Error('knowledge upload ended without a knowledge row')
127
+ }
128
+
129
+ return { fileName, byteLength, knowledge: final.knowledge }
130
+ } catch (error) {
131
+ source.destroy()
132
+ safeDestroy(stream)
133
+
134
+ throw error
135
+ }
136
+ }
137
+
138
+ async function readFinal(stream) {
139
+ let final = null
140
+ for await (const frame of stream) {
141
+ final = frame
142
+ }
143
+
144
+ return final
145
+ }
146
+
147
+ function safeDestroy(stream) {
148
+ try {
149
+ stream.destroy()
150
+ } catch {
151
+ // Cleanup must not replace the file or transport error.
152
+ }
153
+ }
@@ -0,0 +1,21 @@
1
+ import os from 'os'
2
+ import path from 'path'
3
+ import { fileURLToPath } from 'url'
4
+
5
+ // a path as a person types it: a file:// url, ~ for home, or relative to where duck started
6
+ export function resolveLocalPath(input) {
7
+ const value = input.trim()
8
+ if (value.startsWith('file://')) {
9
+ return fileURLToPath(value)
10
+ }
11
+
12
+ if (value === '~') {
13
+ return os.homedir()
14
+ }
15
+
16
+ if (value.startsWith('~/')) {
17
+ return path.join(os.homedir(), value.slice(2))
18
+ }
19
+
20
+ return path.resolve(value)
21
+ }
@@ -0,0 +1,17 @@
1
+ // what one chatMoveWatch frame tells the person who typed /mesh move
2
+ export function describeMove(move, { title, where }) {
3
+ const short = move.targetMeshId.slice(0, 8)
4
+ if (move.state === 'failed') {
5
+ return `move of "${title}" failed: ${move.failure}`
6
+ }
7
+
8
+ if (move.state === 'carrying') {
9
+ const files = move.waiting?.length ? move.waiting.join(', ') : `${move.files - move.carried}`
10
+ return `"${title}" is in ${short} - waiting on ${files}; the source stays until they arrive, /mesh moved shows progress`
11
+ }
12
+
13
+ const retried = move.restarted ? ' - its running turn is answered again there' : ''
14
+ const settled = move.state === 'complete' ? 'moved' : 'moving'
15
+
16
+ return `${settled} "${title}" to ${short}${retried} - ${where}`
17
+ }
@@ -0,0 +1,225 @@
1
+ import { busyWord } from './busy-words.mjs'
2
+ import b4a from 'b4a'
3
+
4
+ const PAYLOAD_FIELDS = {
5
+ content: 'content',
6
+ thinking: 'thinking',
7
+ 'tool-call': 'toolCall',
8
+ 'tool-result': 'toolResult',
9
+ attachment: 'attachment'
10
+ }
11
+
12
+ // a fold lands after its triggering message (and that message's upload), so the marker goes above
13
+ function foldMarkerIndex(turns) {
14
+ let at = turns.length
15
+ while (at > 0 && turns[at - 1].from === 'agent' && turns[at - 1].segments.length === 0) {
16
+ at--
17
+ }
18
+
19
+ if (at === turns.length || at === 0 || turns[at - 1].from !== 'user') {
20
+ return turns.length
21
+ }
22
+
23
+ at--
24
+ while (at > 0 && turns[at - 1].from === 'user' && isUpload(turns[at - 1])) {
25
+ at--
26
+ }
27
+
28
+ return at
29
+ }
30
+
31
+ function isUpload(turn) {
32
+ return turn.segments.every((segment) => segment.type === 'attachment')
33
+ }
34
+
35
+ export function turnsFromChunks(chunks) {
36
+ const turns = []
37
+ const byRun = new Map()
38
+ for (const chunk of chunks) {
39
+ // a video's sampled frames belong to the video, not to the reply that stored them
40
+ if (chunk.sourceId) {
41
+ continue
42
+ }
43
+
44
+ // purely presentational: lets a renderer label the human side per device
45
+ if (chunk.type === 'user-message') {
46
+ turns.push({
47
+ from: 'user',
48
+ deviceId: chunk.originDeviceId && b4a.toHex(chunk.originDeviceId),
49
+ segments: [{ type: 'user-message', text: chunk.userMessage.text }]
50
+ })
51
+ continue
52
+ }
53
+
54
+ // an attachment a tool produced mid-run has a runId and groups into that run's turn below
55
+ if (chunk.type === 'attachment' && !chunk.runId) {
56
+ turns.push({
57
+ from: 'user',
58
+ deviceId: chunk.originDeviceId && b4a.toHex(chunk.originDeviceId),
59
+ segments: [{ type: 'attachment', detail: chunk.attachment }]
60
+ })
61
+ continue
62
+ }
63
+
64
+ // grouped by its absent runId a fold would be an agent turn that never ends, holding the busy gate
65
+ if (chunk.type === 'compaction') {
66
+ turns.splice(foldMarkerIndex(turns), 0, { from: 'compaction', segments: [] })
67
+ continue
68
+ }
69
+
70
+ let turn = byRun.get(chunk.runId)
71
+ if (!turn) {
72
+ turn = { from: 'agent', runId: chunk.runId, status: null, segments: [] }
73
+ byRun.set(chunk.runId, turn)
74
+ turns.push(turn)
75
+ }
76
+
77
+ // the ask materializes the turn so every peer sees a run in flight before the host even starts
78
+ if (chunk.type === 'run-request') {
79
+ continue
80
+ }
81
+
82
+ if (chunk.type === 'run-status') {
83
+ turn.status = chunk.runStatus.state
84
+ turn.statusReason = chunk.runStatus.reason
85
+ turn.statusDetail = chunk.runStatus
86
+ // stamped by the provider, so progress can be labelled with where it is happening
87
+ turn.statusDeviceId = chunk.originDeviceId && b4a.toHex(chunk.originDeviceId)
88
+ continue
89
+ }
90
+
91
+ // the chunk is the approval state, so it is never coalesced and carries its own id to resolve
92
+ if (chunk.type === 'approval-request') {
93
+ turn.segments.push({ type: 'approval-request', id: chunk.id, detail: chunk.approvalRequest })
94
+ continue
95
+ }
96
+
97
+ // recovery appends a fresh sources chunk on the same run - the newest wins (v1 rule)
98
+ if (chunk.type === 'sources') {
99
+ const stale = turn.segments.findIndex((segment) => segment.type === 'sources')
100
+ if (stale >= 0) {
101
+ turn.segments.splice(stale, 1)
102
+ }
103
+
104
+ turn.segments.push({ type: 'sources', detail: chunk.sources })
105
+ continue
106
+ }
107
+
108
+ const detail = chunk[PAYLOAD_FIELDS[chunk.type]] ?? {}
109
+ const last = turn.segments[turn.segments.length - 1]
110
+ if (last && last.type === chunk.type) {
111
+ last.text += detail.text ?? ''
112
+ } else {
113
+ turn.segments.push({
114
+ type: chunk.type,
115
+ text: detail.text ?? '',
116
+ detail
117
+ })
118
+ }
119
+ }
120
+
121
+ return turns
122
+ }
123
+
124
+ // the harness's loop blocks on an approval, so at most one is live at a time
125
+ export function findPendingApproval(turns) {
126
+ for (let i = turns.length - 1; i >= 0; i--) {
127
+ for (const segment of turns[i].segments) {
128
+ if (segment.type === 'approval-request' && segment.detail.status === 'pending') {
129
+ return segment
130
+ }
131
+ }
132
+ }
133
+
134
+ return null
135
+ }
136
+
137
+ export function runningAgentTurn(turns) {
138
+ for (let i = turns.length - 1; i >= 0; i--) {
139
+ const turn = turns[i]
140
+ if (turn.from === 'agent' && turn.status === 'executing') {
141
+ return turn
142
+ }
143
+ }
144
+
145
+ return null
146
+ }
147
+
148
+ const TERMINAL_RUN_STATES = new Set(['completed', 'failed', 'canceled'])
149
+
150
+ export function turnDone(turn) {
151
+ return TERMINAL_RUN_STATES.has(turn.status)
152
+ }
153
+
154
+ export function runInFlight(turns) {
155
+ for (let i = turns.length - 1; i >= 0; i--) {
156
+ if (turns[i].from !== 'agent') continue
157
+ return !TERMINAL_RUN_STATES.has(turns[i].status)
158
+ }
159
+
160
+ return false
161
+ }
162
+
163
+ function awaitingDownloadText(model, runTurn, { selfId, downloads }) {
164
+ const row = selfId !== '' && runTurn.statusDeviceId === selfId ? downloads.get(model) : null
165
+ if (row?.phase === 'held') {
166
+ return `waiting for ${model} - /models download ${model}`
167
+ }
168
+
169
+ if (row?.phase === 'downloading') {
170
+ return `downloading ${model}: ${row.percentage ?? 0}%`
171
+ }
172
+
173
+ return `waiting for ${model} to be downloaded`
174
+ }
175
+
176
+ export function busyStatus(
177
+ modelState,
178
+ runTurn,
179
+ { elapsed = Infinity, selfId = '', downloads = new Map() } = {}
180
+ ) {
181
+ if (modelState?.status === 'loading') {
182
+ return { text: `loading ${modelState.model}…`, on: 'local' }
183
+ }
184
+
185
+ if (modelState?.status === 'downloading') {
186
+ return {
187
+ text: `downloading ${modelState.model}: ${Math.round(modelState.percentage ?? 0)}%`,
188
+ on: 'local'
189
+ }
190
+ }
191
+
192
+ if (modelState?.status === 'unloading') {
193
+ return { text: `unloading ${modelState.model}…`, on: 'local' }
194
+ }
195
+
196
+ const progress = runTurn?.statusDetail?.progress
197
+ if (progress?.phase === 'loading') {
198
+ return { text: `loading ${progress.model}…`, on: 'host' }
199
+ }
200
+
201
+ if (progress?.phase === 'downloading') {
202
+ return { text: `downloading ${progress.model}: ${progress.percentage ?? 0}%`, on: 'host' }
203
+ }
204
+
205
+ if (progress?.phase === 'generating') {
206
+ return { text: `generating image: ${progress.percentage ?? 0}%`, on: 'host' }
207
+ }
208
+
209
+ if (progress?.phase === 'queued') {
210
+ return { text: `queued - agent busy in ${progress.busyChatId}`, on: 'host' }
211
+ }
212
+
213
+ if (progress?.phase === 'awaiting-download') {
214
+ return {
215
+ text: awaitingDownloadText(progress.model, runTurn, { selfId, downloads }),
216
+ on: 'host'
217
+ }
218
+ }
219
+
220
+ if (progress?.phase === 'compacting') {
221
+ return { text: 'compacting conversation…', on: 'host' }
222
+ }
223
+
224
+ return { text: busyWord(runTurn?.runId, elapsed), on: null }
225
+ }