@qvac/core 1.0.0-rc.2 → 1.0.0-rc.3

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 (195) hide show
  1. package/CHANGELOG.md +158 -2
  2. package/dist-lib/index.d.ts +1 -0
  3. package/dist-lib/index.js +1 -0
  4. package/dist-lib/lib/api/chunk-delta.d.ts +7 -2
  5. package/dist-lib/lib/api/chunk-delta.js +89 -7
  6. package/dist-lib/lib/api/chunks.js +14 -8
  7. package/dist-lib/lib/api/config.d.ts +4 -1
  8. package/dist-lib/lib/api/config.js +45 -4
  9. package/dist-lib/lib/api/custom-models.js +3 -5
  10. package/dist-lib/lib/api/devices.js +3 -1
  11. package/dist-lib/lib/api/files.d.ts +1 -1
  12. package/dist-lib/lib/api/files.js +65 -8
  13. package/dist-lib/lib/api/instrument.js +12 -4
  14. package/dist-lib/lib/api/members.js +7 -13
  15. package/dist-lib/lib/api/mesh.d.ts +1 -3
  16. package/dist-lib/lib/api/mesh.js +2 -2
  17. package/dist-lib/lib/api/notifications.js +8 -4
  18. package/dist-lib/lib/api/projects.js +5 -1
  19. package/dist-lib/lib/api/rag.js +32 -19
  20. package/dist-lib/lib/api/served.js +2 -1
  21. package/dist-lib/lib/api/workspace.js +0 -1
  22. package/dist-lib/lib/assistant/harness.d.ts +8 -2
  23. package/dist-lib/lib/assistant/harness.js +17 -4
  24. package/dist-lib/lib/assistant/history.d.ts +1 -1
  25. package/dist-lib/lib/assistant/history.js +19 -13
  26. package/dist-lib/lib/assistant/message.d.ts +6 -1
  27. package/dist-lib/lib/assistant/message.js +22 -2
  28. package/dist-lib/lib/assistant/model-round.d.ts +5 -0
  29. package/dist-lib/lib/assistant/model-round.js +46 -18
  30. package/dist-lib/lib/assistant/pdf-budget.d.ts +10 -2
  31. package/dist-lib/lib/assistant/pdf-budget.js +10 -11
  32. package/dist-lib/lib/assistant/pdf-pages.d.ts +25 -0
  33. package/dist-lib/lib/assistant/pdf-pages.js +75 -0
  34. package/dist-lib/lib/assistant/round-host.js +5 -3
  35. package/dist-lib/lib/assistant-client.d.ts +2 -1
  36. package/dist-lib/lib/assistant-client.js +24 -6
  37. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  38. package/dist-lib/lib/assistant-tree.js +8 -5
  39. package/dist-lib/lib/assistant.d.ts +20 -7
  40. package/dist-lib/lib/assistant.js +468 -240
  41. package/dist-lib/lib/client.js +10 -1
  42. package/dist-lib/lib/compaction.d.ts +3 -1
  43. package/dist-lib/lib/compaction.js +18 -4
  44. package/dist-lib/lib/constants.d.ts +3 -0
  45. package/dist-lib/lib/constants.js +3 -0
  46. package/dist-lib/lib/core/chat-activity.js +13 -16
  47. package/dist-lib/lib/core/chat-copy.js +1 -1
  48. package/dist-lib/lib/core/chat-fork.js +2 -1
  49. package/dist-lib/lib/core/chat-move.d.ts +4 -0
  50. package/dist-lib/lib/core/chat-move.js +42 -11
  51. package/dist-lib/lib/core/chat.d.ts +0 -1
  52. package/dist-lib/lib/core/chat.js +1 -1
  53. package/dist-lib/lib/core/chunk.d.ts +14 -3
  54. package/dist-lib/lib/core/chunk.js +112 -22
  55. package/dist-lib/lib/core/collections.d.ts +12 -1
  56. package/dist-lib/lib/core/collections.js +12 -1
  57. package/dist-lib/lib/core/config-value.d.ts +6 -0
  58. package/dist-lib/lib/core/config-value.js +14 -0
  59. package/dist-lib/lib/core/contract/activity.d.ts +3 -2
  60. package/dist-lib/lib/core/contract/activity.js +39 -21
  61. package/dist-lib/lib/core/contract/agent-join.js +15 -19
  62. package/dist-lib/lib/core/contract/agents.js +8 -7
  63. package/dist-lib/lib/core/contract/chat.d.ts +3 -0
  64. package/dist-lib/lib/core/contract/chat.js +12 -1
  65. package/dist-lib/lib/core/contract/chunks.js +16 -6
  66. package/dist-lib/lib/core/contract/devices.js +6 -4
  67. package/dist-lib/lib/core/contract/index.js +2 -1
  68. package/dist-lib/lib/core/contract/invites.js +12 -31
  69. package/dist-lib/lib/core/contract/joined-meshes.js +2 -1
  70. package/dist-lib/lib/core/contract/mesh-rules.js +4 -0
  71. package/dist-lib/lib/core/contract/model-requests.js +7 -6
  72. package/dist-lib/lib/core/contract/project-device-keys.js +15 -6
  73. package/dist-lib/lib/core/contract/project-host-keys.js +5 -4
  74. package/dist-lib/lib/core/contract/projects.js +12 -13
  75. package/dist-lib/lib/core/contract/public-seeds.js +5 -5
  76. package/dist-lib/lib/core/contract/roles.js +2 -1
  77. package/dist-lib/lib/core/contract/run-requests.d.ts +1 -1
  78. package/dist-lib/lib/core/contract/run-requests.js +19 -13
  79. package/dist-lib/lib/core/contract/shipped-rows.d.ts +2 -0
  80. package/dist-lib/lib/core/contract/shipped-rows.js +22 -0
  81. package/dist-lib/lib/core/contract/workspace.js +4 -10
  82. package/dist-lib/lib/core/contract/writers.js +20 -6
  83. package/dist-lib/lib/core/devices.d.ts +2 -1
  84. package/dist-lib/lib/core/devices.js +4 -2
  85. package/dist-lib/lib/core/document-attachment.d.ts +6 -3
  86. package/dist-lib/lib/core/document-attachment.js +10 -5
  87. package/dist-lib/lib/core/files/attachments.js +3 -3
  88. package/dist-lib/lib/core/files/index.d.ts +8 -5
  89. package/dist-lib/lib/core/files/index.js +109 -18
  90. package/dist-lib/lib/core/files/processing/index.d.ts +1 -1
  91. package/dist-lib/lib/core/files/processing/index.js +8 -2
  92. package/dist-lib/lib/core/files/processing/source.d.ts +1 -0
  93. package/dist-lib/lib/core/files/processing/source.js +3 -0
  94. package/dist-lib/lib/core/files/processing/state.d.ts +1 -0
  95. package/dist-lib/lib/core/files/processing/state.js +7 -0
  96. package/dist-lib/lib/core/files/rag/build.d.ts +1 -0
  97. package/dist-lib/lib/core/files/rag/build.js +14 -1
  98. package/dist-lib/lib/core/files/rag/index.d.ts +1 -1
  99. package/dist-lib/lib/core/files/rag/index.js +1 -1
  100. package/dist-lib/lib/core/files/rag/produce.js +1 -0
  101. package/dist-lib/lib/core/files/rag/retrieval/full-text.d.ts +2 -0
  102. package/dist-lib/lib/core/files/rag/retrieval/full-text.js +7 -1
  103. package/dist-lib/lib/core/first-event.d.ts +6 -0
  104. package/dist-lib/lib/core/first-event.js +13 -0
  105. package/dist-lib/lib/core/invite.d.ts +2 -2
  106. package/dist-lib/lib/core/invite.js +5 -4
  107. package/dist-lib/lib/core/local/index.d.ts +10 -1
  108. package/dist-lib/lib/core/local/index.js +105 -10
  109. package/dist-lib/lib/core/mesh.d.ts +15 -4
  110. package/dist-lib/lib/core/mesh.js +128 -57
  111. package/dist-lib/lib/core/migrations/chat-chunks.d.ts +4 -0
  112. package/dist-lib/lib/core/migrations/chat-chunks.js +47 -0
  113. package/dist-lib/lib/core/migrations/file-index.d.ts +1 -1
  114. package/dist-lib/lib/core/migrations/file-index.js +6 -2
  115. package/dist-lib/lib/core/migrations/index.d.ts +2 -1
  116. package/dist-lib/lib/core/migrations/index.js +66 -9
  117. package/dist-lib/lib/core/notification.js +96 -23
  118. package/dist-lib/lib/core/pdf/figure.d.ts +22 -0
  119. package/dist-lib/lib/core/pdf/figure.js +64 -0
  120. package/dist-lib/lib/core/pdf/rasterize.d.ts +10 -1
  121. package/dist-lib/lib/core/pdf/rasterize.js +72 -22
  122. package/dist-lib/lib/core/peer-duplex.js +57 -5
  123. package/dist-lib/lib/core/public-mesh.js +8 -2
  124. package/dist-lib/lib/core/run-requests.js +2 -3
  125. package/dist-lib/lib/core/senders.d.ts +7 -6
  126. package/dist-lib/lib/core/senders.js +23 -30
  127. package/dist-lib/lib/core/shared-agents.d.ts +1 -0
  128. package/dist-lib/lib/core/shared-agents.js +47 -19
  129. package/dist-lib/lib/core/sync/background.d.ts +3 -15
  130. package/dist-lib/lib/core/sync/background.js +25 -102
  131. package/dist-lib/lib/core/sync/devices.js +6 -3
  132. package/dist-lib/lib/core/sync/index.js +12 -2
  133. package/dist-lib/lib/core/sync-status.js +3 -3
  134. package/dist-lib/lib/core.d.ts +59 -10
  135. package/dist-lib/lib/core.js +706 -174
  136. package/dist-lib/lib/credential-pusher.d.ts +11 -7
  137. package/dist-lib/lib/credential-pusher.js +40 -8
  138. package/dist-lib/lib/device-tree.d.ts +18 -0
  139. package/dist-lib/lib/device-tree.js +32 -0
  140. package/dist-lib/lib/doctor/redact.js +1 -1
  141. package/dist-lib/lib/errors.d.ts +4 -0
  142. package/dist-lib/lib/errors.js +4 -0
  143. package/dist-lib/lib/fs-drive-bridge.d.ts +7 -0
  144. package/dist-lib/lib/fs-drive-bridge.js +308 -30
  145. package/dist-lib/lib/integrations/setup-routes.js +7 -5
  146. package/dist-lib/lib/knowledge-search.d.ts +1 -1
  147. package/dist-lib/lib/knowledge-search.js +5 -46
  148. package/dist-lib/lib/kv-cache-retention.d.ts +35 -0
  149. package/dist-lib/lib/kv-cache-retention.js +98 -0
  150. package/dist-lib/lib/latest-frame.d.ts +10 -0
  151. package/dist-lib/lib/latest-frame.js +48 -0
  152. package/dist-lib/lib/model-download.d.ts +6 -1
  153. package/dist-lib/lib/model-download.js +32 -17
  154. package/dist-lib/lib/oauth/resolve.js +13 -5
  155. package/dist-lib/lib/reconnecting-watch.js +19 -11
  156. package/dist-lib/lib/run-notices.d.ts +2 -0
  157. package/dist-lib/lib/run-notices.js +5 -0
  158. package/dist-lib/lib/run-replay.d.ts +13 -1
  159. package/dist-lib/lib/run-replay.js +58 -21
  160. package/dist-lib/schema/build.js +66 -57
  161. package/dist-lib/schema/content.js +2 -1
  162. package/dist-lib/schema/engine.js +37 -5
  163. package/dist-lib/schema/field-order.js +7 -1
  164. package/dist-lib/schema/indexes.d.ts +4 -0
  165. package/dist-lib/schema/indexes.js +18 -0
  166. package/dist-lib/schema/local.js +9 -2
  167. package/dist-lib/schema/qvac.js +112 -4
  168. package/dist-lib/spec/bind.js +3 -0
  169. package/dist-lib/spec/calls.js +1 -0
  170. package/dist-lib/spec/capabilities.d.ts +2 -0
  171. package/dist-lib/spec/hrpc/hrpc.json +13 -0
  172. package/dist-lib/spec/hrpc/index.js +15 -3
  173. package/dist-lib/spec/hrpc/messages.js +1475 -1392
  174. package/dist-lib/spec/hyperschema/index.js +1475 -1392
  175. package/dist-lib/spec/hyperschema/schema.json +86 -1
  176. package/dist-lib/spec/hyperschema/types.d.ts +21 -1
  177. package/dist-lib/spec/local/hyperdb/messages.js +110 -54
  178. package/dist-lib/spec/local/hyperschema/index.js +56 -28
  179. package/dist-lib/spec/local/hyperschema/schema.json +55 -20
  180. package/dist-lib/spec/local/hyperschema/types.d.ts +8 -1
  181. package/dist-lib/spec/mesh/hyperdb/db.json +255 -51
  182. package/dist-lib/spec/mesh/hyperdb/index.js +1063 -404
  183. package/dist-lib/spec/mesh/hyperdb/messages.js +1647 -1214
  184. package/dist-lib/spec/mesh/hyperdispatch/dispatch.json +62 -56
  185. package/dist-lib/spec/mesh/hyperdispatch/index.js +156 -139
  186. package/dist-lib/spec/mesh/hyperdispatch/messages.js +787 -629
  187. package/dist-lib/spec/mesh/hyperschema/index.js +787 -629
  188. package/dist-lib/spec/mesh/hyperschema/schema.json +283 -174
  189. package/dist-lib/spec/mesh/hyperschema/types.d.ts +29 -1
  190. package/package.json +23 -17
  191. package/worker/assistant-sidecar.mjs +3 -0
  192. package/dist-lib/lib/core/files/processing/settle.d.ts +0 -13
  193. package/dist-lib/lib/core/files/processing/settle.js +0 -86
  194. package/dist-lib/lib/core/migrations/device-indexes.d.ts +0 -2
  195. package/dist-lib/lib/core/migrations/device-indexes.js +0 -7
@@ -22,8 +22,8 @@ import { buildTitlePrompt, deriveChatTitle, isDefaultChatTitle, parseTitleRespon
22
22
  import { buildSuggestionPrompt, parseSuggestionResponse } from './chat-suggestion.js';
23
23
  import { matchApprovalRule } from './core/approval-rules.js';
24
24
  import { isAudioAttachment } from './core/audio-attachment.js';
25
- import { attachTurnDocumentIds, formatRagContext, chooseRagNotice, RAG_KNOWLEDGE_OFF_NOTICE, RAG_TRUNCATED_NOTICE, RAG_UNAVAILABLE_NOTICE, createRagSourceTagFilter, citedByPhraseOverlap, formatFullDocumentContext, isFullTextHit, isTruncatedFullTextHit, sourcesFromHits, WEB_TOOLS, webSourcesFromToolResult, withoutDataChannel } from './core/files/index.js';
26
- import { annotateDocumentAttachments, documentUnreadNotice, documentUnreadReason, pdfPagesCutNotice, pdfPagesSkippedNotice } from './core/document-attachment.js';
25
+ import { attachTurnDocumentIds, formatRagContext, chooseRagNotice, RAG_KNOWLEDGE_OFF_NOTICE, RAG_TRUNCATED_NOTICE, RAG_UNAVAILABLE_NOTICE, createRagSourceTagFilter, citedByPhraseOverlap, formatFullDocumentContext, fullTextAttachmentId, isFullTextHit, isTruncatedFullTextHit, sourcesFromHits, WEB_TOOLS, webSourcesFromToolResult, withoutDataChannel } from './core/files/index.js';
26
+ import { annotateDocumentAttachments, documentUnreadNotice, documentUnreadReason, PDF_PAGES_SOURCE_LINE, pdfPagesCutNotice, pdfPagesShownNotice } from './core/document-attachment.js';
27
27
  import { imageCacheKey, imageCacheName, sweepImageCache } from './core/image/cache-sweep.js';
28
28
  import { IMAGE_MIMES, normalizeImageForModel } from './core/image/normalize.js';
29
29
  import { createPdfRasterizer } from './core/pdf/rasterize.js';
@@ -37,7 +37,9 @@ import { fsGrantsFrom, grantedDirsFrom } from './fs-grants.js';
37
37
  import { persistentDir } from './persistent-dir.js';
38
38
  import { ModelCatalogRevisionHub } from './model-catalog-revision.js';
39
39
  import { agentRekeyFingerprint, agentSwitched, chatKvCacheKey, chatRepairKvCacheKey, disappearedChatIds } from './kv-cache-reclaim.js';
40
- import { buildCompactionPrompt, canCompact, foldReducesPrompt, COMPACTION_KEEP_TURNS, COMPACTION_TURN_PREFIX, isContextOverflowFailure, nearContextLimit, compactionBoundary, lastCompactedThroughId, parseCompactionSummary } from './compaction.js';
40
+ import { KvCacheRetention } from './kv-cache-retention.js';
41
+ import { KV_CACHE_RETENTION_KEY } from './constants.js';
42
+ import { buildCompactionPrompt, canCompact, foldReducesPrompt, COMPACTION_KEEP_TURNS, COMPACTION_TURN_PREFIX, isContextOverflowFailure, nearContextLimit, compactionBoundary, foldsThrough, lastCompactedThroughId, parseCompactionSummary } from './compaction.js';
41
43
  import { ModelDownloadReconciler, musicModelChoiceOf } from './model-download.js';
42
44
  import { AbortedError, raceAbort } from '@qvac/harness/race-abort';
43
45
  import { RunTranscript } from './run-transcript.js';
@@ -47,18 +49,19 @@ import { searchKnowledge } from './knowledge-search.js';
47
49
  import { isLifecycleTeardown, knownAbortOutcome, RUN_ABORT_REASONS, RUN_FAILURE_REASONS, runFailureNotice } from './run-notices.js';
48
50
  import { unref } from './unref.js';
49
51
  import { encodeAgentSkillReadiness } from './skill-readiness.js';
50
- import { harnessClearKvCache, harnessDeathReason, harnessDeleteModel, harnessDied, harnessListModels, harnessPreviewModelSource, harnessSkillCatalog, harnessSkillManagement, harnessDetectLanguage, harnessSpeak, harnessSpeakStream, harnessTools, harnessTranscribe, heldLoadModel, droppedHeldLoadModel, imageDownloadProgress, isHarnessEvent, modelCatalogChanged, toolReportEntry } from './assistant/harness.js';
51
- import { annotateUnreadableImages, audioTranscriptBlock, backfillDocumentOnlyTurn, backfillImageOnlyTurns, silentAudioNotice, unheardAudioNotice, askedIn, nameSenders, restoreSentContent, hiddenVideoNotice, unreadVideoNotice, unsyncedVideoNotice, VIDEO_NO_AUDIO, VIDEO_SILENT, videoAnnotation, videoTranscriptBlock } from './assistant/message.js';
52
+ import { harnessClearKvCache, harnessDeathReason, harnessDeleteModel, harnessDied, harnessListModels, harnessPreviewModelSource, harnessSkillCatalog, harnessSkillManagement, syncedSkills, harnessDetectLanguage, harnessSpeak, harnessSpeakStream, harnessTools, harnessTranscribe, heldLoadModel, droppedHeldLoadModel, imageDownloadProgress, isHarnessEvent, modelCatalogChanged, customModelReportEntries, toolReportEntry } from './assistant/harness.js';
53
+ import { annotateUnreadableImages, audioTranscriptBlock, backfillDocumentOnlyTurn, backfillImageOnlyTurns, silentAudioNotice, unheardAudioNotice, askedIn, claimNewImages, earlierImages, nameSenders, restoreSentContent, hiddenVideoNotice, unreadVideoNotice, unsyncedVideoNotice, VIDEO_NO_AUDIO, VIDEO_SILENT, videoAnnotation, videoTranscriptBlock } from './assistant/message.js';
52
54
  import { frameTimes, probeVideo, sampleFrames } from './core/video/frames.js';
53
55
  import { packVideoDigest, parseVideoDigestHeader, unpackVideoDigest, VIDEO_DIGEST_MIME, videoDigestFileName } from './core/video/digest.js';
54
56
  import { VIDEO_FRAME_EDGE, videoFrameCount } from './assistant/video-budget.js';
55
57
  import { drainBody, raceInactivity } from './assistant/fetch-body.js';
56
- import { pdfPageBudget } from './assistant/pdf-budget.js';
58
+ import { pdfImageRoom } from './assistant/pdf-budget.js';
59
+ import { packPdfSelection, parsePdfSelection, PDF_PAGES_MIME, pdfSelectionFileName, selectPdfPages } from './assistant/pdf-pages.js';
57
60
  import { effectiveCtxSize } from './api/effective-ctx-size.js';
58
61
  import { GENERIC_ACKNOWLEDGEMENTS, HISTORY_TYPES, SKILL_TOOL, TERMINAL_STATES, foldableView, historyFromChunks, listHistoryChunks, replayFromChunks, runPromptView, runView, senderOf, staleToolRunIds, viewOutgrewCache } from './assistant/history.js';
59
62
  import { errorMessage, isRecord } from './guards.js';
60
63
  import { CoreError, isCoreError } from './errors.js';
61
- export { harnessClearKvCache, harnessDeleteModel, harnessListModels, harnessPreviewModelSource, harnessSkillCatalog, harnessSkillManagement, harnessDetectLanguage, harnessSpeak, harnessSpeakStream, harnessTools, harnessTranscribe } from './assistant/harness.js';
64
+ export { harnessClearKvCache, harnessDeleteModel, harnessListModels, harnessPreviewModelSource, harnessSkillCatalog, harnessSkillManagement, syncedSkills, harnessDetectLanguage, harnessSpeak, harnessSpeakStream, harnessTools, harnessTranscribe } from './assistant/harness.js';
62
65
  export {} from './assistant/skill-encode.js';
63
66
  export { annotateUnreadableImages, unheardAudioNotice, unreadableImagesNotice, DOCUMENT_ONLY_USER_PROMPT, IMAGE_AND_DOCUMENT_USER_PROMPT, IMAGE_ONLY_USER_PROMPT, nameSenders, restoreSentContent } from './assistant/message.js';
64
67
  export { historyFromChunks, listHistoryChunks, staleToolRunIds } from './assistant/history.js';
@@ -129,19 +132,16 @@ export const CAPTURE_OFF = 'off';
129
132
  export const SUGGEST_PROMPTS_KEY = 'assistant.suggestPrompts';
130
133
  export const SUGGEST_PROMPTS_ON = 'on';
131
134
  const SUGGESTION_SUPERSEDED = "superseded by the chat's next run";
132
- function pdfCut(doc, from) {
133
- const pageCount = doc.pageCount();
134
- for (let page = from; page < pageCount; page++) {
135
- try {
136
- const flags = doc.pageFlags(page);
137
- if (flags.hasImage || !flags.hasText) {
138
- return { lastPage: page, pageCount };
139
- }
140
- }
141
- catch {
142
- }
143
- }
144
- return undefined;
135
+ const NO_PDF_PAGES = { selection: { pageCount: 0, shots: [] }, names: [], labels: [] };
136
+ function pdfNotices(fileName, pages, wholeText) {
137
+ const { cutAt, pageCount } = pages.selection;
138
+ const shown = pages.names.length;
139
+ return [
140
+ ...(shown ? [pdfPagesShownNotice(fileName, pages.labels)] : []),
141
+ ...(cutAt === undefined
142
+ ? []
143
+ : [pdfPagesCutNotice({ fileName, cutAt, pageCount, shown, wholeText })])
144
+ ];
145
145
  }
146
146
  function attachPages(turn, files) {
147
147
  if (!files.length)
@@ -169,8 +169,22 @@ function videoAudioBlock(fileName, { audio, transcript }) {
169
169
  }
170
170
  return unheardAudioNotice(`The audio of the attached video "${fileName}"`, 'transcription failed');
171
171
  }
172
- function pdfPageCacheName(pdf, page) {
173
- return imageCacheName({ blobId: pdf.blobId, fileName: `${pdf.fileName}.p${page}.jpg` });
172
+ async function cachedPdfPages(selection, { dir, pdf, pinned }) {
173
+ const names = selection.shots.map((shot) => pdfShotCacheName(pdf, shot));
174
+ for (const name of names) {
175
+ pinned.add(name);
176
+ }
177
+ const files = names.map((name) => path.join(dir, name));
178
+ const cached = await Promise.all(files.map((file) => cacheOrTouch(file, noBytes)));
179
+ return cached.every(Boolean)
180
+ ? { selection, names, labels: selection.shots.map((shot) => shot.label) }
181
+ : null;
182
+ }
183
+ function pdfShotCacheName(pdf, shot) {
184
+ const box = shot.clip
185
+ ? `.c${[shot.clip.x, shot.clip.y, shot.clip.width, shot.clip.height].map(Math.round).join('_')}`
186
+ : '';
187
+ return imageCacheName({ blobId: pdf.blobId, fileName: `${pdf.fileName}.p${shot.page}${box}.jpg` });
174
188
  }
175
189
  async function cacheOrTouch(file, produce) {
176
190
  const cached = await fs.promises.stat(file).catch(noop);
@@ -192,6 +206,7 @@ const BLOB_READ_TIMEOUT_MS = 15_000;
192
206
  const SUSPENDED = RUN_ABORT_REASONS.suspended;
193
207
  const OWNERSHIP_LOST = RUN_ABORT_REASONS.ownershipLost;
194
208
  const RUN_SETTLED = RUN_ABORT_REASONS.runSettled;
209
+ const AGENT_REMOVED = RUN_ABORT_REASONS.agentRemoved;
195
210
  const RUNNER_DIED = RUN_ABORT_REASONS.runnerDied;
196
211
  const RUNNER_CLOSED = RUN_ABORT_REASONS.runnerClosed;
197
212
  const MODEL_UNLOADED = RUN_ABORT_REASONS.modelUnloaded;
@@ -215,6 +230,15 @@ function sameLoadSettings(a, b) {
215
230
  (a.kvCacheK ?? '') === (b.kvCacheK ?? '') &&
216
231
  (a.kvCacheV ?? '') === (b.kvCacheV ?? ''));
217
232
  }
233
+ function modelLeft(before, after, deviceId) {
234
+ if (!deviceId || !before.modelName || !runsHere(before, deviceId))
235
+ return null;
236
+ const stays = after && runsHere(after, deviceId) && after.modelName === before.modelName;
237
+ return stays ? null : before.modelName;
238
+ }
239
+ function runsHere(agent, deviceId) {
240
+ return (!agent.deletedAt && !!agent.providerDeviceId && b4a.equals(agent.providerDeviceId, deviceId));
241
+ }
218
242
  function withConfigDefaults(agent, config) {
219
243
  if (agent.ctxSize || !config?.ctxSize)
220
244
  return agent;
@@ -246,6 +270,7 @@ export class QvacAssistant extends ReadyResource {
246
270
  _runIdleTimeoutMs;
247
271
  _modelReloadDelayMs;
248
272
  _reloads = new Map();
273
+ _releases = new Map();
249
274
  _pdfRasterizer;
250
275
  _warmAbort = new AbortController();
251
276
  _unloading = new Map();
@@ -289,19 +314,22 @@ export class QvacAssistant extends ReadyResource {
289
314
  _inferenceCalls;
290
315
  _runReplay;
291
316
  _roundHost;
317
+ _kvRetention;
292
318
  _lifecycle;
293
319
  _suggesting = new Map();
294
320
  _audioTranscripts;
295
321
  _videoProbes;
296
- _pdfPages;
322
+ _pdfSelections;
297
323
  _mediaRefs;
298
324
  _chats;
325
+ _intake = new Map();
299
326
  _runImageCacheNames;
300
327
  _reconciledCompactions;
328
+ _knowledgeCaps = new Map();
301
329
  _modelCatalog = new ModelCatalogRevisionHub();
302
330
  _onHarnessStatus;
303
331
  _onModelCatalogEvent;
304
- constructor(engine, harness, { logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, downloadRetryMs, platform = os.platform(), preloadCurrentAgentModel = true, drives, blobReadTimeoutMs = BLOB_READ_TIMEOUT_MS, runIdleTimeoutMs = RUN_IDLE_TIMEOUT_MS, modelReloadDelayMs = MODEL_RELOAD_DELAY_MS, pdfRasterizer: pdfRasterizerOption } = {}) {
332
+ constructor(engine, harness, { logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, kvCacheRetentionMs, downloadRetryMs, platform = os.platform(), preloadCurrentAgentModel = true, drives, blobReadTimeoutMs = BLOB_READ_TIMEOUT_MS, runIdleTimeoutMs = RUN_IDLE_TIMEOUT_MS, modelReloadDelayMs = MODEL_RELOAD_DELAY_MS, pdfRasterizer: pdfRasterizerOption } = {}) {
305
333
  super();
306
334
  this._engine = engine;
307
335
  this._harness = harness;
@@ -354,10 +382,17 @@ export class QvacAssistant extends ReadyResource {
354
382
  this._backgroundReplays = new Set();
355
383
  this._inferenceCalls = new InferenceCallStore(inferenceCallsDir ?? persistentDir('inspector'));
356
384
  this._runReplay = new RunReplayStore(runReplayDir ?? persistentDir('run-replay'));
385
+ this._kvRetention = new KvCacheRetention(engine, {
386
+ active: () => !this.closing && !this.suspended,
387
+ running: (chatId) => [...this._runs.values()].some((run) => run.chatId === chatId),
388
+ deleteChatKvCache: (chatId) => this._deleteChatKvCache(chatId, 'idle past retention'),
389
+ defaultMs: kvCacheRetentionMs,
390
+ logger
391
+ });
357
392
  this._lifecycle = new AbortController();
358
393
  this._audioTranscripts = new Map();
359
394
  this._videoProbes = new Map();
360
- this._pdfPages = new Map();
395
+ this._pdfSelections = new Map();
361
396
  this._mediaRefs = new Map();
362
397
  this._chats = new Map();
363
398
  this._runImageCacheNames = new Map();
@@ -428,6 +463,7 @@ export class QvacAssistant extends ReadyResource {
428
463
  this._downloads.start();
429
464
  this._meshListWatch.start();
430
465
  this._accountWatch.start();
466
+ this._kvRetention.start(() => this._meshConsumers.keys());
431
467
  void this._bootOnline();
432
468
  this._triggerModelWarm();
433
469
  void this.onlineReady().then(() => this._triggerModelWarm(), noop);
@@ -665,6 +701,7 @@ export class QvacAssistant extends ReadyResource {
665
701
  }
666
702
  const installedModelNames = models.map((model) => model.name);
667
703
  const cachedModelNames = models.filter((model) => model.isCached).map((model) => model.name);
704
+ const customModels = customModelReportEntries(models);
668
705
  let toolCatalog = null;
669
706
  if (this._harness.tools) {
670
707
  try {
@@ -680,7 +717,8 @@ export class QvacAssistant extends ReadyResource {
680
717
  installedModelNames,
681
718
  cachedModelNames,
682
719
  this._readySkills,
683
- toolCatalog
720
+ toolCatalog,
721
+ customModels
684
722
  ]);
685
723
  const meshId = this._accountMeshId;
686
724
  if (!meshId) {
@@ -692,7 +730,8 @@ export class QvacAssistant extends ReadyResource {
692
730
  installedModelNames,
693
731
  cachedModelNames,
694
732
  readySkillNames: this._readySkills ?? undefined,
695
- toolCatalog: toolCatalog ?? undefined
733
+ toolCatalog: toolCatalog ?? undefined,
734
+ customModels
696
735
  });
697
736
  }
698
737
  async _reportInto(meshId, key, report) {
@@ -703,7 +742,7 @@ export class QvacAssistant extends ReadyResource {
703
742
  this._lastCapabilities.set(meshId, key);
704
743
  }
705
744
  catch (err) {
706
- if (isCoreError(err, 'MESH_NOT_FOUND')) {
745
+ if (isCoreError(err, 'MESH_NOT_FOUND') || isCoreError(err, 'MESH_STILL_JOINING')) {
707
746
  return;
708
747
  }
709
748
  this._log?.error('assistant', 'saveDeviceCapabilities failed', err);
@@ -797,6 +836,7 @@ export class QvacAssistant extends ReadyResource {
797
836
  }
798
837
  async _close() {
799
838
  this._stopMeshIntake();
839
+ this._kvRetention.stop();
800
840
  this._harness.off?.('status', this._onHarnessStatus);
801
841
  this._harness.off?.('model', this._onModelCatalogEvent);
802
842
  this._warmAbort.abort(RUNNER_CLOSED);
@@ -958,11 +998,41 @@ export class QvacAssistant extends ReadyResource {
958
998
  const { loaded, reason } = await this._harness.loadModel({ model, agent: knobs });
959
999
  this._log?.info('models', 'model reload requested', { model, loaded, reason });
960
1000
  }
1001
+ _scheduleModelRelease(modelName) {
1002
+ clearTimeout(this._releases.get(modelName));
1003
+ const timer = setTimeout(() => {
1004
+ this._releases.delete(modelName);
1005
+ this._releaseUnusedModel(modelName).catch((err) => this._log?.warn('models', 'model release failed', { model: modelName, err }));
1006
+ }, this._modelReloadDelayMs);
1007
+ unref(timer);
1008
+ this._releases.set(modelName, timer);
1009
+ }
1010
+ async _releaseUnusedModel(modelName) {
1011
+ if (this.closing || this.suspended || !this._harness.unloadModel)
1012
+ return;
1013
+ const model = runnableModelName(modelName, await this._runnableHost());
1014
+ const holders = [...this._runs.values()].filter((run) => run.executing && run.model === model);
1015
+ await Promise.allSettled(holders.map((run) => run.done));
1016
+ if (this.closing || this.suspended) {
1017
+ return;
1018
+ }
1019
+ const rows = await this._harness.list?.({ cachedOnly: true }).catch(noop);
1020
+ if (!rows?.some((row) => row.name === model && row.isLoaded)) {
1021
+ return;
1022
+ }
1023
+ const { agents } = await this.modelUsers(model);
1024
+ if (agents?.length) {
1025
+ return;
1026
+ }
1027
+ const { unloaded } = await this.unloadModel(model);
1028
+ this._log?.info('models', 'unused model released', { model, unloaded });
1029
+ }
961
1030
  _cancelModelReloads() {
962
- for (const timer of this._reloads.values()) {
1031
+ for (const timer of [...this._reloads.values(), ...this._releases.values()]) {
963
1032
  clearTimeout(timer);
964
1033
  }
965
1034
  this._reloads.clear();
1035
+ this._releases.clear();
966
1036
  }
967
1037
  async _agentRunning(model, activeAgentId) {
968
1038
  const deviceId = this._requireDeviceId();
@@ -1145,7 +1215,7 @@ export class QvacAssistant extends ReadyResource {
1145
1215
  };
1146
1216
  return { start, stop };
1147
1217
  }
1148
- async _reclaimDeletedChats(frames, servedIn) {
1218
+ async _reclaimDeletedChats(frames, meshId, served) {
1149
1219
  let known = null;
1150
1220
  let agents = new Map();
1151
1221
  for await (const frame of frames) {
@@ -1155,7 +1225,7 @@ export class QvacAssistant extends ReadyResource {
1155
1225
  const gone = new Set(known === null ? [] : disappearedChatIds(known, ids));
1156
1226
  if (known !== null) {
1157
1227
  for (const chatId of gone) {
1158
- this._dropDeletedChat(chatId);
1228
+ this._dropDeletedChat(meshId, chatId);
1159
1229
  }
1160
1230
  }
1161
1231
  for (const chat of frame.chats ?? []) {
@@ -1166,8 +1236,8 @@ export class QvacAssistant extends ReadyResource {
1166
1236
  }
1167
1237
  known = new Set(ids);
1168
1238
  agents = new Map((frame.chats ?? []).map((chat) => [chat.id, chat.agentId]));
1169
- if (servedIn) {
1170
- this._servedChats.set(servedIn, known);
1239
+ if (served) {
1240
+ this._servedChats.set(meshId, known);
1171
1241
  }
1172
1242
  await this._sweepImageCache(gone);
1173
1243
  await this._sweepInferenceCalls();
@@ -1183,9 +1253,16 @@ export class QvacAssistant extends ReadyResource {
1183
1253
  }
1184
1254
  }
1185
1255
  }
1186
- _dropDeletedChat(chatId) {
1256
+ async _sweepIdleChatCaches(meshId, frames) {
1257
+ for await (const _frame of frames) {
1258
+ if (this.closing || this.suspended)
1259
+ return;
1260
+ void this._kvRetention.sweep(meshId);
1261
+ }
1262
+ }
1263
+ _dropDeletedChat(meshId, chatId) {
1187
1264
  for (const run of this._runs.values()) {
1188
- if (run.chatId === chatId) {
1265
+ if (run.meshId === meshId && run.chatId === chatId) {
1189
1266
  run.controller.abort(RUN_SETTLED);
1190
1267
  }
1191
1268
  }
@@ -1216,7 +1293,14 @@ export class QvacAssistant extends ReadyResource {
1216
1293
  this._scheduleModelReload(agent);
1217
1294
  }
1218
1295
  }
1219
- known = new Map(agents.map((agent) => [agent.id, agent]));
1296
+ const next = new Map(agents.map((agent) => [agent.id, agent]));
1297
+ for (const previous of known?.values() ?? []) {
1298
+ const model = modelLeft(previous, next.get(previous.id), this._deviceId);
1299
+ if (model) {
1300
+ this._scheduleModelRelease(model);
1301
+ }
1302
+ }
1303
+ known = next;
1220
1304
  }
1221
1305
  }
1222
1306
  async _reclaimAgentChatCaches(meshId, agent) {
@@ -1254,13 +1338,16 @@ export class QvacAssistant extends ReadyResource {
1254
1338
  this._reconciledCompactions.set(chatId, newest.id);
1255
1339
  }
1256
1340
  }
1257
- async deleteChatKvCache(chatId) {
1341
+ deleteChatKvCache(chatId) {
1342
+ return this._reclaimChatKvCache(chatId, 'deleted by request');
1343
+ }
1344
+ async _reclaimChatKvCache(chatId, reason) {
1258
1345
  const result = (await this._harness.deleteKvCache?.(chatKvCacheKey(chatId))) ?? {
1259
1346
  status: 'unsupported',
1260
1347
  error: 'Harness does not support KV cache deletion'
1261
1348
  };
1262
1349
  if (result.status === 'success') {
1263
- await this._runReplay.forget(chatId, LOCAL_HOLDER);
1350
+ await this._runReplay.forget(chatId, { holder: LOCAL_HOLDER, reason });
1264
1351
  }
1265
1352
  return result;
1266
1353
  }
@@ -1288,6 +1375,9 @@ export class QvacAssistant extends ReadyResource {
1288
1375
  .record(chatId, entry)
1289
1376
  .catch((err) => this._log?.warn('assistant', 'inference call not recorded', { err }));
1290
1377
  }
1378
+ async _inspectRound(chatId, entry) {
1379
+ this._inspectCall(await this._capturingInferenceCalls(), chatId, entry);
1380
+ }
1291
1381
  _inspectSent(inspecting, chatId, sent) {
1292
1382
  if (!inspecting)
1293
1383
  return;
@@ -1298,20 +1388,29 @@ export class QvacAssistant extends ReadyResource {
1298
1388
  async _sentRuns(chatId, rounds) {
1299
1389
  const served = replayFromChunks(rounds);
1300
1390
  try {
1301
- const sentRuns = await this._runReplay.load({ holder: LOCAL_HOLDER, chatId });
1391
+ const { sentRuns, askedRuns } = await this._runReplay.loadReplay({
1392
+ holder: LOCAL_HOLDER,
1393
+ chatId
1394
+ });
1302
1395
  for (const [runId, turns] of served.sentRuns) {
1303
1396
  sentRuns.set(runId, turns);
1304
1397
  }
1305
1398
  return {
1306
1399
  sentRuns,
1307
- askedRuns: await this._runReplay.loadAsked({ holder: LOCAL_HOLDER, chatId }),
1308
- readRuns: served.readRuns
1400
+ askedRuns,
1401
+ readRuns: served.readRuns,
1402
+ rebuild: await this._runReplay.rebuild({ holder: LOCAL_HOLDER, chatId })
1309
1403
  };
1310
1404
  }
1311
1405
  catch (err) {
1312
1406
  this._log?.warn('assistant', 'run replay unreadable', { chatId, err });
1313
1407
  await this._deleteChatKvCache(chatId, 'run replay unreadable');
1314
- return { sentRuns: new Map(), askedRuns: new Map(), readRuns: new Map() };
1408
+ return {
1409
+ sentRuns: new Map(),
1410
+ askedRuns: new Map(),
1411
+ readRuns: new Map(),
1412
+ rebuild: await this._runReplay.rebuild({ holder: LOCAL_HOLDER, chatId })
1413
+ };
1315
1414
  }
1316
1415
  }
1317
1416
  async _recordSentRun(chatId, { runId, turns, asked }) {
@@ -1331,7 +1430,7 @@ export class QvacAssistant extends ReadyResource {
1331
1430
  }
1332
1431
  async _deleteChatKvCache(chatId, reason) {
1333
1432
  try {
1334
- const result = await this.deleteChatKvCache(chatId);
1433
+ const result = await this._reclaimChatKvCache(chatId, reason);
1335
1434
  if (result.status === 'failure') {
1336
1435
  this._log?.warn('assistant', 'chat kv-cache deletion failed', {
1337
1436
  chatId,
@@ -1414,7 +1513,8 @@ export class QvacAssistant extends ReadyResource {
1414
1513
  }
1415
1514
  _meshConsumer(meshId, served) {
1416
1515
  const watches = [
1417
- this._streamWatch(`chat-list:${meshId}`, () => this._engine.chatsWatch({ meshId }), (frames) => this._reclaimDeletedChats(frames, served ? meshId : null))
1516
+ this._streamWatch(`chat-list:${meshId}`, () => this._engine.chatsWatch({ meshId }), (frames) => this._reclaimDeletedChats(frames, meshId, served)),
1517
+ this._streamWatch(`kv-cache-retention:${meshId}`, () => this._engine.configWatch({ key: KV_CACHE_RETENTION_KEY }), (frames) => this._sweepIdleChatCaches(meshId, frames))
1418
1518
  ];
1419
1519
  if (!served) {
1420
1520
  watches.push(this._streamWatch(`run-requests:${meshId}`, () => this._engine.runRequestsWatch({ meshId }), (frames) => this._dispatchRunRequests(meshId, frames)), this._streamWatch(`agent:${meshId}`, () => this._engine.agentsWatch({ meshId }), (frames) => this._followAgentEdits(meshId, frames)));
@@ -1498,68 +1598,93 @@ export class QvacAssistant extends ReadyResource {
1498
1598
  }
1499
1599
  this._seen.set(runId, meshId);
1500
1600
  const engine = meshScoped(this._engine, meshId);
1501
- const settle = (async () => {
1502
- const agentId = request.runRequest?.agentId;
1503
- const agent = agentId ? await engine.getAgent({ agentId }).catch(noop) : undefined;
1504
- if (!agent) {
1505
- this._seen.delete(runId);
1506
- return;
1507
- }
1508
- const deviceId = this._requireDeviceId();
1509
- if (offeredTo(request, deviceId) && !(await this._isHandled(engine, request))) {
1510
- if (this._backgrounded) {
1511
- this._seen.delete(runId);
1512
- if (this._state === QvacState.PRESUSPEND) {
1513
- this._parked.set(runId, () => this._dispatch(request, meshId));
1514
- }
1515
- return;
1516
- }
1517
- const taken = await engine.takeRunRequest({ chunkId: request.id }).catch(noop);
1518
- if (!taken) {
1519
- this._seen.delete(runId);
1520
- return;
1521
- }
1522
- request = taken;
1601
+ const chat = `${meshId}:${request.chatId}`;
1602
+ const scheduled = (this._intake.get(chat) ?? Promise.resolve()).then(() => this._schedule(engine, request, { runId, meshId, chat }));
1603
+ const turn = scheduled.then(noop, noop);
1604
+ this._intake.set(chat, turn);
1605
+ void turn.then(() => {
1606
+ if (this._intake.get(chat) === turn) {
1607
+ this._intake.delete(chat);
1523
1608
  }
1524
- if (!drivenBy({ request, agent }, deviceId)) {
1525
- return;
1526
- }
1527
- if (await this._isHandled(engine, request)) {
1609
+ });
1610
+ const settle = (async () => {
1611
+ const run = await scheduled;
1612
+ if (!run) {
1528
1613
  return;
1529
1614
  }
1530
- this._log?.info('runs', 'run claimed', { runId, chatId: request.chatId, agentId });
1531
- if (!request.capability) {
1532
- await this._offerSteer(engine, request, agent.id);
1533
- }
1534
- const controller = new AbortController();
1535
- const prior = this._chats.get(request.chatId) ?? Promise.resolve();
1536
- const done = prior.then(() => this._execute(request, agent, { controller, meshId, runId }));
1537
- const link = done.catch(noop);
1538
- this._chats.set(request.chatId, link);
1539
- this._runs.set(runId, {
1540
- controller,
1541
- done,
1542
- chatId: request.chatId,
1543
- agentId: agent.id,
1544
- model: agent.modelName,
1545
- executing: false
1546
- });
1547
1615
  try {
1548
- await done;
1616
+ await run.done;
1549
1617
  }
1550
1618
  finally {
1551
1619
  this._runImageCacheNames.delete(runId);
1552
1620
  this._runs.delete(runId);
1553
1621
  this._runsChanged();
1554
- if (this._chats.get(request.chatId) === link) {
1555
- this._chats.delete(request.chatId);
1622
+ if (this._chats.get(chat) === run.link) {
1623
+ this._chats.delete(chat);
1556
1624
  }
1557
1625
  void this._reportCapabilities();
1558
- this._requeue(runId, controller.signal.reason, () => this._dispatch(request, meshId));
1626
+ this._requeue(runId, run.controller.signal.reason, () => this._dispatch(run.request, meshId));
1559
1627
  }
1560
1628
  })();
1561
1629
  settle.catch((err) => this._log?.error('assistant', `run ${runId} failed`, err));
1562
1630
  }
1631
+ async _schedule(engine, request, { runId, meshId, chat }) {
1632
+ const claim = await this._claim(engine, request, { runId, meshId });
1633
+ if (!claim) {
1634
+ return undefined;
1635
+ }
1636
+ const { agent } = claim;
1637
+ const controller = new AbortController();
1638
+ const prior = this._chats.get(chat) ?? Promise.resolve();
1639
+ const done = prior.then(() => this._execute(claim.request, agent, { controller, meshId, runId }));
1640
+ const link = done.catch(noop);
1641
+ this._chats.set(chat, link);
1642
+ this._runs.set(runId, {
1643
+ controller,
1644
+ done,
1645
+ meshId,
1646
+ chatId: claim.request.chatId,
1647
+ agentId: agent.id,
1648
+ model: agent.modelName,
1649
+ executing: false
1650
+ });
1651
+ return { request: claim.request, controller, done, link };
1652
+ }
1653
+ async _claim(engine, request, { runId, meshId }) {
1654
+ const agentId = request.runRequest?.agentId;
1655
+ const agent = agentId ? await engine.getAgent({ agentId }).catch(noop) : undefined;
1656
+ if (!agent) {
1657
+ this._seen.delete(runId);
1658
+ return undefined;
1659
+ }
1660
+ const deviceId = this._requireDeviceId();
1661
+ if (offeredTo(request, deviceId) && !(await this._isHandled(engine, request))) {
1662
+ if (this._backgrounded) {
1663
+ this._seen.delete(runId);
1664
+ if (this._state === QvacState.PRESUSPEND) {
1665
+ this._parked.set(runId, () => this._dispatch(request, meshId));
1666
+ }
1667
+ return undefined;
1668
+ }
1669
+ const taken = await engine.takeRunRequest({ chunkId: request.id }).catch(noop);
1670
+ if (!taken) {
1671
+ this._seen.delete(runId);
1672
+ return undefined;
1673
+ }
1674
+ request = taken;
1675
+ }
1676
+ if (!drivenBy({ request, agent }, deviceId)) {
1677
+ return undefined;
1678
+ }
1679
+ if (await this._isHandled(engine, request)) {
1680
+ return undefined;
1681
+ }
1682
+ this._log?.info('runs', 'run claimed', { runId, chatId: request.chatId, agentId });
1683
+ if (!request.capability) {
1684
+ await this._offerSteer(engine, request, agent.id);
1685
+ }
1686
+ return { request, agent };
1687
+ }
1563
1688
  async _offerSteer(engine, request, agentId) {
1564
1689
  const running = [...this._runs.values()].find((run) => run.chatId === request.chatId && run.agentId === agentId && run.steering);
1565
1690
  if (!running?.steering || !request.runId) {
@@ -1591,7 +1716,7 @@ export class QvacAssistant extends ReadyResource {
1591
1716
  return;
1592
1717
  }
1593
1718
  try {
1594
- await transcript.chunk({ type: 'sources', sources: { sources: records } });
1719
+ await transcript.chunk({ type: 'sources', sources: { sources: chunkSources(records) } });
1595
1720
  }
1596
1721
  catch (err) {
1597
1722
  this._log?.warn('assistant', 'web sources chunk skipped', { runId, err });
@@ -1792,7 +1917,8 @@ export class QvacAssistant extends ReadyResource {
1792
1917
  agentId: agent.id,
1793
1918
  deviceId,
1794
1919
  from: request.seq,
1795
- media: (file) => this._mediaRefs.get(path.basename(file))
1920
+ media: (file) => this._mediaRefs.get(path.basename(file)),
1921
+ inspect: (call) => void this._inspectRound(chatId, { runId, at: Date.now(), call })
1796
1922
  });
1797
1923
  const folded = !resumed &&
1798
1924
  (await this._compactIfNearFull({
@@ -1817,14 +1943,19 @@ export class QvacAssistant extends ReadyResource {
1817
1943
  type: 'approval-request'
1818
1944
  });
1819
1945
  const { history, stale, repair: currentRepair, acceptedRepairs } = runPromptView(all, priorAsks ?? [], { request, runId });
1820
- const { chunks: priorResults } = await engine.listChunks({ chatId, type: 'tool-result' });
1821
- let ran = (priorResults ?? []).some((chunk) => chunk.runId === runId &&
1946
+ const priorResults = all.filter((chunk) => chunk.type === 'tool-result');
1947
+ let ran = priorResults.some((chunk) => chunk.runId === runId &&
1822
1948
  chunk.toolResult?.name !== SKILL_TOOL &&
1823
1949
  !isDeniedResult(chunk.toolResult?.result));
1824
1950
  let replay = await this._sentRuns(chatId, await listRoundChunks(engine, chatId));
1825
1951
  if (!resumed && viewOutgrewCache(all, { request, runId }, replay.sentRuns)) {
1826
1952
  await this._deleteChatKvCache(chatId, 'a run outside the cached view');
1827
- replay = { sentRuns: new Map(), askedRuns: new Map(), readRuns: new Map() };
1953
+ replay = {
1954
+ sentRuns: new Map(),
1955
+ askedRuns: new Map(),
1956
+ readRuns: new Map(),
1957
+ rebuild: await this._runReplay.rebuild({ holder: LOCAL_HOLDER, chatId })
1958
+ };
1828
1959
  }
1829
1960
  const messages = historyFromChunks(history, stale, replay);
1830
1961
  const typedText = currentRepair
@@ -1853,7 +1984,8 @@ export class QvacAssistant extends ReadyResource {
1853
1984
  await this._storeVideoDigests(sampled.splice(0), { meshId, chatId, runId, deviceId });
1854
1985
  }
1855
1986
  };
1856
- let pdfPages = { rendered: new Set(), cuts: [] };
1987
+ let pdfPages = { rendered: new Set(), notices: [] };
1988
+ const selectedPdfs = [];
1857
1989
  if (!seesImages) {
1858
1990
  const dropped = messages.reduce((count, turn) => count + (turn.images?.length ?? 0), 0);
1859
1991
  if (dropped && (this._harness.supportsImages ?? this._info.supportsImages)) {
@@ -1875,11 +2007,27 @@ export class QvacAssistant extends ReadyResource {
1875
2007
  const ownershipWatch = this._watchOwnership(engine, { request, agentId: agent.id, controller });
1876
2008
  let readinessError = null;
1877
2009
  const held = { status: null };
2010
+ let shown = '';
2011
+ const showWait = (progress) => {
2012
+ const key = JSON.stringify(progress);
2013
+ if (key === shown || (!progress && !held.status)) {
2014
+ return;
2015
+ }
2016
+ shown = key;
2017
+ const runStatus = progress
2018
+ ? { state: 'executing', progress }
2019
+ : { state: 'executing' };
2020
+ if (!held.status) {
2021
+ held.status = transcript.status(runStatus, { resumed });
2022
+ return;
2023
+ }
2024
+ held.status.then(({ id }) => transcript.progress(id, runStatus)).catch(noop);
2025
+ };
1878
2026
  try {
1879
2027
  await this._downloads?.waitUntilCached(model, controller.signal, {
1880
- onHold: () => {
1881
- held.status = transcript.status({ state: 'executing', progress: { phase: 'awaiting-download', model } }, { resumed });
1882
- }
2028
+ onHold: () => showWait({ phase: 'awaiting-download', model }),
2029
+ onProgress: (percentage) => showWait(downloadingProgress(model, percentage)),
2030
+ onStall: () => showWait(null)
1883
2031
  });
1884
2032
  }
1885
2033
  catch (err) {
@@ -1961,6 +2109,9 @@ export class QvacAssistant extends ReadyResource {
1961
2109
  const taken = new Set();
1962
2110
  let inputLength = 0;
1963
2111
  let asked;
2112
+ let primeRound;
2113
+ let primeTokens;
2114
+ let injectedHits = 0;
1964
2115
  const writeText = async (type, raw) => {
1965
2116
  const text = type === 'content' ? sourceTagFilter.push(raw) : raw;
1966
2117
  if (!text) {
@@ -1980,7 +2131,8 @@ export class QvacAssistant extends ReadyResource {
1980
2131
  }
1981
2132
  };
1982
2133
  const failRun = async (message) => {
1983
- const folded = isContextOverflowFailure(message) &&
2134
+ const overflowed = isContextOverflowFailure(message);
2135
+ const folded = overflowed &&
1984
2136
  (await this._runCompaction({
1985
2137
  chatId,
1986
2138
  transcript,
@@ -1990,9 +2142,14 @@ export class QvacAssistant extends ReadyResource {
1990
2142
  run: { request, runId },
1991
2143
  rounds
1992
2144
  }));
2145
+ const shrunk = overflowed && !folded && injectedHits > 1;
2146
+ if (shrunk) {
2147
+ this._knowledgeCaps.set(chatId, Math.floor(injectedHits / 2));
2148
+ this._log?.info('runs', 'knowledge shrunk for retry', { runId, hits: injectedHits });
2149
+ }
1993
2150
  runFailure = runFailureNotice(message);
1994
2151
  await transcript.status({ state: 'failed', reason: runFailure, metrics });
1995
- if (folded) {
2152
+ if (folded || shrunk) {
1996
2153
  await engine
1997
2154
  .runAgent({ chatId, agentId: agent.id, parentRunId: runId })
1998
2155
  .catch((err) => this._log?.warn('runs', 'compaction retry not queued', { runId, err }));
@@ -2062,7 +2219,10 @@ export class QvacAssistant extends ReadyResource {
2062
2219
  chatId,
2063
2220
  attachmentIds: attachTurnIds,
2064
2221
  signal: controller.signal,
2065
- preparing: modelWatch.documents
2222
+ preparing: (active) => {
2223
+ this._markPreparing(runId, active);
2224
+ modelWatch.documents(active);
2225
+ }
2066
2226
  })
2067
2227
  : null;
2068
2228
  if (controller.signal.aborted) {
@@ -2080,9 +2240,18 @@ export class QvacAssistant extends ReadyResource {
2080
2240
  await transcript.status({ state: 'failed', reason: outcome.reason, metrics });
2081
2241
  return;
2082
2242
  }
2083
- const injected = knowledge
2084
- ? await this._injectKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords })
2243
+ const cap = this._knowledgeCaps.get(chatId);
2244
+ this._knowledgeCaps.delete(chatId);
2245
+ const fitted = knowledge && cap ? { ...knowledge, hits: knowledge.hits.slice(0, cap) } : knowledge;
2246
+ const injected = fitted
2247
+ ? await this._injectKnowledge(fitted, {
2248
+ transcript,
2249
+ sourceTagFilter,
2250
+ retrievedRecords,
2251
+ pictured: seesImages && messages.some((turn) => turn.pdfs?.length)
2252
+ })
2085
2253
  : { documentsInjected: false, sourcesWritten: false, ragInjected: false };
2254
+ injectedHits = injected.ragInjected && fitted ? fitted.hits.length : 0;
2086
2255
  const hasAudio = messages.some((turn) => turn.audioAttachments?.length || turn.videos?.length);
2087
2256
  if (hasAudio) {
2088
2257
  modelWatch.transcribe(true);
@@ -2102,14 +2271,22 @@ export class QvacAssistant extends ReadyResource {
2102
2271
  }
2103
2272
  backfillImageOnlyTurns(messages);
2104
2273
  if (seesImages) {
2274
+ const hits = injected.documentsInjected && fitted ? fitted.hits : [];
2105
2275
  pdfPages = await this._hydratePdfPages(messages, {
2106
2276
  signal: controller.signal,
2107
2277
  runId,
2108
- window: { ctxSize: configuredAgent.ctxSize, modelName: model }
2278
+ window: { ctxSize: configuredAgent.ctxSize, modelName: model },
2279
+ reading: { chatId, meshId, folded },
2280
+ textChars: hits.reduce((chars, hit) => chars + hit.content.length, 0),
2281
+ wholeIds: new Set(hits
2282
+ .filter((hit) => !isTruncatedFullTextHit(hit))
2283
+ .map(fullTextAttachmentId)
2284
+ .filter((id) => id !== null)),
2285
+ selected: selectedPdfs
2109
2286
  });
2110
2287
  }
2111
2288
  annotateDocumentAttachments(messages);
2112
- for (const { turn, notice } of pdfPages.cuts) {
2289
+ for (const { turn, notice } of pdfPages.notices) {
2113
2290
  turn.content = `${turn.content}\n${notice}`;
2114
2291
  }
2115
2292
  const unreadIds = attachTurnIds.filter((id) => !pdfPages.rendered.has(id));
@@ -2162,6 +2339,7 @@ export class QvacAssistant extends ReadyResource {
2162
2339
  const input = resent ?? nameSenders(messages);
2163
2340
  inputLength = input.length;
2164
2341
  rounds.inputLength = inputLength;
2342
+ const sentImages = earlierImages(messages);
2165
2343
  const inspecting = await this._capturingInferenceCalls();
2166
2344
  steering = new RunInputQueue();
2167
2345
  const inflight = this._runs.get(runId);
@@ -2218,13 +2396,17 @@ export class QvacAssistant extends ReadyResource {
2218
2396
  taken.add(event.id);
2219
2397
  continue;
2220
2398
  }
2221
- if (event.type === 'metrics') {
2399
+ if (isHarnessEvent(event, 'metrics')) {
2222
2400
  const { type, ...rest } = event;
2223
2401
  metrics = rest;
2402
+ primeTokens = rest.rounds?.find((each) => each.round === primeRound)?.promptTokens;
2224
2403
  recordBackends(this._backendUse, rest.backends);
2225
2404
  this._log?.info('runs', 'run metrics', { runId, ...runMetricsSummary(rest) });
2226
2405
  continue;
2227
2406
  }
2407
+ if (event.type === 'inference-sent' && event.outcome === 'overflowed') {
2408
+ this._log?.info('runs', 'context overflow', { runId, reason: event.reason });
2409
+ }
2228
2410
  if (event.type === 'inference-sent') {
2229
2411
  this._inspectSent(inspecting, chatId, {
2230
2412
  runId,
@@ -2239,6 +2421,8 @@ export class QvacAssistant extends ReadyResource {
2239
2421
  if (event.type === 'inference-call') {
2240
2422
  const call = asRecord(event.call);
2241
2423
  sentRun?.observe(call);
2424
+ primeRound ??= sentRun?.onKey ? Number(call.round ?? 0) : undefined;
2425
+ modelWatch.request(call.messages, sentImages);
2242
2426
  this._inspectCall(inspecting, chatId, { runId, at: Date.now(), call });
2243
2427
  continue;
2244
2428
  }
@@ -2305,19 +2489,25 @@ export class QvacAssistant extends ReadyResource {
2305
2489
  const citedTitles = injected.ragInjected
2306
2490
  ? citedByPhraseOverlap([...answers.values()].join(''), retrievedRecords)
2307
2491
  : null;
2492
+ const primedHere = !!sentRun?.used && rounds.ranHere(primeRound);
2493
+ const primed = primedHere ? replay.rebuild : null;
2494
+ if (primedHere) {
2495
+ await this._runReplay.consume({ holder: LOCAL_HOLDER, chatId });
2496
+ }
2308
2497
  if (sentRun?.used && !rounds.rounds) {
2309
2498
  await this._recordSentRun(chatId, { runId, turns: sentRun.turns(inputLength), asked });
2310
2499
  }
2311
2500
  sentRun = null;
2312
2501
  await transcript.status({
2313
2502
  state: 'completed',
2314
- metrics: citedTitles ? { ...metrics, citedTitles } : metrics
2503
+ metrics: withCacheRebuild(citedTitles ? { ...metrics, citedTitles } : metrics, primed, primeTokens ?? null)
2315
2504
  });
2316
2505
  titleOutcome = 'completed';
2317
2506
  for (const id of taken) {
2318
2507
  this._steered.set(id, runId);
2319
2508
  }
2320
2509
  await this._storeVideoDigests(sampled, { meshId, chatId, runId, deviceId });
2510
+ await this._storePdfSelections(selectedPdfs, { meshId, chatId, runId, deviceId });
2321
2511
  }
2322
2512
  catch (err) {
2323
2513
  const outcome = controller.signal.aborted
@@ -2361,12 +2551,14 @@ export class QvacAssistant extends ReadyResource {
2361
2551
  const answerText = [...answers.values()].join('');
2362
2552
  void this._autoTitle(engine, {
2363
2553
  chatId,
2554
+ history,
2364
2555
  messages,
2365
2556
  model,
2366
2557
  agent: runAgent,
2367
2558
  probe: completed,
2368
2559
  rounds
2369
- }).then(() => completed && answerText.trim()
2560
+ })
2561
+ .then(() => completed && answerText.trim()
2370
2562
  ? this._suggestNext(engine, {
2371
2563
  chatId,
2372
2564
  runId,
@@ -2376,7 +2568,8 @@ export class QvacAssistant extends ReadyResource {
2376
2568
  agent: runAgent,
2377
2569
  rounds
2378
2570
  })
2379
- : undefined);
2571
+ : undefined)
2572
+ .catch((err) => this._log?.warn('runs', 'title or suggestion skipped', { chatId, err }));
2380
2573
  }
2381
2574
  }
2382
2575
  }
@@ -2400,6 +2593,8 @@ export class QvacAssistant extends ReadyResource {
2400
2593
  const modelWatch = this._watchModelProgress((runStatus) => transcript.progress(executing.id, runStatus));
2401
2594
  const settledWatch = this._watchSettled(engine, { chatId, runId, controller });
2402
2595
  const ownershipWatch = this._watchOwnership(engine, { request, agentId: agent.id, controller });
2596
+ const idle = idleWatch(controller, this._runIdleTimeoutMs);
2597
+ idle.touch();
2403
2598
  let metrics;
2404
2599
  const endAbortedCapability = async () => {
2405
2600
  const outcome = this._abortOutcome(runId, controller.signal.reason);
@@ -2426,10 +2621,14 @@ export class QvacAssistant extends ReadyResource {
2426
2621
  agent,
2427
2622
  attach: (input) => this._uploadGenerated(input, { meshId, chatId, runId, deviceId }),
2428
2623
  fetchAttachment: (query) => this._fetchAttachment(engine, chatId, query),
2429
- progress: (update) => modelWatch.image(update),
2624
+ progress: (update) => {
2625
+ idle.touch();
2626
+ return modelWatch.image(update);
2627
+ },
2430
2628
  signal: controller.signal
2431
2629
  });
2432
2630
  for await (const event of events) {
2631
+ idle.touch();
2433
2632
  if (event.type === 'metrics') {
2434
2633
  const { type, ...rest } = event;
2435
2634
  metrics = rest;
@@ -2482,6 +2681,7 @@ export class QvacAssistant extends ReadyResource {
2482
2681
  }
2483
2682
  finally {
2484
2683
  transcript.close();
2684
+ idle.stop();
2485
2685
  modelWatch.stop();
2486
2686
  settledWatch.stop();
2487
2687
  ownershipWatch.stop();
@@ -2978,7 +3178,7 @@ export class QvacAssistant extends ReadyResource {
2978
3178
  return this._servedFrame(source, { frame: ref.frame, frames: ref.frames }, served);
2979
3179
  }
2980
3180
  if (ref.page !== undefined) {
2981
- return this._servedPage(attachment, ref.page, served);
3181
+ return this._servedPage(attachment, { page: ref.page, clip: ref.clip }, served);
2982
3182
  }
2983
3183
  served.pinned.add(imageCacheName(attachment));
2984
3184
  return this._hydrateImage(served.dir, attachment, served.signal);
@@ -2997,8 +3197,8 @@ export class QvacAssistant extends ReadyResource {
2997
3197
  const target = { dir, pinned, digestBlobId: digest.blobId };
2998
3198
  return (await this._cacheVideo(attachment, video, target)).files[frame] ?? null;
2999
3199
  }
3000
- async _servedPage(pdf, page, { dir, pinned, docs, signal }) {
3001
- const name = pdfPageCacheName(pdf, page);
3200
+ async _servedPage(pdf, { page, clip }, { dir, pinned, docs, signal }) {
3201
+ const name = pdfShotCacheName(pdf, { page, clip });
3002
3202
  pinned.add(name);
3003
3203
  const file = path.join(dir, name);
3004
3204
  const rendered = await cacheOrTouch(file, async () => {
@@ -3007,7 +3207,7 @@ export class QvacAssistant extends ReadyResource {
3007
3207
  doc = this._readBlob(pdf.url, signal).then((bytes) => bytes ? this._pdfRasterizer.open(bytes) : null);
3008
3208
  docs.set(pdf.id, doc);
3009
3209
  }
3010
- return (await doc)?.renderPage(page) ?? null;
3210
+ return (await doc)?.renderPage(page, clip) ?? null;
3011
3211
  });
3012
3212
  return rendered ? file : null;
3013
3213
  }
@@ -3026,39 +3226,41 @@ export class QvacAssistant extends ReadyResource {
3026
3226
  });
3027
3227
  return file;
3028
3228
  }
3029
- async _hydratePdfPages(messages, { signal, runId, window }) {
3229
+ async _hydratePdfPages(messages, { signal, runId, window, reading, textChars, wholeIds, selected }) {
3030
3230
  const rendered = new Set();
3031
- const cuts = [];
3231
+ const notices = [];
3032
3232
  const turns = messages.filter((turn) => turn.pdfs?.length);
3033
3233
  if (!turns.length) {
3034
- return { rendered, cuts };
3234
+ return { rendered, notices };
3035
3235
  }
3036
3236
  const dir = this._imageCacheDir;
3037
3237
  await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
3038
3238
  const pinned = this._runImageCacheNames.get(runId) ?? new Set();
3039
3239
  this._runImageCacheNames.set(runId, pinned);
3040
3240
  const latestUser = messages.findLast((turn) => turn.role === 'user');
3041
- const maxPages = await this._pdfPageBudget(window);
3241
+ const measured = await this._pdfReading(window, reading);
3042
3242
  for (const turn of turns) {
3043
- const { shown, notices } = await this._hydrateTurnPdfs(turn, {
3044
- dir,
3045
- pinned,
3046
- signal,
3047
- maxPages
3048
- });
3049
- if (turn === latestUser) {
3050
- for (const id of shown) {
3051
- rendered.add(id);
3243
+ const room = pdfImageRoom(measured, turn === latestUser ? textChars : 0);
3244
+ for (const pdf of turn.pdfs ?? []) {
3245
+ const pages = await this._tryHydratePdf({ dir, pdf, pinned, room, signal, selected });
3246
+ attachPages(turn, pages.names.map((name) => path.join(dir, name)));
3247
+ if (pages.names.length && turn === latestUser) {
3248
+ rendered.add(pdf.id);
3249
+ }
3250
+ const whole = turn === latestUser && wholeIds.has(pdf.id);
3251
+ for (const notice of pdfNotices(pdf.fileName, pages, whole)) {
3252
+ notices.push({ turn, notice });
3052
3253
  }
3053
3254
  }
3054
- cuts.push(...notices.map((notice) => ({ turn, notice })));
3255
+ delete turn.pdfs;
3055
3256
  }
3056
- return { rendered, cuts };
3257
+ return { rendered, notices };
3057
3258
  }
3058
- async _pdfPageBudget({ ctxSize, modelName }) {
3259
+ async _pdfReading({ ctxSize, modelName }, options) {
3059
3260
  const custom = await this._customModel(modelName);
3060
3261
  const window = effectiveCtxSize({ ctxSize, modelName }, { appCtxSize: 0, platform: this._platform, custom });
3061
- return pdfPageBudget(window);
3262
+ const { cacheTokens } = await this._contextReading(options, window);
3263
+ return { ctxSize: window, cacheTokens };
3062
3264
  }
3063
3265
  async _customModel(name) {
3064
3266
  for await (const list of this._engine.customModelsWatch({})) {
@@ -3066,114 +3268,107 @@ export class QvacAssistant extends ReadyResource {
3066
3268
  }
3067
3269
  return null;
3068
3270
  }
3069
- async _hydrateTurnPdfs(turn, { dir, pinned, signal, maxPages }) {
3070
- const shown = [];
3071
- const notices = [];
3072
- let budget = maxPages;
3073
- for (const pdf of turn.pdfs ?? []) {
3074
- if (budget <= 0) {
3075
- notices.push(pdfPagesSkippedNotice(pdf.fileName));
3076
- continue;
3077
- }
3078
- const pages = await this._tryHydratePdf(dir, turn, { pdf, pinned, maxPages: budget, signal });
3079
- budget -= pages.tried;
3080
- if (pages.names.length) {
3081
- shown.push(pdf.id);
3082
- }
3083
- if (pages.cut) {
3084
- notices.push(pdfPagesCutNotice({ fileName: pdf.fileName, ...pages.cut }));
3085
- }
3086
- }
3087
- delete turn.pdfs;
3088
- return { shown, notices };
3089
- }
3090
- async _tryHydratePdf(dir, turn, opts) {
3271
+ async _tryHydratePdf(opts) {
3091
3272
  try {
3092
- return await this._hydratePdf(dir, turn, opts);
3273
+ return await this._hydratePdf(opts);
3093
3274
  }
3094
3275
  catch (err) {
3095
3276
  if (opts.signal.aborted) {
3096
3277
  throw err;
3097
3278
  }
3098
3279
  this._log?.warn('assistant', `pdf rasterization failed — ${opts.pdf.fileName}`, err);
3099
- return { names: [], tried: 0 };
3280
+ return NO_PDF_PAGES;
3100
3281
  }
3101
3282
  }
3102
- async _hydratePdf(dir, turn, { pdf, pinned, maxPages, signal }) {
3103
- const key = `${pdf.blobId}:${maxPages}`;
3104
- const memo = this._pdfPages.get(key);
3105
- if (memo) {
3106
- for (const name of memo.names) {
3107
- pinned.add(name);
3283
+ async _hydratePdf(hydration) {
3284
+ const { dir, pdf, pinned, room, signal, selected } = hydration;
3285
+ const key = pdf.pages?.blobId ?? pdf.id;
3286
+ const remember = (selection) => {
3287
+ this._pdfSelections.set(key, selection);
3288
+ for (const { page, clip } of selection.shots) {
3289
+ this._mediaRefs.set(pdfShotCacheName(pdf, { page, clip }), { id: pdf.id, page, clip });
3108
3290
  }
3109
- const files = memo.names.map((name) => path.join(dir, name));
3110
- if ((await Promise.all(files.map((file) => cacheOrTouch(file, noBytes)))).every(Boolean)) {
3111
- attachPages(turn, files);
3112
- return memo;
3291
+ if (!pdf.pages) {
3292
+ selected.push({ ref: pdf, selection });
3293
+ }
3294
+ };
3295
+ const known = this._pdfSelections.get(key) ?? (await this._storedPdfSelection(pdf, signal));
3296
+ if (known) {
3297
+ remember(known);
3298
+ const cached = await cachedPdfPages(known, { dir, pdf, pinned });
3299
+ if (cached) {
3300
+ return cached;
3113
3301
  }
3114
3302
  }
3115
- const pages = await this._renderPdf(dir, { pdf, pinned, maxPages, signal });
3116
- if (!pages) {
3117
- return { names: [], tried: 0 };
3118
- }
3119
- this._pdfPages.set(key, pages);
3120
- attachPages(turn, pages.names.map((name) => path.join(dir, name)));
3121
- return pages;
3122
- }
3123
- async _renderPdf(dir, { pdf, pinned, maxPages, signal }) {
3124
3303
  const bytes = await this._readBlob(pdf.url, signal);
3125
3304
  if (signal.aborted) {
3126
3305
  throw new Error('hydration aborted');
3127
3306
  }
3128
- if (!bytes) {
3129
- return null;
3130
- }
3131
- const doc = await this._pdfRasterizer.open(bytes);
3307
+ const doc = bytes ? await this._pdfRasterizer.open(bytes) : null;
3132
3308
  if (!doc) {
3133
- return { names: [], tried: 0 };
3309
+ return NO_PDF_PAGES;
3134
3310
  }
3135
3311
  try {
3136
- const names = [];
3137
- let tried = 0;
3138
- let page = 0;
3139
- const pageCount = doc.pageCount();
3140
- for (; page < pageCount && tried < maxPages; page++) {
3141
- if (signal.aborted)
3142
- throw new Error('hydration aborted');
3143
- const outcome = await this._renderPdfPage(doc, { dir, pdf, page, pinned, signal });
3144
- if (outcome.tried) {
3145
- tried++;
3146
- }
3147
- if (outcome.name) {
3148
- names.push(outcome.name);
3149
- }
3312
+ const selection = known ?? (await selectPdfPages(doc, room));
3313
+ if (!known) {
3314
+ remember(selection);
3150
3315
  }
3151
- return { names, tried, cut: pdfCut(doc, page) };
3316
+ return await this._renderPdfShots(doc, selection, hydration);
3152
3317
  }
3153
3318
  finally {
3154
3319
  doc.close();
3155
3320
  }
3156
3321
  }
3157
- async _renderPdfPage(doc, { dir, pdf, page, pinned, signal }) {
3158
- let tried = false;
3322
+ async _storedPdfSelection(pdf, signal) {
3323
+ const bytes = pdf.pages ? await this._readBlob(pdf.pages.url, signal) : null;
3324
+ if (!bytes) {
3325
+ return null;
3326
+ }
3159
3327
  try {
3160
- const flags = doc.pageFlags(page);
3161
- if (flags.hasText && !flags.hasImage) {
3162
- return { tried };
3163
- }
3164
- tried = true;
3165
- const name = pdfPageCacheName(pdf, page);
3166
- pinned.add(name);
3167
- this._mediaRefs.set(name, { id: pdf.id, page });
3168
- const cached = await cacheOrTouch(path.join(dir, name), () => doc.renderPage(page));
3169
- return { tried, name: cached ? name : undefined };
3328
+ return parsePdfSelection(bytes);
3170
3329
  }
3171
3330
  catch (err) {
3172
- if (signal.aborted) {
3173
- throw err;
3331
+ this._log?.warn('assistant', `pdf page choice unreadable — ${pdf.fileName}`, err);
3332
+ return null;
3333
+ }
3334
+ }
3335
+ async _renderPdfShots(doc, selection, { dir, pdf, pinned, signal }) {
3336
+ const names = [];
3337
+ const labels = [];
3338
+ for (const shot of selection.shots) {
3339
+ if (signal.aborted)
3340
+ throw new Error('hydration aborted');
3341
+ const name = pdfShotCacheName(pdf, shot);
3342
+ pinned.add(name);
3343
+ try {
3344
+ const file = path.join(dir, name);
3345
+ if (await cacheOrTouch(file, () => doc.renderPage(shot.page, shot.clip))) {
3346
+ names.push(name);
3347
+ labels.push(shot.label);
3348
+ }
3349
+ }
3350
+ catch (err) {
3351
+ if (signal.aborted) {
3352
+ throw err;
3353
+ }
3354
+ this._log?.warn('assistant', `pdf page skipped — ${pdf.fileName} p${shot.page}`, err);
3355
+ }
3356
+ }
3357
+ return { selection, names, labels };
3358
+ }
3359
+ async _storePdfSelections(selected, target) {
3360
+ for (const { ref, selection } of selected) {
3361
+ try {
3362
+ await this._uploadGenerated({
3363
+ fileName: pdfSelectionFileName(ref.fileName),
3364
+ mimeType: PDF_PAGES_MIME,
3365
+ bytes: packPdfSelection(selection),
3366
+ raw: true
3367
+ }, { ...target, sourceId: ref.id });
3368
+ }
3369
+ catch (err) {
3370
+ this._log?.warn('assistant', `pdf page choice not stored — ${ref.fileName}`, err);
3174
3371
  }
3175
- this._log?.warn('assistant', `pdf page skipped — ${pdf.fileName} p${page}`, err);
3176
- return { tried };
3177
3372
  }
3178
3373
  }
3179
3374
  async _compactIfNearFull(params) {
@@ -3294,7 +3489,7 @@ export class QvacAssistant extends ReadyResource {
3294
3489
  return { compacted: false, reason: 'below-floor' };
3295
3490
  }
3296
3491
  const all = await listHistoryChunks(engine, chatId);
3297
- const stored = options.run ? foldableView(all, options.run) : all;
3492
+ const stored = foldableView(all, options.run);
3298
3493
  const branches = historyBranches(stored);
3299
3494
  const chunks = stored.filter((chunk) => isPromptChunk(chunk, branches));
3300
3495
  const { chunks: priorAsks } = await engine
@@ -3302,11 +3497,12 @@ export class QvacAssistant extends ReadyResource {
3302
3497
  .catch(() => ({ chunks: [] }));
3303
3498
  const lastThroughId = lastCompactedThroughId(chunks);
3304
3499
  const lastThroughSeq = all.find((chunk) => chunk.id === lastThroughId)?.seq ?? -1;
3305
- const userTurns = chunks.filter((chunk) => chunk.userMessage).length;
3500
+ const beforeSeq = options.run?.request.seq ?? Infinity;
3501
+ const userTurns = chunks.filter((chunk) => chunk.userMessage && chunk.seq < beforeSeq).length;
3306
3502
  let announced = false;
3307
3503
  let keepTurns = COMPACTION_KEEP_TURNS;
3308
3504
  for (;;) {
3309
- const boundary = compactionBoundary(chunks, keepTurns);
3505
+ const boundary = compactionBoundary(chunks, keepTurns, beforeSeq);
3310
3506
  if (!boundary) {
3311
3507
  return { compacted: false, reason: 'nothing-to-fold' };
3312
3508
  }
@@ -3317,7 +3513,8 @@ export class QvacAssistant extends ReadyResource {
3317
3513
  if (through.seq <= lastThroughSeq) {
3318
3514
  return { compacted: false, reason: 'already-compacted' };
3319
3515
  }
3320
- const inRange = chunks.filter((chunk) => chunk.seq <= through.seq);
3516
+ const folds = foldsThrough(chunks, through);
3517
+ const inRange = chunks.filter((chunk) => chunk.compaction || folds(chunk));
3321
3518
  const folded = historyFromChunks(inRange, staleToolRunIds(inRange, priorAsks ?? [], ''));
3322
3519
  if (!announced) {
3323
3520
  await options.onFold?.();
@@ -3418,9 +3615,10 @@ export class QvacAssistant extends ReadyResource {
3418
3615
  return { summary: null, overflowed: isContextOverflowFailure(failed) };
3419
3616
  }
3420
3617
  }
3421
- async _autoTitle(engine, { chatId, messages, model, agent, probe, rounds }) {
3618
+ async _autoTitle(engine, { chatId, history, messages, model, agent, probe, rounds }) {
3422
3619
  try {
3423
- const first = messages.find((turn) => turn.role === 'user' && turn.content.trim());
3620
+ const first = history.find((chunk) => chunk.userMessage?.text.trim())?.userMessage?.text ??
3621
+ messages.find((turn) => turn.role === 'user' && turn.content.trim())?.content;
3424
3622
  if (!first) {
3425
3623
  return;
3426
3624
  }
@@ -3428,15 +3626,7 @@ export class QvacAssistant extends ReadyResource {
3428
3626
  if (!isDefaultChatTitle(chat?.title)) {
3429
3627
  return;
3430
3628
  }
3431
- await this._generateChatTitle({
3432
- engine,
3433
- chatId,
3434
- input: first.content,
3435
- model,
3436
- agent,
3437
- probe,
3438
- rounds
3439
- });
3629
+ await this._generateChatTitle({ engine, chatId, input: first, model, agent, probe, rounds });
3440
3630
  }
3441
3631
  catch (err) {
3442
3632
  this._log?.warn('runs', 'auto-title skipped', { chatId, err });
@@ -3806,15 +3996,19 @@ export class QvacAssistant extends ReadyResource {
3806
3996
  _watchOwnership(engine, { request, agentId, controller }) {
3807
3997
  const deviceId = this._requireDeviceId();
3808
3998
  const watches = [
3809
- this._abortOnLoss(engine.agentsWatch({}), controller, ({ agents }) => {
3999
+ this._abortOnLoss(engine.agentsWatch({}), controller, async ({ agents }) => {
3810
4000
  const row = (agents ?? []).find((a) => a.id === agentId);
3811
- return !row || !!row.deletedAt || !drivenBy({ request, agent: row }, deviceId);
4001
+ if (row && !row.deletedAt) {
4002
+ return drivenBy({ request, agent: row }, deviceId) ? null : OWNERSHIP_LOST;
4003
+ }
4004
+ const chat = await engine.getChat({ chatId: request.chatId }).catch(noop);
4005
+ return !chat || chat.agentId === agentId ? AGENT_REMOVED : null;
3812
4006
  })
3813
4007
  ];
3814
4008
  if (request.runnerDeviceId) {
3815
4009
  watches.push(this._abortOnLoss(engine.runRequestsWatch({}), controller, ({ chunks }) => {
3816
4010
  const now = (chunks ?? []).find((chunk) => chunk.id === request.id);
3817
- return !now?.runTakenBy || !b4a.equals(now.runTakenBy, deviceId);
4011
+ return !now?.runTakenBy || !b4a.equals(now.runTakenBy, deviceId) ? OWNERSHIP_LOST : null;
3818
4012
  }));
3819
4013
  }
3820
4014
  return {
@@ -3829,8 +4023,9 @@ export class QvacAssistant extends ReadyResource {
3829
4023
  if (done) {
3830
4024
  return;
3831
4025
  }
3832
- if (lost(value)) {
3833
- controller.abort(OWNERSHIP_LOST);
4026
+ const reason = await lost(value);
4027
+ if (reason) {
4028
+ controller.abort(reason);
3834
4029
  return;
3835
4030
  }
3836
4031
  }
@@ -3854,7 +4049,15 @@ export class QvacAssistant extends ReadyResource {
3854
4049
  }
3855
4050
  }
3856
4051
  _generating() {
3857
- return [...this._runs.values()].some((run) => run.executing);
4052
+ return [...this._runs.values()].some((run) => run.executing && !run.preparing);
4053
+ }
4054
+ _markPreparing(runId, preparing) {
4055
+ const run = this._runs.get(runId);
4056
+ if (!run) {
4057
+ return;
4058
+ }
4059
+ this._runs.set(runId, { ...run, preparing });
4060
+ this._runsChanged();
3858
4061
  }
3859
4062
  idle(signal) {
3860
4063
  if (signal.aborted || !this._generating()) {
@@ -3899,6 +4102,7 @@ export class QvacAssistant extends ReadyResource {
3899
4102
  let transcribing = false;
3900
4103
  let documents = false;
3901
4104
  let sampling = false;
4105
+ let analyzing = false;
3902
4106
  const apply = (progress) => {
3903
4107
  const runStatus = progress
3904
4108
  ? { state: 'executing', progress }
@@ -3906,12 +4110,15 @@ export class QvacAssistant extends ReadyResource {
3906
4110
  if (documents) {
3907
4111
  runStatus.reason = 'preparing-documents';
3908
4112
  }
4113
+ else if (analyzing && !progress) {
4114
+ runStatus.reason = 'analyzing-images';
4115
+ }
3909
4116
  const key = JSON.stringify(runStatus);
3910
4117
  if (key === last) {
3911
4118
  return;
3912
4119
  }
3913
4120
  last = key;
3914
- showing = progress !== null || documents;
4121
+ showing = progress !== null || runStatus.reason !== undefined;
3915
4122
  update(runStatus).catch(noop);
3916
4123
  };
3917
4124
  const onModel = (state) => {
@@ -3924,8 +4131,7 @@ export class QvacAssistant extends ReadyResource {
3924
4131
  apply({ phase: 'awaiting-download', model: state.model });
3925
4132
  }
3926
4133
  else if (state.status === 'downloading') {
3927
- const percentage = Math.floor((state.percentage ?? 0) / 10) * 10;
3928
- apply({ phase: 'downloading', model: state.model, percentage });
4134
+ apply(downloadingProgress(state.model, state.percentage ?? 0));
3929
4135
  }
3930
4136
  else {
3931
4137
  apply(transcribing ? { phase: 'transcribing' } : null);
@@ -3950,9 +4156,16 @@ export class QvacAssistant extends ReadyResource {
3950
4156
  }
3951
4157
  apply({ phase: 'generating', percentage: Math.floor(progress.percentage / 10) * 10 });
3952
4158
  },
4159
+ request: (messages, sent) => {
4160
+ if (claimNewImages(messages, sent)) {
4161
+ analyzing = true;
4162
+ apply(null);
4163
+ }
4164
+ },
3953
4165
  stop: () => this._harness.off?.('model', onModel),
3954
4166
  clear: () => {
3955
4167
  sampling = false;
4168
+ analyzing = false;
3956
4169
  if (!showing) {
3957
4170
  return;
3958
4171
  }
@@ -3990,7 +4203,13 @@ function notReadyLine(search) {
3990
4203
  function filesCount(count, source) {
3991
4204
  return `${count} ${source} file${count === 1 ? '' : 's'}`;
3992
4205
  }
3993
- async function injectRetrievedKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords, injected }) {
4206
+ function chunkSources(records) {
4207
+ return records.map((record) => ({ ...record, page: record.page ?? 0 }));
4208
+ }
4209
+ function downloadingProgress(model, percentage) {
4210
+ return { phase: 'downloading', model, percentage: Math.floor(percentage / 10) * 10 };
4211
+ }
4212
+ async function injectRetrievedKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords, pictured, injected }) {
3994
4213
  const records = sourcesFromHits(knowledge.hits, RAG_SOURCE_BOUNDS);
3995
4214
  const notice = chooseRagNotice({
3996
4215
  errorMessage: knowledge.search.errorMessage,
@@ -4009,11 +4228,17 @@ async function injectRetrievedKnowledge(knowledge, { transcript, sourceTagFilter
4009
4228
  })));
4010
4229
  await transcript.chunk({
4011
4230
  type: 'sources',
4012
- sources: { sources: records, notice: notice ?? undefined, ...notReady(knowledge.search) }
4231
+ sources: {
4232
+ sources: chunkSources(records),
4233
+ notice: notice ?? undefined,
4234
+ ...notReady(knowledge.search)
4235
+ }
4013
4236
  });
4014
4237
  injected.sourcesWritten = true;
4015
4238
  if (records.length > 0) {
4016
- knowledge.lastUser.content = `${formatRagContext(knowledge.hits, knowledge.search.availableFiles ?? [])}\n\nThe user's message:\n${knowledge.lastUser.content}\n\n${RAG_CITATION_LINE}`;
4239
+ const framing = formatRagContext(knowledge.hits, knowledge.search.availableFiles ?? []);
4240
+ const pages = pictured ? `\n${PDF_PAGES_SOURCE_LINE}` : '';
4241
+ knowledge.lastUser.content = `${framing}${pages}\n\nThe user's message:\n${knowledge.lastUser.content}\n\n${RAG_CITATION_LINE}`;
4017
4242
  injected.ragInjected = true;
4018
4243
  injected.documentsInjected = true;
4019
4244
  }
@@ -4035,7 +4260,7 @@ function toolCallChunk(event) {
4035
4260
  function toolResultChunk(event) {
4036
4261
  return {
4037
4262
  type: 'tool-result',
4038
- toolResult: { name: event.name, result: withoutDataChannel(event.result) },
4263
+ toolResult: { name: event.name, result: withoutDataChannel(event.result) ?? null },
4039
4264
  ...callOf(event)
4040
4265
  };
4041
4266
  }
@@ -4065,6 +4290,9 @@ function runMetricsSummary(metrics) {
4065
4290
  stopReason
4066
4291
  };
4067
4292
  }
4293
+ function withCacheRebuild(metrics, reason, tokens) {
4294
+ return reason === null ? metrics : { ...metrics, cacheRebuild: { reason, tokens } };
4295
+ }
4068
4296
  function asRecord(value) {
4069
4297
  return isRecord(value) ? { ...value } : {};
4070
4298
  }