@qvac/core 0.11.1 → 0.11.2

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 (50) hide show
  1. package/CHANGELOG.md +69 -1
  2. package/README.md +19 -16
  3. package/dist-lib/lib/api/chunks.js +4 -2
  4. package/dist-lib/lib/api/rag.js +7 -5
  5. package/dist-lib/lib/assistant/history.d.ts +1 -0
  6. package/dist-lib/lib/assistant/history.js +0 -16
  7. package/dist-lib/lib/assistant-tree.d.ts +2 -0
  8. package/dist-lib/lib/assistant-tree.js +4 -2
  9. package/dist-lib/lib/assistant.d.ts +5 -1
  10. package/dist-lib/lib/assistant.js +63 -20
  11. package/dist-lib/lib/compaction.d.ts +2 -1
  12. package/dist-lib/lib/compaction.js +14 -4
  13. package/dist-lib/lib/constants.d.ts +3 -0
  14. package/dist-lib/lib/constants.js +3 -0
  15. package/dist-lib/lib/core/chat-activity.js +12 -15
  16. package/dist-lib/lib/core/chunk.d.ts +9 -1
  17. package/dist-lib/lib/core/chunk.js +42 -8
  18. package/dist-lib/lib/core/files/attachments.js +3 -3
  19. package/dist-lib/lib/core/files/index.js +2 -1
  20. package/dist-lib/lib/core/files/processing/index.d.ts +1 -0
  21. package/dist-lib/lib/core/files/processing/index.js +8 -0
  22. package/dist-lib/lib/core/files/processing/settle.d.ts +1 -0
  23. package/dist-lib/lib/core/files/processing/settle.js +20 -13
  24. package/dist-lib/lib/core/hosted-agents.d.ts +3 -0
  25. package/dist-lib/lib/core/hosted-agents.js +19 -0
  26. package/dist-lib/lib/core/notification.js +16 -13
  27. package/dist-lib/lib/core.d.ts +6 -0
  28. package/dist-lib/lib/core.js +5 -0
  29. package/dist-lib/lib/credential-pusher.d.ts +11 -7
  30. package/dist-lib/lib/credential-pusher.js +40 -8
  31. package/dist-lib/lib/integrations/setup-routes.js +7 -5
  32. package/dist-lib/lib/kv-cache-retention.d.ts +34 -0
  33. package/dist-lib/lib/kv-cache-retention.js +98 -0
  34. package/dist-lib/schema/content.js +2 -1
  35. package/dist-lib/schema/qvac.js +4 -2
  36. package/dist-lib/spec/hrpc/messages.js +4 -10
  37. package/dist-lib/spec/hyperschema/index.js +4 -10
  38. package/dist-lib/spec/hyperschema/schema.json +2 -1
  39. package/dist-lib/spec/hyperschema/types.d.ts +1 -1
  40. package/dist-lib/spec/mesh/hyperdb/messages.js +34 -14
  41. package/dist-lib/spec/mesh/hyperdispatch/messages.js +18 -8
  42. package/dist-lib/spec/mesh/hyperschema/index.js +18 -8
  43. package/dist-lib/spec/mesh/hyperschema/schema.json +11 -1
  44. package/dist-lib/spec/mesh/hyperschema/types.d.ts +3 -1
  45. package/package.json +5 -2
  46. package/tui/app.mjs +743 -266
  47. package/tui/boot.mjs +2 -2
  48. package/tui/lib/connect-sheet.mjs +350 -0
  49. package/tui/lib/setup.mjs +59 -25
  50. package/tui/lib/skill-connect.mjs +145 -0
package/CHANGELOG.md CHANGED
@@ -13,6 +13,73 @@ release.
13
13
 
14
14
  ## [Unreleased]
15
15
 
16
+ ## [0.11.2] - 2026-10-28
17
+
18
+ ### Added
19
+
20
+ - A chat's KV cache is deleted once the chat has been idle for the retention, so a device no
21
+ longer keeps the cache of every chat it ever ran. The chat itself is untouched; its next message
22
+ primes from history. An app sets its default with `kvCacheRetentionMs` on `assistantChild` (14
23
+ days without it, `0` for Never), and a device overrides it with `kvCache.retentionDays`. (#589)
24
+
25
+ ```js
26
+ import { assistantChild } from '@qvac/core'
27
+ import { KV_CACHE_RETENTION_KEY } from '@qvac/core/constants'
28
+
29
+ assistantChild({ harness, kvCacheRetentionMs: 30 * 24 * 60 * 60_000 })
30
+ await engine.configSet({ key: KV_CACHE_RETENTION_KEY, value: 7 })
31
+ ```
32
+
33
+ - Every credential a skill declares is pushed to the harness, not only the built-in keys and
34
+ OAuth tokens, so a skill with its own key no longer reads needs-setup for good and needs no core
35
+ release. Where a value may be sent is unchanged, and an overlay skill gets no credential. (#596)
36
+ - A credential with no setup block and no token provider gets a one-field token route named after
37
+ its key, so any setup UI can set it. (#591)
38
+ - `duck` sets a skill up through one sheet, opened by `/skill <name>`. (#592)
39
+
40
+ ### Changed
41
+
42
+ - `toolResult.result` is required on the wire, so a tool result of `false`, `0` or `''` reads
43
+ back as written from `listChunks` and `chunksWatch` instead of `null`. A device on 0.11.0 or
44
+ earlier, and a result one of those releases wrote, still read `null`. (#559)
45
+
46
+ ```js
47
+ // 0.11.1
48
+ { type: 'tool-result', toolResult: { name } }
49
+ // 0.11.2
50
+ { type: 'tool-result', toolResult: { name, result: null } }
51
+ ```
52
+
53
+ ### Removed
54
+
55
+ - `duck`'s `/cred`: every value is set through its skill's sheet. (#593)
56
+
57
+ ### Fixed
58
+
59
+ - Chat activity no longer diffs across a fast-forward it has not counted yet. It
60
+ dropped its cached view head only once `fastForwards` moved, which can be
61
+ after the view has landed on another core, and a diff from the old head read
62
+ every node of the new view. It now drops the head whenever the view is on
63
+ another core, as `chunksDeltaWatch` does. (#623)
64
+ - A device that does not hold a mesh no longer downloads most of it to show chat
65
+ activity and notifications. Both read a few chunk types per chat, each through
66
+ its type index and then row by row from `@qvac/chunks`; they now read the
67
+ chat's range of `@qvac/chat-chunks` once and keep those types, where that
68
+ range is whole. A member joining a 170-chat mesh with both open downloaded
69
+ about 39,000 blocks (155 MB) instead of 258,000 (640 MB), and on a device that
70
+ holds the mesh their first frames take 2.2 s and 3.7 s instead of 5.8 s and
71
+ 9.8 s. (#624)
72
+ - `compactChat` folds whole turns, so a chat whose messages were queued no longer keeps answers
73
+ without their questions. (#607)
74
+ - A run whose injected excerpts overflow the model window, with no older turns to fold, is retried
75
+ with half the excerpts instead of failing. (#599)
76
+ - `ragSearch` on a remote agent host waits for an attached file still replicating to it instead of
77
+ answering that the file is still being indexed. (#562)
78
+ - A chat whose first message carries a document is titled from the words the user typed, not the
79
+ document text. (#516)
80
+ - A re-homed agent's skill values are retried until the new host takes them; a host that refused
81
+ before it replicated the re-home left them unset. (#478)
82
+
16
83
  ## [0.11.1] - 2026-10-26
17
84
 
18
85
  ### Added
@@ -2003,7 +2070,8 @@ Published under the `release-0.1` dist-tag.
2003
2070
  await assistant.ready()
2004
2071
  ```
2005
2072
 
2006
- [Unreleased]: https://github.com/tetherto/qvac-core/compare/v0.11.1...HEAD
2073
+ [Unreleased]: https://github.com/tetherto/qvac-core/compare/v0.11.2...HEAD
2074
+ [0.11.2]: https://github.com/tetherto/qvac-core/compare/v0.11.1...v0.11.2
2007
2075
  [0.11.1]: https://github.com/tetherto/qvac-core/compare/v0.11.0...v0.11.1
2008
2076
  [0.11.0]: https://github.com/tetherto/qvac-core/compare/v0.10.4...v0.11.0
2009
2077
  [0.10.4]: https://github.com/tetherto/qvac-core/compare/v0.10.3...v0.10.4
package/README.md CHANGED
@@ -661,19 +661,23 @@ skill's `allow_list` binds that key to the URL prefixes it may be sent to.
661
661
  Credentials are **per agent** (stored at `skills.<agentId>.<key>`), so two
662
662
  agents never share one connection.
663
663
 
664
- Fill a key with a slash command in the running TUI — see
665
- [The duck TUI](#the-duck-tui):
666
-
667
- - `/connect google` · `/connect spotify` · `/connect asana` · `/connect notion` — browser OAuth;
668
- the example stores the token and refreshes it on use.
669
- - `/cred <key> <value>` — set any credential key by hand, for a service with
670
- no built-in OAuth flow.
671
-
672
- `/connect google` needs `GOOGLE_OAUTH_CLIENT_ID` + `GOOGLE_OAUTH_CLIENT_SECRET`
673
- in env, `/connect spotify` needs `SPOTIFY_OAUTH_CLIENT_ID`, `/connect asana` needs
674
- `ASANA_OAUTH_CLIENT_ID` + `ASANA_OAUTH_CLIENT_SECRET` (an MCP-type app registered
675
- at app.asana.com); `/connect notion` needs nothing — its MCP server self-provisions
676
- a public client via dynamic registration (RFC 7591) + PKCE.
664
+ Set a skill up in the running TUI — see [The duck TUI](#the-duck-tui):
665
+
666
+ - `/skill <name>` — opens the skill's setup: what it needs, its fields, and the
667
+ button that finishes it. OAuth skills sign in through the browser and refresh
668
+ on use; a token skill saves its token; a folder skill checks the folder exists.
669
+ Secrets are masked while typed and never reach the transcript or ↑ history.
670
+ - `/skill on <name>` — turning on a skill that needs setup opens it first; the
671
+ skill turns on once the setup succeeds. `/skills` does the same on space.
672
+ - `/skill <name> set <field> [value]` — set one field from a script.
673
+ - `/skill <name> disconnect` — remove what the skill stored.
674
+ - `/connect <name>` is the same sheet, signing in straight away.
675
+
676
+ An OAuth skill asks for its own client app (Client ID and, unless it is
677
+ PKCE-only, Client Secret), and its sheet walks through creating one. Leave the
678
+ fields blank to use `<PROVIDER>_OAUTH_CLIENT_ID` + `<PROVIDER>_OAUTH_CLIENT_SECRET`
679
+ from the env when both are set. Notion needs nothing — its MCP server
680
+ self-provisions a public client via dynamic registration (RFC 7591) + PKCE.
677
681
 
678
682
  ### Notion
679
683
 
@@ -681,13 +685,12 @@ Notion runs over its official MCP server (`https://mcp.notion.com/mcp`) via
681
685
  the `mcp_call` tool, under the credential key `notion_mcp_access_token`:
682
686
 
683
687
  ```
684
- /connect notion # authorize in the browser, pick the pages to share
685
- /skill on notion # if the agent's skill scope is 'selected'
688
+ /skill on notion # sign in through the browser, then the skill turns on
686
689
  ```
687
690
 
688
691
  Then ask the assistant anything Notion — it loads the `notion` skill and calls
689
692
  `mcp_call` itself; the session handshake and auth are handled for you. A `401`
690
- in a tool result means the token expired — run `/connect notion` again.
693
+ in a tool result means the token expired — run `/skill notion connect` again.
691
694
 
692
695
  ## Development
693
696
 
@@ -1,4 +1,4 @@
1
- import { appendChunk, listAttachmentsByKind, listChunks, listRunRequests, recordLinks, resolveApproval, updateChunk } from '../core/chunk.js';
1
+ import { appendChunk, listAttachmentsByKind, listChunks, listRunRequests, readChunk, recordLinks, resolveApproval, updateChunk } from '../core/chunk.js';
2
2
  import { chunkDeltaStream, chunkDeltas } from './chunk-delta.js';
3
3
  import { meshWatchable, requireMesh } from './current-mesh.js';
4
4
  import { bounds } from './range.js';
@@ -41,7 +41,9 @@ export function createChunksApi(pool, deviceId, log) {
41
41
  const watch = meshWatchable(pool, (_request, mesh) => deltas(mesh), { name: 'chunksDeltaWatch', log });
42
42
  return chunkDeltaStream(watch(request));
43
43
  },
44
- runRequestsWatch: meshWatchable(pool, async (_request, mesh) => ({ chunks: await listRunRequests(mesh, deviceId) }), { name: 'runRequestsWatch', log })
44
+ runRequestsWatch: meshWatchable(pool, async (_request, mesh) => ({
45
+ chunks: (await listRunRequests(mesh, deviceId)).map(readChunk)
46
+ }), { name: 'runRequestsWatch', log })
45
47
  };
46
48
  }
47
49
  function chunkSelection({ chatId, type, types, ...rest }) {
@@ -48,16 +48,15 @@ export function createRagApi(pool, { index, embedder, effectiveCtxSize = null })
48
48
  if (!toolMode && !agentAllowsRagSearch(agent)) {
49
49
  return respond({ enabled: false });
50
50
  }
51
- if (rows.length === 0) {
52
- return respond({});
53
- }
54
51
  const namedRows = referencedDocuments(query, rows.map((row) => ({ id: row.id, title: row.fileName })));
55
52
  const unscoped = namedRows.length ? namedRows : rows;
56
53
  const requested = scopeIds.size ? scopeRows : unscoped;
57
- const waiting = requested.filter((row) => !mesh.files.hydratedArtifact(row.id));
54
+ const waiting = scopeIds.size
55
+ ? [...scopeIds].filter((id) => !mesh.files.hydratedArtifact(id))
56
+ : requested.filter((row) => !mesh.files.hydratedArtifact(row.id)).map((row) => row.id);
58
57
  if (waiting.length) {
59
58
  try {
60
- await mesh.files.settle(waiting.map((row) => row.id));
59
+ await mesh.files.settle(waiting, { chatId });
61
60
  }
62
61
  catch (err) {
63
62
  mesh.log?.warn('rag', 'indexing settle failed', { err });
@@ -65,6 +64,9 @@ export function createRagApi(pool, { index, embedder, effectiveCtxSize = null })
65
64
  rows = await mesh.files.listKnowledge(chatId);
66
65
  scopeRows = rows.filter((row) => scopeIds.has(row.id));
67
66
  }
67
+ if (rows.length === 0) {
68
+ return respond({});
69
+ }
68
70
  const hasKnowledge = rows.length > 0;
69
71
  const vectorIndex = index(meshId);
70
72
  const embed = embedder(meshId);
@@ -16,6 +16,7 @@ export interface CompactOptions {
16
16
  readonly signal?: AbortSignal;
17
17
  readonly onFold?: () => Promise<void> | void;
18
18
  readonly meshId: string;
19
+ readonly requestSeq?: number;
19
20
  }
20
21
  export type CompactionTrigger = 'before-run' | 'overflow';
21
22
  export interface CompactResult {
@@ -136,12 +136,6 @@ export function historyFromChunks(chunks, stale = {}, { senderNames = new Map(),
136
136
  }
137
137
  return turn;
138
138
  };
139
- const foldedRequests = foldedRequestRuns(chunks, source);
140
- for (const chunk of source) {
141
- if (chunk.runId && foldedRequests.has(chunk.runId) && (chunk.content || chunk.toolResult)) {
142
- anchor(chunk.runId);
143
- }
144
- }
145
139
  const afterRun = (runId) => {
146
140
  let at = history.indexOf(anchor(runId)) + 1;
147
141
  while (history[at]?.role === 'tool') {
@@ -241,16 +235,6 @@ export function historyFromChunks(chunks, stale = {}, { senderNames = new Map(),
241
235
  }
242
236
  return history.filter((turn) => turn.role === 'user' || turn.content.length > 0 || kept.has(turn));
243
237
  }
244
- function foldedRequestRuns(chunks, kept) {
245
- const keptIds = new Set(kept.map((chunk) => chunk.id));
246
- const folded = new Set();
247
- for (const chunk of chunks) {
248
- if (chunk.type === 'run-request' && chunk.runId && !keptIds.has(chunk.id)) {
249
- folded.add(chunk.runId);
250
- }
251
- }
252
- return folded;
253
- }
254
238
  export function inputAvailableToRun(chunk, requestSeq) {
255
239
  const userInput = Boolean(chunk.userMessage || (chunk.attachment && !chunk.runId));
256
240
  return !userInput || chunk.seq < requestSeq;
@@ -26,6 +26,7 @@ export interface AssistantTreeOptions {
26
26
  runReplayDir?: string;
27
27
  imageCacheMaxBytes?: number;
28
28
  imageCacheMaxAgeMs?: number;
29
+ kvCacheRetentionMs?: number;
29
30
  embedder?: EmbedderFactory;
30
31
  extractors?: RagExtractors;
31
32
  onHarness?: OnHarness;
@@ -43,6 +44,7 @@ export interface AssistantChildOptions {
43
44
  runReplayDir?: string;
44
45
  imageCacheMaxBytes?: number;
45
46
  imageCacheMaxAgeMs?: number;
47
+ kvCacheRetentionMs?: number;
46
48
  embedder?: EmbedderFactory;
47
49
  extractors?: RagExtractors;
48
50
  onHarness?: OnHarness;
@@ -10,7 +10,7 @@ import { serveHarness } from '@qvac/harness';
10
10
  import { duplexPair } from '@qvac/harness/transport';
11
11
  import { lentHarness } from './lent-harness.js';
12
12
  export function assistantTree(opts) {
13
- const { core, harness, logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, embedder, extractors, onHarness, platform, preloadCurrentAgentModel, fakeModels = false } = opts;
13
+ const { core, harness, logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, kvCacheRetentionMs, embedder, extractors, onHarness, platform, preloadCurrentAgentModel, fakeModels = false } = opts;
14
14
  const sup = new Supervisor();
15
15
  const logged = ['child-died', 'child-restarting', 'child-ready', 'gave-up', 'stall'];
16
16
  for (const event of logged) {
@@ -80,6 +80,7 @@ export function assistantTree(opts) {
80
80
  runReplayDir,
81
81
  imageCacheMaxBytes,
82
82
  imageCacheMaxAgeMs,
83
+ kvCacheRetentionMs,
83
84
  platform,
84
85
  preloadCurrentAgentModel,
85
86
  drives: core.fsDrives ?? undefined,
@@ -243,7 +244,7 @@ export function assistantTree(opts) {
243
244
  return sup;
244
245
  }
245
246
  export function assistantChild(opts) {
246
- const { harness, core = 'core', logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, embedder, extractors, onHarness, preloadCurrentAgentModel, fakeModels, ...spec } = opts;
247
+ const { harness, core = 'core', logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, kvCacheRetentionMs, embedder, extractors, onHarness, preloadCurrentAgentModel, fakeModels, ...spec } = opts;
247
248
  return {
248
249
  ...spec,
249
250
  deps: [core],
@@ -257,6 +258,7 @@ export function assistantChild(opts) {
257
258
  runReplayDir,
258
259
  imageCacheMaxBytes,
259
260
  imageCacheMaxAgeMs,
261
+ kvCacheRetentionMs,
260
262
  embedder,
261
263
  extractors,
262
264
  onHarness,
@@ -25,6 +25,7 @@ export interface AssistantOptions {
25
25
  runReplayDir?: string;
26
26
  imageCacheMaxBytes?: number;
27
27
  imageCacheMaxAgeMs?: number;
28
+ kvCacheRetentionMs?: number;
28
29
  downloadRetryMs?: number;
29
30
  platform?: string;
30
31
  preloadCurrentAgentModel?: boolean;
@@ -95,6 +96,7 @@ export declare class QvacAssistant extends ReadyResource {
95
96
  private readonly _backgroundReplays;
96
97
  private readonly _inferenceCalls;
97
98
  private readonly _runReplay;
99
+ private readonly _kvRetention;
98
100
  private readonly _lifecycle;
99
101
  private readonly _audioTranscripts;
100
102
  private readonly _videoProbes;
@@ -103,10 +105,11 @@ export declare class QvacAssistant extends ReadyResource {
103
105
  private readonly _runImageCacheNames;
104
106
  private readonly _reconciledCompactions;
105
107
  private readonly _chatAttribution;
108
+ private readonly _knowledgeCaps;
106
109
  private readonly _modelCatalog;
107
110
  private readonly _onHarnessStatus;
108
111
  private readonly _onModelCatalogEvent;
109
- constructor(engine: Capabilities, harness: Harness, { logger, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, downloadRetryMs, platform, preloadCurrentAgentModel, drives, borrowHarness, blobReadTimeoutMs, runIdleTimeoutMs, modelReloadDelayMs, pdfRasterizer: pdfRasterizerOption }?: AssistantOptions);
112
+ constructor(engine: Capabilities, harness: Harness, { logger, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, kvCacheRetentionMs, downloadRetryMs, platform, preloadCurrentAgentModel, drives, borrowHarness, blobReadTimeoutMs, runIdleTimeoutMs, modelReloadDelayMs, pdfRasterizer: pdfRasterizerOption }?: AssistantOptions);
110
113
  private _requireDeviceId;
111
114
  _open(): Promise<void>;
112
115
  private _triggerModelWarm;
@@ -164,6 +167,7 @@ export declare class QvacAssistant extends ReadyResource {
164
167
  tools(): Promise<ReadonlyArray<ToolCatalogEntry>>;
165
168
  private _supervisedWatch;
166
169
  private _reclaimDeletedChats;
170
+ private _sweepIdleChatCaches;
167
171
  private _dropDeletedChat;
168
172
  private _followAgentEdits;
169
173
  private _reclaimAgentChatCaches;
@@ -35,7 +35,9 @@ import { fsGrantsFrom, grantedDirsFrom } from './fs-grants.js';
35
35
  import { persistentDir } from './persistent-dir.js';
36
36
  import { ModelCatalogRevisionHub } from './model-catalog-revision.js';
37
37
  import { agentRekeyFingerprint, agentSwitched, chatKvCacheKey, chatRepairKvCacheKey, disappearedChatIds } from './kv-cache-reclaim.js';
38
- import { buildCompactionPrompt, canCompact, foldReducesPrompt, COMPACTION_KEEP_TURNS, COMPACTION_TURN_PREFIX, isContextOverflowFailure, nearContextLimit, compactionBoundary, lastCompactedThroughId, parseCompactionSummary } from './compaction.js';
38
+ import { KvCacheRetention } from './kv-cache-retention.js';
39
+ import { KV_CACHE_RETENTION_KEY } from './constants.js';
40
+ import { buildCompactionPrompt, canCompact, foldReducesPrompt, COMPACTION_KEEP_TURNS, COMPACTION_TURN_PREFIX, isContextOverflowFailure, nearContextLimit, compactionBoundary, foldsThrough, lastCompactedThroughId, parseCompactionSummary } from './compaction.js';
39
41
  import { ModelDownloadReconciler, musicModelChoiceOf } from './model-download.js';
40
42
  import { AbortedError, raceAbort } from '@qvac/harness/race-abort';
41
43
  import { RunTranscript } from './run-transcript.js';
@@ -262,6 +264,7 @@ export class QvacAssistant extends ReadyResource {
262
264
  _backgroundReplays;
263
265
  _inferenceCalls;
264
266
  _runReplay;
267
+ _kvRetention;
265
268
  _lifecycle;
266
269
  _audioTranscripts;
267
270
  _videoProbes;
@@ -270,10 +273,11 @@ export class QvacAssistant extends ReadyResource {
270
273
  _runImageCacheNames;
271
274
  _reconciledCompactions;
272
275
  _chatAttribution;
276
+ _knowledgeCaps = new Map();
273
277
  _modelCatalog = new ModelCatalogRevisionHub();
274
278
  _onHarnessStatus;
275
279
  _onModelCatalogEvent;
276
- constructor(engine, harness, { logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, downloadRetryMs, platform = os.platform(), preloadCurrentAgentModel = true, drives, borrowHarness, blobReadTimeoutMs = BLOB_READ_TIMEOUT_MS, runIdleTimeoutMs = RUN_IDLE_TIMEOUT_MS, modelReloadDelayMs = MODEL_RELOAD_DELAY_MS, pdfRasterizer: pdfRasterizerOption } = {}) {
280
+ constructor(engine, harness, { logger = null, imageCacheDir, inferenceCallsDir, runReplayDir, imageCacheMaxBytes, imageCacheMaxAgeMs, kvCacheRetentionMs, downloadRetryMs, platform = os.platform(), preloadCurrentAgentModel = true, drives, borrowHarness, blobReadTimeoutMs = BLOB_READ_TIMEOUT_MS, runIdleTimeoutMs = RUN_IDLE_TIMEOUT_MS, modelReloadDelayMs = MODEL_RELOAD_DELAY_MS, pdfRasterizer: pdfRasterizerOption } = {}) {
277
281
  super();
278
282
  this._engine = engine;
279
283
  this._harness = harness;
@@ -314,6 +318,13 @@ export class QvacAssistant extends ReadyResource {
314
318
  this._backgroundReplays = new Set();
315
319
  this._inferenceCalls = new InferenceCallStore(inferenceCallsDir ?? persistentDir('inspector'));
316
320
  this._runReplay = new RunReplayStore(runReplayDir ?? persistentDir('run-replay'));
321
+ this._kvRetention = new KvCacheRetention(engine, {
322
+ active: () => !this.closing && !this.suspended,
323
+ running: (chatId) => [...this._runs.values()].some((run) => run.chatId === chatId),
324
+ deleteChatKvCache: (chatId) => this._deleteChatKvCache(chatId, 'idle past retention'),
325
+ defaultMs: kvCacheRetentionMs,
326
+ logger
327
+ });
317
328
  this._lifecycle = new AbortController();
318
329
  this._audioTranscripts = new Map();
319
330
  this._videoProbes = new Map();
@@ -388,6 +399,7 @@ export class QvacAssistant extends ReadyResource {
388
399
  this._downloads.start();
389
400
  this._meshListWatch.start();
390
401
  this._accountWatch.start();
402
+ this._kvRetention.start(() => this._meshConsumers.keys());
391
403
  void this._bootOnline();
392
404
  this._triggerModelWarm();
393
405
  void this.onlineReady().then(() => this._triggerModelWarm(), noop);
@@ -780,6 +792,7 @@ export class QvacAssistant extends ReadyResource {
780
792
  }
781
793
  async _close() {
782
794
  this._stopMeshIntake();
795
+ this._kvRetention.stop();
783
796
  this._harness.off?.('status', this._onHarnessStatus);
784
797
  this._harness.off?.('model', this._onModelCatalogEvent);
785
798
  this._warmAbort.abort(RUNNER_CLOSED);
@@ -1150,6 +1163,13 @@ export class QvacAssistant extends ReadyResource {
1150
1163
  await this._sweepInferenceCalls();
1151
1164
  }
1152
1165
  }
1166
+ async _sweepIdleChatCaches(meshId, frames) {
1167
+ for await (const _frame of frames) {
1168
+ if (this.closing || this.suspended)
1169
+ return;
1170
+ void this._kvRetention.sweep(meshId);
1171
+ }
1172
+ }
1153
1173
  _dropDeletedChat(chatId) {
1154
1174
  for (const run of this._runs.values()) {
1155
1175
  if (run.chatId === chatId) {
@@ -1406,7 +1426,8 @@ export class QvacAssistant extends ReadyResource {
1406
1426
  const watches = [
1407
1427
  this._streamWatch(`run-requests:${meshId}`, () => this._engine.runRequestsWatch({ meshId }), (frames) => this._dispatchRunRequests(meshId, frames)),
1408
1428
  this._streamWatch(`chat-list:${meshId}`, () => this._engine.chatsWatch({ meshId }), (frames) => this._reclaimDeletedChats(frames)),
1409
- this._streamWatch(`agent:${meshId}`, () => this._engine.agentsWatch({ meshId }), (frames) => this._followAgentEdits(meshId, frames))
1429
+ this._streamWatch(`agent:${meshId}`, () => this._engine.agentsWatch({ meshId }), (frames) => this._followAgentEdits(meshId, frames)),
1430
+ this._streamWatch(`kv-cache-retention:${meshId}`, () => this._engine.configWatch({ key: KV_CACHE_RETENTION_KEY }), (frames) => this._sweepIdleChatCaches(meshId, frames))
1410
1431
  ];
1411
1432
  return {
1412
1433
  start: () => watches.forEach((watch) => watch.start()),
@@ -1723,7 +1744,8 @@ export class QvacAssistant extends ReadyResource {
1723
1744
  transcript,
1724
1745
  trigger: 'before-run',
1725
1746
  signal: controller.signal,
1726
- meshId
1747
+ meshId,
1748
+ requestSeq: request.seq
1727
1749
  });
1728
1750
  const toolConfigsPromise = this._loadToolConfigs(engine, agent.id);
1729
1751
  const fsGrantsPromise = lender ? Promise.resolve(NO_FS_GRANTS) : this._loadFsGrants(agent.id);
@@ -1891,6 +1913,7 @@ export class QvacAssistant extends ReadyResource {
1891
1913
  let sentRun = null;
1892
1914
  let inputLength = 0;
1893
1915
  let asked;
1916
+ let injectedHits = 0;
1894
1917
  const writeText = async (type, raw) => {
1895
1918
  const text = type === 'content' ? sourceTagFilter.push(raw) : raw;
1896
1919
  if (!text) {
@@ -1902,17 +1925,24 @@ export class QvacAssistant extends ReadyResource {
1902
1925
  await transcript.text(type, text);
1903
1926
  };
1904
1927
  const failRun = async (message) => {
1905
- const folded = isContextOverflowFailure(message) &&
1928
+ const overflowed = isContextOverflowFailure(message);
1929
+ const folded = overflowed &&
1906
1930
  (await this._runCompaction({
1907
1931
  chatId,
1908
1932
  transcript,
1909
1933
  trigger: 'overflow',
1910
1934
  signal: controller.signal,
1911
- meshId
1935
+ meshId,
1936
+ requestSeq: request.seq
1912
1937
  }));
1938
+ const shrunk = overflowed && !folded && injectedHits > 1;
1939
+ if (shrunk) {
1940
+ this._knowledgeCaps.set(chatId, Math.floor(injectedHits / 2));
1941
+ this._log?.info('runs', 'knowledge shrunk for retry', { runId, hits: injectedHits });
1942
+ }
1913
1943
  runFailure = runFailureNotice(message);
1914
1944
  await transcript.status({ state: 'failed', reason: runFailure, metrics });
1915
- if (folded) {
1945
+ if (folded || shrunk) {
1916
1946
  await engine
1917
1947
  .runAgent({ chatId, agentId: agent.id, parentRunId: runId })
1918
1948
  .catch((err) => this._log?.warn('runs', 'compaction retry not queued', { runId, err }));
@@ -1975,9 +2005,13 @@ export class QvacAssistant extends ReadyResource {
1975
2005
  await transcript.status({ state: 'failed', reason: outcome.reason, metrics });
1976
2006
  return;
1977
2007
  }
1978
- const injected = knowledge
1979
- ? await this._injectKnowledge(knowledge, { transcript, sourceTagFilter, retrievedRecords })
2008
+ const cap = this._knowledgeCaps.get(chatId);
2009
+ this._knowledgeCaps.delete(chatId);
2010
+ const fitted = knowledge && cap ? { ...knowledge, hits: knowledge.hits.slice(0, cap) } : knowledge;
2011
+ const injected = fitted
2012
+ ? await this._injectKnowledge(fitted, { transcript, sourceTagFilter, retrievedRecords })
1980
2013
  : { documentsInjected: false, sourcesWritten: false, ragInjected: false };
2014
+ injectedHits = injected.ragInjected && fitted ? fitted.hits.length : 0;
1981
2015
  const hasAudio = messages.some((turn) => turn.audioAttachments?.length || turn.videos?.length);
1982
2016
  if (hasAudio) {
1983
2017
  modelWatch.transcribe(true);
@@ -2127,6 +2161,9 @@ export class QvacAssistant extends ReadyResource {
2127
2161
  this._log?.info('runs', 'run metrics', { runId, ...runMetricsSummary(rest) });
2128
2162
  continue;
2129
2163
  }
2164
+ if (event.type === 'inference-sent' && event.outcome === 'overflowed') {
2165
+ this._log?.info('runs', 'context overflow', { runId, reason: event.reason });
2166
+ }
2130
2167
  if (event.type === 'inference-sent') {
2131
2168
  this._inspectSent(inspecting, chatId, {
2132
2169
  runId,
@@ -2254,6 +2291,7 @@ export class QvacAssistant extends ReadyResource {
2254
2291
  if (titleOutcome && !diagramRepair) {
2255
2292
  void this._autoTitle(engine, {
2256
2293
  chatId,
2294
+ history,
2257
2295
  messages,
2258
2296
  model,
2259
2297
  agent: runAgent,
@@ -2997,7 +3035,7 @@ export class QvacAssistant extends ReadyResource {
2997
3035
  }
2998
3036
  }
2999
3037
  async _compactIfNearFull(params) {
3000
- const { chatId, transcript, trigger, signal, meshId } = params;
3038
+ const { chatId, transcript, trigger, signal, meshId, requestSeq } = params;
3001
3039
  const metrics = await this._lastRunMetrics(chatId, meshId);
3002
3040
  if (!nearContextLimit(metrics.cacheTokens, metrics.ctxSize)) {
3003
3041
  return false;
@@ -3015,11 +3053,12 @@ export class QvacAssistant extends ReadyResource {
3015
3053
  trigger,
3016
3054
  signal,
3017
3055
  occupancy: metrics,
3018
- meshId
3056
+ meshId,
3057
+ requestSeq
3019
3058
  });
3020
3059
  }
3021
3060
  async _runCompaction(params) {
3022
- const { chatId, transcript, trigger, signal, meshId } = params;
3061
+ const { chatId, transcript, trigger, signal, meshId, requestSeq } = params;
3023
3062
  let statusId = null;
3024
3063
  const started = Date.now();
3025
3064
  try {
@@ -3032,7 +3071,8 @@ export class QvacAssistant extends ReadyResource {
3032
3071
  statusId = status.id;
3033
3072
  },
3034
3073
  meshId,
3035
- signal
3074
+ signal,
3075
+ requestSeq
3036
3076
  });
3037
3077
  this._log?.info('runs', 'compaction', {
3038
3078
  chatId,
@@ -3117,12 +3157,13 @@ export class QvacAssistant extends ReadyResource {
3117
3157
  .catch(() => ({ chunks: [] }));
3118
3158
  const lastThroughId = lastCompactedThroughId(chunks);
3119
3159
  const lastThroughSeq = chunks.find((chunk) => chunk.id === lastThroughId)?.seq ?? -1;
3120
- const userTurns = chunks.filter((chunk) => chunk.userMessage).length;
3160
+ const beforeSeq = options.requestSeq ?? Infinity;
3161
+ const userTurns = chunks.filter((chunk) => chunk.userMessage && chunk.seq < beforeSeq).length;
3121
3162
  let announced = false;
3122
3163
  let keepTurns = COMPACTION_KEEP_TURNS;
3123
3164
  const senders = await this._senderNames(engine, chunks);
3124
3165
  for (;;) {
3125
- const boundary = compactionBoundary(chunks, keepTurns);
3166
+ const boundary = compactionBoundary(chunks, keepTurns, beforeSeq);
3126
3167
  if (!boundary) {
3127
3168
  return { compacted: false, reason: 'nothing-to-fold' };
3128
3169
  }
@@ -3133,7 +3174,8 @@ export class QvacAssistant extends ReadyResource {
3133
3174
  if (through.seq <= lastThroughSeq) {
3134
3175
  return { compacted: false, reason: 'already-compacted' };
3135
3176
  }
3136
- const inRange = chunks.filter((chunk) => chunk.seq <= through.seq);
3177
+ const folds = foldsThrough(chunks, through);
3178
+ const inRange = chunks.filter((chunk) => chunk.compaction || folds(chunk));
3137
3179
  const folded = historyFromChunks(inRange, staleToolRunIds(inRange, priorAsks ?? [], ''), {
3138
3180
  senderNames: senders
3139
3181
  });
@@ -3219,9 +3261,10 @@ export class QvacAssistant extends ReadyResource {
3219
3261
  }
3220
3262
  return { summary: parseCompactionSummary(text), overflowed: false };
3221
3263
  }
3222
- async _autoTitle(engine, { chatId, messages, model, agent, probe }) {
3264
+ async _autoTitle(engine, { chatId, history, messages, model, agent, probe }) {
3223
3265
  try {
3224
- const first = messages.find((turn) => turn.role === 'user' && turn.content.trim());
3266
+ const first = history.find((chunk) => chunk.userMessage?.text.trim())?.userMessage?.text ??
3267
+ messages.find((turn) => turn.role === 'user' && turn.content.trim())?.content;
3225
3268
  if (!first) {
3226
3269
  return;
3227
3270
  }
@@ -3229,7 +3272,7 @@ export class QvacAssistant extends ReadyResource {
3229
3272
  if (!isDefaultChatTitle(chat?.title)) {
3230
3273
  return;
3231
3274
  }
3232
- await this._generateChatTitle({ engine, chatId, input: first.content, model, agent, probe });
3275
+ await this._generateChatTitle({ engine, chatId, input: first, model, agent, probe });
3233
3276
  }
3234
3277
  catch (err) {
3235
3278
  this._log?.warn('runs', 'auto-title skipped', { chatId, err });
@@ -3707,7 +3750,7 @@ function toolCallChunk(event) {
3707
3750
  function toolResultChunk(event) {
3708
3751
  return {
3709
3752
  type: 'tool-result',
3710
- toolResult: { name: event.name, result: withoutDataChannel(event.result) }
3753
+ toolResult: { name: event.name, result: withoutDataChannel(event.result) ?? null }
3711
3754
  };
3712
3755
  }
3713
3756
  function runMetricsSummary(metrics) {
@@ -14,7 +14,8 @@ export interface CompactionBoundary {
14
14
  throughId: string;
15
15
  foldedTurns: number;
16
16
  }
17
- export declare function compactionBoundary(chunks: ReadonlyArray<AssistantChunk>, keepTurns?: number): CompactionBoundary | null;
17
+ export declare function compactionBoundary(chunks: ReadonlyArray<AssistantChunk>, keepTurns?: number, beforeSeq?: number): CompactionBoundary | null;
18
+ export declare function foldsThrough(chunks: ReadonlyArray<AssistantChunk>, through: AssistantChunk): (chunk: AssistantChunk) => boolean;
18
19
  export declare function lastCompactedThroughId(chunks: ReadonlyArray<AssistantChunk>): string | null;
19
20
  export interface FoldedChunks {
20
21
  chunks: ReadonlyArray<AssistantChunk>;
@@ -35,10 +35,10 @@ export function parseCompactionSummary(text) {
35
35
  const summary = text.trim();
36
36
  return summary.length > 0 ? summary : null;
37
37
  }
38
- export function compactionBoundary(chunks, keepTurns = COMPACTION_KEEP_TURNS) {
38
+ export function compactionBoundary(chunks, keepTurns = COMPACTION_KEEP_TURNS, beforeSeq = Infinity) {
39
39
  const userTurns = [];
40
40
  for (let index = 0; index < chunks.length; index++) {
41
- if (chunks[index].userMessage) {
41
+ if (chunks[index].userMessage && chunks[index].seq < beforeSeq) {
42
42
  userTurns.push(index);
43
43
  }
44
44
  }
@@ -52,12 +52,21 @@ export function compactionBoundary(chunks, keepTurns = COMPACTION_KEEP_TURNS) {
52
52
  from = index;
53
53
  }
54
54
  }
55
- const boundary = chunks[from - 1];
55
+ const boundary = chunks.slice(0, from).findLast((chunk) => chunk.type === 'run-request') ?? chunks[from - 1];
56
56
  if (!boundary) {
57
57
  return null;
58
58
  }
59
59
  return { throughId: boundary.id, foldedTurns: userTurns.length - keepTurns };
60
60
  }
61
+ export function foldsThrough(chunks, through) {
62
+ const requested = new Map();
63
+ for (const chunk of chunks) {
64
+ if (chunk.type === 'run-request' && chunk.runId && !requested.has(chunk.runId)) {
65
+ requested.set(chunk.runId, chunk.seq);
66
+ }
67
+ }
68
+ return (chunk) => (chunk.runId ? (requested.get(chunk.runId) ?? chunk.seq) : chunk.seq) <= through.seq;
69
+ }
61
70
  function newestCompaction(chunks) {
62
71
  let newest = null;
63
72
  for (const chunk of chunks) {
@@ -79,8 +88,9 @@ export function foldCompactedChunks(chunks) {
79
88
  if (!through) {
80
89
  return { chunks, summary: null };
81
90
  }
91
+ const folded = foldsThrough(chunks, through);
82
92
  return {
83
- chunks: chunks.filter((chunk) => chunk.seq > through.seq && !chunk.compaction),
93
+ chunks: chunks.filter((chunk) => !folded(chunk) && !chunk.compaction),
84
94
  summary: compaction.summary
85
95
  };
86
96
  }
@@ -9,5 +9,8 @@ export declare const MODEL_MEMORY_CAP_KEY = "model.memoryCapPercent";
9
9
  export declare const MODEL_MEMORY_CAP_DEFAULT = 85;
10
10
  export declare const MODEL_MEMORY_CAP_MIN = 10;
11
11
  export declare const MODEL_MEMORY_CAP_MAX = 100;
12
+ export declare const KV_CACHE_RETENTION_KEY = "kvCache.retentionDays";
13
+ export declare const KV_CACHE_RETENTION_DAYS_DEFAULT = 14;
14
+ export declare const KV_CACHE_RETENTION_NEVER = 0;
12
15
  export declare const FAKE_MODELS_KEY = "debug.fakeModels";
13
16
  export declare const QUACK_MODEL = "quack";
@@ -11,5 +11,8 @@ export const MODEL_MEMORY_CAP_KEY = 'model.memoryCapPercent';
11
11
  export const MODEL_MEMORY_CAP_DEFAULT = 85;
12
12
  export const MODEL_MEMORY_CAP_MIN = 10;
13
13
  export const MODEL_MEMORY_CAP_MAX = 100;
14
+ export const KV_CACHE_RETENTION_KEY = 'kvCache.retentionDays';
15
+ export const KV_CACHE_RETENTION_DAYS_DEFAULT = 14;
16
+ export const KV_CACHE_RETENTION_NEVER = 0;
14
17
  export const FAKE_MODELS_KEY = 'debug.fakeModels';
15
18
  export const QUACK_MODEL = 'quack';