@picassohq/cli 1.0.3 → 1.0.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 (64) hide show
  1. package/dist/build-info.json +2 -1
  2. package/dist/index.js +1860 -1316
  3. package/package.json +1 -1
  4. package/runtime/dsh/picasso-ecosystem.cordis.patch.yml +4 -7
  5. package/runtime/dsh/picasso-sdk.patch.yml +47 -0
  6. package/runtime/engine-manifest.json +37 -16
  7. package/runtime/packages/picasso-compaction/cordis.patch.yml +4 -0
  8. package/runtime/packages/picasso-compaction/index.js +875 -0
  9. package/runtime/packages/picasso-compaction/package.json +27 -0
  10. package/runtime/packages/picasso-hooks/cordis.patch.yml +4 -0
  11. package/runtime/packages/picasso-hooks/index.js +302 -0
  12. package/runtime/packages/picasso-hooks/lifecycle-events.js +651 -0
  13. package/runtime/packages/picasso-hooks/package.json +29 -0
  14. package/runtime/packages/picasso-lean-context/argument-repair.js +422 -0
  15. package/runtime/packages/picasso-lean-context/glob-walk.js +518 -0
  16. package/runtime/packages/picasso-lean-context/index.js +159 -11
  17. package/runtime/packages/picasso-memory/index.js +66 -24
  18. package/runtime/packages/picasso-model-router/connections.js +213 -10
  19. package/runtime/packages/picasso-model-router/index.js +128 -1
  20. package/runtime/packages/picasso-model-router/package.json +3 -1
  21. package/runtime/packages/picasso-model-router/thinking-default.js +236 -0
  22. package/runtime/packages/picasso-progress-reports/index.js +128 -18
  23. package/runtime/packages/picasso-sdk-server/command-runs.js +37 -0
  24. package/runtime/packages/picasso-sdk-server/ignore-file.js +5 -1
  25. package/runtime/packages/picasso-sdk-server/index.js +11 -3
  26. package/runtime/packages/picasso-sdk-server/package.json +1 -0
  27. package/runtime/packages/picasso-sdk-server/wave2-hooks.js +26 -6
  28. package/runtime/packages/picasso-web-search/backends.js +245 -195
  29. package/runtime/packages/picasso-web-search/config.js +75 -27
  30. package/runtime/packages/picasso-web-search/cordis.patch.yml +2 -1
  31. package/runtime/packages/picasso-web-search/failure.js +7 -1
  32. package/runtime/packages/picasso-web-search/index.js +7 -5
  33. package/runtime/packages/picasso-web-search/package.json +6 -0
  34. package/runtime/packages/picasso-web-search/requests.js +339 -0
  35. package/runtime/packages/picasso-web-search/router.js +17 -12
  36. package/runtime/packages/picasso-x-reader/settings.js +4 -1
  37. package/runtime/plugins/picasso-auto-approve/index.js +21 -8
  38. package/runtime/plugins/picasso-compaction/index.js +875 -0
  39. package/runtime/plugins/picasso-compaction/package.json +27 -0
  40. package/runtime/plugins/picasso-hooks/index.js +302 -0
  41. package/runtime/plugins/picasso-hooks/lifecycle-events.js +651 -0
  42. package/runtime/plugins/picasso-hooks/package.json +29 -0
  43. package/runtime/plugins/picasso-lean-context/argument-repair.js +422 -0
  44. package/runtime/plugins/picasso-lean-context/glob-walk.js +518 -0
  45. package/runtime/plugins/picasso-lean-context/index.js +159 -11
  46. package/runtime/plugins/picasso-memory/index.js +66 -24
  47. package/runtime/plugins/picasso-model-router/connections.js +213 -10
  48. package/runtime/plugins/picasso-model-router/index.js +128 -1
  49. package/runtime/plugins/picasso-model-router/package.json +3 -1
  50. package/runtime/plugins/picasso-model-router/thinking-default.js +236 -0
  51. package/runtime/plugins/picasso-progress-reports/index.js +128 -18
  52. package/runtime/plugins/picasso-provider-models/index.js +236 -4
  53. package/runtime/plugins/picasso-trackers/index.js +12 -2
  54. package/runtime/plugins/picasso-web-search/backends.js +245 -195
  55. package/runtime/plugins/picasso-web-search/config.js +75 -27
  56. package/runtime/plugins/picasso-web-search/failure.js +7 -1
  57. package/runtime/plugins/picasso-web-search/index.js +7 -5
  58. package/runtime/plugins/picasso-web-search/package.json +6 -0
  59. package/runtime/plugins/picasso-web-search/requests.js +339 -0
  60. package/runtime/plugins/picasso-web-search/router.js +17 -12
  61. package/runtime/plugins/picasso-x-reader/settings.js +4 -1
  62. package/runtime/relay/main.mjs +3877 -1989
  63. package/runtime/relay/model-listing.mjs +337 -26
  64. package/runtime/relay/versions-routes.mjs +86 -20
@@ -0,0 +1,875 @@
1
+ // @picasso/compaction — conversation compaction that always summarizes on a model that works now.
2
+ //
3
+ // The engine's compaction (dsh-compaction-basic) summarizes on the model of the conversation's LAST request. When that
4
+ // model's connection is gone (a provider the person removed) every compaction fails — the switch to another model that
5
+ // needs one, and `/compact` too ("no adapter registered for provider …"); and a history longer than the summarizing
6
+ // model's window could never be summarized in its single call. This plugin replaces only the engine's documented
7
+ // summarizer hook (`summarize(input, agent, signal)`, "the sole subclass customization hook"); range selection,
8
+ // pricing, the checkpoint framing and the durable replacement stay the engine's.
9
+ //
10
+ // Which model summarizes, in order, each one only if it resolves now (its connection is registered):
11
+ // 1. the model the conversation is switching to / has selected (the pending selection);
12
+ // 2. the model of the last request;
13
+ // 3. the agent's configured route;
14
+ // 4. other connected models, Picasso's managed route first, then the largest context window (at most
15
+ // MAX_FALLBACK_ATTEMPTS of them are tried).
16
+ // A model whose call fails is followed by the next; when every one fails the error says so in plain words.
17
+ //
18
+ // When the history fits the model in one call, the call is the engine's own shape (system, tools, history, then the
19
+ // instruction), so a model that served the last request reuses its warm prompt cache; it IS the engine's call when the
20
+ // engine would have picked that model anyway. When it does not fit, the history is rendered as plain text, split into
21
+ // parts that fit, each part is summarized, and the part summaries are merged (in rounds, if even they do not fit).
22
+ //
23
+ // Two more things, on the same engine backend (`installSummarizer`): the engine's between-step pressure check is
24
+ // skipped while the step runs on another model than the last request (it would price the old model; the engine's
25
+ // switch check prices the model the step really runs on), and every compaction records why, for which model and how
26
+ // big the conversation is (`plugin:picasso/compaction` → `compaction/notice`) just before its summary, which the TUI
27
+ // shows as one line ("Shortened this conversation to fit <model> (321k → 60k tokens): <reason>"). The engine's
28
+ // tool-output trimming (its pruner, which runs first under pressure) records the same notice with scope
29
+ // `tool-outputs`, and shortening starts only near the window (PRESSURE_RATIO, 0.92, not the engine's 0.8).
30
+ //
31
+ // C1 zero-fallback: the summary is always the model's own text. Nothing is synthesized when no model can produce
32
+ // one; the compaction fails and the engine records the attempt. Tier 1 is untouched: the summary lands in history
33
+ // (Tier 2) through the engine's checkpoint message, exactly as before.
34
+
35
+ export const name = 'picasso-compaction';
36
+ export const dshTarget = '0.2.2-rc.3';
37
+
38
+ /** The managed route (`packages/core/src/dsh/managed-transport.ts` MANAGED_DSH_PROVIDER). */
39
+ export const MANAGED_ROUTE = 'picasso-managed';
40
+ /** Window assumed for a model whose connection states none (conservative: it only makes parts smaller). */
41
+ export const FALLBACK_CONTEXT_WINDOW = 65_536;
42
+ /** Output cap of one summary call; a checkpoint is a few thousand tokens. */
43
+ export const SUMMARY_MAX_TOKENS = 16_384;
44
+ /** The engine's own summary cap when its config names none (`headroomTokens` default). */
45
+ export const ENGINE_DEFAULT_MAX_TOKENS = 65_536;
46
+ /**
47
+ * The share of a model's window where the engine starts shortening a conversation (first trimming old tool outputs,
48
+ * then summarizing). The engine's default, 0.8, trimmed a 1M-token Claude conversation at 800k (owner 2026-11-17:
49
+ * "nothing chopped off"); the engine still caps it at the window less the request's output reservation and the
50
+ * compaction headroom, so a request always has room to answer. A configured ratio below this is raised to it.
51
+ */
52
+ export const PRESSURE_RATIO = 0.92;
53
+ /** Other connected models tried after the selected, last-used and configured ones. */
54
+ export const MAX_FALLBACK_ATTEMPTS = 2;
55
+ /** Merge rounds before giving up on a history whose part summaries still do not fit. */
56
+ export const MAX_MERGE_ROUNDS = 5;
57
+ /** Characters per token for sizing; lower than the engine's 4 so code and JSON never overflow a part. */
58
+ const CHARS_PER_TOKEN = 3;
59
+ /** Share of the input room actually filled (tokenizers differ from any estimate). */
60
+ const FILL_RATIO = 0.9;
61
+ /** Tokens kept for the instruction and framing around a part. */
62
+ const PROMPT_OVERHEAD_TOKENS = 2_000;
63
+ /** Halvings of the part size after a route refuses a request as too large. */
64
+ const MAX_SHRINKS = 4;
65
+ const MIN_PART_TOKENS = 2_000;
66
+ const MAX_PROVIDERS_SCANNED = 8;
67
+ const MAX_MODELS_PER_PROVIDER = 6;
68
+ const ORIGINAL = Symbol.for('cordis.original');
69
+
70
+ const SECTIONS = [
71
+ '## Primary Request and Intent',
72
+ "- [the user's original and evolving goals; quote verbatim where the exact wording matters]",
73
+ '',
74
+ '## Key Technical Concepts',
75
+ '- [technologies, frameworks, patterns, and conventions in play]',
76
+ '',
77
+ '## Files and Code',
78
+ '- [exact path: why it matters, key changes or snippets]',
79
+ '',
80
+ '## Errors and Fixes',
81
+ '- [error: how it was resolved, plus any related user feedback]',
82
+ '',
83
+ '## Pending Jobs',
84
+ '- [explicitly requested work not yet completed]',
85
+ '',
86
+ '## Current Work',
87
+ '- [precisely what was in progress at this checkpoint]',
88
+ '',
89
+ '## Next Step',
90
+ '- [the single next action, directly in line with the most recent request, or "(none)"]',
91
+ '',
92
+ '## Critical Context',
93
+ '- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]',
94
+ ].join('\n');
95
+
96
+ const RULES = [
97
+ 'Rules:',
98
+ '- Output EXACTLY the Markdown structure above: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section.',
99
+ '- Write concise English engineering prose. Preserve exact file paths, commands, error strings, identifiers, numeric values, function signatures, and syntax fragments.',
100
+ '- Capture user feedback and explicit instructions faithfully, especially corrections.',
101
+ '- Never copy a secret value (API key, token, password, private key, connection string with credentials) into the checkpoint: name it and where it lives instead (for example "the OpenAI key in .env").',
102
+ '- Do NOT mention this summarization request or that the context was compacted.',
103
+ '- Output only the checkpoint text: do not call any tool or take any other action.',
104
+ '- A <compacted-summary> block in the material is an earlier checkpoint: keep its still-true facts, drop stale ones, and merge newer information into one consolidated summary.',
105
+ ].join('\n');
106
+
107
+ /** The instruction after the replayed history (single call: the engine's request shape). */
108
+ export const SUMMARY_INSTRUCTION = [
109
+ 'You are now acting as a compaction engine for this AI coding assistant. Condense the conversation ABOVE into a structured checkpoint that lets another model resume the work with no loss of essential context.',
110
+ '',
111
+ SECTIONS,
112
+ '',
113
+ RULES,
114
+ ].join('\n');
115
+
116
+ /** One part of a history too long for one call. */
117
+ export function partPrompt(text, index, count) {
118
+ return [
119
+ `<transcript part="${index + 1} of ${count}">`,
120
+ text,
121
+ '</transcript>',
122
+ '',
123
+ `You are now acting as a compaction engine for an AI coding assistant. The transcript above is part ${index + 1} of ${count} of one earlier conversation between a person and the assistant (oldest part first). Condense THIS PART into a structured checkpoint; later steps merge the parts, so record what this part establishes even when it continues work from an earlier part.`,
124
+ '',
125
+ SECTIONS,
126
+ '',
127
+ RULES,
128
+ ].join('\n');
129
+ }
130
+
131
+ /** Merge the checkpoints of consecutive parts into one. */
132
+ export function mergePrompt(summaries) {
133
+ return [
134
+ ...summaries.flatMap((summary, index) => [`<checkpoint part="${index + 1} of ${summaries.length}">`, summary, '</checkpoint>', '']),
135
+ `You are now acting as a compaction engine for an AI coding assistant. The ${summaries.length} checkpoints above summarize consecutive parts of ONE conversation, oldest first. Merge them into a single checkpoint: later parts override earlier ones where they disagree, "Current Work" and "Next Step" come from the latest part, and nothing still true is lost.`,
136
+ '',
137
+ SECTIONS,
138
+ '',
139
+ RULES,
140
+ ].join('\n');
141
+ }
142
+
143
+ /** A compaction failure in plain words (the engine records `message` on the compaction and shows it). */
144
+ export class CompactionSummaryError extends Error {
145
+ constructor(message, attempts = []) {
146
+ super(message);
147
+ this.name = 'CompactionSummaryError';
148
+ this.code = 'PICASSO_COMPACTION_SUMMARY';
149
+ this.attempts = attempts;
150
+ }
151
+ }
152
+
153
+ const text = (value) => (typeof value === 'string' ? value : '');
154
+ const firstLine = (value) => {
155
+ const raw = value instanceof Error ? value.message : String(value ?? '');
156
+ const line = raw.split('\n').find((part) => part.trim() !== '') ?? raw;
157
+ return line.length > 200 ? `${line.slice(0, 199)}…` : line;
158
+ };
159
+
160
+ export function estimateTextTokens(value) {
161
+ return Math.ceil(text(value).length / CHARS_PER_TOKEN) + 4;
162
+ }
163
+
164
+ function estimateBlocks(blocks) {
165
+ let tokens = 4;
166
+ for (const block of Array.isArray(blocks) ? blocks : []) {
167
+ if (block?.type === 'text' || block?.type === 'reasoning') tokens += estimateTextTokens(block.text);
168
+ else if (block?.type === 'tool-call') tokens += estimateTextTokens(`${text(block.name)} ${text(block.arguments)}`);
169
+ else tokens += estimateTextTokens(safeJson(block));
170
+ }
171
+ return tokens;
172
+ }
173
+
174
+ function safeJson(value) {
175
+ try {
176
+ return JSON.stringify(value) ?? '';
177
+ } catch {
178
+ return '';
179
+ }
180
+ }
181
+
182
+ /** Tokens the engine's request shape costs: every message plus the tool schemas. */
183
+ export function estimateInputTokens(input) {
184
+ let tokens = 0;
185
+ for (const message of input?.messages ?? []) tokens += estimateBlocks(message?.content);
186
+ if (Array.isArray(input?.tools) && input.tools.length > 0) tokens += estimateTextTokens(safeJson(input.tools));
187
+ return tokens;
188
+ }
189
+
190
+ /** Output cap and input room of one call on a model with `window` tokens. */
191
+ export function callBudget(window, defaultMaxTokens) {
192
+ const capped = Math.min(SUMMARY_MAX_TOKENS, Math.floor(window / 4), defaultMaxTokens ?? Number.POSITIVE_INFINITY);
193
+ const maxTokens = Math.max(1_024, capped);
194
+ const inputTokens = Math.max(1_024, Math.floor((window - maxTokens) * FILL_RATIO) - PROMPT_OVERHEAD_TOKENS);
195
+ return { maxTokens, inputTokens };
196
+ }
197
+
198
+ function inputRoom(window, maxTokens) {
199
+ return Math.floor((window - maxTokens) * FILL_RATIO) - PROMPT_OVERHEAD_TOKENS;
200
+ }
201
+
202
+ const ROLE_LABEL = { user: 'User', assistant: 'Assistant', tool: 'Tool result' };
203
+
204
+ /** One history message as transcript text; '' for messages a summary does not need (system prompt, tool changes). */
205
+ export function renderMessage(message) {
206
+ const label = ROLE_LABEL[message?.role];
207
+ if (label === undefined) return '';
208
+ const parts = [];
209
+ for (const block of Array.isArray(message.content) ? message.content : []) {
210
+ switch (block?.type) {
211
+ case 'text':
212
+ if (text(block.text).length > 0) parts.push(block.text);
213
+ break;
214
+ case 'reasoning':
215
+ case 'tool-addition':
216
+ case 'tool-removal':
217
+ break;
218
+ case 'tool-call':
219
+ parts.push(`[tool call ${text(block.name)} ${text(block.arguments)}]`);
220
+ break;
221
+ case 'image':
222
+ parts.push('[image]');
223
+ break;
224
+ case 'file':
225
+ parts.push(`[file ${text(block.attachment?.name) || text(block.attachment?.path)}]`.trim());
226
+ break;
227
+ default:
228
+ parts.push(safeJson(block));
229
+ }
230
+ }
231
+ if (parts.length === 0) return '';
232
+ const heading = message.role === 'tool' && message.isError === true ? `${label} (error)` : label;
233
+ return `### ${heading}\n${parts.join('\n')}`;
234
+ }
235
+
236
+ /**
237
+ * The history as transcript parts of at most `partTokens` estimated tokens each, in order. A message larger than a
238
+ * part is split across parts (marked as continued); nothing is dropped.
239
+ */
240
+ export function transcriptParts(messages, partTokens) {
241
+ const maxChars = Math.max(1_000, (partTokens - 4) * CHARS_PER_TOKEN);
242
+ const parts = [];
243
+ let current = '';
244
+ const flush = () => {
245
+ if (current.length > 0) parts.push(current);
246
+ current = '';
247
+ };
248
+ for (const message of messages ?? []) {
249
+ const rendered = renderMessage(message);
250
+ if (rendered.length === 0) continue;
251
+ const joined = current.length === 0 ? rendered : `${current}\n\n${rendered}`;
252
+ if (joined.length <= maxChars) {
253
+ current = joined;
254
+ continue;
255
+ }
256
+ flush();
257
+ if (rendered.length <= maxChars) {
258
+ current = rendered;
259
+ continue;
260
+ }
261
+ for (let start = 0; start < rendered.length; start += maxChars) {
262
+ const piece = rendered.slice(start, start + maxChars);
263
+ parts.push(start === 0 ? piece : `(continued)\n${piece}`);
264
+ }
265
+ }
266
+ flush();
267
+ return parts;
268
+ }
269
+
270
+ /** Group checkpoint texts so each group's merge prompt fits `inputTokens`. */
271
+ export function packSummaries(summaries, inputTokens) {
272
+ const groups = [];
273
+ let current = [];
274
+ let size = 0;
275
+ for (const summary of summaries) {
276
+ const cost = estimateTextTokens(summary) + 16;
277
+ if (current.length > 0 && size + cost > inputTokens) {
278
+ groups.push(current);
279
+ current = [];
280
+ size = 0;
281
+ }
282
+ current.push(summary);
283
+ size += cost;
284
+ }
285
+ if (current.length > 0) groups.push(current);
286
+ return groups;
287
+ }
288
+
289
+ function addUsage(total, usage) {
290
+ if (usage === undefined || usage === null || typeof usage !== 'object') return total;
291
+ const sum = { ...(total ?? { inputTokens: 0, outputTokens: 0 }) };
292
+ for (const key of ['inputTokens', 'outputTokens', 'totalTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens']) {
293
+ const value = usage[key];
294
+ if (typeof value === 'number' && Number.isFinite(value)) sum[key] = (sum[key] ?? 0) + value;
295
+ }
296
+ return sum;
297
+ }
298
+
299
+ /** One model call's output: content blocks in index order, the finish reason and the usage. */
300
+ async function collect(stream) {
301
+ const ended = new Map();
302
+ const deltas = new Map();
303
+ let finish;
304
+ let usage;
305
+ for await (const chunk of stream) {
306
+ switch (chunk?.type) {
307
+ case 'text-delta':
308
+ deltas.set(chunk.index, (deltas.get(chunk.index) ?? '') + text(chunk.text));
309
+ break;
310
+ case 'block-end':
311
+ ended.set(chunk.index, chunk.block);
312
+ break;
313
+ case 'usage':
314
+ usage = chunk.usage;
315
+ break;
316
+ case 'finish':
317
+ finish = chunk.reason;
318
+ break;
319
+ default:
320
+ break;
321
+ }
322
+ }
323
+ const indices = [...new Set([...ended.keys(), ...deltas.keys()])].sort((a, b) => a - b);
324
+ const blocks = indices.map((index) => ended.get(index) ?? { type: 'text', text: deltas.get(index) ?? '' });
325
+ return { blocks, finish, usage };
326
+ }
327
+
328
+ function finishFailure(finish) {
329
+ if (finish === undefined) return undefined;
330
+ if (finish.kind === 'error' || finish.kind === 'aborted') {
331
+ const failure = finish.failure ?? {};
332
+ const error = new Error(text(failure.message) || `the model stopped (${finish.kind})`);
333
+ if (typeof failure.code === 'string') error.code = failure.code;
334
+ return error;
335
+ }
336
+ if (finish.kind === 'max-tokens') {
337
+ const error = new Error('the summary was cut off at its length limit');
338
+ error.code = 'MAX_TOKENS';
339
+ return error;
340
+ }
341
+ return undefined;
342
+ }
343
+
344
+ /** A route refused the request for its size (HTTP 413, "payload too large", a context overflow). */
345
+ export function isTooLarge(error) {
346
+ const status = error?.details?.status ?? error?.status ?? error?.cause?.details?.status;
347
+ if (status === 413) return true;
348
+ // The model said the request overflowed its window: the size estimate was off, so smaller parts are the answer too.
349
+ if (error?.code === 'CONTEXT_WINDOW_EXCEEDED') return true;
350
+ const message = error instanceof Error ? error.message : String(error ?? '');
351
+ return /\b413\b|payload too large|request(?:_| )too(?:_| )large|body is too large|entity too large/iu.test(message);
352
+ }
353
+
354
+ const sameTarget = (a, b) => a !== undefined && b !== undefined && a.provider === b.provider && a.model === b.model;
355
+
356
+ function target(provider, model) {
357
+ return typeof provider === 'string' && provider.length > 0 && typeof model === 'string' && model.length > 0 ? { provider, model } : undefined;
358
+ }
359
+
360
+ /** The pending model selection (what the conversation is switching to), else the last used one. */
361
+ function selectedTarget(agent) {
362
+ try {
363
+ const current = agent?.model?.current?.();
364
+ return target(current?.provider, current?.model);
365
+ } catch {
366
+ return undefined;
367
+ }
368
+ }
369
+
370
+ function lastRequestTarget(agent) {
371
+ try {
372
+ const config = agent?.session?.requestHeader?.()?.config;
373
+ return target(config?.provider, config?.model);
374
+ } catch {
375
+ return undefined;
376
+ }
377
+ }
378
+
379
+ function optionsTarget(agent) {
380
+ return target(agent?.options?.provider, agent?.options?.model);
381
+ }
382
+
383
+ /**
384
+ * The summarizer. `llm` is the engine's LLM service (`resolveModelInfo`, `stream`, `listProviders`, `listModels`);
385
+ * `stock` is the engine's own summarize for the case it would already handle; `engineConfig` its resolved config.
386
+ */
387
+ export function createSummarizer({ llm, stock, engineConfig = () => undefined, log = () => undefined }) {
388
+ const resolve = async (candidate, origin, signal) => {
389
+ try {
390
+ const info = await llm.resolveModelInfo(candidate.provider, candidate.model, signal);
391
+ const window = info?.context?.contextWindow;
392
+ return {
393
+ ...candidate,
394
+ origin,
395
+ window: Number.isSafeInteger(window) && window > 0 ? window : FALLBACK_CONTEXT_WINDOW,
396
+ ...(Number.isSafeInteger(info?.defaultMaxTokens) && info.defaultMaxTokens > 0 ? { defaultMaxTokens: info.defaultMaxTokens } : {}),
397
+ };
398
+ } catch (error) {
399
+ if (signal?.aborted) throw error;
400
+ // Its connection is gone or does not serve that model: never summarize on it.
401
+ log(`compaction: ${candidate.provider}/${candidate.model} is not available (${firstLine(error)})`);
402
+ return undefined;
403
+ }
404
+ };
405
+
406
+ /** Other connected models: the managed route first, then the largest window. */
407
+ const fallbacks = async (seen, signal) => {
408
+ let providers = [];
409
+ try {
410
+ providers = (await llm.listProviders?.()) ?? [];
411
+ } catch {
412
+ providers = [];
413
+ }
414
+ const ids = [...new Set(providers.map((entry) => (typeof entry === 'string' ? entry : entry?.id)).filter((id) => typeof id === 'string' && id.length > 0))];
415
+ ids.sort((a, b) => (a === MANAGED_ROUTE ? -1 : b === MANAGED_ROUTE ? 1 : 0));
416
+ const found = [];
417
+ for (const provider of ids.slice(0, MAX_PROVIDERS_SCANNED)) {
418
+ let models = [];
419
+ try {
420
+ models = (await llm.listModels?.(provider)) ?? [];
421
+ } catch {
422
+ models = [];
423
+ }
424
+ for (const model of models.slice(0, MAX_MODELS_PER_PROVIDER)) {
425
+ const candidate = target(provider, typeof model === 'string' ? model : model?.id);
426
+ if (candidate === undefined || seen.has(`${candidate.provider}\u0000${candidate.model}`)) continue;
427
+ seen.add(`${candidate.provider}\u0000${candidate.model}`);
428
+ const resolved = await resolve(candidate, 'fallback', signal);
429
+ if (resolved !== undefined) found.push(resolved);
430
+ }
431
+ }
432
+ found.sort((a, b) => (a.provider === MANAGED_ROUTE) !== (b.provider === MANAGED_ROUTE) ? (a.provider === MANAGED_ROUTE ? -1 : 1) : b.window - a.window);
433
+ return found.slice(0, MAX_FALLBACK_ATTEMPTS);
434
+ };
435
+
436
+ /** Candidates in order, resolved lazily: a later one is only looked up when every earlier one failed. */
437
+ async function* candidates(agent, signal) {
438
+ const seen = new Set();
439
+ for (const [candidate, origin] of [[selectedTarget(agent), 'selection'], [lastRequestTarget(agent), 'last-request'], [optionsTarget(agent), 'configured']]) {
440
+ if (candidate === undefined) continue;
441
+ const key = `${candidate.provider}\u0000${candidate.model}`;
442
+ if (seen.has(key)) continue;
443
+ seen.add(key);
444
+ const resolved = await resolve(candidate, origin, signal);
445
+ if (resolved !== undefined) yield resolved;
446
+ }
447
+ yield* await fallbacks(seen, signal);
448
+ }
449
+
450
+ /** The model the engine's own summarizer would call (configured, else the last request, else the agent's route). */
451
+ const stockTarget = (agent) => {
452
+ const config = engineConfig();
453
+ const configured = target(config?.summarizationProvider, config?.summarizationModel);
454
+ return configured ?? lastRequestTarget(agent) ?? optionsTarget(agent);
455
+ };
456
+
457
+ const call = async (candidate, request, agent, signal) => {
458
+ const options = {
459
+ provider: candidate.provider,
460
+ model: candidate.model,
461
+ ...request,
462
+ ...(agent?.session?.id === undefined ? {} : { sessionId: agent.session.id }),
463
+ purpose: 'compaction',
464
+ ...(signal === undefined ? {} : { signal }),
465
+ };
466
+ const { blocks, finish, usage } = await collect(llm.stream(options));
467
+ const failure = finishFailure(finish);
468
+ if (failure !== undefined) throw failure;
469
+ if (blocks.some((block) => block?.type === 'image')) throw new Error('the model answered with an image instead of a summary');
470
+ const summary = blocks.filter((block) => block?.type === 'text' && text(block.text).trim().length > 0);
471
+ if (summary.length === 0) {
472
+ const called = blocks.some((block) => block?.type === 'tool-call');
473
+ throw new Error(called ? 'the model called a tool instead of writing a summary' : 'the model returned an empty summary');
474
+ }
475
+ return { blocks, summary, text: summary.map((block) => block.text).join('\n'), usage };
476
+ };
477
+
478
+ const singleCall = async (candidate, input, agent, signal, maxTokens) => {
479
+ let toolHistory;
480
+ try {
481
+ toolHistory = agent?.session?.toolHistory?.();
482
+ } catch {
483
+ toolHistory = undefined;
484
+ }
485
+ const out = await call(candidate, {
486
+ messages: [...(input.messages ?? []), { role: 'user', content: [{ type: 'text', text: SUMMARY_INSTRUCTION }] }],
487
+ ...(Array.isArray(input.tools) && input.tools.length > 0 ? { tools: [...input.tools] } : {}),
488
+ ...(toolHistory === undefined ? {} : { toolHistory }),
489
+ maxTokens,
490
+ }, agent, signal);
491
+ return {
492
+ summary: out.summary.map((block) => ({ type: 'text', text: block.text })),
493
+ rawOutput: out.blocks,
494
+ llmStreamCall: true,
495
+ provider: candidate.provider,
496
+ model: candidate.model,
497
+ maxTokens,
498
+ ...(out.usage === undefined ? {} : { usage: out.usage }),
499
+ };
500
+ };
501
+
502
+ const textCall = async (candidate, prompt, agent, signal, maxTokens) =>
503
+ call(candidate, { messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }], maxTokens }, agent, signal);
504
+
505
+ const chunked = async (candidate, input, agent, signal, budget) => {
506
+ let usage;
507
+ const parts = transcriptParts(input.messages, budget.inputTokens);
508
+ if (parts.length === 0) throw new Error('there is no conversation text to summarize');
509
+ let summaries = [];
510
+ for (const [index, part] of parts.entries()) {
511
+ signal?.throwIfAborted?.();
512
+ const out = await textCall(candidate, partPrompt(part, index, parts.length), agent, signal, budget.maxTokens);
513
+ usage = addUsage(usage, out.usage);
514
+ summaries.push(out.text);
515
+ }
516
+ for (let round = 0; summaries.length > 1; round += 1) {
517
+ if (round >= MAX_MERGE_ROUNDS) throw new Error('the part summaries could not be merged into one');
518
+ const groups = packSummaries(summaries, budget.inputTokens);
519
+ if (groups.length === summaries.length && summaries.length > 1 && groups.every((group) => group.length === 1)) {
520
+ throw new Error('the part summaries are each too long to merge on this model');
521
+ }
522
+ const merged = [];
523
+ for (const group of groups) {
524
+ signal?.throwIfAborted?.();
525
+ if (group.length === 1) {
526
+ merged.push(group[0]);
527
+ continue;
528
+ }
529
+ const out = await textCall(candidate, mergePrompt(group), agent, signal, budget.maxTokens);
530
+ usage = addUsage(usage, out.usage);
531
+ merged.push(out.text);
532
+ }
533
+ summaries = merged;
534
+ }
535
+ log(`compaction: summarized ${parts.length} parts on ${candidate.provider}/${candidate.model}`);
536
+ return {
537
+ summary: [{ type: 'text', text: summaries[0] }],
538
+ provider: candidate.provider,
539
+ model: candidate.model,
540
+ maxTokens: budget.maxTokens,
541
+ ...(usage === undefined ? {} : { usage }),
542
+ };
543
+ };
544
+
545
+ /**
546
+ * Summarize on one model: the engine's call when it would make it and it fits, one call when it fits, else parts.
547
+ * A request the route refuses as too large (an HTTP 413: Picasso's managed API caps one request's size below the
548
+ * model's window) is retried on the same model in parts half the size, a few times.
549
+ */
550
+ const summarizeOn = async (candidate, input, agent, signal) => {
551
+ const needed = estimateInputTokens(input);
552
+ const engineMax = engineConfig()?.maxTokens ?? ENGINE_DEFAULT_MAX_TOKENS;
553
+ const budget = callBudget(candidate.window, candidate.defaultMaxTokens);
554
+ let partTokens = budget.inputTokens;
555
+ let split = needed > budget.inputTokens;
556
+ for (let shrink = 0; ; shrink += 1) {
557
+ try {
558
+ if (!split) {
559
+ if (stock !== undefined && sameTarget(candidate, stockTarget(agent)) && needed <= inputRoom(candidate.window, engineMax)) {
560
+ return await stock(input, agent, signal);
561
+ }
562
+ return await singleCall(candidate, input, agent, signal, budget.maxTokens);
563
+ }
564
+ return await chunked(candidate, input, agent, signal, { ...budget, inputTokens: partTokens });
565
+ } catch (error) {
566
+ if (signal?.aborted || !isTooLarge(error) || shrink >= MAX_SHRINKS) throw error;
567
+ partTokens = Math.max(MIN_PART_TOKENS, Math.floor(Math.min(partTokens, needed) / 2));
568
+ split = true;
569
+ log(`compaction: ${candidate.provider}/${candidate.model} refused a request as too large; summarizing in parts of ~${partTokens} tokens`);
570
+ }
571
+ }
572
+ };
573
+
574
+ return {
575
+ candidates,
576
+ async summarize(input, agent, signal) {
577
+ const attempts = [];
578
+ for await (const candidate of candidates(agent, signal)) {
579
+ signal?.throwIfAborted?.();
580
+ try {
581
+ return await summarizeOn(candidate, input, agent, signal);
582
+ } catch (error) {
583
+ if (signal?.aborted) throw error;
584
+ attempts.push({ provider: candidate.provider, model: candidate.model, reason: firstLine(error) });
585
+ log(`compaction: summary on ${candidate.provider}/${candidate.model} failed (${firstLine(error)})`);
586
+ }
587
+ }
588
+ if (attempts.length === 0) {
589
+ throw new CompactionSummaryError("Couldn't shorten this conversation: none of your models is available to summarize it", attempts);
590
+ }
591
+ const tried = attempts.map((attempt) => `${attempt.model}: ${attempt.reason}`).join('; ');
592
+ throw new CompactionSummaryError(`Couldn't shorten this conversation: no model could summarize it (${tried})`, attempts);
593
+ },
594
+ };
595
+ }
596
+
597
+ /** The service object behind cordis's tracing proxy (its own `summarize` must be set on the real instance). */
598
+ function rawService(service) {
599
+ if (service === undefined || service === null) return undefined;
600
+ try {
601
+ return service[ORIGINAL] ?? service;
602
+ } catch {
603
+ return service;
604
+ }
605
+ }
606
+
607
+ /** Session-log record type of the compaction notice (`compaction/notice` inside; projected to the transcript line). */
608
+ export const COMPACTION_NOTICE_RECORD = 'plugin:picasso/compaction';
609
+
610
+ const sameRoute = (a, b) => a !== undefined && b !== undefined && a.provider === b.provider && a.model === b.model;
611
+
612
+ /**
613
+ * Whether the engine's between-step pressure check would price the wrong model: the session's last request ran on
614
+ * one model and this step runs on another (a pick, a reopened session on the current selection). The engine prices
615
+ * that check on the last request's model (owner 2026-11-17: a 321k conversation reopened on a 1M managed model was
616
+ * shortened to 60k because the old model, unknown to the new route, was sized at the 200k default). The switch check
617
+ * on the step's own request prices the model the step really runs on, so the stale check is skipped.
618
+ */
619
+ export function stalePressureHeader(agent) {
620
+ const last = lastRequestTarget(agent);
621
+ const selected = selectedTarget(agent);
622
+ return last !== undefined && selected !== undefined && !sameRoute(last, selected);
623
+ }
624
+
625
+ /**
626
+ * The tokens at which the engine starts shortening a conversation on a model (dsh-compaction-basic
627
+ * `resolveCompactSpec`: the lower of `thresholdRatio` of the window and the window less the request's output
628
+ * reservation and the compaction headroom). For the notice only; the engine's own figure decides.
629
+ */
630
+ export function compactionThreshold(config, target, window, reserved = 0) {
631
+ if (!Number.isSafeInteger(window) || window <= 0) return undefined;
632
+ const policy = (Array.isArray(config?.modelPolicies) ? config.modelPolicies : []).find((entry) => sameRoute(entry, target)) ?? {};
633
+ const ratio = policy.thresholdRatio ?? config?.thresholdRatio ?? 0.8;
634
+ const headroom = policy.headroomTokens ?? config?.headroomTokens ?? ENGINE_DEFAULT_MAX_TOKENS;
635
+ const threshold = Math.floor(Math.min(window * ratio, window - reserved - headroom));
636
+ return threshold > 0 ? threshold : undefined;
637
+ }
638
+
639
+ /**
640
+ * The engine's compaction config with its pressure ratio raised to `ratio` (PRESSURE_RATIO) when lower; per-model
641
+ * policies keep theirs. Unchanged (the same object) when already at or above it, or when it names no ratio.
642
+ */
643
+ export function withPressureRatio(config, ratio = PRESSURE_RATIO) {
644
+ if (config === null || typeof config !== 'object') return config;
645
+ const current = config.thresholdRatio;
646
+ if (typeof current !== 'number' || !(current < ratio)) return config;
647
+ return Object.freeze({ ...config, thresholdRatio: ratio });
648
+ }
649
+
650
+ /** Load `appendPluginRecord` from the running engine install (bare specifiers do not resolve from this file). */
651
+ async function engineAppendPluginRecord() {
652
+ const { createRequire } = await import('node:module');
653
+ const { realpathSync } = await import('node:fs');
654
+ const { join } = await import('node:path');
655
+ const { pathToFileURL } = await import('node:url');
656
+ const anchors = [process.argv[1], process.env.PICASSO_DSH_INSTALL_DIR && join(process.env.PICASSO_DSH_INSTALL_DIR, 'package.json')].filter(Boolean);
657
+ for (const anchor of anchors) {
658
+ try {
659
+ const require = createRequire(realpathSync(anchor));
660
+ const mod = await import(pathToFileURL(require.resolve('@deepseek-ai/dsh-session')).href);
661
+ if (typeof mod.appendPluginRecord === 'function') return mod.appendPluginRecord;
662
+ } catch {
663
+ // not an engine install: try the next anchor
664
+ }
665
+ }
666
+ return undefined;
667
+ }
668
+
669
+ /**
670
+ * Why a compaction runs and how big the conversation is, recorded in the session log just before the summary is
671
+ * written (`plugin:picasso/compaction` → `compaction/notice`), so the transcript says it plainly: "Shortened this
672
+ * conversation to fit <model> (321k → 60k tokens): <reason>". Reasons: `model-switch` (the model the conversation
673
+ * moves to has less room), `pressure` (the conversation reached the model's limit), `overflow` (the provider refused
674
+ * the request as too long), `requested` (/compact).
675
+ */
676
+ function createNoticeWriter({ engine, llm, log, appendRecord }) {
677
+ let append = appendRecord;
678
+ let loading;
679
+ const resolveAppend = async () => {
680
+ if (append !== undefined) return append;
681
+ loading ??= engineAppendPluginRecord().catch(() => undefined);
682
+ append = (await loading) ?? null;
683
+ return append;
684
+ };
685
+ return async (agent, reason, extra = {}) => {
686
+ try {
687
+ const write = await resolveAppend();
688
+ if (typeof write !== 'function' || agent?.session === undefined) return;
689
+ const header = reason?.header;
690
+ const route = target(header?.config?.provider, header?.config?.model) ?? selectedTarget(agent) ?? lastRequestTarget(agent);
691
+ // A prune measured the conversation before it trimmed (by now the measure is after).
692
+ let tokensBefore = extra.tokensBefore;
693
+ if (tokensBefore === undefined) {
694
+ try {
695
+ const measured = engine.ctx?.tokenMeter?.measure?.(agent.session, ...(header === undefined ? [] : [header]));
696
+ tokensBefore = Number.isFinite(measured?.totalTokens) ? Math.round(measured.totalTokens) : undefined;
697
+ } catch {
698
+ tokensBefore = undefined;
699
+ }
700
+ }
701
+ let window;
702
+ let reserved = 0;
703
+ if (route !== undefined) {
704
+ try {
705
+ const info = await llm.resolveModelInfo(route.provider, route.model);
706
+ window = Number.isSafeInteger(info?.context?.contextWindow) ? info.context.contextWindow : undefined;
707
+ reserved = header?.config?.maxTokens ?? info?.defaultMaxTokens ?? 0;
708
+ } catch {
709
+ window = undefined;
710
+ }
711
+ }
712
+ const thresholdTokens = reason?.kind === 'pressure' || reason?.kind === 'model-switch'
713
+ ? compactionThreshold(engine.config, route, window, reserved)
714
+ : undefined;
715
+ write(agent.session, COMPACTION_NOTICE_RECORD, {
716
+ event: {
717
+ type: 'compaction/notice',
718
+ reason: reason?.kind ?? 'requested',
719
+ ...(extra.scope === undefined ? {} : { scope: extra.scope }),
720
+ ...(route === undefined ? {} : { provider: route.provider, model: route.model }),
721
+ ...(tokensBefore === undefined ? {} : { tokensBefore }),
722
+ ...(window === undefined ? {} : { contextWindow: window }),
723
+ ...(thresholdTokens === undefined ? {} : { thresholdTokens }),
724
+ },
725
+ });
726
+ } catch (error) {
727
+ // The notice explains a compaction; it never stops one.
728
+ log(`compaction: the notice was not recorded (${firstLine(error)})`);
729
+ }
730
+ };
731
+ }
732
+
733
+ /**
734
+ * Installs the summarizer on the engine's compaction backend, the stale-pressure guard, and the compaction notice;
735
+ * returns the undo. `deps.appendRecord` replaces the engine's `appendPluginRecord` (tests).
736
+ */
737
+ export function installSummarizer(compaction, llm, log = () => undefined, deps = {}) {
738
+ const engine = rawService(compaction);
739
+ if (engine === undefined || typeof engine.summarize !== 'function') return () => undefined;
740
+ const stockSummarize = engine.summarize;
741
+ const summarizer = createSummarizer({
742
+ llm,
743
+ stock: (input, agent, signal) => stockSummarize.call(engine, input, agent, signal),
744
+ engineConfig: () => engine.config,
745
+ log,
746
+ });
747
+ /** agent → why the compaction now running started (set by the engine entry points below). */
748
+ const reasons = new WeakMap();
749
+ /** session → the agent compacting it (the engine's tool-output pruner is handed the session only). */
750
+ const sessionAgents = new WeakMap();
751
+ const notice = createNoticeWriter({ engine, llm, log, appendRecord: deps.appendRecord });
752
+ const override = async function summarize(input, agent, signal) {
753
+ await notice(agent, reasons.get(agent));
754
+ return summarizer.summarize(input, agent, signal);
755
+ };
756
+ const installed = { summarize: override };
757
+ // Shortening starts near the window, not at 80% of it (PRESSURE_RATIO). The engine reads its config at every check.
758
+ const stockConfig = engine.config;
759
+ const raisedConfig = withPressureRatio(stockConfig);
760
+ if (raisedConfig !== stockConfig) {
761
+ try {
762
+ engine.config = raisedConfig;
763
+ } catch (error) {
764
+ log(`compaction: the pressure ratio was not raised (${firstLine(error)})`);
765
+ }
766
+ }
767
+ // The engine's tool-output pruner (dsh-compaction-tool-result-pruner) trims old outputs before any summary; each
768
+ // pass that trims something records the same notice with scope `tool-outputs`, so the transcript's one trimmed line
769
+ // says why ("Shortened 14 old tool outputs to fit <model> (39k tokens saved): <reason>").
770
+ let prunerUndo;
771
+ const wrapPruner = () => {
772
+ if (prunerUndo !== undefined) return;
773
+ let pruner;
774
+ try {
775
+ pruner = rawService(deps.pruner ?? engine.ctx?.get?.('toolResultPruner') ?? engine.ctx?.toolResultPruner);
776
+ } catch {
777
+ pruner = undefined;
778
+ }
779
+ if (pruner === undefined || typeof pruner.pruneSession !== 'function') return;
780
+ const original = pruner.pruneSession;
781
+ const wrapped = function pruneSession(session, ...rest) {
782
+ const agent = sessionAgents.get(session);
783
+ const reason = agent === undefined ? undefined : reasons.get(agent);
784
+ let tokensBefore;
785
+ if (agent !== undefined) {
786
+ try {
787
+ const header = reason?.header;
788
+ const measured = engine.ctx?.tokenMeter?.measure?.(session, ...(header === undefined ? [] : [header]));
789
+ tokensBefore = Number.isFinite(measured?.totalTokens) ? Math.round(measured.totalTokens) : undefined;
790
+ } catch {
791
+ tokensBefore = undefined;
792
+ }
793
+ }
794
+ const result = original.call(this, session, ...rest);
795
+ if (agent !== undefined && Array.isArray(result?.pruned) && result.pruned.length > 0) {
796
+ void notice(agent, reason, { scope: 'tool-outputs', ...(tokensBefore === undefined ? {} : { tokensBefore }) });
797
+ }
798
+ return result;
799
+ };
800
+ pruner.pruneSession = wrapped;
801
+ prunerUndo = () => {
802
+ if (pruner.pruneSession === wrapped) {
803
+ if (Object.getPrototypeOf(pruner)?.pruneSession === original) delete pruner.pruneSession;
804
+ else pruner.pruneSession = original;
805
+ }
806
+ };
807
+ };
808
+ const withReason = (agent, reason, run) => {
809
+ if (agent === undefined || agent === null || typeof agent !== 'object') return run();
810
+ wrapPruner();
811
+ const previous = reasons.get(agent);
812
+ reasons.set(agent, reason);
813
+ const session = agent.session;
814
+ const previousAgent = session !== null && typeof session === 'object' ? sessionAgents.get(session) : undefined;
815
+ if (session !== null && typeof session === 'object') sessionAgents.set(session, agent);
816
+ const restore = () => {
817
+ if (previous === undefined) reasons.delete(agent);
818
+ else reasons.set(agent, previous);
819
+ if (session !== null && typeof session === 'object') {
820
+ if (previousAgent === undefined) sessionAgents.delete(session);
821
+ else sessionAgents.set(session, previousAgent);
822
+ }
823
+ };
824
+ let pending;
825
+ try {
826
+ pending = run();
827
+ } catch (error) {
828
+ restore();
829
+ throw error;
830
+ }
831
+ return Promise.resolve(pending).finally(restore);
832
+ };
833
+ if (typeof engine.compactIfNeeded === 'function') {
834
+ const original = engine.compactIfNeeded;
835
+ installed.compactIfNeeded = function compactIfNeeded(agent, trigger, signal) {
836
+ if (trigger === 'pressure' && stalePressureHeader(agent)) return Promise.resolve(null);
837
+ if (trigger === 'context-overflow') return withReason(agent, { kind: 'overflow' }, () => original.call(engine, agent, trigger, signal));
838
+ return original.call(engine, agent, trigger, signal);
839
+ };
840
+ }
841
+ if (typeof engine.compactPressure === 'function') {
842
+ const original = engine.compactPressure;
843
+ installed.compactPressure = function compactPressure(agent, header, signal, requireBelowThreshold) {
844
+ const kind = requireBelowThreshold === true ? 'model-switch' : 'pressure';
845
+ return withReason(agent, { kind, header }, () => original.call(engine, agent, header, signal, requireBelowThreshold));
846
+ };
847
+ }
848
+ if (typeof engine.compactNow === 'function') {
849
+ const original = engine.compactNow;
850
+ installed.compactNow = function compactNow(agent, signal, sourceCommandId) {
851
+ return withReason(agent, { kind: 'requested' }, () => original.call(engine, agent, signal, sourceCommandId));
852
+ };
853
+ }
854
+ for (const [key, value] of Object.entries(installed)) engine[key] = value;
855
+ return () => {
856
+ for (const [key, value] of Object.entries(installed)) {
857
+ if (engine[key] === value) delete engine[key];
858
+ }
859
+ if (raisedConfig !== stockConfig && engine.config === raisedConfig) engine.config = stockConfig;
860
+ prunerUndo?.();
861
+ };
862
+ }
863
+
864
+ export function apply(ctx) {
865
+ ctx.inject?.(['compaction', 'llm'], (inner) => {
866
+ const log = (message) => {
867
+ try {
868
+ inner.logger?.info?.(message);
869
+ } catch {
870
+ // logging never fails a compaction
871
+ }
872
+ };
873
+ return installSummarizer(inner.compaction, inner.llm, log);
874
+ });
875
+ }