@circuitwall/jarela 0.7.2 → 0.7.3

package/README.md

@@ -14,6 +14,7 @@
 
 <p align="center">
   <a href="#quick-start">Quick start</a> ·
+  <a href="#configuration-guide-home--work">Config guide</a> ·
   <a href="#supported-platforms">Platforms</a> ·
   <a href="#features">Features</a> ·
   <a href="#productivity-stacks-google--microsoft-at-parity">Google + Microsoft</a> ·
@@ -59,6 +60,87 @@
   </video>
 </p>
 
+## Quick start
+
+Get to a working local agent in under 10 minutes:
+
+1. Install using one channel:
+  - npm: `npm install -g @circuitwall/jarela`
+  - Docker: `docker run -d -p 127.0.0.1:4312:4312 -v jarela-data:/data andrewgewu/jarela`
+  - portable archive: download from [Releases](https://github.com/CircuitWall/jarela/releases/latest)
+2. Start Jarela:
+  - npm install: run `jarela`
+  - source checkout: run `npm run dev` (dev) or `npm run build && npm start` (prod)
+3. Open the app:
+  - dev mode: `http://localhost:3000`
+  - installed/prod mode: `http://127.0.0.1:4312`
+4. Complete first-run setup:
+  - add one provider key (Models/setup screen), then create your first agent
+  - enable tool categories that match your workflow (Mail, Calendar, Files, Web, etc.)
+5. Optionally connect integrations from Connections:
+  - Gmail/Calendar, Outlook/Calendar, GitHub, Atlassian, MCP servers, WhatsApp bridge
+
+For platform-specific install, service/autostart, and operations detail, jump to
+[Installation and runtime details](#installation-and-runtime-details).
+
+## Configuration guide (home + work)
+
+This section gives opinionated starter configs and tool chains you can adapt.
+Pattern that works well: one agent per lane (home, work), each with a narrow
+tool policy and clear trigger source.
+
+### Home setup
+
+Recommended baseline:
+
+- Agent name: `Home assistant`
+- Model: low-cost chat model for routine tasks
+- Tool categories: `Mail`, `Calendar`, `Web`, `Memory`, `Schedule`
+- Bridges: WhatsApp route for family group in `silent_mode` for monitoring, and
+  one direct route with replies enabled for active planning
+
+Popular goals and tool chains:
+
+1. Daily family agenda brief
+  - Chain: `calendar_list_events` -> `gmail_search`/`outlook_search` -> `memory_write`
+  - Result: one morning summary with events + high-priority emails
+2. Trip planning helper
+  - Chain: `web_search` -> `calendar_create_event` -> `gmail_create_draft`/`outlook_create_draft`
+  - Result: compares options, blocks time, drafts confirmation mail
+3. Household reminders
+  - Chain: `schedule_task` -> `memory_read` -> `calendar_create_event`
+  - Result: recurring reminders with memory-backed context
+
+### Work setup
+
+Recommended baseline:
+
+- Agent name: `Work operator`
+- Model: stronger reasoning model for cross-system workflows
+- Tool categories: `Work` (GitHub + Atlassian), `Mail`, `Calendar`, `Files`, `Documents`, `Schedule`
+- Connections: GitHub PAT, Atlassian token, one mail/calendar stack (or both)
+- Safety: keep destructive operations behind approvals and draft-first mail policy
+
+Popular goals and tool chains:
+
+1. Standup prep in 5 minutes
+  - Chain: `jira_search_issues` -> `github_list_pulls` -> `documents_search` -> `memory_write`
+  - Result: compact status grouped by in-progress, blocked, and review-ready
+2. Incident follow-up workflow
+  - Chain: `github_get_issue`/`jira_get_issue` -> `file_write` (draft runbook notes) -> `outlook_create_draft`/`gmail_create_draft`
+  - Result: structured summary plus stakeholder update draft without auto-send
+3. Weekly planning and meeting slots
+  - Chain: `calendar_list_events` -> `outlook_calendar_create_event`/`calendar_create_event` -> `jira_update_issue`
+  - Result: reserves focus blocks and updates ticket state in one pass
+
+### Suggested operating pattern
+
+1. Keep `Home assistant` and `Work operator` separate.
+2. Use `silent_mode` on noisy bridge/group channels so the agent reports important events without replying publicly.
+3. Prefer watcher/scheduled `script` reactions for deterministic automations; use `agent_prompt` when judgment is required.
+4. Store recurring context in memory namespaces (`home/*`, `work/*`) so prompts stay compact.
+5. Start with minimal tool categories, then expand only where needed.
+
 ## What is Jarela?
 
 Jarela is a desktop-grade chat UI for **LangGraph** agents that runs as a
@@ -180,7 +262,7 @@ create an Outlook Calendar invite in the same turn.
   required when the corporate roots are already in the system keychain
   (ADR-0020).
 
-## Quick start
+## Installation and runtime details
 
 Works on **Windows 10/11**, **macOS 12+**, and **Linux** (any modern glibc
 distro). See [Supported platforms](#supported-platforms) for the per-OS

package/api/types.ts

@@ -120,6 +120,13 @@ export interface ModelConfig {
     extra_headers?: Record<string, string>;
     temperature?: number;
     max_tokens?: number;
+    context_window_tokens?: number;
+    context_tier_proportions?: {
+      hot?: number;
+      warm?: number;
+      facts?: number;
+    };
+    context_tier_priority?: ["hot" | "warm" | "facts", "hot" | "warm" | "facts", "hot" | "warm" | "facts"];
   };
   is_default: boolean;
   created_at: string;

package/app/api/v1/agents/[id]/compact/route.ts

@@ -5,35 +5,10 @@ import { getModelConfig, getDefaultModelConfig } from "@/lib/stores/model-config
 import { getProvider } from "@/lib/providers";
 import { putMemory } from "@/lib/stores/memory";
 import type { ProviderParams } from "@/lib/providers/types";
-import type { ContentPart } from "@/lib/tools/types";
+import { summarizeTranscript, transcriptText } from "@/lib/agents/conversation-summary";
 
 type Params = { params: Promise<{ id: string }> };
 
-// Messages with attachments are stored as a JSON-stringified ContentPart[]
-// (text + image/file parts whose `data` is base64). Feeding that raw into
-// the summarizer dumps multi-MB base64 blobs into the prompt and blows the
-// context window. For compaction we only need the textual narrative; replace
-// image/file parts with short stubs so the summary still mentions them.
-function transcriptText(raw: string): string {
-  if (!raw.startsWith("[")) return raw;
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (!Array.isArray(parsed)) return raw;
-    return (parsed as ContentPart[])
-      .map((p) => {
-        if (p.type === "text") return p.text;
-        if (p.type === "image") return `[image attachment: ${p.media_type}]`;
-        if (p.type === "file") return `[file attachment: ${p.name} (${p.media_type})]`;
-        return "";
-      })
-      .filter(Boolean)
-      .join(" ")
-      .trim();
-  } catch {
-    return raw;
-  }
-}
-
 export async function POST(_req: Request, { params }: Params) {
   const { id } = await params;
   const agent = getAgentConfig(id);
@@ -76,26 +51,13 @@ export async function POST(_req: Request, { params }: Params) {
   const messageCount = rows.length;
 
   const provider = getProvider(cfg.provider);
-  const summaryMessages = [
-    {
-      role: "system" as const,
-      content: "You are a concise summarizer. Summarize the conversation below in 3-7 bullet points, capturing key facts, decisions, and context that would be useful to remember later.",
-    },
-    {
-      role: "user" as const,
-      content: `Conversation to summarize:\n\n${transcript}`,
-    },
-  ];
 
   // Summarize FIRST. Only clear messages once we have a summary safely
   // persisted to memory — otherwise a model failure would lose history with
   // no recovery path.
   let summary = "";
   try {
-    const { stream } = await provider.chat(cfg.model_id, summaryMessages, providerParams);
-    for await (const chunk of stream) {
-      summary += chunk;
-    }
+    summary = await summarizeTranscript(provider, cfg.model_id, providerParams, transcript);
   } catch (err) {
     return NextResponse.json(
       { error: `Summarization failed: ${String(err)}`, code: "summarize_failed" },

package/components/bridges/BridgeEditor.tsx

@@ -556,6 +556,14 @@ function RouteTable({ bridge_id }: { bridge_id: string }) {
         <p className="text-[11px] text-fg-faint py-2">No routes. Inbound messages will be ignored unless you add a catch-all route.</p>
       )}
 
+      {routes.length > 0 && (
+        <p className="text-[10px] text-fg-faint pb-1">
+          Route settings: pick which agent receives this chat, choose whether replies are
+          sent back to chat (Silent mode off) or kept user-side only (Silent mode on), and
+          select who should trigger outbound replies when not silent.
+        </p>
+      )}
+
       {routes.map((r) => {
         const a = agents.find((x) => x.id === r.agent_id) ?? null;
         return (

package/components/chat/MessageBubble.tsx

@@ -14,6 +14,7 @@ import { ToolList } from "@/components/chat/ToolList";
 import { useAppContext } from "@/contexts/AppContext";
 import { parseHref } from "@/lib/ui/navigate";
 import { pushToast } from "@/lib/ui/toasts";
+import { parseBridgePrompt, type BridgePromptContext } from "@/lib/bridges/message-role";
 
 interface ExtractedRef {
   title: string;
@@ -376,48 +377,14 @@ function UserAvatar({ profile }: { profile?: UserProfile | null }) {
 // metadata as a compact header card instead of dumping six bracketed `[key:value]`
 // lines at the top of every bubble. Format is fixed by dispatcher; if either
 // side changes, update both.
-interface BridgeContext {
-  bridgeId: string;
-  chatJid: string;
-  chatName: string;
-  isGroup: boolean;
-  senderJid: string;
-  senderName: string;
-  body: string;
-}
-
-function parseBridgeContext(raw: string): BridgeContext | null {
-  if (!raw.startsWith("[bridge:")) return null;
-  // Walk the contiguous `[key:value]` prefix line-by-line; stop at the first
-  // blank line (dispatcher always separates the header from the body with one).
-  const headers: Record<string, string> = {};
-  const lines = raw.split("\n");
-  let i = 0;
-  for (; i < lines.length; i++) {
-    const line = lines[i];
-    if (line === "") { i++; break; }
-    const m = /^\[([a-z_]+):([\s\S]*)\]$/.exec(line);
-    if (!m) return null;
-    headers[m[1]] = m[2];
-  }
-  if (!headers.bridge || !headers.chat_jid || !headers.chat_type) return null;
-  return {
-    bridgeId: headers.bridge,
-    chatJid: headers.chat_jid,
-    chatName: headers.chat_name || headers.chat_jid,
-    isGroup: headers.chat_type === "group",
-    senderJid: headers.sender_jid || headers.chat_jid,
-    senderName: headers.sender_name || headers.sender_jid || "Unknown",
-    body: lines.slice(i).join("\n").trimEnd(),
-  };
-}
+const parseBridgeContext = parseBridgePrompt;
 
 // Compact header card for inbound bridge messages. Shows sender + chat
 // context as a single line of metadata above the actual message text, so a
 // WhatsApp DM looks like "Alice • DM\n<text>" and a group message looks
 // like "Alice in Family Chat • Group\n<text>". Always on the user-bubble
 // (accent) side because bridge messages are persisted with role=user.
-function BridgeMessageCard({ ctx }: { ctx: BridgeContext }) {
+function BridgeMessageCard({ ctx }: { ctx: BridgePromptContext }) {
   const showChat = ctx.isGroup && ctx.chatName && ctx.chatName !== ctx.senderName;
   return (
     <div className="flex flex-col gap-1.5 min-w-0">

package/components/models/ModelEditor.tsx

@@ -9,6 +9,29 @@ import { CapBadges } from "./CapBadges";
 const FALLBACK_PROVIDERS = ["anthropic", "openai", "github-copilot", "deepseek", "gemini", "langchain"];
 
 const CATALOG_PROVIDERS = new Set<string>(["openai", "github-copilot", "anthropic", "gemini", "deepseek"]);
+const DEFAULT_CONTEXT_WINDOW = 8192;
+const DEFAULT_TIER_PROPORTIONS = { hot: 60, warm: 25, facts: 15 };
+
+type Tier = "hot" | "warm" | "facts";
+
+function sanitizeTierPriority(
+  value: ModelConfig["params"]["context_tier_priority"] | undefined,
+): [Tier, Tier, Tier] {
+  if (!Array.isArray(value) || value.length !== 3) return ["hot", "warm", "facts"];
+  const filtered = value.filter((v): v is Tier => v === "hot" || v === "warm" || v === "facts");
+  if (filtered.length !== 3 || new Set(filtered).size !== 3) return ["hot", "warm", "facts"];
+  return [filtered[0], filtered[1], filtered[2]];
+}
+
+function toNumberOrEmpty(v: string): number | undefined {
+  if (!v.trim()) return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function fmtInt(n: number): string {
+  return n.toLocaleString();
+}
 
 interface Props {
   model?: ModelConfig;
@@ -35,6 +58,11 @@ export function ModelEditor({ model, onSave, onClose }: Props) {
   );
   const [temperature, setTemperature] = useState(String(model?.params.temperature ?? ""));
   const [maxTokens, setMaxTokens] = useState(String(model?.params.max_tokens ?? ""));
+  const [contextWindowTokens, setContextWindowTokens] = useState(String(model?.params.context_window_tokens ?? ""));
+  const [hotRatio, setHotRatio] = useState(String(Math.round((model?.params.context_tier_proportions?.hot ?? (DEFAULT_TIER_PROPORTIONS.hot / 100)) * 100)));
+  const [warmRatio, setWarmRatio] = useState(String(Math.round((model?.params.context_tier_proportions?.warm ?? (DEFAULT_TIER_PROPORTIONS.warm / 100)) * 100)));
+  const [factsRatio, setFactsRatio] = useState(String(Math.round((model?.params.context_tier_proportions?.facts ?? (DEFAULT_TIER_PROPORTIONS.facts / 100)) * 100)));
+  const [tierPriority, setTierPriority] = useState<[Tier, Tier, Tier]>(sanitizeTierPriority(model?.params.context_tier_priority));
   const [isDefault, setIsDefault] = useState(model?.is_default ?? false);
   const [error, setError] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
@@ -107,11 +135,40 @@ export function ModelEditor({ model, onSave, onClose }: Props) {
     setSaving(true);
     try {
       const params: ModelConfig["params"] = {};
+      const parsedWindow = toNumberOrEmpty(contextWindowTokens);
+      const parsedHot = toNumberOrEmpty(hotRatio);
+      const parsedWarm = toNumberOrEmpty(warmRatio);
+      const parsedFacts = toNumberOrEmpty(factsRatio);
+      const tiers = [parsedHot ?? 0, parsedWarm ?? 0, parsedFacts ?? 0];
+      if (tiers.some((n) => n < 0)) {
+        setError("Tier proportions cannot be negative");
+        setSaving(false);
+        return;
+      }
+      const tierSum = tiers[0] + tiers[1] + tiers[2];
+      if (tierSum <= 0) {
+        setError("Tier proportions must add up to more than 0");
+        setSaving(false);
+        return;
+      }
+      if (new Set(tierPriority).size !== 3) {
+        setError("Tier priority must list hot, warm, and facts exactly once");
+        setSaving(false);
+        return;
+      }
+
       if (apiKey) params.api_key = apiKey;
       if (baseUrl) params.base_url = baseUrl;
       if (parsed_headers) params.extra_headers = parsed_headers;
       if (temperature) params.temperature = Number(temperature);
       if (maxTokens) params.max_tokens = Number(maxTokens);
+      if (parsedWindow && parsedWindow > 0) params.context_window_tokens = Math.floor(parsedWindow);
+      params.context_tier_proportions = {
+        hot: (parsedHot ?? 0) / tierSum,
+        warm: (parsedWarm ?? 0) / tierSum,
+        facts: (parsedFacts ?? 0) / tierSum,
+      };
+      params.context_tier_priority = tierPriority;
       await onSave(name.trim(), { provider, model_id: modelId.trim(), params, is_default: isDefault });
       onClose();
     } catch (e) {
@@ -126,6 +183,29 @@ export function ModelEditor({ model, onSave, onClose }: Props) {
 
   const showGitHub = provider === "github-copilot";
 
+  const contextWindow = Math.max(1, Math.floor(toNumberOrEmpty(contextWindowTokens) ?? DEFAULT_CONTEXT_WINDOW));
+  const outputReserve = Math.max(256, Math.min(contextWindow - 1, Math.floor(toNumberOrEmpty(maxTokens) ?? contextWindow * 0.2)));
+  const inputBudget = Math.max(0, contextWindow - outputReserve - Math.min(1200, contextWindow - outputReserve));
+  const hotP = Math.max(0, toNumberOrEmpty(hotRatio) ?? DEFAULT_TIER_PROPORTIONS.hot);
+  const warmP = Math.max(0, toNumberOrEmpty(warmRatio) ?? DEFAULT_TIER_PROPORTIONS.warm);
+  const factsP = Math.max(0, toNumberOrEmpty(factsRatio) ?? DEFAULT_TIER_PROPORTIONS.facts);
+  const totalP = hotP + warmP + factsP || 1;
+  const hotBudget = Math.floor(inputBudget * (hotP / totalP));
+  const warmBudget = Math.floor(inputBudget * (warmP / totalP));
+  const factsBudget = Math.max(0, inputBudget - hotBudget - warmBudget);
+
+  function updatePriority(index: 0 | 1 | 2, value: Tier) {
+    setTierPriority((prev) => {
+      const next: [Tier, Tier, Tier] = [...prev] as [Tier, Tier, Tier];
+      const existing = next.indexOf(value);
+      if (existing !== -1 && existing !== index) {
+        next[existing] = next[index];
+      }
+      next[index] = value;
+      return next;
+    });
+  }
+
   const filteredCatalog = catalog?.filter((m) =>
     !catalogSearch || m.id.toLowerCase().includes(catalogSearch.toLowerCase())
   ) ?? [];
@@ -243,6 +323,67 @@ export function ModelEditor({ model, onSave, onClose }: Props) {
             </label>
           </div>
 
+          <label className="block">
+            <span className="text-xs text-fg-subtle mb-1 block">Context window tokens</span>
+            <input type="number" min="1" className="w-full bg-surface-3 text-fg text-sm rounded px-2 py-1.5 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+              value={contextWindowTokens} onChange={(e) => setContextWindowTokens(e.target.value)} placeholder="8192" />
+          </label>
+
+          <div className="rounded-lg border border-border bg-surface-3 p-3 space-y-2">
+            <p className="text-xs text-fg-subtle">Context tiers and resource usage</p>
+            <div className="grid grid-cols-3 gap-2">
+              <label className="block">
+                <span className="text-[11px] text-fg-faint mb-1 block">Hot %</span>
+                <input type="number" min="0" className="w-full bg-surface text-fg text-xs rounded px-2 py-1 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+                  value={hotRatio} onChange={(e) => setHotRatio(e.target.value)} />
+              </label>
+              <label className="block">
+                <span className="text-[11px] text-fg-faint mb-1 block">Warm %</span>
+                <input type="number" min="0" className="w-full bg-surface text-fg text-xs rounded px-2 py-1 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+                  value={warmRatio} onChange={(e) => setWarmRatio(e.target.value)} />
+              </label>
+              <label className="block">
+                <span className="text-[11px] text-fg-faint mb-1 block">Facts %</span>
+                <input type="number" min="0" className="w-full bg-surface text-fg text-xs rounded px-2 py-1 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+                  value={factsRatio} onChange={(e) => setFactsRatio(e.target.value)} />
+              </label>
+            </div>
+            <div className="grid grid-cols-3 gap-2">
+              <label className="block">
+                <span className="text-[11px] text-fg-faint mb-1 block">Priority 1</span>
+                <select className="w-full bg-surface text-fg text-xs rounded px-2 py-1 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+                  value={tierPriority[0]} onChange={(e) => updatePriority(0, e.target.value as Tier)}>
+                  <option value="hot">hot</option>
+                  <option value="warm">warm</option>
+                  <option value="facts">facts</option>
+                </select>
+              </label>
+              <label className="block">
+                <span className="text-[11px] text-fg-faint mb-1 block">Priority 2</span>
+                <select className="w-full bg-surface text-fg text-xs rounded px-2 py-1 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+                  value={tierPriority[1]} onChange={(e) => updatePriority(1, e.target.value as Tier)}>
+                  <option value="hot">hot</option>
+                  <option value="warm">warm</option>
+                  <option value="facts">facts</option>
+                </select>
+              </label>
+              <label className="block">
+                <span className="text-[11px] text-fg-faint mb-1 block">Priority 3</span>
+                <select className="w-full bg-surface text-fg text-xs rounded px-2 py-1 border border-border focus:outline-none focus:ring-1 focus:ring-accent"
+                  value={tierPriority[2]} onChange={(e) => updatePriority(2, e.target.value as Tier)}>
+                  <option value="hot">hot</option>
+                  <option value="warm">warm</option>
+                  <option value="facts">facts</option>
+                </select>
+              </label>
+            </div>
+            <p className="text-[11px] text-fg-faint leading-relaxed">
+              Estimated per-turn allocation: window {fmtInt(contextWindow)} tokens, output reserve {fmtInt(outputReserve)}, input {fmtInt(inputBudget)}.
+              Hot gets about {fmtInt(hotBudget)}, warm {fmtInt(warmBudget)}, facts {fmtInt(factsBudget)} tokens.
+              Higher hot keeps recent messages; higher warm favors recap summaries; higher facts favors durable memory retrieval.
+            </p>
+          </div>
+
           <label className="block">
             <span className="text-xs text-fg-subtle mb-1 block">Extra headers (JSON, optional)</span>
             <textarea className="w-full bg-surface-3 text-fg text-sm rounded px-2 py-1.5 border border-border focus:outline-none focus:ring-1 focus:ring-accent font-mono h-20 resize-none"

package/components/scheduled-tasks/ScheduledTasksPanel.tsx

@@ -330,6 +330,11 @@ function TaskReactionEditor({
           Script
         </KindPill>
       </div>
+      <p className="text-[10px] text-fg-faint leading-snug">
+        Reaction mode controls what happens when this task fires:
+        <span className="text-fg-subtle"> Agent prompt</span> runs the task&apos;s agent prompt;
+        <span className="text-fg-subtle"> Script</span> runs a built-in reaction script with no LLM chat turn.
+      </p>
       {task.reaction_kind === "script" && (
         <ReactionScriptEditor
           initialScript={task.reaction_script}

package/components/scheduled-tasks/WatchersSection.tsx

@@ -330,6 +330,11 @@ function ReactionEditor({
           Script
         </KindPill>
       </div>
+      <p className="text-[10px] text-fg-faint leading-snug">
+        Choose how this watcher reacts on change:
+        <span className="text-fg-subtle"> Agent prompt</span> runs the assigned agent with diff context;
+        <span className="text-fg-subtle"> Script</span> runs a built-in automation without an LLM round-trip.
+      </p>
       {watcher.reaction_kind === "script"
         ? (
           <ReactionScriptEditor

package/lib/agents/context-budget.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import {
+  computeContextBudget,
+  normalizeTierPriority,
+  normalizeTierProportions,
+  takeRecentMessagesWithinBudget,
+  estimateTokens,
+} from "./context-budget";
+import type { MessageRow } from "@/lib/stores/threads";
+
+function msg(content: string): MessageRow {
+  return {
+    msg_id: "m",
+    thread_id: "t",
+    role: "user",
+    content,
+    created_at: "2026-01-01T00:00:00.000Z",
+    tool_events: null,
+    category: null,
+  };
+}
+
+describe("estimateTokens", () => {
+  it("uses a 4-char token heuristic with minimum 1 for non-empty text", () => {
+    expect(estimateTokens("a")).toBe(1);
+    expect(estimateTokens("abcd")).toBe(1);
+    expect(estimateTokens("abcde")).toBe(2);
+  });
+
+  it("returns 0 for empty/whitespace input", () => {
+    expect(estimateTokens("")).toBe(0);
+    expect(estimateTokens("   ")).toBe(0);
+  });
+});
+
+describe("normalizeTierPriority", () => {
+  it("accepts valid permutations", () => {
+    expect(normalizeTierPriority(["facts", "warm", "hot"]))
+      .toEqual(["facts", "warm", "hot"]);
+  });
+
+  it("falls back to default for invalid values", () => {
+    expect(normalizeTierPriority(["hot", "hot", "warm"]))
+      .toEqual(["hot", "warm", "facts"]);
+    expect(normalizeTierPriority(["hot", "warm"]))
+      .toEqual(["hot", "warm", "facts"]);
+    expect(normalizeTierPriority("bad"))
+      .toEqual(["hot", "warm", "facts"]);
+  });
+});
+
+describe("normalizeTierProportions", () => {
+  it("normalizes arbitrary positive numbers to sum to 1", () => {
+    const p = normalizeTierProportions({ hot: 2, warm: 1, facts: 1 });
+    expect(p.hot).toBeCloseTo(0.5, 6);
+    expect(p.warm).toBeCloseTo(0.25, 6);
+    expect(p.facts).toBeCloseTo(0.25, 6);
+  });
+
+  it("falls back to defaults when values are non-positive", () => {
+    const p = normalizeTierProportions({ hot: 0, warm: -1, facts: 0 });
+    expect(p.hot).toBeCloseTo(0.6, 6);
+    expect(p.warm).toBeCloseTo(0.25, 6);
+    expect(p.facts).toBeCloseTo(0.15, 6);
+  });
+});
+
+describe("computeContextBudget", () => {
+  it("applies defaults when model params are absent", () => {
+    const b = computeContextBudget({});
+    expect(b.contextWindowTokens).toBe(8192);
+    expect(b.outputReserveTokens).toBe(1638);
+    expect(b.overheadTokens).toBe(1200);
+    expect(b.inputBudgetTokens).toBe(5354);
+    expect(b.tierPriority).toEqual(["hot", "warm", "facts"]);
+    expect(b.tierBudgets.hot + b.tierBudgets.warm + b.tierBudgets.facts).toBe(b.inputBudgetTokens);
+  });
+
+  it("respects explicit max_tokens and context_window_tokens", () => {
+    const b = computeContextBudget({
+      context_window_tokens: 10000,
+      max_tokens: 500,
+      context_tier_proportions: { hot: 0.5, warm: 0.3, facts: 0.2 },
+      context_tier_priority: ["warm", "facts", "hot"],
+    });
+    expect(b.contextWindowTokens).toBe(10000);
+    expect(b.outputReserveTokens).toBe(500);
+    expect(b.tierPriority).toEqual(["warm", "facts", "hot"]);
+    expect(b.tierBudgets.hot + b.tierBudgets.warm + b.tierBudgets.facts).toBe(b.inputBudgetTokens);
+  });
+
+  it("enforces minimum output reserve", () => {
+    const b = computeContextBudget({ context_window_tokens: 600, max_tokens: 1 });
+    expect(b.outputReserveTokens).toBe(256);
+  });
+});
+
+describe("takeRecentMessagesWithinBudget", () => {
+  it("returns most-recent-first slice bounded by token budget", () => {
+    const rows = [
+      msg("first message has some words"),
+      msg("second message has some words"),
+      msg("third message has some words"),
+    ];
+    // One message is about 7 tokens with current heuristic.
+    const out = takeRecentMessagesWithinBudget(rows, 10);
+    expect(out).toHaveLength(1);
+    expect(out[0].content).toContain("third");
+  });
+
+  it("always includes latest message when budget is tiny", () => {
+    const rows = [msg("older"), msg("latest message with many chars")];
+    const out = takeRecentMessagesWithinBudget(rows, 1);
+    expect(out).toHaveLength(1);
+    expect(out[0].content).toContain("latest");
+  });
+
+  it("handles attachment-encoded content via transcriptText path", () => {
+    const withAttachment = JSON.stringify([
+      { type: "text", text: "hello" },
+      { type: "file", name: "doc.txt", media_type: "text/plain", data: "x" },
+    ]);
+    const rows = [msg(withAttachment), msg("latest")];
+    const out = takeRecentMessagesWithinBudget(rows, 8);
+    expect(out.at(-1)?.content).toBe("latest");
+    expect(out.length).toBeGreaterThan(0);
+  });
+});