@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
@@ -7,6 +7,7 @@
7
7
  // 4. Tier-1 system-prompt/assemble normalizer (byte-identical across TUI/Desktop and plan/default/auto modes).
8
8
  // 5. Tier-1 agent/pre-step normalizer (8 KB instruction cap + SHA-1/@AGENTS.md dedupe, 2 KB skill catalog cap + skill_search overflow, plan-mode history reminder injection, stale-todos nudge).
9
9
  // 6. `read_image` recovery for misnamed / HEIC / TIFF images (read-image-recovery.js, a `tools/execute` wrapper).
10
+ // 7. A fast, complete `glob` for large workspaces (glob-walk.js, `tools/execute` wrappers).
10
11
  //
11
12
  // Zero external runtime dependencies (Node.js built-ins only).
12
13
 
@@ -27,8 +28,18 @@ import { basename, delimiter, dirname, join, resolve } from "node:path";
27
28
  import { fileURLToPath } from "node:url";
28
29
  import { buildContextTimeline } from "./timeline.js";
29
30
  import { installReadImageRecovery } from "./read-image-recovery.js";
31
+ import { installGlobWalk } from "./glob-walk.js";
32
+ import { installArgumentRepair, repairToolArguments } from "./argument-repair.js";
30
33
 
31
34
  export { createReadImageRecovery, recoverReadImage, sniffImageFormat } from "./read-image-recovery.js";
35
+ export { GLOB_WALK_MAX_MS, buildGlobArgv, createGlobWalk, installGlobWalk, walkGlob } from "./glob-walk.js";
36
+ export {
37
+ createArgumentErrorExplainer,
38
+ createArgumentRepairStream,
39
+ plainArgumentsCorrection,
40
+ repairArgumentsText,
41
+ repairToolArguments,
42
+ } from "./argument-repair.js";
32
43
  export {
33
44
  CONTEXT_TIMELINE_VERSION,
34
45
  buildContextTimeline,
@@ -590,7 +601,12 @@ export function measureSkillCatalogCosts(messages = [], known = new Map()) {
590
601
  for (const entry of entries) {
591
602
  if (!isRecord(entry) || typeof entry.name !== "string" || entry.name === "skill_search") continue;
592
603
  const line = lines.find((candidate) => candidate.startsWith(`- ${entry.name}: `));
593
- const bytes = line === undefined ? 0 : utf8Bytes(line) + 1;
604
+ // `source.entries` is the engine's whole catalog; an entry with no line was folded into `skill_search`.
605
+ if (line === undefined) {
606
+ skills.push(costItem("skill", entry.name, 0, bodyBytes(entry.name), { overflow: true }));
607
+ continue;
608
+ }
609
+ const bytes = utf8Bytes(line) + 1;
594
610
  lineBytes += bytes;
595
611
  skills.push(costItem("skill", entry.name, bytes, bodyBytes(entry.name)));
596
612
  }
@@ -4203,15 +4219,48 @@ export function normalizeSkillCatalogMessage(message, maxBytes = SKILL_CATALOG_M
4203
4219
  ? [...keptEntries, buildCollapseEntry(overflowSkills.length)]
4204
4220
  : keptEntries;
4205
4221
  const finalText = renderLines(finalEntries);
4206
- const cleanSourceEntries = finalEntries.map(({ isProject: _isProject, ...rest }) => rest);
4207
4222
 
4208
4223
  emitStats({ capped: overflowSkills.length > 0 });
4224
+ // Only the text the model reads changes. `source.entries` stays exactly as the engine wrote it: the engine's skill
4225
+ // tool digests the durable catalog's `[name, description]` entries against its live catalog at every step and
4226
+ // publishes a replacement catalog whenever they differ. Writing the trimmed, budget-capped list (with the
4227
+ // `skill_search` fold entry) back into `source.entries` made those digests never match, so every step appended a
4228
+ // byte-identical "catalog changed" reminder (381 of 381 steps in one session).
4209
4229
  return {
4210
- message: replaceMessageText(message, finalText, { entries: cleanSourceEntries }),
4230
+ message: replaceMessageText(message, finalText),
4211
4231
  overflowSkills,
4212
4232
  };
4213
4233
  }
4214
4234
 
4235
+ /**
4236
+ * The part of a rendered skill catalog that carries information: everything after the header line. The first catalog
4237
+ * and a "catalog changed" replacement differ only in that header, so equal bodies mean the model already has this list.
4238
+ */
4239
+ export function skillCatalogBody(text) {
4240
+ const lines = String(text ?? "").split("\n");
4241
+ const start = lines[0]?.trim() === "<system-reminder>" ? 2 : 1;
4242
+ return lines.slice(start).join("\n");
4243
+ }
4244
+
4245
+ /**
4246
+ * The text of the newest skill catalog the model can still see in `session` (its visible surface, so a catalog a
4247
+ * compaction summarised away does not count), or undefined when there is none or the session has no readable surface.
4248
+ */
4249
+ export function visibleSkillCatalogText(session) {
4250
+ const nodes = session?.surface?.nodes;
4251
+ if (!Array.isArray(nodes) || typeof session?.eventAt !== "function") return undefined;
4252
+ for (let index = nodes.length - 1; index >= 0; index -= 1) {
4253
+ let event;
4254
+ try {
4255
+ event = session.eventAt(nodes[index]);
4256
+ } catch {
4257
+ return undefined;
4258
+ }
4259
+ if (event?.type === "user/message" && event.data?.source?.kind === "skill-catalog") return extractMessageText(event.data);
4260
+ }
4261
+ return undefined;
4262
+ }
4263
+
4215
4264
  // ── Stale-todos nudge (Tier 2) ──────────────────────────────────────────────────────────────────────
4216
4265
  //
4217
4266
  // Some models call `todo_write` once and never again, so the plan the UI shows freezes on step 1. When the
@@ -4505,7 +4554,8 @@ function emptyStepStats() {
4505
4554
  return {
4506
4555
  messageCount: 0,
4507
4556
  instructions: { before: 0, after: 0, capped: false },
4508
- skillCatalog: { before: 0, after: 0, capped: false, overflowCount: 0 },
4557
+ // `unchangedDropped`: catalogs not sent because the model already sees the same list (`visibleSkillCatalogText`).
4558
+ skillCatalog: { before: 0, after: 0, capped: false, overflowCount: 0, unchangedDropped: 0 },
4509
4559
  dedupe: { removedBlocks: 0, removedNames: [] },
4510
4560
  injected: { planMode: false, runtimePolicy: false, staleTodos: false, planNudge: false },
4511
4561
  // UTF-8 bytes of each injected reminder, by reminder name (the context timeline's sizes).
@@ -4516,7 +4566,8 @@ function emptyStepStats() {
4516
4566
  /**
4517
4567
  * Normalizes a `pre-step` `decision.messages` array in place / returns normalized copy:
4518
4568
  * 1. Deduplicates & caps `agent-instructions` at 8,192 B.
4519
- * 2. Trims & caps `skill-catalog` at 2,048 B with `skill_search` collapse entry.
4569
+ * 2. Trims & caps `skill-catalog` at 2,048 B with `skill_search` collapse entry, and drops it when its list equals
4570
+ * `options.visibleSkillCatalogText` (the newest catalog the model still sees).
4520
4571
  * 3. Appends `plan-mode` reminder message if the agent has active `plan:policy` text.
4521
4572
  * 4. Appends the `stale-todos` nudge at the tail when `options.staleTodos` (the todo list) is passed.
4522
4573
  * 5. Appends the `plan-nudge` reminder at the tail when `options.planNudge === true` and no stale-todos nudge is
@@ -4629,6 +4680,15 @@ export function normalizePreStepMessages(messages, options = {}) {
4629
4680
  const catalogStats = {};
4630
4681
  const { message: nextMsg, overflowSkills } = normalizeSkillCatalogMessage(msg, skillCatalogMaxBytes, catalogStats);
4631
4682
  collectedOverflowSkills.push(...overflowSkills);
4683
+ // A catalog the model already sees, word for word, is not sent again. Sessions written before the fix above carry
4684
+ // trimmed `source.entries`, so the engine still re-publishes there at every step; this keeps them from growing.
4685
+ if (
4686
+ typeof options.visibleSkillCatalogText === "string" &&
4687
+ skillCatalogBody(extractMessageText(nextMsg)) === skillCatalogBody(options.visibleSkillCatalogText)
4688
+ ) {
4689
+ stats.skillCatalog.unchangedDropped += 1;
4690
+ continue;
4691
+ }
4632
4692
  stats.skillCatalog.before += rawBefore;
4633
4693
  stats.skillCatalog.after += Buffer.byteLength(extractMessageText(nextMsg), "utf8");
4634
4694
  stats.skillCatalog.capped = stats.skillCatalog.capped || catalogStats.capped === true;
@@ -4754,6 +4814,62 @@ function formatSchemaOnError(toolName, errorMsg, schema) {
4754
4814
  return `${cleanError}${schemaBlock}`;
4755
4815
  }
4756
4816
 
4817
+ /** Job tools that name a background job by id (`job_id`). */
4818
+ const JOB_TOOLS = new Set(["job_output", "job_kill", "job_wait"]);
4819
+ const LOST_JOB_OUTPUT_CHARS = 2000;
4820
+
4821
+ /**
4822
+ * The plain answer for a job tool that names a job this engine does not know (`unknown job <id>`), from the session's
4823
+ * own log: a background job lives in the engine that started it, and ends with it (the engine stops its jobs when the
4824
+ * session closes, restarts or is reopened on another model). Instead of "unknown job" the model reads what happened,
4825
+ * when, the last output it had read (if any) and the command, so it can run it again. Undefined when the log never
4826
+ * had that job (a mistyped id keeps the engine's own error).
4827
+ * @param {string} toolName
4828
+ * @param {unknown} rawErr
4829
+ * @param {{ ownEvents?: () => readonly any[] } | undefined} session
4830
+ */
4831
+ export function lostJobLine(toolName, rawErr, session) {
4832
+ if (!JOB_TOOLS.has(String(toolName ?? ""))) return undefined;
4833
+ const match = /unknown job (\S+)/u.exec(String(rawErr ?? ""));
4834
+ if (match === null) return undefined;
4835
+ const id = match[1];
4836
+ let events = [];
4837
+ try {
4838
+ events = typeof session?.ownEvents === "function" ? session.ownEvents() : [];
4839
+ } catch {
4840
+ events = [];
4841
+ }
4842
+ let registered;
4843
+ let settled;
4844
+ let lastOutput;
4845
+ for (const event of Array.isArray(events) ? events : []) {
4846
+ const data = event?.data;
4847
+ if (!isRecord(data)) continue;
4848
+ if (event.type === "job/registered" && data.jobId === id) registered = data;
4849
+ else if (event.type === "job/settled" && data.jobId === id) settled = data;
4850
+ else if (event.type === "tool/ptc-dispatch" && data.name === "job_output" && data.isError !== true && data.arguments?.job_id === id) {
4851
+ const text = (Array.isArray(data.content) ? data.content : []).map((block) => (typeof block?.text === "string" ? block.text : "")).join("\n").trim();
4852
+ if (text.length > 0 && !text.startsWith("(no new output)")) lastOutput = text;
4853
+ }
4854
+ }
4855
+ if (registered === undefined && settled === undefined) return undefined;
4856
+ const at = (time) => (Number.isFinite(time) ? ` at ${new Date(time).toISOString().slice(11, 16)} UTC` : "");
4857
+ const record = settled ?? registered;
4858
+ const detail = typeof settled?.detail === "string" && settled.detail.length > 0 ? ` (${settled.detail})` : "";
4859
+ const ended =
4860
+ settled === undefined
4861
+ ? "was started by an earlier run of this session and ended with it"
4862
+ : settled.cause === "teardown" || settled.status === "killed"
4863
+ ? `ended when the session restarted${at(settled.finishedAt)}${detail}`
4864
+ : `finished${at(settled.finishedAt)} with status ${String(settled.status ?? "unknown")}${detail}`;
4865
+ const output =
4866
+ lastOutput === undefined
4867
+ ? "Its output was not kept."
4868
+ : `Its last output was:\n${lastOutput.length > LOST_JOB_OUTPUT_CHARS ? `…${lastOutput.slice(-LOST_JOB_OUTPUT_CHARS)}` : lastOutput}`;
4869
+ const command = typeof record?.label === "string" && record.label.length > 0 ? `\nCommand: ${record.label}` : "";
4870
+ return `Job ${id} is not running any more: it ${ended}. ${output}${command}\nRun it again if you still need its result.`;
4871
+ }
4872
+
4757
4873
  /**
4758
4874
  * Session-history failures that mean the feature itself is unavailable (not a bad argument), by the engine's
4759
4875
  * `SessionQueryError` code, as the one plain line both the model and the person see. Keyed by code, with the engine
@@ -5317,7 +5433,7 @@ export function apply(ctx, config = {}, deps = {}) {
5317
5433
  const toolMeta = serverMap?.get(shortName) ?? deferredTools.get(fullMcpName);
5318
5434
  const cachedSchema = toolMeta?.parameters ?? toolMeta?.inputSchema;
5319
5435
 
5320
- const callArgs = cachedSchema ? normalizeToolArguments(subArgs, cachedSchema) : subArgs;
5436
+ const callArgs = cachedSchema ? normalizeToolArguments(repairToolArguments(subArgs, cachedSchema).args, cachedSchema) : subArgs;
5321
5437
  if (cachedSchema) {
5322
5438
  const validation = validateAgainstInputSchema(callArgs, cachedSchema);
5323
5439
  if (!validation.valid) {
@@ -5419,7 +5535,7 @@ export function apply(ctx, config = {}, deps = {}) {
5419
5535
 
5420
5536
  // Reshape what models naturally send (`query` for a required `queries` list), then validate required parameters
5421
5537
  // and basic property types before invoking.
5422
- if (cachedSchema) args = normalizeToolArguments(args, cachedSchema);
5538
+ if (cachedSchema) args = normalizeToolArguments(repairToolArguments(args, cachedSchema).args, cachedSchema);
5423
5539
  if (cachedSchema) {
5424
5540
  const validation = validateAgainstInputSchema(args, cachedSchema);
5425
5541
  if (!validation.valid) {
@@ -5501,10 +5617,12 @@ export function apply(ctx, config = {}, deps = {}) {
5501
5617
  outcome.error?.message ??
5502
5618
  (Array.isArray(outcome.content) ? outcome.content.map((c) => c?.text).join("\n") : "") ??
5503
5619
  `Tool "${targetName}" failed.`;
5504
- // An unavailable feature is not an argument problem: the plain line goes back alone, without the schema.
5505
- const enriched = SESSION_QUERY_UNAVAILABLE_LINES.has(String(rawErr).trim())
5620
+ // An unavailable feature or a job that ended with an earlier engine is not an argument problem: the plain
5621
+ // line goes back alone, without the schema.
5622
+ const lostJob = lostJobLine(targetName, rawErr, session);
5623
+ const enriched = lostJob ?? (SESSION_QUERY_UNAVAILABLE_LINES.has(String(rawErr).trim())
5506
5624
  ? String(rawErr).trim()
5507
- : formatSchemaOnError(targetName, rawErr, cachedSchema);
5625
+ : formatSchemaOnError(targetName, rawErr, cachedSchema));
5508
5626
  return {
5509
5627
  ok: false,
5510
5628
  isError: true,
@@ -6036,7 +6154,10 @@ export function apply(ctx, config = {}, deps = {}) {
6036
6154
  "tools/post-execute",
6037
6155
  async (exec, result, next) => {
6038
6156
  const downstream = typeof next === "function" ? await next() : { kind: "accept" };
6039
- const line = sessionQueryUnavailableLine(exec?.name, result);
6157
+ const failure = isRecord(result) && result.isError === true
6158
+ ? result.error?.message ?? (Array.isArray(result.content) ? result.content.map((block) => block?.text ?? "").join("\n") : "")
6159
+ : undefined;
6160
+ const line = sessionQueryUnavailableLine(exec?.name, result) ?? (failure === undefined ? undefined : lostJobLine(exec?.name, failure, exec?.agent?.session));
6040
6161
  if (line === undefined) return downstream;
6041
6162
  return { kind: "block", feedback: [{ type: "text", text: line }] };
6042
6163
  },
@@ -6051,6 +6172,26 @@ export function apply(ctx, config = {}, deps = {}) {
6051
6172
  installReadImageRecovery(ctx, deps.readImageRecovery);
6052
6173
  }
6053
6174
 
6175
+ // `glob` in a large workspace: the engine walks every ignored tree on one thread and hits its 30 s limit. This answers
6176
+ // the same call with a gitignore-aware parallel walk that still returns every match, under the caller's own abort
6177
+ // and a 10 min ceiling (glob-walk.js). Tier 1 is untouched. Off with `globWalk: false` or PICASSO_LEAN_CONTEXT_GLOB_WALK=0.
6178
+ if (config.globWalk !== false && process.env.PICASSO_LEAN_CONTEXT_GLOB_WALK !== "0") {
6179
+ installGlobWalk(ctx, deps.globWalk);
6180
+ }
6181
+
6182
+ // A nested list/object/number/boolean the model sent as a JSON string is decoded against the tool's own schema
6183
+ // before the engine logs and validates the call; a call that still fails gets a plain-words expected shape
6184
+ // (argument-repair.js). Tier 1 is untouched. Off with `argumentRepair: false` or PICASSO_LEAN_CONTEXT_ARGUMENT_REPAIR=0.
6185
+ if (config.argumentRepair !== false && process.env.PICASSO_LEAN_CONTEXT_ARGUMENT_REPAIR !== "0") {
6186
+ installArgumentRepair(ctx, {
6187
+ schemaFor: (exec) => {
6188
+ const tool = toolsServiceOf(ctx)?.get?.(exec?.name, exec?.agent, exec?.toolSet);
6189
+ return tool?.parameters ?? tool?.inputSchema;
6190
+ },
6191
+ ...(deps.argumentRepairLog === undefined ? {} : { log: deps.argumentRepairLog }),
6192
+ });
6193
+ }
6194
+
6054
6195
  // Propagate `isError: true` from `tool_call` / `<server>_call` through dsh-tools `tools/post-execute`
6055
6196
  ctx?.on?.(
6056
6197
  "tools/post-execute",
@@ -6246,8 +6387,15 @@ export function apply(ctx, config = {}, deps = {}) {
6246
6387
  statedReminders = scanStatedReminders(statedReminderStates, session).last;
6247
6388
  }
6248
6389
 
6390
+ // The catalog the model already sees; read only when this step carries one (start, compaction, real change).
6391
+ const visibleCatalog =
6392
+ session && !payload?.signal?.aborted && decision.messages.some((m) => m?.source?.kind === "skill-catalog")
6393
+ ? visibleSkillCatalogText(session)
6394
+ : undefined;
6395
+
6249
6396
  const { messages: normalizedMessages, overflowSkills, stats: stepStats } =
6250
6397
  normalizePreStepMessages(decision.messages, {
6398
+ visibleSkillCatalogText: visibleCatalog,
6251
6399
  statedReminders,
6252
6400
  instructionMaxBytes,
6253
6401
  skillCatalogMaxBytes,
@@ -61,7 +61,12 @@ export const SERVICE_KEY = 'memory';
61
61
  const REMOTE_METHOD_DESCRIPTOR = '@deepseek-ai/dsh-typert-protocol/remote-methods';
62
62
  /** Memory classes the Mac's `MemoryClass` enum stores verbatim. */
63
63
  export const MEMORY_CLASSES = ['fact', 'decision', 'style', 'workflow', 'repo-rule', 'failure', 'model-performance'];
64
- const REMEMBER_MAX_BODY = 4000;
64
+ /**
65
+ * Largest `remember` body (bytes). A saved note is loaded in full only on demand (`recall`, Tier 2); Tier 1 carries at
66
+ * most its index line, so a long note costs nothing until asked for. Raised from 4000 (owner 2026-11-17: a note was
67
+ * refused for being too long): no real note reaches this.
68
+ */
69
+ export const REMEMBER_MAX_BODY = 65_536;
65
70
  const INLINE_PREFERENCE_MAX_CHARS = 240;
66
71
  /** Scopes the Mac writes for "All projects" (`MemoryView.projectLabel`). */
67
72
  const GLOBAL_SCOPES = new Set(['', 'workspace', 'global', 'all projects']);
@@ -210,10 +215,15 @@ function formatIndexLine(record) {
210
215
  return `- ${record.id} · ${classOf(record)} · ${titleOrPreview} · ${scope}`;
211
216
  }
212
217
 
218
+ /** Said when more memories match than the reminder holds: they are never dropped without a word. */
219
+ const omittedLine = (count) => `${count} more saved ${count === 1 ? 'memory matches' : 'memories match'}; recall({ query: "<topic>" }) finds ${count === 1 ? 'it' : 'them'}.`;
220
+ /** Bytes kept free for the omitted line (its longest form, with a 4-digit count, is under 100 bytes). */
221
+ const OMITTED_LINE_RESERVE = 100;
222
+
213
223
  const TIER1_FOOTER = 'Use recall({ ids: ["<id>"] }) or recall({ query: "<topic>" }) to load full memory bodies on demand.';
214
224
 
215
225
  /** Renders the Two-Tier Tier 1 `<system-reminder>` text from partitioned `inlineRecords` and `indexRecords`. */
216
- export function renderTier1Recall(inlineRecords = [], indexRecords = []) {
226
+ export function renderTier1Recall(inlineRecords = [], indexRecords = [], omitted = 0) {
217
227
  const lines = [
218
228
  '<system-reminder>',
219
229
  'Picasso memory:',
@@ -223,6 +233,7 @@ export function renderTier1Recall(inlineRecords = [], indexRecords = []) {
223
233
  if (indexRecords.length > 0) {
224
234
  lines.push(TIER1_FOOTER);
225
235
  }
236
+ if (omitted > 0) lines.push(omittedLine(omitted));
226
237
  lines.push('</system-reminder>');
227
238
  return escapeSystemReminder(lines.join('\n'));
228
239
  }
@@ -253,31 +264,40 @@ export function selectForTurn(
253
264
  const inlineCandidates = scored.filter((r) => isInlineAlways(r));
254
265
  const indexCandidates = scored.filter((r) => !isInlineAlways(r));
255
266
 
256
- const inlineRecords = [];
257
- const indexRecords = [];
258
-
259
- for (const record of inlineCandidates) {
260
- if (inlineRecords.length + indexRecords.length >= maxItems) break;
261
- const candidateInline = [...inlineRecords, record];
262
- const candidateText = renderTier1Recall(candidateInline, indexRecords);
263
- if (Buffer.byteLength(candidateText, 'utf8') > effectiveMaxBytes) continue;
264
- inlineRecords.push(record);
265
- }
266
-
267
- for (const record of indexCandidates) {
268
- if (inlineRecords.length + indexRecords.length >= maxItems) break;
269
- const candidateIndex = [...indexRecords, record];
270
- const candidateText = renderTier1Recall(inlineRecords, candidateIndex);
271
- if (Buffer.byteLength(candidateText, 'utf8') > effectiveMaxBytes) continue;
272
- indexRecords.push(record);
273
- }
267
+ // A memory that does not fit inline (a long pinned note) is listed as an index line instead, so it stays reachable
268
+ // through `recall`; whatever still does not fit is counted in one line rather than dropped silently. When something
269
+ // is left out, the selection is redone with room kept for that line, so the reminder stays within the byte budget.
270
+ const partition = (budget) => {
271
+ const inline = [];
272
+ const index = [];
273
+ const demoted = [];
274
+ for (const record of inlineCandidates) {
275
+ if (inline.length + index.length >= maxItems) break;
276
+ if (Buffer.byteLength(renderTier1Recall([...inline, record], index), 'utf8') > budget) {
277
+ demoted.push(record);
278
+ continue;
279
+ }
280
+ inline.push(record);
281
+ }
282
+ for (const record of [...demoted, ...indexCandidates]) {
283
+ if (inline.length + index.length >= maxItems) break;
284
+ if (Buffer.byteLength(renderTier1Recall(inline, [...index, record]), 'utf8') > budget) continue;
285
+ index.push(record);
286
+ }
287
+ return { inline, index, omitted: scored.length - inline.length - index.length };
288
+ };
289
+ let picked = partition(effectiveMaxBytes);
290
+ if (picked.omitted > 0) picked = partition(Math.max(0, effectiveMaxBytes - OMITTED_LINE_RESERVE));
291
+ const inlineRecords = picked.inline;
292
+ const indexRecords = picked.index;
293
+ const omitted = picked.omitted;
274
294
 
275
295
  if (shown) {
276
296
  for (const record of inlineRecords) shown.add(record.id);
277
297
  }
278
298
 
279
299
  const chosen = [...inlineRecords, ...indexRecords];
280
- const text = chosen.length > 0 ? renderTier1Recall(inlineRecords, indexRecords) : '';
300
+ const text = chosen.length > 0 || omitted > 0 ? renderTier1Recall(inlineRecords, indexRecords, omitted) : '';
281
301
  const source = Object.freeze({
282
302
  kind: SOURCE_KIND,
283
303
  form: indexRecords.length > 0 ? 'index' : 'recall',
@@ -286,7 +306,7 @@ export function selectForTurn(
286
306
  indexIds: Object.freeze(indexRecords.map((r) => r.id)),
287
307
  availableCount: inlineRecords.length + indexRecords.length,
288
308
  });
289
- const message = chosen.length > 0
309
+ const message = text.length > 0
290
310
  ? Object.freeze({
291
311
  role: 'user',
292
312
  content: Object.freeze([Object.freeze({ type: 'text', text })]),
@@ -319,12 +339,29 @@ function historyOf(agentOrSession) {
319
339
  agentOrSession?.messages ??
320
340
  agentOrSession?.session?.context?.messages ??
321
341
  agentOrSession?.session?.messages;
322
- return Array.isArray(visible) ? visible : [];
342
+ if (Array.isArray(visible)) return visible;
343
+ return surfaceRecalls(agentOrSession?.session ?? agentOrSession);
323
344
  } catch {
324
345
  return [];
325
346
  }
326
347
  }
327
348
 
349
+ /**
350
+ * The memory reminders the model can still see, read from the engine's durable session surface (`surface.nodes` +
351
+ * `eventAt`). dsh sessions expose no `messages` array, so without this a reopened session (a model switch or a resume
352
+ * builds a new agent) read an empty history and inlined the same memory body again on its next turn.
353
+ */
354
+ function surfaceRecalls(session) {
355
+ const nodes = session?.surface?.nodes;
356
+ if (!Array.isArray(nodes) || typeof session?.eventAt !== 'function') return [];
357
+ const recalls = [];
358
+ for (const seq of nodes) {
359
+ const event = session.eventAt(seq);
360
+ if (event?.type === 'user/message' && isRecall(event.data)) recalls.push(event.data);
361
+ }
362
+ return recalls;
363
+ }
364
+
328
365
  /** All memory ids surfaced in Tier 1 (inline or index) in an agent's message history. */
329
366
  function tier1SeenInHistory(messages) {
330
367
  const ids = new Set();
@@ -479,6 +516,11 @@ export function recallMemories(fileOrRecords, args = {}, exec = {}, { defaultSes
479
516
  }
480
517
  }
481
518
 
519
+ // More matches than `limit`: say so, with how to reach the rest, instead of dropping them silently.
520
+ const remaining = matched.length - selected.length;
521
+ if (remaining > 0) {
522
+ lines.push(`(${remaining} more matching ${remaining === 1 ? 'memory' : 'memories'} not shown; call recall again with a larger limit, their ids, or a narrower query)`);
523
+ }
482
524
  const text = lines.length > 0 ? lines.join('\n') : 'No matching memories found.';
483
525
  // Plain JSON only: dsh rejects a tool output that is not lossless JSON (a method here made every recall fail).
484
526
  return { text, content: [{ type: 'text', text }], items, loadedIds, dedupedIds };
@@ -731,7 +773,7 @@ export function rememberWrite(file, args, exec, invalidate) {
731
773
  if (!file) throw new Error(`${REMEMBER_TOOL}: ${FILE_ENV} is not configured for this engine`);
732
774
  const body = String(args?.body ?? '').trim();
733
775
  if (!body) throw new Error(`${REMEMBER_TOOL}: 'body' is required`);
734
- if (Buffer.byteLength(body, 'utf8') > REMEMBER_MAX_BODY) throw new Error(`${REMEMBER_TOOL}: memory is over ${REMEMBER_MAX_BODY} bytes — keep it to one short sentence`);
776
+ if (Buffer.byteLength(body, 'utf8') > REMEMBER_MAX_BODY) throw new Error(`${REMEMBER_TOOL}: this memory is ${Buffer.byteLength(body, 'utf8')} bytes, over the ${REMEMBER_MAX_BODY}-byte limit for one memory — save it as several memories, or write it to a file in the project and remember the path`);
735
777
  const memoryClass = args?.memoryClass === undefined ? 'fact' : String(args.memoryClass);
736
778
  if (!MEMORY_CLASSES.includes(memoryClass)) throw new Error(`${REMEMBER_TOOL}: memoryClass must be one of ${MEMORY_CLASSES.join(', ')}`);
737
779
  const cwd = typeof exec?.agent?.cwd === 'string' && exec.agent.cwd ? exec.agent.cwd : undefined;