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

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 (213) hide show
  1. package/CHANGELOG.md +238 -12
  2. package/dist-lib/index.d.ts +3 -1
  3. package/dist-lib/index.js +1 -0
  4. package/dist-lib/lib/api/approval-rules.d.ts +1 -1
  5. package/dist-lib/lib/api/approval-rules.js +5 -1
  6. package/dist-lib/lib/api/chunk-delta.d.ts +7 -2
  7. package/dist-lib/lib/api/chunk-delta.js +89 -7
  8. package/dist-lib/lib/api/chunks.js +14 -8
  9. package/dist-lib/lib/api/config.d.ts +10 -3
  10. package/dist-lib/lib/api/config.js +51 -6
  11. package/dist-lib/lib/api/custom-models.js +3 -5
  12. package/dist-lib/lib/api/devices.js +3 -1
  13. package/dist-lib/lib/api/files.d.ts +1 -1
  14. package/dist-lib/lib/api/files.js +65 -8
  15. package/dist-lib/lib/api/index.d.ts +12 -2
  16. package/dist-lib/lib/api/index.js +6 -1
  17. package/dist-lib/lib/api/instrument.js +12 -4
  18. package/dist-lib/lib/api/members.js +7 -13
  19. package/dist-lib/lib/api/mesh.d.ts +1 -3
  20. package/dist-lib/lib/api/mesh.js +2 -2
  21. package/dist-lib/lib/api/notifications.js +8 -4
  22. package/dist-lib/lib/api/projects.js +5 -1
  23. package/dist-lib/lib/api/rag.js +32 -19
  24. package/dist-lib/lib/api/served.js +2 -1
  25. package/dist-lib/lib/api/workspace.js +0 -1
  26. package/dist-lib/lib/assistant/harness.d.ts +8 -2
  27. package/dist-lib/lib/assistant/harness.js +17 -4
  28. package/dist-lib/lib/assistant/history.d.ts +1 -1
  29. package/dist-lib/lib/assistant/history.js +19 -13
  30. package/dist-lib/lib/assistant/message.d.ts +6 -1
  31. package/dist-lib/lib/assistant/message.js +22 -2
  32. package/dist-lib/lib/assistant/model-round.d.ts +5 -0
  33. package/dist-lib/lib/assistant/model-round.js +47 -19
  34. package/dist-lib/lib/assistant/pdf-budget.d.ts +10 -2
  35. package/dist-lib/lib/assistant/pdf-budget.js +10 -11
  36. package/dist-lib/lib/assistant/pdf-pages.d.ts +25 -0
  37. package/dist-lib/lib/assistant/pdf-pages.js +75 -0
  38. package/dist-lib/lib/assistant/round-host.js +5 -3
  39. package/dist-lib/lib/assistant-client.d.ts +2 -1
  40. package/dist-lib/lib/assistant-client.js +24 -6
  41. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  42. package/dist-lib/lib/assistant-tree.js +8 -5
  43. package/dist-lib/lib/assistant.d.ts +21 -7
  44. package/dist-lib/lib/assistant.js +481 -244
  45. package/dist-lib/lib/client.js +10 -1
  46. package/dist-lib/lib/compaction.d.ts +3 -1
  47. package/dist-lib/lib/compaction.js +18 -4
  48. package/dist-lib/lib/constants.d.ts +3 -0
  49. package/dist-lib/lib/constants.js +3 -0
  50. package/dist-lib/lib/core/agent-copies.js +7 -1
  51. package/dist-lib/lib/core/agent.js +1 -0
  52. package/dist-lib/lib/core/approval-rules.d.ts +5 -1
  53. package/dist-lib/lib/core/approval-rules.js +16 -1
  54. package/dist-lib/lib/core/chat-activity.js +13 -16
  55. package/dist-lib/lib/core/chat-copy.js +1 -1
  56. package/dist-lib/lib/core/chat-fork.js +2 -1
  57. package/dist-lib/lib/core/chat-move.d.ts +4 -0
  58. package/dist-lib/lib/core/chat-move.js +42 -11
  59. package/dist-lib/lib/core/chat.d.ts +0 -1
  60. package/dist-lib/lib/core/chat.js +1 -1
  61. package/dist-lib/lib/core/chunk.d.ts +14 -3
  62. package/dist-lib/lib/core/chunk.js +116 -25
  63. package/dist-lib/lib/core/collections.d.ts +12 -1
  64. package/dist-lib/lib/core/collections.js +12 -1
  65. package/dist-lib/lib/core/config-value.d.ts +7 -0
  66. package/dist-lib/lib/core/config-value.js +15 -0
  67. package/dist-lib/lib/core/contract/activity.d.ts +3 -2
  68. package/dist-lib/lib/core/contract/activity.js +39 -21
  69. package/dist-lib/lib/core/contract/agent-join.js +15 -19
  70. package/dist-lib/lib/core/contract/agents.js +8 -7
  71. package/dist-lib/lib/core/contract/chat.d.ts +3 -0
  72. package/dist-lib/lib/core/contract/chat.js +12 -1
  73. package/dist-lib/lib/core/contract/chunks.js +16 -6
  74. package/dist-lib/lib/core/contract/devices.js +6 -4
  75. package/dist-lib/lib/core/contract/index.js +2 -1
  76. package/dist-lib/lib/core/contract/invites.js +12 -31
  77. package/dist-lib/lib/core/contract/joined-meshes.js +2 -1
  78. package/dist-lib/lib/core/contract/mesh-rules.js +4 -0
  79. package/dist-lib/lib/core/contract/model-requests.js +7 -6
  80. package/dist-lib/lib/core/contract/project-device-keys.js +15 -6
  81. package/dist-lib/lib/core/contract/project-host-keys.js +5 -4
  82. package/dist-lib/lib/core/contract/projects.js +12 -13
  83. package/dist-lib/lib/core/contract/public-seeds.js +5 -5
  84. package/dist-lib/lib/core/contract/roles.js +2 -1
  85. package/dist-lib/lib/core/contract/run-requests.d.ts +1 -1
  86. package/dist-lib/lib/core/contract/run-requests.js +19 -13
  87. package/dist-lib/lib/core/contract/shipped-rows.d.ts +2 -0
  88. package/dist-lib/lib/core/contract/shipped-rows.js +22 -0
  89. package/dist-lib/lib/core/contract/workspace.js +6 -12
  90. package/dist-lib/lib/core/contract/writers.js +20 -6
  91. package/dist-lib/lib/core/deleted-agent-runs.d.ts +7 -0
  92. package/dist-lib/lib/core/deleted-agent-runs.js +46 -0
  93. package/dist-lib/lib/core/devices.d.ts +2 -1
  94. package/dist-lib/lib/core/devices.js +4 -2
  95. package/dist-lib/lib/core/document-attachment.d.ts +6 -3
  96. package/dist-lib/lib/core/document-attachment.js +10 -5
  97. package/dist-lib/lib/core/files/attachments.js +3 -3
  98. package/dist-lib/lib/core/files/index.d.ts +8 -5
  99. package/dist-lib/lib/core/files/index.js +111 -18
  100. package/dist-lib/lib/core/files/processing/index.d.ts +1 -1
  101. package/dist-lib/lib/core/files/processing/index.js +8 -2
  102. package/dist-lib/lib/core/files/processing/source.d.ts +1 -0
  103. package/dist-lib/lib/core/files/processing/source.js +3 -0
  104. package/dist-lib/lib/core/files/processing/state.d.ts +1 -0
  105. package/dist-lib/lib/core/files/processing/state.js +7 -0
  106. package/dist-lib/lib/core/files/rag/build.d.ts +1 -0
  107. package/dist-lib/lib/core/files/rag/build.js +14 -1
  108. package/dist-lib/lib/core/files/rag/index.d.ts +1 -1
  109. package/dist-lib/lib/core/files/rag/index.js +1 -1
  110. package/dist-lib/lib/core/files/rag/produce.js +1 -0
  111. package/dist-lib/lib/core/files/rag/retrieval/full-text.d.ts +2 -0
  112. package/dist-lib/lib/core/files/rag/retrieval/full-text.js +7 -1
  113. package/dist-lib/lib/core/first-event.d.ts +6 -0
  114. package/dist-lib/lib/core/first-event.js +13 -0
  115. package/dist-lib/lib/core/invite.d.ts +2 -2
  116. package/dist-lib/lib/core/invite.js +5 -4
  117. package/dist-lib/lib/core/local/index.d.ts +16 -1
  118. package/dist-lib/lib/core/local/index.js +119 -10
  119. package/dist-lib/lib/core/mesh.d.ts +14 -3
  120. package/dist-lib/lib/core/mesh.js +127 -54
  121. package/dist-lib/lib/core/migrations/chat-chunks.d.ts +4 -0
  122. package/dist-lib/lib/core/migrations/chat-chunks.js +47 -0
  123. package/dist-lib/lib/core/migrations/file-index.d.ts +1 -1
  124. package/dist-lib/lib/core/migrations/file-index.js +6 -2
  125. package/dist-lib/lib/core/migrations/index.d.ts +2 -1
  126. package/dist-lib/lib/core/migrations/index.js +66 -9
  127. package/dist-lib/lib/core/notification.js +96 -23
  128. package/dist-lib/lib/core/pdf/figure.d.ts +22 -0
  129. package/dist-lib/lib/core/pdf/figure.js +64 -0
  130. package/dist-lib/lib/core/pdf/rasterize.d.ts +10 -1
  131. package/dist-lib/lib/core/pdf/rasterize.js +72 -22
  132. package/dist-lib/lib/core/peer-duplex.js +57 -5
  133. package/dist-lib/lib/core/public-mesh.js +8 -2
  134. package/dist-lib/lib/core/run-requests.js +2 -3
  135. package/dist-lib/lib/core/senders.d.ts +7 -6
  136. package/dist-lib/lib/core/senders.js +23 -30
  137. package/dist-lib/lib/core/shared-agents.d.ts +1 -0
  138. package/dist-lib/lib/core/shared-agents.js +47 -19
  139. package/dist-lib/lib/core/skill-secrets.d.ts +3 -2
  140. package/dist-lib/lib/core/skill-secrets.js +4 -1
  141. package/dist-lib/lib/core/sync/background.d.ts +3 -15
  142. package/dist-lib/lib/core/sync/background.js +25 -102
  143. package/dist-lib/lib/core/sync/devices.js +6 -3
  144. package/dist-lib/lib/core/sync/index.js +25 -3
  145. package/dist-lib/lib/core/sync-status.js +3 -3
  146. package/dist-lib/lib/core/vault-managed-skills.d.ts +18 -0
  147. package/dist-lib/lib/core/vault-managed-skills.js +105 -0
  148. package/dist-lib/lib/core.d.ts +66 -10
  149. package/dist-lib/lib/core.js +768 -179
  150. package/dist-lib/lib/credential-pusher.d.ts +11 -7
  151. package/dist-lib/lib/credential-pusher.js +40 -8
  152. package/dist-lib/lib/device-tree.d.ts +18 -0
  153. package/dist-lib/lib/device-tree.js +32 -0
  154. package/dist-lib/lib/doctor/redact.js +1 -1
  155. package/dist-lib/lib/errors.d.ts +12 -0
  156. package/dist-lib/lib/errors.js +12 -0
  157. package/dist-lib/lib/fs-drive-bridge.d.ts +7 -0
  158. package/dist-lib/lib/fs-drive-bridge.js +308 -30
  159. package/dist-lib/lib/integrations/setup-routes.js +7 -5
  160. package/dist-lib/lib/knowledge-search.d.ts +1 -1
  161. package/dist-lib/lib/knowledge-search.js +5 -46
  162. package/dist-lib/lib/kv-cache-retention.d.ts +35 -0
  163. package/dist-lib/lib/kv-cache-retention.js +98 -0
  164. package/dist-lib/lib/latest-frame.d.ts +10 -0
  165. package/dist-lib/lib/latest-frame.js +48 -0
  166. package/dist-lib/lib/mesh-scoped-engine.js +1 -0
  167. package/dist-lib/lib/model-download.d.ts +6 -1
  168. package/dist-lib/lib/model-download.js +32 -17
  169. package/dist-lib/lib/oauth/resolve.js +13 -5
  170. package/dist-lib/lib/reconnecting-watch.js +19 -11
  171. package/dist-lib/lib/run-notices.d.ts +2 -0
  172. package/dist-lib/lib/run-notices.js +5 -0
  173. package/dist-lib/lib/run-replay.d.ts +13 -1
  174. package/dist-lib/lib/run-replay.js +58 -21
  175. package/dist-lib/schema/build.js +66 -57
  176. package/dist-lib/schema/config.d.ts +1 -1
  177. package/dist-lib/schema/config.js +1 -1
  178. package/dist-lib/schema/content.js +2 -1
  179. package/dist-lib/schema/engine.js +70 -6
  180. package/dist-lib/schema/field-order.js +7 -1
  181. package/dist-lib/schema/indexes.d.ts +4 -0
  182. package/dist-lib/schema/indexes.js +18 -0
  183. package/dist-lib/schema/local.js +9 -2
  184. package/dist-lib/schema/qvac.js +116 -6
  185. package/dist-lib/spec/bind.js +15 -0
  186. package/dist-lib/spec/calls.js +5 -0
  187. package/dist-lib/spec/capabilities.d.ts +10 -0
  188. package/dist-lib/spec/config/hyperconf/index.js +1 -1
  189. package/dist-lib/spec/hrpc/hrpc.json +65 -0
  190. package/dist-lib/spec/hrpc/index.js +63 -3
  191. package/dist-lib/spec/hrpc/messages.js +1537 -1395
  192. package/dist-lib/spec/hyperschema/index.js +1537 -1395
  193. package/dist-lib/spec/hyperschema/schema.json +126 -1
  194. package/dist-lib/spec/hyperschema/types.d.ts +33 -1
  195. package/dist-lib/spec/local/hyperdb/messages.js +110 -54
  196. package/dist-lib/spec/local/hyperschema/index.js +56 -28
  197. package/dist-lib/spec/local/hyperschema/schema.json +55 -20
  198. package/dist-lib/spec/local/hyperschema/types.d.ts +8 -1
  199. package/dist-lib/spec/mesh/hyperdb/db.json +255 -51
  200. package/dist-lib/spec/mesh/hyperdb/index.js +1063 -404
  201. package/dist-lib/spec/mesh/hyperdb/messages.js +1673 -1202
  202. package/dist-lib/spec/mesh/hyperdispatch/dispatch.json +62 -56
  203. package/dist-lib/spec/mesh/hyperdispatch/index.js +156 -139
  204. package/dist-lib/spec/mesh/hyperdispatch/messages.js +809 -632
  205. package/dist-lib/spec/mesh/hyperschema/index.js +809 -632
  206. package/dist-lib/spec/mesh/hyperschema/schema.json +293 -174
  207. package/dist-lib/spec/mesh/hyperschema/types.d.ts +31 -1
  208. package/package.json +32 -26
  209. package/worker/assistant-sidecar.mjs +3 -0
  210. package/dist-lib/lib/core/files/processing/settle.d.ts +0 -13
  211. package/dist-lib/lib/core/files/processing/settle.js +0 -86
  212. package/dist-lib/lib/core/migrations/device-indexes.d.ts +0 -2
  213. 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();
@@ -1038,6 +1108,11 @@ export class QvacAssistant extends ReadyResource {
1038
1108
  }));
1039
1109
  return perAgent.flat();
1040
1110
  }
1111
+ async _runModel(agent, deviceId) {
1112
+ if (!b4a.equals(agent.providerDeviceId, deviceId))
1113
+ return agent.modelName;
1114
+ return runnableModelName(agent.modelName, await this._runnableHost());
1115
+ }
1041
1116
  async _runnableHost() {
1042
1117
  const capability = await this._ensureCapability();
1043
1118
  return capability && { ...capability, mobile: this._mobileClass };
@@ -1145,7 +1220,7 @@ export class QvacAssistant extends ReadyResource {
1145
1220
  };
1146
1221
  return { start, stop };
1147
1222
  }
1148
- async _reclaimDeletedChats(frames, servedIn) {
1223
+ async _reclaimDeletedChats(frames, meshId, served) {
1149
1224
  let known = null;
1150
1225
  let agents = new Map();
1151
1226
  for await (const frame of frames) {
@@ -1155,7 +1230,7 @@ export class QvacAssistant extends ReadyResource {
1155
1230
  const gone = new Set(known === null ? [] : disappearedChatIds(known, ids));
1156
1231
  if (known !== null) {
1157
1232
  for (const chatId of gone) {
1158
- this._dropDeletedChat(chatId);
1233
+ this._dropDeletedChat(meshId, chatId);
1159
1234
  }
1160
1235
  }
1161
1236
  for (const chat of frame.chats ?? []) {
@@ -1166,8 +1241,8 @@ export class QvacAssistant extends ReadyResource {
1166
1241
  }
1167
1242
  known = new Set(ids);
1168
1243
  agents = new Map((frame.chats ?? []).map((chat) => [chat.id, chat.agentId]));
1169
- if (servedIn) {
1170
- this._servedChats.set(servedIn, known);
1244
+ if (served) {
1245
+ this._servedChats.set(meshId, known);
1171
1246
  }
1172
1247
  await this._sweepImageCache(gone);
1173
1248
  await this._sweepInferenceCalls();
@@ -1183,9 +1258,16 @@ export class QvacAssistant extends ReadyResource {
1183
1258
  }
1184
1259
  }
1185
1260
  }
1186
- _dropDeletedChat(chatId) {
1261
+ async _sweepIdleChatCaches(meshId, frames) {
1262
+ for await (const _frame of frames) {
1263
+ if (this.closing || this.suspended)
1264
+ return;
1265
+ void this._kvRetention.sweep(meshId);
1266
+ }
1267
+ }
1268
+ _dropDeletedChat(meshId, chatId) {
1187
1269
  for (const run of this._runs.values()) {
1188
- if (run.chatId === chatId) {
1270
+ if (run.meshId === meshId && run.chatId === chatId) {
1189
1271
  run.controller.abort(RUN_SETTLED);
1190
1272
  }
1191
1273
  }
@@ -1216,7 +1298,14 @@ export class QvacAssistant extends ReadyResource {
1216
1298
  this._scheduleModelReload(agent);
1217
1299
  }
1218
1300
  }
1219
- known = new Map(agents.map((agent) => [agent.id, agent]));
1301
+ const next = new Map(agents.map((agent) => [agent.id, agent]));
1302
+ for (const previous of known?.values() ?? []) {
1303
+ const model = modelLeft(previous, next.get(previous.id), this._deviceId);
1304
+ if (model) {
1305
+ this._scheduleModelRelease(model);
1306
+ }
1307
+ }
1308
+ known = next;
1220
1309
  }
1221
1310
  }
1222
1311
  async _reclaimAgentChatCaches(meshId, agent) {
@@ -1254,13 +1343,16 @@ export class QvacAssistant extends ReadyResource {
1254
1343
  this._reconciledCompactions.set(chatId, newest.id);
1255
1344
  }
1256
1345
  }
1257
- async deleteChatKvCache(chatId) {
1346
+ deleteChatKvCache(chatId) {
1347
+ return this._reclaimChatKvCache(chatId, 'deleted by request');
1348
+ }
1349
+ async _reclaimChatKvCache(chatId, reason) {
1258
1350
  const result = (await this._harness.deleteKvCache?.(chatKvCacheKey(chatId))) ?? {
1259
1351
  status: 'unsupported',
1260
1352
  error: 'Harness does not support KV cache deletion'
1261
1353
  };
1262
1354
  if (result.status === 'success') {
1263
- await this._runReplay.forget(chatId, LOCAL_HOLDER);
1355
+ await this._runReplay.forget(chatId, { holder: LOCAL_HOLDER, reason });
1264
1356
  }
1265
1357
  return result;
1266
1358
  }
@@ -1288,6 +1380,9 @@ export class QvacAssistant extends ReadyResource {
1288
1380
  .record(chatId, entry)
1289
1381
  .catch((err) => this._log?.warn('assistant', 'inference call not recorded', { err }));
1290
1382
  }
1383
+ async _inspectRound(chatId, entry) {
1384
+ this._inspectCall(await this._capturingInferenceCalls(), chatId, entry);
1385
+ }
1291
1386
  _inspectSent(inspecting, chatId, sent) {
1292
1387
  if (!inspecting)
1293
1388
  return;
@@ -1298,20 +1393,29 @@ export class QvacAssistant extends ReadyResource {
1298
1393
  async _sentRuns(chatId, rounds) {
1299
1394
  const served = replayFromChunks(rounds);
1300
1395
  try {
1301
- const sentRuns = await this._runReplay.load({ holder: LOCAL_HOLDER, chatId });
1396
+ const { sentRuns, askedRuns } = await this._runReplay.loadReplay({
1397
+ holder: LOCAL_HOLDER,
1398
+ chatId
1399
+ });
1302
1400
  for (const [runId, turns] of served.sentRuns) {
1303
1401
  sentRuns.set(runId, turns);
1304
1402
  }
1305
1403
  return {
1306
1404
  sentRuns,
1307
- askedRuns: await this._runReplay.loadAsked({ holder: LOCAL_HOLDER, chatId }),
1308
- readRuns: served.readRuns
1405
+ askedRuns,
1406
+ readRuns: served.readRuns,
1407
+ rebuild: await this._runReplay.rebuild({ holder: LOCAL_HOLDER, chatId })
1309
1408
  };
1310
1409
  }
1311
1410
  catch (err) {
1312
1411
  this._log?.warn('assistant', 'run replay unreadable', { chatId, err });
1313
1412
  await this._deleteChatKvCache(chatId, 'run replay unreadable');
1314
- return { sentRuns: new Map(), askedRuns: new Map(), readRuns: new Map() };
1413
+ return {
1414
+ sentRuns: new Map(),
1415
+ askedRuns: new Map(),
1416
+ readRuns: new Map(),
1417
+ rebuild: await this._runReplay.rebuild({ holder: LOCAL_HOLDER, chatId })
1418
+ };
1315
1419
  }
1316
1420
  }
1317
1421
  async _recordSentRun(chatId, { runId, turns, asked }) {
@@ -1331,7 +1435,7 @@ export class QvacAssistant extends ReadyResource {
1331
1435
  }
1332
1436
  async _deleteChatKvCache(chatId, reason) {
1333
1437
  try {
1334
- const result = await this.deleteChatKvCache(chatId);
1438
+ const result = await this._reclaimChatKvCache(chatId, reason);
1335
1439
  if (result.status === 'failure') {
1336
1440
  this._log?.warn('assistant', 'chat kv-cache deletion failed', {
1337
1441
  chatId,
@@ -1414,7 +1518,8 @@ export class QvacAssistant extends ReadyResource {
1414
1518
  }
1415
1519
  _meshConsumer(meshId, served) {
1416
1520
  const watches = [
1417
- this._streamWatch(`chat-list:${meshId}`, () => this._engine.chatsWatch({ meshId }), (frames) => this._reclaimDeletedChats(frames, served ? meshId : null))
1521
+ this._streamWatch(`chat-list:${meshId}`, () => this._engine.chatsWatch({ meshId }), (frames) => this._reclaimDeletedChats(frames, meshId, served)),
1522
+ this._streamWatch(`kv-cache-retention:${meshId}`, () => this._engine.configWatch({ key: KV_CACHE_RETENTION_KEY }), (frames) => this._sweepIdleChatCaches(meshId, frames))
1418
1523
  ];
1419
1524
  if (!served) {
1420
1525
  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 +1603,93 @@ export class QvacAssistant extends ReadyResource {
1498
1603
  }
1499
1604
  this._seen.set(runId, meshId);
1500
1605
  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;
1606
+ const chat = `${meshId}:${request.chatId}`;
1607
+ const scheduled = (this._intake.get(chat) ?? Promise.resolve()).then(() => this._schedule(engine, request, { runId, meshId, chat }));
1608
+ const turn = scheduled.then(noop, noop);
1609
+ this._intake.set(chat, turn);
1610
+ void turn.then(() => {
1611
+ if (this._intake.get(chat) === turn) {
1612
+ this._intake.delete(chat);
1507
1613
  }
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;
1523
- }
1524
- if (!drivenBy({ request, agent }, deviceId)) {
1525
- return;
1526
- }
1527
- if (await this._isHandled(engine, request)) {
1614
+ });
1615
+ const settle = (async () => {
1616
+ const run = await scheduled;
1617
+ if (!run) {
1528
1618
  return;
1529
1619
  }
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
1620
  try {
1548
- await done;
1621
+ await run.done;
1549
1622
  }
1550
1623
  finally {
1551
1624
  this._runImageCacheNames.delete(runId);
1552
1625
  this._runs.delete(runId);
1553
1626
  this._runsChanged();
1554
- if (this._chats.get(request.chatId) === link) {
1555
- this._chats.delete(request.chatId);
1627
+ if (this._chats.get(chat) === run.link) {
1628
+ this._chats.delete(chat);
1556
1629
  }
1557
1630
  void this._reportCapabilities();
1558
- this._requeue(runId, controller.signal.reason, () => this._dispatch(request, meshId));
1631
+ this._requeue(runId, run.controller.signal.reason, () => this._dispatch(run.request, meshId));
1559
1632
  }
1560
1633
  })();
1561
1634
  settle.catch((err) => this._log?.error('assistant', `run ${runId} failed`, err));
1562
1635
  }
1636
+ async _schedule(engine, request, { runId, meshId, chat }) {
1637
+ const claim = await this._claim(engine, request, { runId, meshId });
1638
+ if (!claim) {
1639
+ return undefined;
1640
+ }
1641
+ const { agent } = claim;
1642
+ const controller = new AbortController();
1643
+ const prior = this._chats.get(chat) ?? Promise.resolve();
1644
+ const done = prior.then(() => this._execute(claim.request, agent, { controller, meshId, runId }));
1645
+ const link = done.catch(noop);
1646
+ this._chats.set(chat, link);
1647
+ this._runs.set(runId, {
1648
+ controller,
1649
+ done,
1650
+ meshId,
1651
+ chatId: claim.request.chatId,
1652
+ agentId: agent.id,
1653
+ model: agent.modelName,
1654
+ executing: false
1655
+ });
1656
+ return { request: claim.request, controller, done, link };
1657
+ }
1658
+ async _claim(engine, request, { runId, meshId }) {
1659
+ const agentId = request.runRequest?.agentId;
1660
+ const agent = agentId ? await engine.getAgent({ agentId }).catch(noop) : undefined;
1661
+ if (!agent) {
1662
+ this._seen.delete(runId);
1663
+ return undefined;
1664
+ }
1665
+ const deviceId = this._requireDeviceId();
1666
+ if (offeredTo(request, deviceId) && !(await this._isHandled(engine, request))) {
1667
+ if (this._backgrounded) {
1668
+ this._seen.delete(runId);
1669
+ if (this._state === QvacState.PRESUSPEND) {
1670
+ this._parked.set(runId, () => this._dispatch(request, meshId));
1671
+ }
1672
+ return undefined;
1673
+ }
1674
+ const taken = await engine.takeRunRequest({ chunkId: request.id }).catch(noop);
1675
+ if (!taken) {
1676
+ this._seen.delete(runId);
1677
+ return undefined;
1678
+ }
1679
+ request = taken;
1680
+ }
1681
+ if (!drivenBy({ request, agent }, deviceId)) {
1682
+ return undefined;
1683
+ }
1684
+ if (await this._isHandled(engine, request)) {
1685
+ return undefined;
1686
+ }
1687
+ this._log?.info('runs', 'run claimed', { runId, chatId: request.chatId, agentId });
1688
+ if (!request.capability) {
1689
+ await this._offerSteer(engine, request, agent.id);
1690
+ }
1691
+ return { request, agent };
1692
+ }
1563
1693
  async _offerSteer(engine, request, agentId) {
1564
1694
  const running = [...this._runs.values()].find((run) => run.chatId === request.chatId && run.agentId === agentId && run.steering);
1565
1695
  if (!running?.steering || !request.runId) {
@@ -1591,7 +1721,7 @@ export class QvacAssistant extends ReadyResource {
1591
1721
  return;
1592
1722
  }
1593
1723
  try {
1594
- await transcript.chunk({ type: 'sources', sources: { sources: records } });
1724
+ await transcript.chunk({ type: 'sources', sources: { sources: chunkSources(records) } });
1595
1725
  }
1596
1726
  catch (err) {
1597
1727
  this._log?.warn('assistant', 'web sources chunk skipped', { runId, err });
@@ -1757,7 +1887,8 @@ export class QvacAssistant extends ReadyResource {
1757
1887
  await this._deleteChatKvCache(chatId, 'superseding run');
1758
1888
  }
1759
1889
  }
1760
- const model = runnableModelName(agent.modelName, await this._runnableHost());
1890
+ const servedElsewhere = !b4a.equals(agent.providerDeviceId, deviceId);
1891
+ const model = await this._runModel(agent, deviceId);
1761
1892
  if (model !== agent.modelName) {
1762
1893
  this._log?.warn('runs', 'model clamped to what this device can run', {
1763
1894
  runId,
@@ -1792,7 +1923,8 @@ export class QvacAssistant extends ReadyResource {
1792
1923
  agentId: agent.id,
1793
1924
  deviceId,
1794
1925
  from: request.seq,
1795
- media: (file) => this._mediaRefs.get(path.basename(file))
1926
+ media: (file) => this._mediaRefs.get(path.basename(file)),
1927
+ inspect: (call) => void this._inspectRound(chatId, { runId, at: Date.now(), call })
1796
1928
  });
1797
1929
  const folded = !resumed &&
1798
1930
  (await this._compactIfNearFull({
@@ -1817,14 +1949,19 @@ export class QvacAssistant extends ReadyResource {
1817
1949
  type: 'approval-request'
1818
1950
  });
1819
1951
  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 &&
1952
+ const priorResults = all.filter((chunk) => chunk.type === 'tool-result');
1953
+ let ran = priorResults.some((chunk) => chunk.runId === runId &&
1822
1954
  chunk.toolResult?.name !== SKILL_TOOL &&
1823
1955
  !isDeniedResult(chunk.toolResult?.result));
1824
1956
  let replay = await this._sentRuns(chatId, await listRoundChunks(engine, chatId));
1825
1957
  if (!resumed && viewOutgrewCache(all, { request, runId }, replay.sentRuns)) {
1826
1958
  await this._deleteChatKvCache(chatId, 'a run outside the cached view');
1827
- replay = { sentRuns: new Map(), askedRuns: new Map(), readRuns: new Map() };
1959
+ replay = {
1960
+ sentRuns: new Map(),
1961
+ askedRuns: new Map(),
1962
+ readRuns: new Map(),
1963
+ rebuild: await this._runReplay.rebuild({ holder: LOCAL_HOLDER, chatId })
1964
+ };
1828
1965
  }
1829
1966
  const messages = historyFromChunks(history, stale, replay);
1830
1967
  const typedText = currentRepair
@@ -1853,7 +1990,8 @@ export class QvacAssistant extends ReadyResource {
1853
1990
  await this._storeVideoDigests(sampled.splice(0), { meshId, chatId, runId, deviceId });
1854
1991
  }
1855
1992
  };
1856
- let pdfPages = { rendered: new Set(), cuts: [] };
1993
+ let pdfPages = { rendered: new Set(), notices: [] };
1994
+ const selectedPdfs = [];
1857
1995
  if (!seesImages) {
1858
1996
  const dropped = messages.reduce((count, turn) => count + (turn.images?.length ?? 0), 0);
1859
1997
  if (dropped && (this._harness.supportsImages ?? this._info.supportsImages)) {
@@ -1875,12 +2013,30 @@ export class QvacAssistant extends ReadyResource {
1875
2013
  const ownershipWatch = this._watchOwnership(engine, { request, agentId: agent.id, controller });
1876
2014
  let readinessError = null;
1877
2015
  const held = { status: null };
2016
+ let shown = '';
2017
+ const showWait = (progress) => {
2018
+ const key = JSON.stringify(progress);
2019
+ if (key === shown || (!progress && !held.status)) {
2020
+ return;
2021
+ }
2022
+ shown = key;
2023
+ const runStatus = progress
2024
+ ? { state: 'executing', progress }
2025
+ : { state: 'executing' };
2026
+ if (!held.status) {
2027
+ held.status = transcript.status(runStatus, { resumed });
2028
+ return;
2029
+ }
2030
+ held.status.then(({ id }) => transcript.progress(id, runStatus)).catch(noop);
2031
+ };
1878
2032
  try {
1879
- await this._downloads?.waitUntilCached(model, controller.signal, {
1880
- onHold: () => {
1881
- held.status = transcript.status({ state: 'executing', progress: { phase: 'awaiting-download', model } }, { resumed });
1882
- }
1883
- });
2033
+ if (!servedElsewhere) {
2034
+ await this._downloads?.waitUntilCached(model, controller.signal, {
2035
+ onHold: () => showWait({ phase: 'awaiting-download', model }),
2036
+ onProgress: (percentage) => showWait(downloadingProgress(model, percentage)),
2037
+ onStall: () => showWait(null)
2038
+ });
2039
+ }
1884
2040
  }
1885
2041
  catch (err) {
1886
2042
  readinessError = err instanceof Error ? err : new Error(String(err));
@@ -1961,6 +2117,9 @@ export class QvacAssistant extends ReadyResource {
1961
2117
  const taken = new Set();
1962
2118
  let inputLength = 0;
1963
2119
  let asked;
2120
+ let primeRound;
2121
+ let primeTokens;
2122
+ let injectedHits = 0;
1964
2123
  const writeText = async (type, raw) => {
1965
2124
  const text = type === 'content' ? sourceTagFilter.push(raw) : raw;
1966
2125
  if (!text) {
@@ -1980,7 +2139,8 @@ export class QvacAssistant extends ReadyResource {
1980
2139
  }
1981
2140
  };
1982
2141
  const failRun = async (message) => {
1983
- const folded = isContextOverflowFailure(message) &&
2142
+ const overflowed = isContextOverflowFailure(message);
2143
+ const folded = overflowed &&
1984
2144
  (await this._runCompaction({
1985
2145
  chatId,
1986
2146
  transcript,
@@ -1990,9 +2150,14 @@ export class QvacAssistant extends ReadyResource {
1990
2150
  run: { request, runId },
1991
2151
  rounds
1992
2152
  }));
2153
+ const shrunk = overflowed && !folded && injectedHits > 1;
2154
+ if (shrunk) {
2155
+ this._knowledgeCaps.set(chatId, Math.floor(injectedHits / 2));
2156
+ this._log?.info('runs', 'knowledge shrunk for retry', { runId, hits: injectedHits });
2157
+ }
1993
2158
  runFailure = runFailureNotice(message);
1994
2159
  await transcript.status({ state: 'failed', reason: runFailure, metrics });
1995
- if (folded) {
2160
+ if (folded || shrunk) {
1996
2161
  await engine
1997
2162
  .runAgent({ chatId, agentId: agent.id, parentRunId: runId })
1998
2163
  .catch((err) => this._log?.warn('runs', 'compaction retry not queued', { runId, err }));
@@ -2062,7 +2227,10 @@ export class QvacAssistant extends ReadyResource {
2062
2227
  chatId,
2063
2228
  attachmentIds: attachTurnIds,
2064
2229
  signal: controller.signal,
2065
- preparing: modelWatch.documents
2230
+ preparing: (active) => {
2231
+ this._markPreparing(runId, active);
2232
+ modelWatch.documents(active);
2233
+ }
2066
2234
  })
2067
2235
  : null;
2068
2236
  if (controller.signal.aborted) {
@@ -2080,9 +2248,18 @@ export class QvacAssistant extends ReadyResource {
2080
2248
  await transcript.status({ state: 'failed', reason: outcome.reason, metrics });
2081
2249
  return;
2082
2250
  }
2083
- const injected = knowledge
2084
- ? await this._injectKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords })
2251
+ const cap = this._knowledgeCaps.get(chatId);
2252
+ this._knowledgeCaps.delete(chatId);
2253
+ const fitted = knowledge && cap ? { ...knowledge, hits: knowledge.hits.slice(0, cap) } : knowledge;
2254
+ const injected = fitted
2255
+ ? await this._injectKnowledge(fitted, {
2256
+ transcript,
2257
+ sourceTagFilter,
2258
+ retrievedRecords,
2259
+ pictured: seesImages && messages.some((turn) => turn.pdfs?.length)
2260
+ })
2085
2261
  : { documentsInjected: false, sourcesWritten: false, ragInjected: false };
2262
+ injectedHits = injected.ragInjected && fitted ? fitted.hits.length : 0;
2086
2263
  const hasAudio = messages.some((turn) => turn.audioAttachments?.length || turn.videos?.length);
2087
2264
  if (hasAudio) {
2088
2265
  modelWatch.transcribe(true);
@@ -2102,14 +2279,22 @@ export class QvacAssistant extends ReadyResource {
2102
2279
  }
2103
2280
  backfillImageOnlyTurns(messages);
2104
2281
  if (seesImages) {
2282
+ const hits = injected.documentsInjected && fitted ? fitted.hits : [];
2105
2283
  pdfPages = await this._hydratePdfPages(messages, {
2106
2284
  signal: controller.signal,
2107
2285
  runId,
2108
- window: { ctxSize: configuredAgent.ctxSize, modelName: model }
2286
+ window: { ctxSize: configuredAgent.ctxSize, modelName: model },
2287
+ reading: { chatId, meshId, folded },
2288
+ textChars: hits.reduce((chars, hit) => chars + hit.content.length, 0),
2289
+ wholeIds: new Set(hits
2290
+ .filter((hit) => !isTruncatedFullTextHit(hit))
2291
+ .map(fullTextAttachmentId)
2292
+ .filter((id) => id !== null)),
2293
+ selected: selectedPdfs
2109
2294
  });
2110
2295
  }
2111
2296
  annotateDocumentAttachments(messages);
2112
- for (const { turn, notice } of pdfPages.cuts) {
2297
+ for (const { turn, notice } of pdfPages.notices) {
2113
2298
  turn.content = `${turn.content}\n${notice}`;
2114
2299
  }
2115
2300
  const unreadIds = attachTurnIds.filter((id) => !pdfPages.rendered.has(id));
@@ -2162,6 +2347,7 @@ export class QvacAssistant extends ReadyResource {
2162
2347
  const input = resent ?? nameSenders(messages);
2163
2348
  inputLength = input.length;
2164
2349
  rounds.inputLength = inputLength;
2350
+ const sentImages = earlierImages(messages);
2165
2351
  const inspecting = await this._capturingInferenceCalls();
2166
2352
  steering = new RunInputQueue();
2167
2353
  const inflight = this._runs.get(runId);
@@ -2218,13 +2404,17 @@ export class QvacAssistant extends ReadyResource {
2218
2404
  taken.add(event.id);
2219
2405
  continue;
2220
2406
  }
2221
- if (event.type === 'metrics') {
2407
+ if (isHarnessEvent(event, 'metrics')) {
2222
2408
  const { type, ...rest } = event;
2223
2409
  metrics = rest;
2410
+ primeTokens = rest.rounds?.find((each) => each.round === primeRound)?.promptTokens;
2224
2411
  recordBackends(this._backendUse, rest.backends);
2225
2412
  this._log?.info('runs', 'run metrics', { runId, ...runMetricsSummary(rest) });
2226
2413
  continue;
2227
2414
  }
2415
+ if (event.type === 'inference-sent' && event.outcome === 'overflowed') {
2416
+ this._log?.info('runs', 'context overflow', { runId, reason: event.reason });
2417
+ }
2228
2418
  if (event.type === 'inference-sent') {
2229
2419
  this._inspectSent(inspecting, chatId, {
2230
2420
  runId,
@@ -2239,6 +2429,8 @@ export class QvacAssistant extends ReadyResource {
2239
2429
  if (event.type === 'inference-call') {
2240
2430
  const call = asRecord(event.call);
2241
2431
  sentRun?.observe(call);
2432
+ primeRound ??= sentRun?.onKey ? Number(call.round ?? 0) : undefined;
2433
+ modelWatch.request(call.messages, sentImages);
2242
2434
  this._inspectCall(inspecting, chatId, { runId, at: Date.now(), call });
2243
2435
  continue;
2244
2436
  }
@@ -2305,19 +2497,25 @@ export class QvacAssistant extends ReadyResource {
2305
2497
  const citedTitles = injected.ragInjected
2306
2498
  ? citedByPhraseOverlap([...answers.values()].join(''), retrievedRecords)
2307
2499
  : null;
2500
+ const primedHere = !!sentRun?.used && rounds.ranHere(primeRound);
2501
+ const primed = primedHere ? replay.rebuild : null;
2502
+ if (primedHere) {
2503
+ await this._runReplay.consume({ holder: LOCAL_HOLDER, chatId });
2504
+ }
2308
2505
  if (sentRun?.used && !rounds.rounds) {
2309
2506
  await this._recordSentRun(chatId, { runId, turns: sentRun.turns(inputLength), asked });
2310
2507
  }
2311
2508
  sentRun = null;
2312
2509
  await transcript.status({
2313
2510
  state: 'completed',
2314
- metrics: citedTitles ? { ...metrics, citedTitles } : metrics
2511
+ metrics: withCacheRebuild(citedTitles ? { ...metrics, citedTitles } : metrics, primed, primeTokens ?? null)
2315
2512
  });
2316
2513
  titleOutcome = 'completed';
2317
2514
  for (const id of taken) {
2318
2515
  this._steered.set(id, runId);
2319
2516
  }
2320
2517
  await this._storeVideoDigests(sampled, { meshId, chatId, runId, deviceId });
2518
+ await this._storePdfSelections(selectedPdfs, { meshId, chatId, runId, deviceId });
2321
2519
  }
2322
2520
  catch (err) {
2323
2521
  const outcome = controller.signal.aborted
@@ -2361,12 +2559,14 @@ export class QvacAssistant extends ReadyResource {
2361
2559
  const answerText = [...answers.values()].join('');
2362
2560
  void this._autoTitle(engine, {
2363
2561
  chatId,
2562
+ history,
2364
2563
  messages,
2365
2564
  model,
2366
2565
  agent: runAgent,
2367
2566
  probe: completed,
2368
2567
  rounds
2369
- }).then(() => completed && answerText.trim()
2568
+ })
2569
+ .then(() => completed && answerText.trim()
2370
2570
  ? this._suggestNext(engine, {
2371
2571
  chatId,
2372
2572
  runId,
@@ -2376,7 +2576,8 @@ export class QvacAssistant extends ReadyResource {
2376
2576
  agent: runAgent,
2377
2577
  rounds
2378
2578
  })
2379
- : undefined);
2579
+ : undefined)
2580
+ .catch((err) => this._log?.warn('runs', 'title or suggestion skipped', { chatId, err }));
2380
2581
  }
2381
2582
  }
2382
2583
  }
@@ -2400,6 +2601,8 @@ export class QvacAssistant extends ReadyResource {
2400
2601
  const modelWatch = this._watchModelProgress((runStatus) => transcript.progress(executing.id, runStatus));
2401
2602
  const settledWatch = this._watchSettled(engine, { chatId, runId, controller });
2402
2603
  const ownershipWatch = this._watchOwnership(engine, { request, agentId: agent.id, controller });
2604
+ const idle = idleWatch(controller, this._runIdleTimeoutMs);
2605
+ idle.touch();
2403
2606
  let metrics;
2404
2607
  const endAbortedCapability = async () => {
2405
2608
  const outcome = this._abortOutcome(runId, controller.signal.reason);
@@ -2426,10 +2629,14 @@ export class QvacAssistant extends ReadyResource {
2426
2629
  agent,
2427
2630
  attach: (input) => this._uploadGenerated(input, { meshId, chatId, runId, deviceId }),
2428
2631
  fetchAttachment: (query) => this._fetchAttachment(engine, chatId, query),
2429
- progress: (update) => modelWatch.image(update),
2632
+ progress: (update) => {
2633
+ idle.touch();
2634
+ return modelWatch.image(update);
2635
+ },
2430
2636
  signal: controller.signal
2431
2637
  });
2432
2638
  for await (const event of events) {
2639
+ idle.touch();
2433
2640
  if (event.type === 'metrics') {
2434
2641
  const { type, ...rest } = event;
2435
2642
  metrics = rest;
@@ -2482,6 +2689,7 @@ export class QvacAssistant extends ReadyResource {
2482
2689
  }
2483
2690
  finally {
2484
2691
  transcript.close();
2692
+ idle.stop();
2485
2693
  modelWatch.stop();
2486
2694
  settledWatch.stop();
2487
2695
  ownershipWatch.stop();
@@ -2978,7 +3186,7 @@ export class QvacAssistant extends ReadyResource {
2978
3186
  return this._servedFrame(source, { frame: ref.frame, frames: ref.frames }, served);
2979
3187
  }
2980
3188
  if (ref.page !== undefined) {
2981
- return this._servedPage(attachment, ref.page, served);
3189
+ return this._servedPage(attachment, { page: ref.page, clip: ref.clip }, served);
2982
3190
  }
2983
3191
  served.pinned.add(imageCacheName(attachment));
2984
3192
  return this._hydrateImage(served.dir, attachment, served.signal);
@@ -2997,8 +3205,8 @@ export class QvacAssistant extends ReadyResource {
2997
3205
  const target = { dir, pinned, digestBlobId: digest.blobId };
2998
3206
  return (await this._cacheVideo(attachment, video, target)).files[frame] ?? null;
2999
3207
  }
3000
- async _servedPage(pdf, page, { dir, pinned, docs, signal }) {
3001
- const name = pdfPageCacheName(pdf, page);
3208
+ async _servedPage(pdf, { page, clip }, { dir, pinned, docs, signal }) {
3209
+ const name = pdfShotCacheName(pdf, { page, clip });
3002
3210
  pinned.add(name);
3003
3211
  const file = path.join(dir, name);
3004
3212
  const rendered = await cacheOrTouch(file, async () => {
@@ -3007,7 +3215,7 @@ export class QvacAssistant extends ReadyResource {
3007
3215
  doc = this._readBlob(pdf.url, signal).then((bytes) => bytes ? this._pdfRasterizer.open(bytes) : null);
3008
3216
  docs.set(pdf.id, doc);
3009
3217
  }
3010
- return (await doc)?.renderPage(page) ?? null;
3218
+ return (await doc)?.renderPage(page, clip) ?? null;
3011
3219
  });
3012
3220
  return rendered ? file : null;
3013
3221
  }
@@ -3026,39 +3234,41 @@ export class QvacAssistant extends ReadyResource {
3026
3234
  });
3027
3235
  return file;
3028
3236
  }
3029
- async _hydratePdfPages(messages, { signal, runId, window }) {
3237
+ async _hydratePdfPages(messages, { signal, runId, window, reading, textChars, wholeIds, selected }) {
3030
3238
  const rendered = new Set();
3031
- const cuts = [];
3239
+ const notices = [];
3032
3240
  const turns = messages.filter((turn) => turn.pdfs?.length);
3033
3241
  if (!turns.length) {
3034
- return { rendered, cuts };
3242
+ return { rendered, notices };
3035
3243
  }
3036
3244
  const dir = this._imageCacheDir;
3037
3245
  await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
3038
3246
  const pinned = this._runImageCacheNames.get(runId) ?? new Set();
3039
3247
  this._runImageCacheNames.set(runId, pinned);
3040
3248
  const latestUser = messages.findLast((turn) => turn.role === 'user');
3041
- const maxPages = await this._pdfPageBudget(window);
3249
+ const measured = await this._pdfReading(window, reading);
3042
3250
  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);
3251
+ const room = pdfImageRoom(measured, turn === latestUser ? textChars : 0);
3252
+ for (const pdf of turn.pdfs ?? []) {
3253
+ const pages = await this._tryHydratePdf({ dir, pdf, pinned, room, signal, selected });
3254
+ attachPages(turn, pages.names.map((name) => path.join(dir, name)));
3255
+ if (pages.names.length && turn === latestUser) {
3256
+ rendered.add(pdf.id);
3257
+ }
3258
+ const whole = turn === latestUser && wholeIds.has(pdf.id);
3259
+ for (const notice of pdfNotices(pdf.fileName, pages, whole)) {
3260
+ notices.push({ turn, notice });
3052
3261
  }
3053
3262
  }
3054
- cuts.push(...notices.map((notice) => ({ turn, notice })));
3263
+ delete turn.pdfs;
3055
3264
  }
3056
- return { rendered, cuts };
3265
+ return { rendered, notices };
3057
3266
  }
3058
- async _pdfPageBudget({ ctxSize, modelName }) {
3267
+ async _pdfReading({ ctxSize, modelName }, options) {
3059
3268
  const custom = await this._customModel(modelName);
3060
3269
  const window = effectiveCtxSize({ ctxSize, modelName }, { appCtxSize: 0, platform: this._platform, custom });
3061
- return pdfPageBudget(window);
3270
+ const { cacheTokens } = await this._contextReading(options, window);
3271
+ return { ctxSize: window, cacheTokens };
3062
3272
  }
3063
3273
  async _customModel(name) {
3064
3274
  for await (const list of this._engine.customModelsWatch({})) {
@@ -3066,114 +3276,107 @@ export class QvacAssistant extends ReadyResource {
3066
3276
  }
3067
3277
  return null;
3068
3278
  }
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) {
3279
+ async _tryHydratePdf(opts) {
3091
3280
  try {
3092
- return await this._hydratePdf(dir, turn, opts);
3281
+ return await this._hydratePdf(opts);
3093
3282
  }
3094
3283
  catch (err) {
3095
3284
  if (opts.signal.aborted) {
3096
3285
  throw err;
3097
3286
  }
3098
3287
  this._log?.warn('assistant', `pdf rasterization failed — ${opts.pdf.fileName}`, err);
3099
- return { names: [], tried: 0 };
3288
+ return NO_PDF_PAGES;
3100
3289
  }
3101
3290
  }
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);
3291
+ async _hydratePdf(hydration) {
3292
+ const { dir, pdf, pinned, room, signal, selected } = hydration;
3293
+ const key = pdf.pages?.blobId ?? pdf.id;
3294
+ const remember = (selection) => {
3295
+ this._pdfSelections.set(key, selection);
3296
+ for (const { page, clip } of selection.shots) {
3297
+ this._mediaRefs.set(pdfShotCacheName(pdf, { page, clip }), { id: pdf.id, page, clip });
3108
3298
  }
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;
3299
+ if (!pdf.pages) {
3300
+ selected.push({ ref: pdf, selection });
3301
+ }
3302
+ };
3303
+ const known = this._pdfSelections.get(key) ?? (await this._storedPdfSelection(pdf, signal));
3304
+ if (known) {
3305
+ remember(known);
3306
+ const cached = await cachedPdfPages(known, { dir, pdf, pinned });
3307
+ if (cached) {
3308
+ return cached;
3113
3309
  }
3114
3310
  }
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
3311
  const bytes = await this._readBlob(pdf.url, signal);
3125
3312
  if (signal.aborted) {
3126
3313
  throw new Error('hydration aborted');
3127
3314
  }
3128
- if (!bytes) {
3129
- return null;
3130
- }
3131
- const doc = await this._pdfRasterizer.open(bytes);
3315
+ const doc = bytes ? await this._pdfRasterizer.open(bytes) : null;
3132
3316
  if (!doc) {
3133
- return { names: [], tried: 0 };
3317
+ return NO_PDF_PAGES;
3134
3318
  }
3135
3319
  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
- }
3320
+ const selection = known ?? (await selectPdfPages(doc, room));
3321
+ if (!known) {
3322
+ remember(selection);
3150
3323
  }
3151
- return { names, tried, cut: pdfCut(doc, page) };
3324
+ return await this._renderPdfShots(doc, selection, hydration);
3152
3325
  }
3153
3326
  finally {
3154
3327
  doc.close();
3155
3328
  }
3156
3329
  }
3157
- async _renderPdfPage(doc, { dir, pdf, page, pinned, signal }) {
3158
- let tried = false;
3330
+ async _storedPdfSelection(pdf, signal) {
3331
+ const bytes = pdf.pages ? await this._readBlob(pdf.pages.url, signal) : null;
3332
+ if (!bytes) {
3333
+ return null;
3334
+ }
3159
3335
  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 };
3336
+ return parsePdfSelection(bytes);
3170
3337
  }
3171
3338
  catch (err) {
3172
- if (signal.aborted) {
3173
- throw err;
3339
+ this._log?.warn('assistant', `pdf page choice unreadable — ${pdf.fileName}`, err);
3340
+ return null;
3341
+ }
3342
+ }
3343
+ async _renderPdfShots(doc, selection, { dir, pdf, pinned, signal }) {
3344
+ const names = [];
3345
+ const labels = [];
3346
+ for (const shot of selection.shots) {
3347
+ if (signal.aborted)
3348
+ throw new Error('hydration aborted');
3349
+ const name = pdfShotCacheName(pdf, shot);
3350
+ pinned.add(name);
3351
+ try {
3352
+ const file = path.join(dir, name);
3353
+ if (await cacheOrTouch(file, () => doc.renderPage(shot.page, shot.clip))) {
3354
+ names.push(name);
3355
+ labels.push(shot.label);
3356
+ }
3357
+ }
3358
+ catch (err) {
3359
+ if (signal.aborted) {
3360
+ throw err;
3361
+ }
3362
+ this._log?.warn('assistant', `pdf page skipped — ${pdf.fileName} p${shot.page}`, err);
3363
+ }
3364
+ }
3365
+ return { selection, names, labels };
3366
+ }
3367
+ async _storePdfSelections(selected, target) {
3368
+ for (const { ref, selection } of selected) {
3369
+ try {
3370
+ await this._uploadGenerated({
3371
+ fileName: pdfSelectionFileName(ref.fileName),
3372
+ mimeType: PDF_PAGES_MIME,
3373
+ bytes: packPdfSelection(selection),
3374
+ raw: true
3375
+ }, { ...target, sourceId: ref.id });
3376
+ }
3377
+ catch (err) {
3378
+ this._log?.warn('assistant', `pdf page choice not stored — ${ref.fileName}`, err);
3174
3379
  }
3175
- this._log?.warn('assistant', `pdf page skipped — ${pdf.fileName} p${page}`, err);
3176
- return { tried };
3177
3380
  }
3178
3381
  }
3179
3382
  async _compactIfNearFull(params) {
@@ -3287,14 +3490,14 @@ export class QvacAssistant extends ReadyResource {
3287
3490
  if (!agent || !(options.run || b4a.equals(agent.providerDeviceId, deviceId))) {
3288
3491
  return { compacted: false, reason: 'not the provider device' };
3289
3492
  }
3290
- const model = runnableModelName(agent.modelName, await this._runnableHost());
3493
+ const model = await this._runModel(agent, deviceId);
3291
3494
  const config = await engine.getConfig({}).catch(noop);
3292
3495
  const ctxSize = agent.ctxSize || config?.ctxSize || undefined;
3293
3496
  if (ctxSize !== undefined && !canCompact(ctxSize)) {
3294
3497
  return { compacted: false, reason: 'below-floor' };
3295
3498
  }
3296
3499
  const all = await listHistoryChunks(engine, chatId);
3297
- const stored = options.run ? foldableView(all, options.run) : all;
3500
+ const stored = foldableView(all, options.run);
3298
3501
  const branches = historyBranches(stored);
3299
3502
  const chunks = stored.filter((chunk) => isPromptChunk(chunk, branches));
3300
3503
  const { chunks: priorAsks } = await engine
@@ -3302,11 +3505,12 @@ export class QvacAssistant extends ReadyResource {
3302
3505
  .catch(() => ({ chunks: [] }));
3303
3506
  const lastThroughId = lastCompactedThroughId(chunks);
3304
3507
  const lastThroughSeq = all.find((chunk) => chunk.id === lastThroughId)?.seq ?? -1;
3305
- const userTurns = chunks.filter((chunk) => chunk.userMessage).length;
3508
+ const beforeSeq = options.run?.request.seq ?? Infinity;
3509
+ const userTurns = chunks.filter((chunk) => chunk.userMessage && chunk.seq < beforeSeq).length;
3306
3510
  let announced = false;
3307
3511
  let keepTurns = COMPACTION_KEEP_TURNS;
3308
3512
  for (;;) {
3309
- const boundary = compactionBoundary(chunks, keepTurns);
3513
+ const boundary = compactionBoundary(chunks, keepTurns, beforeSeq);
3310
3514
  if (!boundary) {
3311
3515
  return { compacted: false, reason: 'nothing-to-fold' };
3312
3516
  }
@@ -3317,7 +3521,8 @@ export class QvacAssistant extends ReadyResource {
3317
3521
  if (through.seq <= lastThroughSeq) {
3318
3522
  return { compacted: false, reason: 'already-compacted' };
3319
3523
  }
3320
- const inRange = chunks.filter((chunk) => chunk.seq <= through.seq);
3524
+ const folds = foldsThrough(chunks, through);
3525
+ const inRange = chunks.filter((chunk) => chunk.compaction || folds(chunk));
3321
3526
  const folded = historyFromChunks(inRange, staleToolRunIds(inRange, priorAsks ?? [], ''));
3322
3527
  if (!announced) {
3323
3528
  await options.onFold?.();
@@ -3418,9 +3623,10 @@ export class QvacAssistant extends ReadyResource {
3418
3623
  return { summary: null, overflowed: isContextOverflowFailure(failed) };
3419
3624
  }
3420
3625
  }
3421
- async _autoTitle(engine, { chatId, messages, model, agent, probe, rounds }) {
3626
+ async _autoTitle(engine, { chatId, history, messages, model, agent, probe, rounds }) {
3422
3627
  try {
3423
- const first = messages.find((turn) => turn.role === 'user' && turn.content.trim());
3628
+ const first = history.find((chunk) => chunk.userMessage?.text.trim())?.userMessage?.text ??
3629
+ messages.find((turn) => turn.role === 'user' && turn.content.trim())?.content;
3424
3630
  if (!first) {
3425
3631
  return;
3426
3632
  }
@@ -3428,15 +3634,7 @@ export class QvacAssistant extends ReadyResource {
3428
3634
  if (!isDefaultChatTitle(chat?.title)) {
3429
3635
  return;
3430
3636
  }
3431
- await this._generateChatTitle({
3432
- engine,
3433
- chatId,
3434
- input: first.content,
3435
- model,
3436
- agent,
3437
- probe,
3438
- rounds
3439
- });
3637
+ await this._generateChatTitle({ engine, chatId, input: first, model, agent, probe, rounds });
3440
3638
  }
3441
3639
  catch (err) {
3442
3640
  this._log?.warn('runs', 'auto-title skipped', { chatId, err });
@@ -3671,6 +3869,7 @@ export class QvacAssistant extends ReadyResource {
3671
3869
  toolName: call.name,
3672
3870
  resource: call.resource,
3673
3871
  agentId,
3872
+ chatId,
3674
3873
  memberId: ourMemberId
3675
3874
  });
3676
3875
  if (rule) {
@@ -3806,15 +4005,19 @@ export class QvacAssistant extends ReadyResource {
3806
4005
  _watchOwnership(engine, { request, agentId, controller }) {
3807
4006
  const deviceId = this._requireDeviceId();
3808
4007
  const watches = [
3809
- this._abortOnLoss(engine.agentsWatch({}), controller, ({ agents }) => {
4008
+ this._abortOnLoss(engine.agentsWatch({}), controller, async ({ agents }) => {
3810
4009
  const row = (agents ?? []).find((a) => a.id === agentId);
3811
- return !row || !!row.deletedAt || !drivenBy({ request, agent: row }, deviceId);
4010
+ if (row && !row.deletedAt) {
4011
+ return drivenBy({ request, agent: row }, deviceId) ? null : OWNERSHIP_LOST;
4012
+ }
4013
+ const chat = await engine.getChat({ chatId: request.chatId }).catch(noop);
4014
+ return !chat || chat.agentId === agentId ? AGENT_REMOVED : null;
3812
4015
  })
3813
4016
  ];
3814
4017
  if (request.runnerDeviceId) {
3815
4018
  watches.push(this._abortOnLoss(engine.runRequestsWatch({}), controller, ({ chunks }) => {
3816
4019
  const now = (chunks ?? []).find((chunk) => chunk.id === request.id);
3817
- return !now?.runTakenBy || !b4a.equals(now.runTakenBy, deviceId);
4020
+ return !now?.runTakenBy || !b4a.equals(now.runTakenBy, deviceId) ? OWNERSHIP_LOST : null;
3818
4021
  }));
3819
4022
  }
3820
4023
  return {
@@ -3829,8 +4032,9 @@ export class QvacAssistant extends ReadyResource {
3829
4032
  if (done) {
3830
4033
  return;
3831
4034
  }
3832
- if (lost(value)) {
3833
- controller.abort(OWNERSHIP_LOST);
4035
+ const reason = await lost(value);
4036
+ if (reason) {
4037
+ controller.abort(reason);
3834
4038
  return;
3835
4039
  }
3836
4040
  }
@@ -3854,7 +4058,15 @@ export class QvacAssistant extends ReadyResource {
3854
4058
  }
3855
4059
  }
3856
4060
  _generating() {
3857
- return [...this._runs.values()].some((run) => run.executing);
4061
+ return [...this._runs.values()].some((run) => run.executing && !run.preparing);
4062
+ }
4063
+ _markPreparing(runId, preparing) {
4064
+ const run = this._runs.get(runId);
4065
+ if (!run) {
4066
+ return;
4067
+ }
4068
+ this._runs.set(runId, { ...run, preparing });
4069
+ this._runsChanged();
3858
4070
  }
3859
4071
  idle(signal) {
3860
4072
  if (signal.aborted || !this._generating()) {
@@ -3899,6 +4111,7 @@ export class QvacAssistant extends ReadyResource {
3899
4111
  let transcribing = false;
3900
4112
  let documents = false;
3901
4113
  let sampling = false;
4114
+ let analyzing = false;
3902
4115
  const apply = (progress) => {
3903
4116
  const runStatus = progress
3904
4117
  ? { state: 'executing', progress }
@@ -3906,12 +4119,15 @@ export class QvacAssistant extends ReadyResource {
3906
4119
  if (documents) {
3907
4120
  runStatus.reason = 'preparing-documents';
3908
4121
  }
4122
+ else if (analyzing && !progress) {
4123
+ runStatus.reason = 'analyzing-images';
4124
+ }
3909
4125
  const key = JSON.stringify(runStatus);
3910
4126
  if (key === last) {
3911
4127
  return;
3912
4128
  }
3913
4129
  last = key;
3914
- showing = progress !== null || documents;
4130
+ showing = progress !== null || runStatus.reason !== undefined;
3915
4131
  update(runStatus).catch(noop);
3916
4132
  };
3917
4133
  const onModel = (state) => {
@@ -3924,8 +4140,7 @@ export class QvacAssistant extends ReadyResource {
3924
4140
  apply({ phase: 'awaiting-download', model: state.model });
3925
4141
  }
3926
4142
  else if (state.status === 'downloading') {
3927
- const percentage = Math.floor((state.percentage ?? 0) / 10) * 10;
3928
- apply({ phase: 'downloading', model: state.model, percentage });
4143
+ apply(downloadingProgress(state.model, state.percentage ?? 0));
3929
4144
  }
3930
4145
  else {
3931
4146
  apply(transcribing ? { phase: 'transcribing' } : null);
@@ -3950,9 +4165,16 @@ export class QvacAssistant extends ReadyResource {
3950
4165
  }
3951
4166
  apply({ phase: 'generating', percentage: Math.floor(progress.percentage / 10) * 10 });
3952
4167
  },
4168
+ request: (messages, sent) => {
4169
+ if (claimNewImages(messages, sent)) {
4170
+ analyzing = true;
4171
+ apply(null);
4172
+ }
4173
+ },
3953
4174
  stop: () => this._harness.off?.('model', onModel),
3954
4175
  clear: () => {
3955
4176
  sampling = false;
4177
+ analyzing = false;
3956
4178
  if (!showing) {
3957
4179
  return;
3958
4180
  }
@@ -3990,7 +4212,13 @@ function notReadyLine(search) {
3990
4212
  function filesCount(count, source) {
3991
4213
  return `${count} ${source} file${count === 1 ? '' : 's'}`;
3992
4214
  }
3993
- async function injectRetrievedKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords, injected }) {
4215
+ function chunkSources(records) {
4216
+ return records.map((record) => ({ ...record, page: record.page ?? 0 }));
4217
+ }
4218
+ function downloadingProgress(model, percentage) {
4219
+ return { phase: 'downloading', model, percentage: Math.floor(percentage / 10) * 10 };
4220
+ }
4221
+ async function injectRetrievedKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords, pictured, injected }) {
3994
4222
  const records = sourcesFromHits(knowledge.hits, RAG_SOURCE_BOUNDS);
3995
4223
  const notice = chooseRagNotice({
3996
4224
  errorMessage: knowledge.search.errorMessage,
@@ -4009,11 +4237,17 @@ async function injectRetrievedKnowledge(knowledge, { transcript, sourceTagFilter
4009
4237
  })));
4010
4238
  await transcript.chunk({
4011
4239
  type: 'sources',
4012
- sources: { sources: records, notice: notice ?? undefined, ...notReady(knowledge.search) }
4240
+ sources: {
4241
+ sources: chunkSources(records),
4242
+ notice: notice ?? undefined,
4243
+ ...notReady(knowledge.search)
4244
+ }
4013
4245
  });
4014
4246
  injected.sourcesWritten = true;
4015
4247
  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}`;
4248
+ const framing = formatRagContext(knowledge.hits, knowledge.search.availableFiles ?? []);
4249
+ const pages = pictured ? `\n${PDF_PAGES_SOURCE_LINE}` : '';
4250
+ knowledge.lastUser.content = `${framing}${pages}\n\nThe user's message:\n${knowledge.lastUser.content}\n\n${RAG_CITATION_LINE}`;
4017
4251
  injected.ragInjected = true;
4018
4252
  injected.documentsInjected = true;
4019
4253
  }
@@ -4035,7 +4269,7 @@ function toolCallChunk(event) {
4035
4269
  function toolResultChunk(event) {
4036
4270
  return {
4037
4271
  type: 'tool-result',
4038
- toolResult: { name: event.name, result: withoutDataChannel(event.result) },
4272
+ toolResult: { name: event.name, result: withoutDataChannel(event.result) ?? null },
4039
4273
  ...callOf(event)
4040
4274
  };
4041
4275
  }
@@ -4065,6 +4299,9 @@ function runMetricsSummary(metrics) {
4065
4299
  stopReason
4066
4300
  };
4067
4301
  }
4302
+ function withCacheRebuild(metrics, reason, tokens) {
4303
+ return reason === null ? metrics : { ...metrics, cacheRebuild: { reason, tokens } };
4304
+ }
4068
4305
  function asRecord(value) {
4069
4306
  return isRecord(value) ? { ...value } : {};
4070
4307
  }