@circuitwall/jarela 2.2.1 → 2.4.0

package/lib/agents/instruction-edits.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { applyInstructionEdits } from "./instruction-edits";
+
+function edit(base: string, edits: unknown): string {
+  const out = applyInstructionEdits(base, edits);
+  if (!out.ok) throw new Error(out.error);
+  return out.text;
+}
+
+describe("applyInstructionEdits validation", () => {
+  it("rejects a non-array and reports the failing index", () => {
+    expect(applyInstructionEdits("x", { op: "append" })).toEqual({ ok: false, error: "instructions_edits must be an array" });
+    expect(applyInstructionEdits("x", [{ op: "append", text: "a" }, null])).toEqual({ ok: false, error: "instructions_edits[1] must be an object" });
+    expect(applyInstructionEdits("x", [{}])).toEqual({ ok: false, error: "instructions_edits[0].op is required" });
+    expect(applyInstructionEdits("x", [{ op: "rewrite" }])).toEqual({ ok: false, error: "instructions_edits[0].op is not supported" });
+    expect(applyInstructionEdits("x", [{ op: "replace", find: "x" }])).toEqual({ ok: false, error: "instructions_edits[0].replace must be a string" });
+  });
+
+  it("fails the whole batch instead of applying a prefix of it", () => {
+    const out = applyInstructionEdits("keep", [{ op: "append", text: " more" }, { op: "remove" }]);
+    expect(out.ok).toBe(false);
+  });
+});
+
+describe("append / prepend", () => {
+  it("skips an if_missing append when the text is already present, honoring ignore_case", () => {
+    const out = applyInstructionEdits("Always cite sources.", [
+      { op: "append", text: "always CITE sources.", if_missing: true, ignore_case: true },
+      { op: "prepend", text: "Be brief. ", if_missing: true },
+    ]);
+    expect(out).toEqual({
+      ok: true,
+      text: "Be brief. Always cite sources.",
+      summary: [
+        { index: 0, op: "append", applied: false },
+        { index: 1, op: "prepend", applied: true },
+      ],
+    });
+  });
+});
+
+describe("replace / remove", () => {
+  it("treats find text literally, including regex metacharacters and $ patterns", () => {
+    expect(edit("cost is $5 (approx.)", [{ op: "replace", find: "$5 (approx.)", replace: "$$ & $&", ignore_case: true }]))
+      .toBe("cost is $$ & $&");
+    expect(edit("a.b a.b", [{ op: "replace", find: "a.b", replace: "$'", all: true }])).toBe("$' $'");
+  });
+
+  it("replaces only the first match unless all is set, and counts replacements", () => {
+    const out = applyInstructionEdits("Foo foo FOO", [
+      { op: "replace", find: "foo", replace: "bar", ignore_case: true },
+      { op: "remove", text: "FOO", all: true },
+    ]);
+    expect(out).toMatchObject({ ok: true, text: "bar foo ", summary: [{ replacements: 1 }, { removals: 1 }] });
+  });
+
+  it("is a no-op for an empty find string rather than inserting between every character", () => {
+    expect(edit("abc", [{ op: "replace", find: "", replace: "-", all: true }])).toBe("abc");
+  });
+});
+
+describe("dedupe_lines", () => {
+  it("removes repeated rules case-insensitively but keeps blank lines", () => {
+    const out = applyInstructionEdits("- Cite sources\n\n- cite sources \n- Be brief\n\n", [{ op: "dedupe_lines" }]);
+    expect(out).toMatchObject({ ok: true, text: "- Cite sources\n\n- Be brief\n\n", summary: [{ removed: 1 }] });
+  });
+
+  it("keeps the last occurrence when asked", () => {
+    expect(edit("a\nb\nA", [{ op: "dedupe_lines", keep: "last" }])).toBe("b\nA");
+  });
+
+  it("never removes code fence markers, fenced content, or horizontal rules", () => {
+    const base = [
+      "Rule one",
+      "```json",
+      "{ \"a\": 1 }",
+      "```",
+      "---",
+      "Example two:",
+      "```json",
+      "{ \"a\": 1 }",
+      "```",
+      "---",
+      "Rule one",
+    ].join("\n");
+    const expected = base.split("\n").slice(0, -1).join("\n");
+    expect(edit(base, [{ op: "dedupe_lines" }])).toBe(expected);
+  });
+
+  it("does not treat a fence line with an info string as the closing fence", () => {
+    const base = "```text\n```json\nx\nx\n```\n";
+    expect(edit(base, [{ op: "dedupe_lines" }])).toBe(base);
+  });
+  it("preserves CRLF line endings", () => {
+    expect(edit("a\r\nb\r\na\r\nc", [{ op: "dedupe_lines" }])).toBe("a\r\nb\r\nc");
+  });
+});
+
+describe("dedupe_paragraphs", () => {
+  it("removes a repeated paragraph and leaves the rest of the text byte-identical", () => {
+    const base = "# Rules\n\n  - indented item\n  - second\n\n\nAlways cite.\n\nalways cite.\n";
+    expect(edit(base, [{ op: "dedupe_paragraphs" }])).toBe("# Rules\n\n  - indented item\n  - second\n\n\nAlways cite.\n");
+  });
+
+  it("does not touch whitespace when there is nothing to remove", () => {
+    const base = "\n\nIntro\n\n\n\n    indented code\n";
+    const out = applyInstructionEdits(base, [{ op: "dedupe_paragraphs" }]);
+    expect(out).toMatchObject({ ok: true, text: base, summary: [{ removed: 0 }] });
+  });
+
+  it("respects trim: false by treating differently indented paragraphs as distinct", () => {
+    const base = "item\n\n  item";
+    expect(edit(base, [{ op: "dedupe_paragraphs", trim: false }])).toBe(base);
+    expect(edit(base, [{ op: "dedupe_paragraphs" }])).toBe("item");
+  });
+
+  it("keeps the last occurrence and drops the separator that belonged to the removed paragraph", () => {
+    expect(edit("A\n\nB\n\na", [{ op: "dedupe_paragraphs", keep: "last" }])).toBe("B\n\na");
+  });
+});

package/lib/agents/instruction-edits.ts

@@ -172,58 +172,81 @@ function containsText(source: string, needle: string, ignoreCase: boolean): bool
   return source.toLowerCase().includes(needle.toLowerCase());
 }
 
+const FENCE_RE = /^\s{0,3}(`{3,}|~{3,})/;
+const HORIZONTAL_RULE_RE = /^\s{0,3}([-*_])(?:\s*\1){2,}\s*$/;
+
+/**
+ * Drop duplicate segments from `parts`, which alternates content (even
+ * indexes) and the original separator that follows it (odd indexes).
+ * Separators are preserved verbatim, so only removed segments change the
+ * text. `keyOf` returns null for a segment that must always be kept.
+ */
+function dedupeSegments(
+  parts: readonly string[],
+  keyOf: (segmentIndex: number) => string | null,
+  keep: "first" | "last",
+): { text: string; removed: number } {
+  const contentIdx = parts.map((_, i) => i).filter((i) => i % 2 === 0);
+  const visit = keep === "first" ? contentIdx : [...contentIdx].reverse();
+  const seen = new Set<string>();
+  const dropped = new Set<number>();
+  for (const idx of visit) {
+    const key = keyOf(idx);
+    if (key === null) continue;
+    if (seen.has(key)) dropped.add(idx);
+    else seen.add(key);
+  }
+  if (dropped.size === 0) return { text: parts.join(""), removed: 0 };
+  let text = "";
+  let emitted = false;
+  for (const idx of contentIdx) {
+    if (dropped.has(idx)) continue;
+    if (emitted && idx > 0) text += parts[idx - 1];
+    text += parts[idx];
+    emitted = true;
+  }
+  return { text, removed: dropped.size };
+}
+
 function dedupeLines(
   source: string,
   opts: { trim: boolean; ignoreCase: boolean; skipBlank: boolean; keep: "first" | "last" },
 ): { text: string; removed: number } {
-  const lines = source.split(/\r?\n/);
-  const keyed = lines.map((line) => {
-    const normalized = opts.trim ? line.trim() : line;
-    return opts.ignoreCase ? normalized.toLowerCase() : normalized;
-  });
-
-  const keep = new Set<number>();
-  const visit = opts.keep === "first"
-    ? [...keyed.keys()]
-    : [...keyed.keys()].reverse();
-  const seen = new Set<string>();
-  for (const idx of visit) {
-    const key = keyed[idx];
-    if (opts.skipBlank && key.length === 0) {
-      keep.add(idx);
-      continue;
+  const parts = source.split(/(\r?\n)/);
+  // Fence markers, fenced code and horizontal rules repeat by design; a
+  // closing ``` is always a "duplicate" of the opening one.
+  const protectedIdx = new Set<number>();
+  let fence: string | null = null;
+  for (let i = 0; i < parts.length; i += 2) {
+    const marker = FENCE_RE.exec(parts[i])?.[1];
+    if (fence !== null) {
+      protectedIdx.add(i);
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length && /^\s*[`~]+\s*$/.test(parts[i])) fence = null;
+    } else if (marker) {
+      protectedIdx.add(i);
+      fence = marker;
+    } else if (HORIZONTAL_RULE_RE.test(parts[i])) {
+      protectedIdx.add(i);
     }
-    if (seen.has(key)) continue;
-    seen.add(key);
-    keep.add(idx);
   }
-  const next = lines.filter((_, idx) => keep.has(idx));
-  return { text: next.join("\n"), removed: lines.length - next.length };
+  return dedupeSegments(parts, (i) => {
+    if (protectedIdx.has(i)) return null;
+    const normalized = opts.trim ? parts[i].trim() : parts[i];
+    if (opts.skipBlank && normalized.length === 0) return null;
+    return opts.ignoreCase ? normalized.toLowerCase() : normalized;
+  }, opts.keep);
 }
 
 function dedupeParagraphs(
   source: string,
   opts: { trim: boolean; ignoreCase: boolean; keep: "first" | "last" },
 ): { text: string; removed: number } {
-  const paragraphs = source
-    .split(/\n\s*\n/)
-    .map((p) => p.trim())
-    .filter((p) => p.length > 0);
-  const keys = paragraphs.map((p) => {
-    const base = opts.trim ? p.trim() : p;
+  const tail = /\s*$/.exec(source)?.[0] ?? "";
+  const parts = source.slice(0, source.length - tail.length).split(/(\r?\n(?:[ \t]*\r?\n)+)/);
+  const out = dedupeSegments(parts, (i) => {
+    if (parts[i].trim().length === 0) return null;
+    const base = opts.trim ? parts[i].trim() : parts[i];
     return opts.ignoreCase ? base.toLowerCase() : base;
-  });
-  const keep = new Set<number>();
-  const visit = opts.keep === "first"
-    ? [...keys.keys()]
-    : [...keys.keys()].reverse();
-  const seen = new Set<string>();
-  for (const idx of visit) {
-    const key = keys[idx];
-    if (seen.has(key)) continue;
-    seen.add(key);
-    keep.add(idx);
-  }
-  const next = paragraphs.filter((_, idx) => keep.has(idx));
-  return { text: next.join("\n\n"), removed: paragraphs.length - next.length };
-}
+  }, opts.keep);
+  return { text: out.text + tail, removed: out.removed };
+}

package/lib/agents/prepare/history-window.test.ts

@@ -576,6 +576,24 @@ describe("buildHistoryWindow warm-summary cache", () => {
     expect(getThread(thread_id)?.warm_summary).toBeFalsy();
   });
 
+  it("strips the machine-readable topics fence from an in-turn warm summary and renders the topic recaps instead", async () => {
+    const thread_id = seedWarmThread();
+    chatReturns([
+      "Prose recap body.",
+      "",
+      "```jarela-topics",
+      JSON.stringify([{ title: "Fence topic", start_seq: 1, end_seq: 2, start_at: "a", end_at: "b", recap: "TOPIC-RECAP-TEXT", facts: [{ subject: "S", content: "C" }] }]),
+      "```",
+    ].join("\n"));
+
+    const result = await buildHistoryWindow(thread_id, agentCfg(), providerParams, "q", modelInfo);
+
+    expect(result.warmSummaryCtx).toContain("### Fence topic");
+    expect(result.warmSummaryCtx).toContain("TOPIC-RECAP-TEXT");
+    expect(result.warmSummaryCtx).not.toContain("jarela-topics");
+    expect(result.warmSummaryCtx).not.toContain("Memorized:");
+  });
+
   it("clips an oversized latest hot message even when warm summary succeeds", async () => {
     const thread_id = seedWarmThread();
     addMessage(thread_id, "user", "latest " + "y ".repeat(20_000));

package/lib/agents/prepare/history-window.ts

@@ -21,7 +21,8 @@ import {
   truncateLargestMessagesWithinBudget,
   type ContextBudget,
 } from "@/lib/agents/context-budget";
-import { summarizeTranscript, transcriptText } from "@/lib/agents/conversation-summary";
+import { extractTopicSegments, summarizeTranscript, transcriptText } from "@/lib/agents/conversation-summary";
+import { renderTopicRecaps } from "@/lib/agents/warm-topics";
 import type { MessageRow } from "@/lib/stores/threads";
 import { listMemory } from "@/lib/stores/memory";
 import { recall } from "@/lib/embeddings";
@@ -538,7 +539,15 @@ async function buildWarmSummary(
     const summaryParams: typeof providerParams = providerParams.max_tokens
       ? providerParams
       : { ...providerParams, max_tokens: 1024 };
-    const summary = await summarizeTranscript(provider, modelId, summaryParams, transcript);
+    const raw = (await summarizeTranscript(provider, modelId, summaryParams, transcript)).trim();
+    if (!raw) return "";
+    // The summarizer appends a machine-readable topics fence; the model only
+    // needs the readable recap. Nothing is memorised on this path, so facts are dropped.
+    const { body, topics } = extractTopicSegments(raw);
+    const recapped = topics.filter((topic) => topic.recap);
+    const summary = recapped.length > 0
+      ? renderTopicRecaps(recapped.map((topic) => ({ ...topic, facts: [] })))
+      : body;
     if (!summary) return "";
     return [
       "--- Warm context summary ---",

package/lib/agents/prepare/request.ts

@@ -38,8 +38,6 @@ export interface ThreadRunRequest {
   _onCompacting?: () => void;
   /** Internal — the submission path already committed this user's transcript row. */
   _user_message_persisted?: boolean;
-  /** Thread message count captured before an eagerly persisted user turn. */
-  _message_count_before_user?: number;
   /** Conversation idle duration captured before an eagerly persisted user turn. */
   _idle_ms_before_user?: number | null;
   /**
@@ -117,6 +115,10 @@ export interface ThreadRunRequest {
    *  stall-retry recursion. */
   _stall_retries_left?: number;
 
+  /** Internal — public callers leave undefined. Automatic workflow-step
+   *  contract retries already spent this turn, keyed by `workflow_id:item_id`. */
+  _workflow_step_retries?: Readonly<Record<string, number>>;
+
   /**
    * Internal — public callers leave undefined. When set, prepareThreadRun
    * will NOT call addMessage/touchThread for this request. Retry paths set

package/lib/agents/prepare/system-prompt.test.ts

@@ -78,6 +78,8 @@ describe("buildSystemPrompt delivery channel", () => {
     // The directive must reassure the agent it has access to the channel —
     // that's the whole point of this block.
     expect(prompt).toMatch(/DO have access to WhatsApp/);
+    // WhatsApp shows markdown links as raw text.
+    expect(prompt).toContain("WhatsApp does not render markdown links: write any link as the bare URL, even where a cite_as value is given.");
   });
 
   it("falls back to the raw kind when no human label is mapped", () => {
@@ -95,6 +97,7 @@ describe("buildSystemPrompt delivery channel", () => {
 
     expect(prompt).toContain("--- Delivery channel ---");
     expect(prompt).toContain("carrier-pigeon");
+    expect(prompt).not.toContain("does not render markdown links");
   });
 
   it("omits the block entirely for direct chat (no delivery_channel set)", () => {
@@ -148,6 +151,45 @@ describe("buildSystemPrompt self-configuration", () => {
   });
 });
 
+describe("buildSystemPrompt proactive memory saving", () => {
+  const build = () => buildSystemPrompt({
+    agentCfg: agentCfg(),
+    trimmedMessage: "I prefer short answers",
+    budget,
+    recallCtx: "",
+    warmSummaryCtx: "",
+    factsCtx: "",
+    experienceMode: "full",
+    delegateRosterLines: [],
+  });
+
+  it("orders the save procedure as trigger, check, write, validate, cite", () => {
+    const prompt = build();
+    const steps = ["1. Trigger:", "2. Check:", "3. Write:", "4. Validate:", "5. Cite:"].map((s) => prompt.indexOf(s));
+    expect(steps.every((i) => i >= 0)).toBe(true);
+    expect([...steps].sort((a, b) => a - b)).toEqual(steps);
+    expect(prompt).toContain("backstop, not your save step");
+  });
+
+  it("keeps the save procedure in the cached agent-stable block", () => {
+    const prompt = build();
+    const split = prompt.indexOf(CACHE_SPLIT_SENTINEL);
+    expect(split).toBeGreaterThan(0);
+    expect(prompt.indexOf("Proactive save procedure")).toBeLessThan(split);
+  });
+
+  it("only names memory tools that are registered", async () => {
+    const memory = await import("@/lib/tools/general/memory");
+    const registered = new Set(Object.values(memory)
+      .filter((v): v is { name: string } => typeof v === "object" && v !== null && "name" in v)
+      .map((t) => t.name));
+    const block = build().split("--- Memory & recall ---")[1]?.split("\n---")[0] ?? "";
+    const named = new Set(block.match(/\bmemory_[a-z]+\b/g) ?? []);
+    expect(named.size).toBeGreaterThan(0);
+    for (const name of named) expect(registered).toContain(name);
+  });
+});
+
 const permissionMapFixture = [
   {
     name: "file_read",
@@ -267,6 +309,13 @@ describe("buildToolPermissionContext", () => {
     expect(ctx).toContain("6. Read large results by reference.");
     expect(ctx).toContain("7. Verify before reporting.");
     expect(ctx).toContain("8. Stop and ask.");
+    expect(ctx).toContain("10. Link the source.");
+    // Every source-link field a tool or bridge prompt emits must be named,
+    // or the model cannot tell which value links back to the item.
+    for (const field of ["cite_as", "web_link", "html_link", "chat_link"]) {
+      expect(ctx).toContain(field);
+    }
+    expect(ctx).toContain("never construct, guess, or edit one");
     expect(ctx).toContain("For substantial tasks with several dependent phases, likely cross-turn progress, or explicit verification, use workflow_progress");
     expect(ctx).toContain("every built-in Jarela workflow and every workflow you create or follow");
     expect(ctx).toContain("each step must state its input, expected output, and concrete validation criteria");

package/lib/agents/prepare/system-prompt.ts

@@ -272,7 +272,7 @@ export function buildSharedToolCatalogContext(): string {
   return [
     "--- Tool usage SOP ---",
     "Static cross-agent procedure. The per-turn bound list and counts appear later under \"Enabled tools\".",
-    `0. Classify the request. Informational answers may be direct; read/retrieve requests need a read tool; write/change requests need a state-changing tool; destructive requests also need the required confirmation. ${formatActionVocabularyInstruction()} For substantial tasks with several dependent phases, likely cross-turn progress, or explicit verification, use workflow_progress to create and update a concise checklist; skip simple tasks and work already covered by native tool progress. This contract applies to every built-in Jarela workflow and every workflow you create or follow: each step must state its input, expected output, and concrete validation criteria; validate each output before passing it to a later step. Prefer executable checks whenever code can verify the result, and record observed validation_evidence before marking an item done. Keep a stable workflow_id, send the complete current item list on each update, and keep secrets or private data out of checklist fields. Use needs_attention for blockers; set phase=complete only when all items are done or skipped. Never claim an output or validation result that you did not observe.`,
+    `0. Classify the request. Informational answers may be direct; read/retrieve requests need a read tool; write/change requests need a state-changing tool; destructive requests also need the required confirmation. ${formatActionVocabularyInstruction()} For substantial tasks with several dependent phases, likely cross-turn progress, or explicit verification, use workflow_progress to create and update a concise checklist; skip simple tasks and work already covered by native tool progress. This contract applies to every built-in Jarela workflow and every workflow you create or follow: each step must state its input, expected output, and concrete validation criteria; validate each output before passing it to a later step. Prefer executable checks whenever code can verify the result, and record observed validation_evidence before marking an item done. Keep a stable workflow_id, send the complete current item list on each update, and keep secrets or private data out of checklist fields. Use needs_attention for blockers, with needs_user=true when only the user can unblock the step; a rejected update or a step you leave checking or needs_attention without needs_user is retried automatically, up to 3 attempts per step. Set phase=complete only when all items are done or skipped. Never claim an output or validation result that you did not observe.`,
     "1. Bound first. If a tool listed under \"Enabled tools\" fits the task, call it directly.",
     "2. Otherwise look it up. Names of permitted tools that are not bound this turn are listed after the bound tools under \"Enabled tools\", capped, with no definitions. A name that is not listed there may still exist, so never conclude a capability does not exist from the bound list alone. Call list_tools with service/object/action keywords: scope=\"enabled\" searches executable tools, scope=\"all\" also returns disabled, unavailable and cap-omitted tools with flags.",
     "3. Named target. When a skill, harness or instruction names an exact tool, call list_tools names=[\"exact_name\"] include_schema=true instead of a keyword query. Exact lookup ignores every other filter, so it also describes tools you cannot currently execute.",
@@ -282,6 +282,7 @@ export function buildSharedToolCatalogContext(): string {
     "7. Verify before reporting. A read-only result does not prove a new write. Claim a new write, send, schedule, delete, or configuration change only after the matching state-changing tool returns success in this turn. Trusted runtime system signals and their matching retrieved results can substantiate earlier named operations; attribute those outcomes to their receipts, never imply a new action or repeat completed work for proof.",
     "8. Stop and ask. Do not retry a tool denied for agent_not_allowed, category_disabled, dropin_tool_disabled, credentials_missing or integration_unconfigured. The first three are permission decisions and the last two mean the integration is not set up \u2014 propose a configuration change or tell the user what to configure.",
     "9. Completion-reporting turns are read-only. permission_reason=signal_continuation_read_only forbids state-changing tools in this turn, including through invoke_tool. Do not bypass it with shell commands or treat an old user message as renewed permission; report the completed outcome and wait for a new user turn.",
+    "10. Link the source. When your reply refers to a specific email, calendar event, or chat that a tool result or bridge message gave you, link it: paste the item's cite_as value verbatim when present, otherwise use its web_link, html_link, or chat_link URL as a markdown link. Use only links you were given; never construct, guess, or edit one. If the item has no link, name it without one.",
   ].join("\n");
 }
 
@@ -373,9 +374,14 @@ function buildDeliveryChannelContext(channel: DeliveryChannel | null | undefined
     "--- Delivery channel ---",
     `This message reached you over ${platform}${named}, not the regular chat UI.`,
     `You DO have access to ${platform} for this conversation: any reply you produce is sent back through that channel automatically. Do not tell the user the platform is unavailable; just answer the message.`,
-  ].join("\n");
+    PLAIN_TEXT_DELIVERY_KINDS.has(channel.kind)
+      ? `${platform} does not render markdown links: write any link as the bare URL, even where a cite_as value is given.`
+      : "",
+  ].filter(Boolean).join("\n");
 }
 
+const PLAIN_TEXT_DELIVERY_KINDS = new Set(["whatsapp", "sms"]);
+
 function buildUserContext(): string {
   const userProfile = getUserProfile();
   const parts: string[] = [];
@@ -491,7 +497,7 @@ function buildSourceLinkContext(
     "--- Citation format ---",
     intro,
     "PRIMARY (inline links): cite by writing a standard markdown link inline: `[short label](https://example.com/path)` or `[file name](/abs/path.ts)` or `[earlier reply](#msg-<id>)`. Wrap the cited PHRASE itself as the link text when natural — `Jade has [ice skating at 16:00](?thread=…&agent=…)` reads better than a trailing `[1]`.",
-    "When a tool result contains a `cite_as` field (delegate_to_agent does, and so do some integrations), paste that exact value somewhere in your reply — it's a pre-built markdown link to the source. Anything you summarize from a delegate or from a web/file tool result MUST carry at least one inline link back to where it came from; a summary with zero links reads as if you made the facts up.",
+    "When a tool result contains a `cite_as` field (delegate_to_agent does, and so do the email and calendar tools), paste that exact value somewhere in your reply — it's a pre-built markdown link to the source. Anything you summarize from a delegate or from a web/file tool result MUST carry at least one inline link back to where it came from; a summary with zero links reads as if you made the facts up.",
     "For web_search / fetch_webpage results, the URL is right there in the tool output — use it: `[headline or short label](https://...)`. For file_read results, link the absolute path: `[filename.ext](/abs/path/filename.ext)`.",
     "FALLBACK (declared refs block): if a source is awkward to cite inline (e.g. you summarized 4 articles in one paragraph), you MAY end your reply with a fenced block exactly like this:",
     "```jarela-references",
@@ -603,11 +609,16 @@ function buildMemoryContext(budget: ContextBudget): string {
       : "Store explicit preferences, verified facts, durable decisions, constraints, and project context. Store task details only when they will matter across sessions.";
   return [
     "--- Memory & recall ---",
-    "You have long-term memory across sessions.",
+    "You have long-term memory across sessions, shared with every other Jarela agent. A record you save is available to other agents immediately. Background compaction also extracts facts later, but it runs late and can miss details, so it is a backstop, not your save step.",
     `- Hot conversation history is budgeted by model context size: ${formatContextBudgetSummary(budget)}.`,
     `- Active memory policy: ${policy}. ${writeGuidance}`,
-    "- Use memory_upsert proactively for structured records. Use namespace='facts', concise tags, confidence='explicit' for user-stated information, observed_at when the information was true, and expires_at for temporary facts. Keep memory_write only for legacy/free-form notes.",
     "- Use memory_search proactively when relevant saved facts or prior conversations could help. Use memory_read / memory_list to inspect known entries.",
+    "Proactive save procedure — run it whenever information fits the active memory policy, without waiting to be asked:",
+    "1. Trigger: the user states a preference, a fact about themselves or their work, a decision, a constraint, or a correction to something saved; or a tool result verifies a durable fact. Routine status, one-off chatter, secrets, credentials, and raw transcripts never qualify.",
+    "2. Check: memory_search (or memory_read for a known key) for an existing record on the same subject. Update that stable key rather than creating a duplicate or contradictory copy.",
+    "3. Write: call memory_upsert in the same turn, before your final reply, with namespace='facts', a stable descriptive key, standalone content, concise tags, confidence='explicit' for user-stated information ('verified' when tool-backed, 'inferred' only when useful and reversible), observed_at when the information became true, and expires_at for temporary facts. Keep memory_write only for legacy/free-form notes.",
+    "4. Validate: the memory_upsert result must contain ok:true and the key you sent. If it failed, correct the arguments and retry once; if it still fails, tell the user it was not saved.",
+    "5. Cite: end your reply with one short line naming each saved key, for example 'Saved to memory: facts/answer-format-preference'. Omit the line when nothing was saved.",
   ].join("\n");
 }
 

package/lib/agents/prompt-registry.test.ts

@@ -1,6 +1,6 @@
 /**
  * Assembles every prompt Jarela can send and checks it for completeness and
- * correctness. Reading the builders is not enough — the bugs found so far
+ * correctness. Reading the builders is not enough — the bugs found so far
  * (contradictory tool counts, undocumented denial reasons) were only visible
  * in the assembled text.
  *
@@ -16,151 +16,15 @@ const tmpRoot = mkdtempSync(join(tmpdir(), "jarela-prompt-verify-"));
 process.env.JARELA_DB_DIR = tmpRoot;
 
 const { buildSystemPrompt, CACHE_SHARED_SPLIT_SENTINEL, CACHE_SPLIT_SENTINEL } = await import("./prepare/system-prompt");
-const { getUsageStrategyProfile } = await import("./usage-strategy");
 const { listStaticPrompts, promptsAffectedBy, SYSTEM_PROMPT_SOURCE_PREFIXES } = await import("./prompt-registry");
-const { getAllToolCatalogAsync, applyAgentPermissionsToCatalog, markProxyOnlyTools } = await import("@/lib/tools");
+const { getAllToolCatalogAsync, applyAgentPermissionsToCatalog } = await import("@/lib/tools");
 import type { AgentConfigRow } from "@/lib/stores/agent-configs";
-import type { ContextBudget } from "@/lib/agents/context-budget";
 
 afterAll(() => {
   try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* held open */ }
 });
 
-const budget: ContextBudget = {
-  contextWindowTokens: 200000,
-  outputReserveTokens: 8000,
-  inputBudgetTokens: 120000,
-  overheadTokens: 4000,
-  tierPriority: ["hot", "warm", "facts"],
-  tierBudgets: { hot: 60000, warm: 40000, facts: 20000 },
-};
-
-function agentCfg(overrides: Partial<AgentConfigRow> = {}): AgentConfigRow {
-  return {
-    id: "verify-agent",
-    name: "Verify",
-    icon: null,
-    identity: "You are Jarela, a local assistant.",
-    instructions: "Be terse.",
-    tools: "[]",
-    model_config_name: null,
-    is_default: 1,
-    history_limit: 50,
-    history_window_hours: 8,
-    never_reply: 0,
-    adaptive_persona_enabled: 0,
-    adaptive_persona_strength: 0,
-    adaptive_empathy: 50,
-    adaptive_expressiveness: 50,
-    adaptive_verbosity: 50,
-    adaptive_mbti: "INTJ",
-    voice_enabled: 0,
-    voice_model: "",
-    voice_name: "",
-    voice_stt_model: "",
-    voice_auto_speak: 0,
-    display_filters: null,
-    harness_id: null,
-    delegate_targets: null,
-    context_tier_proportions: null,
-    anti_hallucination_mode: null,
-    ...overrides,
-  } as AgentConfigRow;
-}
-
-interface Variant {
-  id: string;
-  prompt: string;
-  /** Counts derived from the permission map, to check the prompt's own arithmetic. */
-  expected?: { bound: number; proxy: number; denied: number; unavailable: number };
-}
-
-async function buildVariants(): Promise<Variant[]> {
-  const catalog = await getAllToolCatalogAsync();
-  const pinned = ["gmail_search", "gmail_send_email"];
-  const cfg = agentCfg({ tools: JSON.stringify(pinned) });
-  const permissions = applyAgentPermissionsToCatalog(catalog, cfg);
-  const permitted = permissions.filter((t) => t.permission === "enabled").map((t) => t.name);
-
-  // Bind everything permitted: no proxy_only, the common case today.
-  const allBound = markProxyOnlyTools(permissions, permitted, permitted);
-  // Bind only the self-config tools so the rest becomes proxy_only.
-  const narrowBound = permitted.filter((n) => n === "invoke_tool" || n === "list_tools");
-  const withProxy = markProxyOnlyTools(permissions, narrowBound, permitted);
-  // Simulate a provider cap displacing tools.
-  const withCap = withProxy.map((t) =>
-    t.name === "web_search"
-      ? { ...t, permission: "disabled" as const, permission_reason: "provider_tool_limit" }
-      : t);
-
-  const base = {
-    trimmedMessage: "check my unread mail",
-    budget,
-    recallCtx: "",
-    warmSummaryCtx: "",
-    factsCtx: "",
-    delegateRosterLines: [],
-    runtimeInstanceId: "verify-instance",
-    usageStrategyInstruction: getUsageStrategyProfile("cost_saving").promptInstruction,
-    systemSignals: [{
-      seq: 1, id: "verify-signal", kind: "runtime.restart.completed" as const, schema_version: 1,
-      operation_id: "verify-operation", agent_id: cfg.id, thread_id: "verify-thread",
-      payload: '{"restarted":true,"protected_state_available":true}', created_at: 1,
-    }],
-  };
-
-  const expectedFor = (map: readonly { permission?: string; permission_reason?: string | null }[]) => {
-    const reachable = new Set(["proxy_only", "provider_tool_limit"]);
-    return {
-      bound: map.filter((t) => t.permission === "enabled").length,
-      proxy: map.filter((t) => t.permission_reason && reachable.has(t.permission_reason)).length,
-      denied: map.filter((t) =>
-        t.permission === "disabled" && !(t.permission_reason && reachable.has(t.permission_reason))).length,
-      unavailable: map.filter((t) => t.permission === "unavailable").length,
-    };
-  };
-
-  return [
-    {
-      id: "minimal-agent",
-      prompt: buildSystemPrompt({ ...base, agentCfg: agentCfg(), experienceMode: "essential" }),
-    },
-    {
-      id: "pinned-tools-all-bound",
-      prompt: buildSystemPrompt({
-        ...base,
-        agentCfg: cfg,
-        experienceMode: "full",
-        allowedTools: permitted,
-        toolPermissionMap: allBound,
-      }),
-      expected: expectedFor(allBound),
-    },
-    {
-      id: "proxy-only-and-provider-cap",
-      prompt: buildSystemPrompt({
-        ...base,
-        agentCfg: cfg,
-        experienceMode: "full",
-        allowedTools: narrowBound,
-        toolPermissionMap: withCap,
-      }),
-      expected: expectedFor(withCap),
-    },
-    {
-      id: "delivery-channel",
-      prompt: buildSystemPrompt({
-        ...base,
-        agentCfg: cfg,
-        experienceMode: "full",
-        deliveryChannel: { kind: "whatsapp" },
-        allowedTools: permitted,
-        toolPermissionMap: allBound,
-      }),
-      expected: expectedFor(allBound),
-    },
-  ];
-}
+const { agentCfg, budget, buildVariants } = await import("./prompt-variants");
 
 const variants = await buildVariants();
 const staticPrompts = listStaticPrompts();
@@ -198,7 +62,7 @@ if (process.env.JARELA_PROMPT_DUMP === "1") {
       ...variants.map((v) => `- \`system-prompt.${v.id}.txt\` (${v.prompt.length} chars)`),
       "",
       "## Static prompts",
-      ...staticPrompts.map((p) => `- \`static.${p.id}.txt\` — ${p.purpose}`),
+      ...staticPrompts.map((p) => `- \`static.${p.id}.txt\` — ${p.purpose}`),
     ].join("\n"),
     "utf8",
   );
@@ -267,6 +131,7 @@ describe("prompt registry coverage", () => {
       "lib/agents/citation-checker.ts",
       "lib/agents/hallucination-classifier.ts",
       "lib/agents/conversation-summary.ts",
+      "lib/agents/compaction-pipeline.ts",
       "lib/pricing/llm-extract.ts",
       "lib/tools/claude-delegate.ts",
       "lib/agents/prepare/system-prompt.ts",