@crossworks/content-core 0.235.1 → 0.237.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/content-core",
-  "version": "0.235.1",
+  "version": "0.237.1",
   "description": "Browser-safe content logic — markdown, blocks, pages, tables, formulas — shared by the server and any client. Zero server deps by design: nothing here may reach @mantle/db, node-only APIs, or the network (the jackdaw-repo-split P0 boundary).",
   "exports": {
     "./app-nav": "./src/app-nav.ts",
@@ -14,6 +14,7 @@
     "./formula-seed": "./src/formula-seed.ts",
     "./formula-signature": "./src/formula-signature.ts",
     "./formula-spec": "./src/formula-spec.ts",
+    "./heading-fold": "./src/heading-fold.ts",
     "./journal-options": "./src/journal-options.ts",
     "./markdown": "./src/markdown-to-doc.ts",
     "./markdown-refs": "./src/markdown-refs.ts",
@@ -32,7 +33,7 @@
     "./tree": "./src/tree.ts"
   },
   "dependencies": {
-    "@mantle/client-types": "npm:@crossworks/client-types@0.235.1",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.237.1",
     "marked": "^18.0.11",
     "mathjs": "15.2.0"
   },

package/src/agent-thinking.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import {
+  AGENT_THINKING_EFFORTS,
+  NO_THINKING,
+  applyAgentThinking,
+  parseAgentThinkingEffort,
+  profileThinking,
+  resolveAgentThinking,
+  thinkingBudgetForEffort,
+} from './profile-projections';
+
+const ON_MEDIUM = { streamThoughts: true, thinkingBudget: 4096 };
+const ON_OFF = { streamThoughts: true, thinkingBudget: 0 };
+const SWITCH_OFF = { streamThoughts: false, thinkingBudget: 8000 };
+
+describe('resolveAgentThinking: the precedence table', () => {
+  // [agent effort, profile, expected]
+  const rows: Array<[string | null, typeof ON_MEDIUM | null, number, string | undefined]> = [
+    // Inherit = today's behaviour exactly.
+    [null, ON_MEDIUM, 4096, 'medium'],
+    [null, ON_OFF, 0, undefined],
+    [null, SWITCH_OFF, 0, undefined],
+    [null, null, 0, undefined],
+    // Own 'off' beats any profile.
+    ['off', ON_MEDIUM, 0, undefined],
+    ['off', SWITCH_OFF, 0, undefined],
+    // Own tier beats the profile, the profile's Off, and the display switch.
+    ['low', ON_MEDIUM, 1024, 'low'],
+    ['high', ON_OFF, 8000, 'high'],
+    ['medium', SWITCH_OFF, 4096, 'medium'],
+    ['xhigh', null, 16000, 'xhigh'],
+    ['max', ON_MEDIUM, 24000, 'max'],
+  ];
+  for (const [own, prefs, budget, effort] of rows) {
+    it(`agent ${own ?? 'inherit'} + profile ${JSON.stringify(prefs)} → ${budget}/${effort}`, () => {
+      expect(resolveAgentThinking({ thinkingEffort: own }, prefs)).toEqual({ budget, effort });
+    });
+  }
+
+  it('a missing agent row is inherit', () => {
+    expect(resolveAgentThinking(null, ON_MEDIUM)).toEqual(profileThinking(ON_MEDIUM));
+    expect(resolveAgentThinking(undefined, ON_MEDIUM)).toEqual({ budget: 4096, effort: 'medium' });
+  });
+
+  it('a bad stored value is inherit, never reasoning on', () => {
+    for (const bad of ['', 'inherit', 'HIGH', 'none', 'extreme']) {
+      expect(resolveAgentThinking({ thinkingEffort: bad }, ON_OFF)).toEqual(NO_THINKING);
+    }
+  });
+});
+
+describe('applyAgentThinking', () => {
+  it('passes the inherited value through untouched on inherit', () => {
+    const inherited = { budget: 2048, effort: undefined };
+    expect(applyAgentThinking({ thinkingEffort: null }, inherited)).toBe(inherited);
+  });
+});
+
+describe('agent effort vocabulary', () => {
+  it("is 'off' plus every provider tier, in order", () => {
+    expect(AGENT_THINKING_EFFORTS).toEqual(['off', 'low', 'medium', 'high', 'xhigh', 'max']);
+  });
+
+  it('parses only known values', () => {
+    expect(parseAgentThinkingEffort('max')).toBe('max');
+    expect(parseAgentThinkingEffort('off')).toBe('off');
+    expect(parseAgentThinkingEffort(null)).toBeNull();
+    expect(parseAgentThinkingEffort(3)).toBeNull();
+  });
+
+  it('backs the profile tiers with their own ids, the upper rungs with more headroom', () => {
+    expect(thinkingBudgetForEffort('low')).toBe(1024);
+    expect(thinkingBudgetForEffort('medium')).toBe(4096);
+    expect(thinkingBudgetForEffort('high')).toBe(8000);
+    expect(thinkingBudgetForEffort('xhigh')).toBe(16000);
+    expect(thinkingBudgetForEffort('max')).toBe(24000);
+  });
+});

package/src/block-list.ts

@@ -144,7 +144,11 @@ function blockMeta(kind: string, node: AnyNode): Record<string, unknown> | null
   const attrs = node.attrs ?? {};
   switch (kind) {
     case 'heading':
-      return typeof attrs.level === 'number' ? { level: attrs.level } : null;
+      if (typeof attrs.level !== 'number') return null;
+      // A foldable heading says so (and how it starts), so an agent can see it.
+      return attrs.fold === 'open' || attrs.fold === 'closed'
+        ? { level: attrs.level, fold: attrs.fold }
+        : { level: attrs.level };
     case 'codeBlock':
       return typeof attrs.language === 'string' && attrs.language
         ? { language: attrs.language }

package/src/doc-to-markdown.ts

@@ -27,6 +27,7 @@
  */
 
 import { FOLDER_HERE } from './markdown-refs';
+import { foldMarker, normalizeFold } from './heading-fold';
 
 type PMMark = { type?: string; attrs?: Record<string, unknown> };
 type PMNode = {
@@ -220,7 +221,14 @@ function blockToMd(node: PMNode): string {
       return escapeLeading(inlineNodes(node.content));
     case 'heading': {
       const level = Math.min(Math.max(Number(node.attrs?.level) || 1, 1), 6);
-      return `${'#'.repeat(level)} ${inlineNodes(node.content)}`;
+      // A heading whose own words END in a fold marker escapes its `{`, so it
+      // re-parses as that text and not as a foldable heading.
+      const text = inlineNodes(node.content).replace(
+        /\{(fold(?:=(?:open|closed))?\}\s*)$/,
+        '\\{$1',
+      );
+      const fold = normalizeFold(node.attrs?.fold);
+      return `${'#'.repeat(level)} ${text}${fold ? ` ${foldMarker(fold)}` : ''}`;
     }
     case 'horizontalRule':
       return '---';

package/src/heading-fold.test.ts

@@ -0,0 +1,211 @@
+/**
+ * Foldable headings: the markdown marker round-trips losslessly, old docs are
+ * untouched, and the shared section rule + reader-choice store behave.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { markdownToDoc } from './markdown-to-doc';
+import { docToMarkdown } from './doc-to-markdown';
+import { listBlocks } from './block-list';
+import {
+  FOLD_CHOICES_MAX,
+  FOLD_STORAGE_KEY,
+  foldSections,
+  isFolded,
+  normalizeFold,
+  readFoldChoices,
+  writeFoldChoice,
+} from './heading-fold';
+
+type N = { type?: string; attrs?: Record<string, unknown>; content?: N[]; text?: string };
+
+const blocks = (md: string) => (markdownToDoc(md) as { content: N[] }).content;
+const heading = (md: string) => blocks(md).find((b) => b.type === 'heading')!;
+const text = (n: N) => (n.content ?? []).map((c) => c.text ?? '').join('');
+
+describe('foldable heading markdown', () => {
+  it('`{fold}` makes a foldable heading that starts open', () => {
+    const h = heading('## Plans {fold}');
+    expect(h.attrs).toMatchObject({ level: 2, fold: 'open' });
+    expect(text(h)).toBe('Plans');
+  });
+
+  it('`{fold=closed}` starts folded; `{fold=open}` is the same as `{fold}`', () => {
+    expect(heading('# A {fold=closed}').attrs?.fold).toBe('closed');
+    expect(heading('# A {fold=open}').attrs?.fold).toBe('open');
+  });
+
+  it('keeps inline marks before the marker', () => {
+    const h = heading('### **Bold** and `code` {fold}');
+    expect(h.attrs?.fold).toBe('open');
+    expect(docToMarkdown({ type: 'doc', content: [h] })).toBe('### **Bold** and `code` {fold}');
+  });
+
+  it('a heading without a marker has NO fold attr (old docs unchanged)', () => {
+    const h = heading('## Plans');
+    expect(h.attrs).not.toHaveProperty('fold');
+    expect(Object.keys(h.attrs ?? {}).sort()).toEqual(['id', 'level']);
+  });
+
+  it('only the trailing marker counts, and only on headings', () => {
+    expect(heading('## a {fold} b').attrs).not.toHaveProperty('fold');
+    expect(text(heading('## a {fold} b'))).toBe('a {fold} b');
+    const p = blocks('text {fold}')[0]!;
+    expect(p.type).toBe('paragraph');
+    expect(text(p)).toBe('text {fold}');
+    expect(heading('## a {folded}').attrs).not.toHaveProperty('fold');
+  });
+
+  it('an escaped marker is plain heading text', () => {
+    const h = heading('## Use \\{fold} here \\{fold}');
+    expect(h.attrs).not.toHaveProperty('fold');
+    expect(text(h)).toBe('Use {fold} here {fold}');
+  });
+
+  it('works inside containers (callout, list item)', () => {
+    const callout = blocks(':::info\n## Inner {fold=closed}\nbody\n:::')[0]!;
+    expect(callout.content?.[0]?.attrs?.fold).toBe('closed');
+  });
+});
+
+describe('foldable heading round-trip (markdown -> doc -> markdown)', () => {
+  const cases = [
+    '## Plans {fold}',
+    '# Top {fold=closed}\n\nBody text.\n\n## Child {fold}\n\n- a\n- b',
+    '### **Bold** and *em* {fold}',
+    '## Plain heading\n\nNo fold here.',
+    '## Literal \\{fold}',
+    ':::info\n## In a callout {fold}\n\nx\n:::',
+  ];
+  for (const md of cases) {
+    it(`is identical: ${JSON.stringify(md)}`, () => {
+      expect(docToMarkdown(markdownToDoc(md))).toBe(md);
+    });
+  }
+
+  it('a heading whose WORDS end in a marker survives an editor save', () => {
+    // As the editor stores it: plain text, no fold attr.
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'x {fold}' }] },
+      ],
+    };
+    const md = docToMarkdown(doc);
+    expect(md).toBe('## x \\{fold}');
+    const back = heading(md);
+    expect(back.attrs).not.toHaveProperty('fold');
+    expect(text(back)).toBe('x {fold}');
+  });
+
+  it('`{fold=closed}` as heading WORDS stays words (its `=` is escaped)', () => {
+    const md = docToMarkdown(markdownToDoc('## Literal \\{fold=closed}'));
+    expect(md).toBe('## Literal {fold\\=closed}');
+    expect(heading(md).attrs).not.toHaveProperty('fold');
+    expect(text(heading(md))).toBe('Literal {fold=closed}');
+  });
+
+  it('a literal backslash before the words stays text too', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'a\\{fold}' }] },
+      ],
+    };
+    const back = heading(docToMarkdown(doc));
+    expect(back.attrs).not.toHaveProperty('fold');
+    expect(text(back)).toBe('a\\{fold}');
+  });
+
+  it('an editor-saved non-foldable heading (fold: null) writes plain markdown', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'heading',
+          attrs: { level: 2, fold: null },
+          content: [{ type: 'text', text: 'T' }],
+        },
+      ],
+    };
+    expect(docToMarkdown(doc)).toBe('## T');
+  });
+});
+
+describe('page_blocks_list meta', () => {
+  it('names the fold of a foldable heading only', () => {
+    const list = listBlocks(markdownToDoc('## A {fold=closed}\n\n## B') as Record<string, unknown>);
+    expect(list[0]!.meta).toEqual({ level: 2, fold: 'closed' });
+    expect(list[1]!.meta).toEqual({ level: 2 });
+  });
+});
+
+describe('foldSections', () => {
+  // h1 p h2 p h3 p h2 p h1 p
+  const levels = [1, null, 2, null, 3, null, 2, null, 1, null];
+  const lv = (i: number) => levels[i] ?? null;
+
+  it('a section runs to the next heading of the same or a higher level', () => {
+    const all = foldSections(levels.length, lv, () => true);
+    expect(all.get(0)).toBe(8); // h1 → next h1
+    expect(all.get(2)).toBe(6); // h2 → next h2 (skips the h3)
+    expect(all.get(4)).toBe(6); // h3 → the h2
+    expect(all.get(6)).toBe(8); // h2 → the h1
+    expect(all.get(8)).toBe(10); // last h1 → the end
+  });
+
+  it('only foldable headings get a section', () => {
+    const one = foldSections(levels.length, lv, (i) => i === 2);
+    expect([...one.keys()]).toEqual([2]);
+  });
+});
+
+describe('fold choices', () => {
+  const store = new Map<string, string>();
+  beforeEach(() => {
+    store.clear();
+    (globalThis as { localStorage?: unknown }).localStorage = {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => void store.set(k, v),
+      removeItem: (k: string) => void store.delete(k),
+    };
+  });
+  afterEach(() => {
+    delete (globalThis as { localStorage?: unknown }).localStorage;
+  });
+
+  it('normalizeFold accepts only open/closed', () => {
+    expect(normalizeFold('open')).toBe('open');
+    expect(normalizeFold('closed')).toBe('closed');
+    expect(normalizeFold(null)).toBeNull();
+    expect(normalizeFold('x')).toBeNull();
+  });
+
+  it('the reader choice wins over the doc default; no choice = the default', () => {
+    expect(isFolded('h1', 'closed', {})).toBe(true);
+    expect(isFolded('h1', 'open', {})).toBe(false);
+    expect(isFolded('h1', 'closed', { h1: false })).toBe(false);
+    expect(isFolded('h1', 'open', { h1: true })).toBe(true);
+    expect(isFolded('h1', null, { h1: true })).toBe(false); // not foldable = never folded
+  });
+
+  it('writes, reads back, and keeps only the newest choices', () => {
+    writeFoldChoice('a', true);
+    writeFoldChoice('b', false);
+    expect(readFoldChoices()).toEqual({ a: true, b: false });
+    for (let i = 0; i < FOLD_CHOICES_MAX + 5; i++) writeFoldChoice(`k${i}`, true);
+    const keys = Object.keys(readFoldChoices());
+    expect(keys).toHaveLength(FOLD_CHOICES_MAX);
+    expect(keys).not.toContain('a');
+    expect(keys[keys.length - 1]).toBe(`k${FOLD_CHOICES_MAX + 4}`);
+  });
+
+  it('survives junk in storage and no storage at all', () => {
+    store.set(FOLD_STORAGE_KEY, 'not json');
+    expect(readFoldChoices()).toEqual({});
+    store.set(FOLD_STORAGE_KEY, '{"a":true,"b":"x"}');
+    expect(readFoldChoices()).toEqual({ a: true });
+    delete (globalThis as { localStorage?: unknown }).localStorage;
+    expect(readFoldChoices()).toEqual({});
+    expect(() => writeFoldChoice('a', true)).not.toThrow();
+  });
+});

package/src/heading-fold.ts

@@ -0,0 +1,152 @@
+/**
+ * Foldable headings: the shared rules every surface folds by.
+ *
+ * A heading can be FOLDABLE (Notion's toggle heading). The document stores
+ * only that fact, plus an optional default for a reader who never chose:
+ *
+ *   heading attrs.fold   null | 'open' | 'closed'
+ *   markdown             `## Title {fold}`   foldable, starts open
+ *                        `## Title {fold=closed}`   foldable, starts folded
+ *
+ * Whether a heading is folded RIGHT NOW is the reader's own choice, not part
+ * of the document: it is a reading preference, like a scroll position, and
+ * one reader folding a section must not hide it from everyone else (nor make
+ * a draft "changed"). The choice lives in the reader's localStorage, keyed by
+ * the heading's block id, so it follows the heading across the editor, the
+ * read view, the member and client views and the share reader of one browser.
+ * Block ids are UUIDs, so one map holds every page; it keeps the most recent
+ * FOLD_CHOICES_MAX choices.
+ *
+ * What a fold hides: the blocks after the heading, in the same parent, up to
+ * the next heading of the same or a higher level (level <= the heading's), or
+ * the end of the parent. A heading inside a callout or a column folds within
+ * that container. Print always shows everything (CSS, see share-ui app.css).
+ *
+ * Pure and browser-safe. The storage helpers no-op where localStorage is
+ * missing or refuses (SSR, private mode).
+ */
+
+export type HeadingFold = 'open' | 'closed';
+
+/** The stored attr, normalised: anything else is "not foldable". */
+export function normalizeFold(v: unknown): HeadingFold | null {
+  return v === 'open' || v === 'closed' ? v : null;
+}
+
+/**
+ * The trailing markdown marker, matched against a heading's LAST inline text
+ * run (so an escaped `\{fold}` is plain text: `marked` splits the escape into
+ * its own token). Group 1 is the optional `=open` / `=closed` value.
+ */
+export const FOLD_MARKER_RE = /\s*\{fold(?:=(open|closed))?\}\s*$/;
+
+/**
+ * A heading's trailing marker, read off its LAST inline `marked` token and
+ * removed from it. An escaped `\{fold}` never matches: `marked` lexes the
+ * escape as its own token, so the last text run is `fold}`. Shared by
+ * markdownToDoc and the client's chat renderer, so both read it the same way.
+ */
+export function splitFoldMarker<T extends { type: string; text?: string }>(
+  tokens: T[] | undefined,
+): { tokens: T[] | undefined; fold: HeadingFold | null } {
+  const last = tokens?.[tokens.length - 1];
+  if (!tokens || !last || last.type !== 'text') return { tokens, fold: null };
+  const m = FOLD_MARKER_RE.exec(last.text ?? '');
+  if (!m) return { tokens, fold: null };
+  const rest = (last.text ?? '').slice(0, m.index).replace(/\s+$/, '');
+  const head = tokens.slice(0, -1);
+  return {
+    tokens: rest ? [...head, { ...last, text: rest }] : head,
+    fold: m[1] === 'closed' ? 'closed' : 'open',
+  };
+}
+
+/** The marker docToMarkdown writes for a stored fold value. */
+export function foldMarker(fold: HeadingFold): string {
+  return fold === 'closed' ? '{fold=closed}' : '{fold}';
+}
+
+/**
+ * For each foldable heading among a run of SIBLING blocks, the index just past
+ * its section (exclusive). `level(i)` is the heading level of sibling i, or
+ * null when it is not a heading; `foldable(i)` says whether it folds.
+ */
+export function foldSections(
+  count: number,
+  level: (i: number) => number | null,
+  foldable: (i: number) => boolean,
+): Map<number, number> {
+  const out = new Map<number, number>();
+  for (let i = 0; i < count; i++) {
+    const lv = level(i);
+    if (lv == null || !foldable(i)) continue;
+    let end = i + 1;
+    while (end < count) {
+      const next = level(end);
+      if (next != null && next <= lv) break;
+      end++;
+    }
+    out.set(i, end);
+  }
+  return out;
+}
+
+/* ─────────────────────────── the reader's choices ─────────────────────────── */
+
+export const FOLD_STORAGE_KEY = 'pages.headingFolds';
+export const FOLD_CHOICES_MAX = 1000;
+
+/** heading id → true (folded) / false (open). Absent = the document default. */
+export type FoldChoices = Record<string, boolean>;
+
+function storage(): Storage | null {
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function readFoldChoices(): FoldChoices {
+  const s = storage();
+  if (!s) return {};
+  try {
+    const raw = JSON.parse(s.getItem(FOLD_STORAGE_KEY) ?? '{}') as unknown;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+    const out: FoldChoices = {};
+    for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof v === 'boolean') out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** Remember one choice. The newest choices are kept, the oldest dropped. */
+export function writeFoldChoice(id: string, folded: boolean): void {
+  const s = storage();
+  if (!s || !id) return;
+  const choices = readFoldChoices();
+  delete choices[id]; // re-insert at the end: insertion order = recency
+  choices[id] = folded;
+  const keys = Object.keys(choices);
+  for (const k of keys.slice(0, Math.max(0, keys.length - FOLD_CHOICES_MAX))) delete choices[k];
+  try {
+    s.setItem(FOLD_STORAGE_KEY, JSON.stringify(choices));
+  } catch {
+    // Quota or private mode: the fold still works for this view.
+  }
+}
+
+/** Is this heading folded for this reader? Their choice, else the doc default. */
+export function isFolded(
+  id: string | null | undefined,
+  fold: unknown,
+  choices: FoldChoices,
+): boolean {
+  const f = normalizeFold(fold);
+  if (!f) return false;
+  if (id && typeof choices[id] === 'boolean') return choices[id]!;
+  return f === 'closed';
+}

package/src/markdown-to-doc.ts

@@ -19,6 +19,7 @@
  *   Columns:  :::columns … +++ … :::   (2+ parts split by a lone +++)
  *   Highlight: ==text==
  *   Colour:    [text]{color=chart-2}  /  [text]{highlight=chart-3}  (chart-1..5)
+ *   Foldable heading: ## Title {fold}  /  ## Title {fold=closed}  (heading-fold.ts)
  *
  * Pure (only `marked`) and DB-free, so it's safe to call from the tool
  * runtime. Defensive: anything it can't map degrades to a paragraph rather
@@ -37,6 +38,7 @@ import {
   FOLDER_HREF,
   FOLDER_HERE,
 } from './markdown-refs';
+import { splitFoldMarker } from './heading-fold';
 
 type PMMark = { type: string; attrs?: Record<string, unknown> };
 type PMNode = {
@@ -375,13 +377,18 @@ function blocks(tokens: Tok[] | undefined): PMNode[] {
       case 'space':
       case 'def':
         break;
-      case 'heading':
+      case 'heading': {
+        const { tokens, fold } = splitFoldMarker(t.tokens);
+        const level = Math.min(Math.max(t.depth ?? 1, 1), 3);
         out.push({
           type: 'heading',
-          attrs: { level: Math.min(Math.max(t.depth ?? 1, 1), 3) },
-          content: inline(t.tokens),
+          // `fold` only on a foldable heading, so every other heading's JSON
+          // is exactly what it was before foldable headings existed.
+          attrs: fold ? { level, fold } : { level },
+          content: inline(tokens),
         });
         break;
+      }
       case 'paragraph': {
         const ref = blockRefNode(t.tokens);
         if (ref) {

package/src/profile-projections.ts

@@ -24,7 +24,12 @@ import type {
   ThoughtTrailMode,
 } from '@mantle/client-types';
 
-import { thinkingEffortForBudget, type ThinkingEffort } from './thinking-tiers';
+import {
+  parseAgentThinkingEffort,
+  thinkingBudgetForEffort,
+  thinkingEffortForBudget,
+  type ThinkingEffort,
+} from './thinking-tiers';
 import {
   APP_OPENS_MAX,
   APP_PINS_MAX,
@@ -347,9 +352,14 @@ export function resolveThinkingBudget(
 // can use the values without pulling @mantle/db into the browser bundle.
 // Re-exported here so server-side callers keep importing from one place.
 export {
+  AGENT_THINKING_EFFORTS,
+  AGENT_THINKING_EFFORT_LABELS,
   THINKING_EFFORTS,
   THINKING_TIERS,
+  parseAgentThinkingEffort,
+  thinkingBudgetForEffort,
   thinkingEffortForBudget,
+  type AgentThinkingEffort,
   type ThinkingEffort,
 } from './thinking-tiers';
 
@@ -363,6 +373,56 @@ export function resolveThinkingEffort(
   return thinkingEffortForBudget(resolveThinkingBudget(prefs));
 }
 
+/** The thinking a turn asks for: `budget` > 0 turns reasoning on (and sizes
+ *  the max_tokens headroom), `effort` is the tier the providers honour.
+ *  `{ budget: 0, effort: undefined }` = no reasoning. */
+export type ResolvedThinking = { budget: number; effort: ThinkingEffort | undefined };
+
+export const NO_THINKING: ResolvedThinking = Object.freeze({ budget: 0, effort: undefined });
+
+/** Apply an agent's own effort over what it would otherwise inherit. The one
+ *  precedence rule, shared by every turn path:
+ *
+ *    agent effort set   → that effort ('off' = none), whatever was inherited
+ *    agent effort NULL  → `inherited`, unchanged (the behaviour before 0228)
+ *
+ *  An agent's own effort is NOT gated by the person's live-thinking switch:
+ *  that switch is about what a person likes to watch, while the effort is a
+ *  property of the agent (an owner who sets High on a research agent wants it
+ *  to reason, whether or not they watch the trail). The switch still gates
+ *  the INHERITED profile budget, so an agent on inherit behaves exactly as
+ *  before, and a profile at Off still sends no reasoning for it. */
+export function applyAgentThinking(
+  agent: { thinkingEffort?: string | null } | null | undefined,
+  inherited: ResolvedThinking,
+): ResolvedThinking {
+  const own = parseAgentThinkingEffort(agent?.thinkingEffort);
+  if (own === null) return inherited;
+  if (own === 'off') return NO_THINKING;
+  return { budget: thinkingBudgetForEffort(own), effort: own };
+}
+
+/** Resolve a top-level turn's thinking: the agent's own effort when set, else
+ *  the person's profile (gated by the live-thinking switch AND a positive
+ *  budget, see {@link resolveThinkingEffort}). `prefs: null` means the profile
+ *  does not apply on this path (a team or client turn, where the profile is the
+ *  owner's and not the caller's): inherit is then off. */
+export function resolveAgentThinking(
+  agent: { thinkingEffort?: string | null } | null | undefined,
+  prefs: Pick<ProfilePreferences, 'streamThoughts' | 'thinkingBudget'> | null,
+): ResolvedThinking {
+  return applyAgentThinking(agent, profileThinking(prefs));
+}
+
+/** The person's profile thinking alone (what an agent on inherit gets). */
+export function profileThinking(
+  prefs: Pick<ProfilePreferences, 'streamThoughts' | 'thinkingBudget'> | null,
+): ResolvedThinking {
+  if (!prefs) return NO_THINKING;
+  const budget = resolveThinkingBudget(prefs);
+  return budget > 0 ? { budget, effort: resolveThinkingEffort(prefs) } : NO_THINKING;
+}
+
 /** Whitelist projection for {@link OnboardingModelChoices} — same contract as
  *  projectThinkingBudget: read and write MUST share this, or the field gets
  *  silently dropped on read. */
@@ -467,9 +527,24 @@ export function projectAppOpens(raw: unknown): Record<string, AppOpenStat> | und
   return Object.fromEntries(rows.slice(0, APP_OPENS_MAX));
 }
 
+/** The house style a NEW brain starts with (Settings, Profile). Seeded only when
+ *  a profile row is first created, so an owner who edits or clears it keeps
+ *  their choice. The dash characters are escapes so the source holds none. */
+export const DEFAULT_HOUSE_STYLE =
+  'Never use em dashes (\u2014). Rewrite instead: a comma, a colon, parentheses, or two ' +
+  'sentences all carry the same break, so use whichever reads best. The character should ' +
+  'not appear in your output at all.\n\n' +
+  'The same goes for an en dash (\u2013) used as a sentence break. En dashes inside numeric ' +
+  'ranges (2020\u20132024, pages 10\u201314) are correct and stay, and hyphens in compound ' +
+  'words (self-hosted, read-only) are unaffected.';
+
 export const DEFAULT_PREFERENCES: ProfilePreferences = {
   timezone: 'UTC',
   locale: 'en-GB',
+  houseStyle: DEFAULT_HOUSE_STYLE,
+  // Live thinking on (streamThoughts defaults on) at Medium: the 4096 tier of
+  // THINKING_TIERS. Unset would mean no thinking at all.
+  thinkingBudget: 4096,
 };
 
 /** IANA tz validation via Intl.DateTimeFormat — the runtime throws

package/src/thinking-tiers.ts

@@ -54,3 +54,43 @@ export function thinkingEffortForBudget(budget: number | undefined): ThinkingEff
   );
   return nearest.effort ?? undefined;
 }
+
+/** The values an AGENT's own thinking effort may hold (`agents.thinking_effort`,
+ *  migration 0228): 'off' plus every tier. NULL (not in this list) means
+ *  "inherit the person's profile setting". Wider than THINKING_TIERS on
+ *  purpose: the profile dropdown stops at High, but an agent may ask for the
+ *  upper rungs; the provider adapters downgrade a rung a model lacks (see
+ *  anthropicEffort in @mantle/voice). The migration's CHECK holds this list. */
+export const AGENT_THINKING_EFFORTS = ['off', ...THINKING_EFFORTS] as const;
+export type AgentThinkingEffort = (typeof AGENT_THINKING_EFFORTS)[number];
+
+/** Labels for the agent select, in order. */
+export const AGENT_THINKING_EFFORT_LABELS: Record<AgentThinkingEffort, string> = {
+  off: 'Off',
+  low: 'Low',
+  medium: 'Medium',
+  high: 'High',
+  xhigh: 'Extra high',
+  max: 'Max',
+};
+
+/** Narrow an unknown value to an agent effort. Anything else (null, '',
+ *  'inherit', a typo) is null = inherit, so a bad value can never turn
+ *  reasoning ON. */
+export function parseAgentThinkingEffort(raw: unknown): AgentThinkingEffort | null {
+  return typeof raw === 'string' && (AGENT_THINKING_EFFORTS as readonly string[]).includes(raw)
+    ? (raw as AgentThinkingEffort)
+    : null;
+}
+
+/** The budget (tier id) that backs an effort. The runtime still gates on a
+ *  positive budget and sizes the max_tokens headroom from it (see
+ *  clampThinkingBudget / resolveMaxTokens in @mantle/runtime), so an agent's
+ *  effort needs one. The profile tiers keep their ids; the two upper rungs
+ *  have no profile tier, so they get a larger headroom of their own (24000 is
+ *  the profile route's ceiling). */
+export function thinkingBudgetForEffort(effort: ThinkingEffort): number {
+  const tier = THINKING_TIERS.find((t) => t.effort === effort);
+  if (tier) return tier.budget;
+  return effort === 'xhigh' ? 16000 : 24000;
+}