openwriter 0.23.0 → 0.25.0

package/dist/server/peek-outline.js

@@ -0,0 +1,370 @@
+/**
+ * Outline + peek primitives for node-level doc navigation.
+ *
+ * The "orient by content, pick by node" architectural rule lives here.
+ *
+ * - outline returns the heading skeleton (and optional drill-down into one
+ *   section) so an agent can see what a doc IS without reading bodies.
+ * - peek returns a windowed slice of nodes (around an anchor, by range, by
+ *   position, by explicit IDs) once the agent has a node ID to orient on.
+ *
+ * Neither tool initiates by node — node IDs are byproducts of content
+ * orientation (search hit, outline pick, deep-link click, prior peek).
+ */
+/** Render the outline for a doc.
+ *
+ *  Default behavior: heading tree only (filtered by depth).
+ *  underHeading set: full block list inside that section, with one-line
+ *    previews per block (~10–15 tokens each).
+ *  No headings present: falls back to top-level block previews.
+ */
+export function outline(doc, opts = {}) {
+    const depth = Math.max(1, Math.min(6, opts.depth ?? 3));
+    const content = doc.content || [];
+    let lines;
+    if (opts.underHeading) {
+        lines = renderSection(content, opts.underHeading);
+    }
+    else {
+        const headings = collectHeadings(content, depth);
+        // In OpenWriter convention the first h1 IS the doc title (already
+        // surfaced by every other read tool — read_pad header, search_docs,
+        // browse_docs). Drop it from the outline so we don't waste a line
+        // restating what the caller already knows. Subsequent h1s (rare —
+        // would be a multi-chapter doc) are kept; they're real structure.
+        const filtered = headings.length > 0 && headings[0].level === 1
+            ? headings.slice(1)
+            : headings;
+        if (filtered.length > 0) {
+            lines = filtered.map(renderHeading);
+        }
+        else if (headings.length === 0) {
+            // Doc has no headings — fall back to block previews so the agent
+            // still gets a structural read.
+            lines = collectTopLevelPreviews(content);
+        }
+        else {
+            // Doc has ONLY the title h1 (no body headings). Fall back to
+            // top-level block previews so the agent has something to navigate.
+            lines = collectTopLevelPreviews(content);
+        }
+    }
+    // Pagination — applied to rendered lines so the agent can walk a
+    // huge skeleton incrementally without re-fetching the whole thing.
+    const offset = Math.max(0, opts.offset ?? 0);
+    const limit = Math.max(1, opts.limit ?? 200);
+    const total = lines.length;
+    const slice = lines.slice(offset, offset + limit);
+    const header = opts.underHeading
+        ? `outline (section ${opts.underHeading}):`
+        : `outline (depth ${depth}):`;
+    const footer = total > offset + limit
+        ? `\n[showing ${slice.length} of ${total} lines — call again with offset=${offset + limit} for more]`
+        : '';
+    return `${header}\n${slice.join('\n')}${footer}`;
+}
+function collectHeadings(content, maxDepth) {
+    const out = [];
+    function walk(nodes) {
+        for (const n of nodes) {
+            if (n.type === 'heading') {
+                const level = n.attrs?.level ?? 1;
+                if (level <= maxDepth) {
+                    out.push({ level, text: extractText(n), id: n.attrs?.id });
+                }
+            }
+            // Headings can only legally appear at top level in OpenWriter docs,
+            // but recurse defensively so we don't miss any author-malformed trees.
+            if (n.content)
+                walk(n.content);
+        }
+    }
+    walk(content);
+    return out;
+}
+function renderHeading(h) {
+    const indent = '  '.repeat(Math.max(0, h.level - 1));
+    const idTag = h.id ? `[h${h.level}:${h.id}] ` : `[h${h.level}] `;
+    return `${indent}${idTag}${h.text}`;
+}
+/** Return preview lines for every top-level block in the doc — used when
+ *  there are no headings to anchor an outline on. */
+function collectTopLevelPreviews(content) {
+    return content.map((node) => previewLine(node));
+}
+/** Walk the doc and return preview lines for every block from the named
+ *  heading up to (but not including) the next heading at the same level
+ *  or shallower. */
+function renderSection(content, headingId) {
+    // Find the heading at top level
+    let startIdx = -1;
+    let startLevel = 0;
+    for (let i = 0; i < content.length; i++) {
+        const n = content[i];
+        if (n.type === 'heading' && n.attrs?.id === headingId) {
+            startIdx = i;
+            startLevel = n.attrs?.level ?? 1;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return [`(no heading with id ${headingId} found at top level)`];
+    const lines = [];
+    // Include the heading itself first, then walk forward until end-of-section.
+    for (let i = startIdx; i < content.length; i++) {
+        const n = content[i];
+        if (i > startIdx && n.type === 'heading' && (n.attrs?.level ?? 1) <= startLevel)
+            break;
+        lines.push(previewLine(n));
+    }
+    return lines;
+}
+/** ~10–15 token preview of a top-level block — type tag + nodeId + first
+ *  ~80 chars of inner text. Lists collapse to their item-count summary. */
+function previewLine(node) {
+    const id = node.attrs?.id ? `:${node.attrs.id}` : '';
+    if (node.type === 'heading') {
+        const level = node.attrs?.level ?? 1;
+        return `[h${level}${id}] ${extractText(node)}`;
+    }
+    if (node.type === 'paragraph') {
+        const txt = extractText(node);
+        return `[p${id}] ${truncate(txt, 80)}`;
+    }
+    if (node.type === 'bulletList' || node.type === 'orderedList' || node.type === 'taskList') {
+        const count = (node.content ?? []).length;
+        const shortType = node.type === 'bulletList' ? 'ul' : node.type === 'orderedList' ? 'ol' : 'tl';
+        return `[${shortType}${id}] (${count} item${count === 1 ? '' : 's'})`;
+    }
+    if (node.type === 'blockquote') {
+        return `[bq${id}] ${truncate(firstChildText(node), 80)}`;
+    }
+    if (node.type === 'codeBlock') {
+        const lang = node.attrs?.language || '';
+        return `[code${id}${lang ? ' ' + lang : ''}] ${truncate(extractText(node), 60)}`;
+    }
+    if (node.type === 'horizontalRule') {
+        return `[hr${id}] ---`;
+    }
+    if (node.type === 'table') {
+        const rows = (node.content ?? []).length;
+        return `[table${id}] (${rows} row${rows === 1 ? '' : 's'})`;
+    }
+    if (node.type === 'image') {
+        return `[img${id}] ${node.attrs?.alt || node.attrs?.src || ''}`;
+    }
+    if (node.type === 'footnoteSection' || node.type === 'footnoteDefinition') {
+        return `[${node.type}${id}] ${truncate(firstChildText(node), 60)}`;
+    }
+    return `[${node.type}${id}]`;
+}
+function firstChildText(node) {
+    if (!node.content)
+        return '';
+    for (const c of node.content) {
+        const t = extractText(c);
+        if (t)
+            return t;
+    }
+    return '';
+}
+function extractText(node) {
+    if (node.type === 'text' && typeof node.text === 'string')
+        return node.text;
+    if (!node.content)
+        return '';
+    return node.content.map(extractText).join('');
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max).trimEnd() + '…';
+}
+/** Return a windowed slice of TipTap nodes from a doc per the target spec.
+ *  The caller renders via compactNodes — this function returns raw nodes
+ *  so the rendering pipeline stays uniform with read_pad / get_nodes. */
+export function peek(doc, target) {
+    const content = doc.content || [];
+    if ('node' in target) {
+        return findById(content, [target.node]);
+    }
+    if ('nodes' in target) {
+        return findById(content, target.nodes);
+    }
+    if ('around' in target) {
+        const idx = findTopLevelIndex(content, target.around);
+        if (idx === -1)
+            return [];
+        const before = Math.max(0, target.before ?? 1);
+        const after = Math.max(0, target.after ?? 1);
+        return content.slice(Math.max(0, idx - before), Math.min(content.length, idx + after + 1));
+    }
+    if ('from' in target) {
+        const a = findTopLevelIndex(content, target.from);
+        const b = findTopLevelIndex(content, target.to);
+        if (a === -1 || b === -1)
+            return [];
+        const [lo, hi] = a <= b ? [a, b] : [b, a];
+        return content.slice(lo, hi + 1);
+    }
+    if ('first' in target) {
+        return content.slice(0, Math.max(1, target.first));
+    }
+    if ('last' in target) {
+        const n = Math.max(1, target.last);
+        return content.slice(Math.max(0, content.length - n));
+    }
+    if ('position' in target) {
+        const pos = Math.max(0, Math.min(1, target.position));
+        const span = Math.max(1, target.span ?? 3);
+        const idx = Math.min(content.length - 1, Math.floor(content.length * pos));
+        return content.slice(idx, Math.min(content.length, idx + span));
+    }
+    return [];
+}
+/** Find every node matching one of the given IDs — full-tree walk to support
+ *  IDs on nested blocks (list items, table cells, etc.). Same shape as
+ *  state.findNodesByIds but lives here to keep peek-outline self-contained. */
+function findById(content, ids) {
+    const set = new Set(ids);
+    const out = [];
+    function walk(nodes) {
+        for (const n of nodes) {
+            if (n.attrs?.id && set.has(n.attrs.id))
+                out.push(n);
+            if (n.content)
+                walk(n.content);
+        }
+    }
+    walk(content);
+    return out;
+}
+/** Return the top-level doc.content index whose subtree contains nodeId.
+ *  Handles nested IDs by walking each top-level subtree. */
+function findTopLevelIndex(content, id) {
+    function contains(node) {
+        if (node.attrs?.id === id)
+            return true;
+        if (!node.content)
+            return false;
+        for (const c of node.content)
+            if (contains(c))
+                return true;
+        return false;
+    }
+    for (let i = 0; i < content.length; i++) {
+        if (contains(content[i]))
+            return i;
+    }
+    return -1;
+}
+/** Count whitespace-delimited tokens across every text node in `nodes`.
+ *  Mirrors the convention used elsewhere in the server (extractText + split). */
+export function countWords(nodes) {
+    function collect(node) {
+        if (node.type === 'text' && typeof node.text === 'string')
+            return node.text;
+        if (!node.content)
+            return '';
+        return node.content.map(collect).join(' ');
+    }
+    const text = nodes.map(collect).join(' ').trim();
+    if (!text)
+        return 0;
+    return text.split(/\s+/).length;
+}
+/** Truncate a doc at a top-level node boundary so the returned content
+ *  doesn't exceed `maxWords`. Returns the original doc unchanged if it
+ *  already fits. Always includes at least one top-level node so callers
+ *  never receive an empty body.
+ *
+ *  read_pad's contract: a fixed-window read, not a full-body read. Above
+ *  the cap, the agent gets the doc opening (most context-rich slice —
+ *  title, intro, first few sections) plus the lastNodeId so `peek_doc`
+ *  can continue from the boundary, or `outline_doc` / `search_docs` can
+ *  jump elsewhere.
+ *
+ *  Node-boundary truncation (never splits a top-level block) keeps the
+ *  returned slice structurally valid markdown — list items, blockquotes,
+ *  and code blocks stay intact. */
+export function truncateRead(doc, maxWords) {
+    const content = doc.content || [];
+    const totalWords = countWords(content);
+    const lastTopId = (n) => n?.attrs?.id ?? null;
+    if (totalWords <= maxWords) {
+        return {
+            doc,
+            truncated: false,
+            totalWords,
+            returnedWords: totalWords,
+            lastNodeId: lastTopId(content[content.length - 1]),
+            remaining: 0,
+        };
+    }
+    const included = [];
+    let words = 0;
+    let lastNodeId = null;
+    for (const n of content) {
+        const w = countWords([n]);
+        // Always include at least one node — even if it alone exceeds the cap,
+        // an empty body would be a worse failure mode than a slightly oversize one.
+        if (included.length > 0 && words + w > maxWords)
+            break;
+        included.push(n);
+        words += w;
+        if (n.attrs?.id)
+            lastNodeId = n.attrs.id;
+    }
+    return {
+        doc: { ...doc, content: included },
+        truncated: true,
+        totalWords,
+        returnedWords: words,
+        lastNodeId,
+        remaining: totalWords - words,
+    };
+}
+/** Find blocks whose text matches the query inside one doc. Returns up to
+ *  `limit` matches with the matched node's ID, type, and a snippet around
+ *  the hit. Case-insensitive substring match, same shape as the workspace-
+ *  scoped search but scoped to one doc and returning node-level handles.
+ *
+ *  Only nodes with an addressable `attrs.id` are emitted as matches. The
+ *  walker still descends into IDless children (text runs, inline marks) so
+ *  block-level matches are found, but it does NOT emit those children as
+ *  their own hits — they're already represented by their parent block's
+ *  entry, and emitting them duplicates results. */
+export function searchInDoc(doc, query, limit = 10) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const out = [];
+    function walk(nodes) {
+        if (out.length >= limit)
+            return;
+        for (const n of nodes) {
+            if (out.length >= limit)
+                return;
+            if (n.attrs?.id) {
+                const text = extractText(n);
+                if (text) {
+                    const lower = text.toLowerCase();
+                    const idx = lower.indexOf(q);
+                    if (idx !== -1) {
+                        const start = Math.max(0, idx - 30);
+                        const end = Math.min(text.length, idx + q.length + 50);
+                        out.push({
+                            nodeId: n.attrs.id,
+                            type: n.type,
+                            snippet: (start > 0 ? '…' : '') + text.slice(start, end) + (end < text.length ? '…' : ''),
+                        });
+                    }
+                }
+            }
+            if (n.content)
+                walk(n.content);
+        }
+    }
+    walk(doc.content || []);
+    return out;
+}

package/dist/server/state.js

@@ -19,6 +19,7 @@ import { markdownToNodes, resolvePreviousNodes, resolveGraveyard } from './markd
 import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
 import { harvestSentenceHashes, harvestCharCount, isEnrichmentStale } from './enrichment.js';
 import { clearActivityBuffer } from './activity-log.js';
+import { titleFromDoc, shouldAutoTitle } from './title-from-body.js';
 /** Read the persisted identity graph (nodes + graveyard) from a file's
  *  frontmatter. The save-time matcher reads previousNodes + graveyard
  *  directly from disk every write — the disk is the source of truth, not
@@ -195,6 +196,21 @@ export function onExternalWriteConflict(listener) {
     externalWriteConflictListeners.add(listener);
     return () => externalWriteConflictListeners.delete(listener);
 }
+const autoTitleAppliedListeners = new Set();
+export function onAutoTitleApplied(listener) {
+    autoTitleAppliedListeners.add(listener);
+    return () => autoTitleAppliedListeners.delete(listener);
+}
+function notifyAutoTitleApplied(newTitle) {
+    for (const listener of autoTitleAppliedListeners) {
+        try {
+            listener(newTitle);
+        }
+        catch (err) {
+            console.error('[State] auto-title listener threw:', err);
+        }
+    }
+}
 function notifyExternalWriteConflict(filePath, diskMtime, loadedMtime) {
     for (const listener of externalWriteConflictListeners) {
         try {
@@ -2240,6 +2256,26 @@ function writeToDisk() {
     }
 }
 export function save() {
+    // Auto-title from body content if the title is still default/empty.
+    // Runs BEFORE filePath assignment so a brand-new doc lands at its
+    // derived-title filename directly (no temp-file detour). For already-
+    // saved temp files, the listener (ws.ts) calls promoteTempFile to
+    // rename on disk. External docs are skipped — we never rename files
+    // the user manages outside the openwriter data dir.
+    //
+    // `bumpDocVersion()` is required to defeat writeToDisk's no-op gate
+    // when only the title changed (no body mutation between saves). Without
+    // it, the title update would live in memory only and never reach disk.
+    if (!isExternalDoc(state.filePath ?? '') && shouldAutoTitle(state.title)) {
+        const derived = titleFromDoc(state.document);
+        if (derived && derived !== state.title) {
+            state.title = derived;
+            if (state.metadata)
+                state.metadata.title = derived;
+            bumpDocVersion();
+            notifyAutoTitleApplied(derived);
+        }
+    }
     if (!state.filePath) {
         // First save — assign a file path. Canonicalize at this identity
         // boundary so cache lookups and watcher subscriptions key on the
@@ -2655,6 +2691,87 @@ export function setAutoAcceptOnFile(filename, enabled) {
     }
     catch { /* best-effort */ }
 }
+/** Write a sortRequest marker onto a file. Stamps requestedAt; the agent
+ *  picks the doc up via list_pending_sorts and writes a proposal back. */
+export function setSortRequestOnFile(filename) {
+    const targetPath = resolveDocPath(filename);
+    if (!existsSync(targetPath))
+        return;
+    try {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = markdownToTiptap(raw);
+        parsed.metadata.sortRequest = { requestedAt: new Date().toISOString() };
+        let markdown;
+        if (isExternalDoc(targetPath)) {
+            const body = tiptapToBody(parsed.document);
+            markdown = parsed.rawFrontmatter
+                ? `---\n${parsed.rawFrontmatter}\n---\n\n${body}`
+                : body;
+        }
+        else {
+            markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
+        }
+        atomicWriteFileSync(targetPath, markdown);
+        invalidateDocCache(targetPath);
+    }
+    catch { /* best-effort */ }
+}
+/** Clear sortRequest and stamp lastSortedAt. Used on fulfillment (accept
+ *  or reject) — the marker retires the same way enrichmentStale retires
+ *  to lastEnrichedAt. */
+export function clearSortRequestOnFile(filename) {
+    const targetPath = resolveDocPath(filename);
+    if (!existsSync(targetPath))
+        return;
+    try {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = markdownToTiptap(raw);
+        delete parsed.metadata.sortRequest;
+        parsed.metadata.lastSortedAt = new Date().toISOString();
+        let markdown;
+        if (isExternalDoc(targetPath)) {
+            const body = tiptapToBody(parsed.document);
+            markdown = parsed.rawFrontmatter
+                ? `---\n${parsed.rawFrontmatter}\n---\n\n${body}`
+                : body;
+        }
+        else {
+            markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
+        }
+        atomicWriteFileSync(targetPath, markdown);
+        invalidateDocCache(targetPath);
+    }
+    catch { /* best-effort */ }
+}
+/** Stamp a proposal onto an existing sortRequest. Used by the agent after
+ *  it has picked a destination — the UI flips the badge to "proposal ready"
+ *  and the user accepts/rejects via the in-menu popover. */
+export function setSortProposalOnFile(filename, proposal) {
+    const targetPath = resolveDocPath(filename);
+    if (!existsSync(targetPath))
+        return;
+    try {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = markdownToTiptap(raw);
+        const existing = parsed.metadata.sortRequest;
+        if (!existing || typeof existing !== 'object')
+            return; // no request to attach to
+        parsed.metadata.sortRequest = { ...existing, proposal };
+        let markdown;
+        if (isExternalDoc(targetPath)) {
+            const body = tiptapToBody(parsed.document);
+            markdown = parsed.rawFrontmatter
+                ? `---\n${parsed.rawFrontmatter}\n---\n\n${body}`
+                : body;
+        }
+        else {
+            markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
+        }
+        atomicWriteFileSync(targetPath, markdown);
+        invalidateDocCache(targetPath);
+    }
+    catch { /* best-effort */ }
+}
 /**
  * Strip pending attrs from a specific file on disk (not the active document).
  *

package/dist/server/title-from-body.js

@@ -0,0 +1,125 @@
+/**
+ * Auto-derive a document title from its body content.
+ *
+ * Algorithm adapted from Joplin's `markdownUtils.titleFromBody`
+ * (https://github.com/laurent22/joplin, AGPL-3.0) — algorithm only, fresh
+ * implementation in this repo under MIT. Same approach Bear, iA Writer,
+ * Apple Notes, and Joplin all converge on: the first non-empty line of
+ * the body, stripped of formatting, becomes the title.
+ *
+ * Lock detection schema: implicit via `shouldAutoTitle()`. While the title
+ * is in the `DEFAULT_TITLES` set or empty, we own the title and re-derive
+ * on every save. The moment the user (or an agent via rename_item) sets
+ * the title to anything else, auto-naming stops permanently for that doc.
+ * No frontmatter flag needed — the title itself IS the state.
+ *
+ * Notes on the TipTap-native approach: we walk the document JSON tree
+ * directly instead of running regexes on serialized markdown. Marks like
+ * link/bold/italic/strike are transparent to text extraction (TipTap stores
+ * inner text on text nodes, not raw `[text](url)`/`**bold**` syntax). That
+ * eliminates an entire class of edge cases Joplin's regex chain handles
+ * defensively. We still strip leading punctuation as a safety net for
+ * users who type raw markdown into a fresh paragraph that hasn't been
+ * input-parsed.
+ */
+const DEFAULT_TITLES = new Set(['Untitled', 'New Document', 'Article']);
+/**
+ * Hard ceiling for an auto-derived title. Titles that fit a natural
+ * sentence ending below this cap will use the sentence boundary (clean,
+ * no ellipsis). Titles whose first sentence runs past the cap get
+ * truncated at the nearest word boundary inside the limit. Tuned to
+ * what reads cleanly in a sidebar row — Bear and iA Writer's effective
+ * display widths are in this neighborhood. Joplin's 80 was usable but
+ * visually heavy; 60 reads tighter without losing useful information.
+ */
+const TITLE_MAX_LENGTH = 60;
+/**
+ * Trim a string to a usable title length, preferring sentence ending
+ * inside the cap, falling back to word-boundary truncation.
+ */
+function trimToTitleLength(text, maxLen) {
+    // Prefer the first sentence boundary if it lands within the cap.
+    // Matches up to (but excluding) the punctuation, then whitespace or end.
+    const sentenceMatch = text.match(/^([^.!?]+)[.!?](?:\s|$)/);
+    if (sentenceMatch && sentenceMatch[1].trim().length <= maxLen) {
+        return sentenceMatch[1].trim();
+    }
+    if (text.length <= maxLen)
+        return text;
+    // Hard truncate. Prefer the last word boundary in the last 30% of the
+    // window so we don't chop mid-word when a clean break is close at hand.
+    const trunc = text.substring(0, maxLen);
+    const lastSpace = trunc.lastIndexOf(' ');
+    if (lastSpace > maxLen * 0.7) {
+        return trunc.substring(0, lastSpace);
+    }
+    return trunc;
+}
+/** Block types we skip entirely — code is rarely a good title, and
+ *  decorative elements have no useful text. */
+const SKIP_BLOCK_TYPES = new Set([
+    'codeBlock',
+    'horizontalRule',
+    'hardBreak',
+    'image',
+]);
+/** Recursively collect inline text from a node tree, skipping atom/leaf
+ *  types we don't want in titles (images, code blocks, etc.). */
+function extractText(node) {
+    if (!node)
+        return '';
+    if (SKIP_BLOCK_TYPES.has(node.type))
+        return '';
+    if (typeof node.text === 'string')
+        return node.text;
+    if (!node.content || !Array.isArray(node.content))
+        return '';
+    let out = '';
+    for (const child of node.content) {
+        out += extractText(child);
+    }
+    return out;
+}
+/** Strip leading markdown-syntax characters that survive when a user
+ *  typed raw markdown into a paragraph that didn't get input-parsed
+ *  (e.g. a fresh stub block). Also handles trailing setext-style
+ *  underline noise that might cling to a heading line. */
+function cleanMarkdownNoise(text) {
+    let out = text;
+    // Leading list/heading/quote/emphasis markers
+    out = out.replace(/^[\s#>*_~`+\-=]+/, '');
+    // Trailing setext underline residue or whitespace
+    out = out.replace(/[\s#>*_~`+\-=]+$/, '');
+    return out.trim();
+}
+/**
+ * Extract a title from a TipTap document. Returns an empty string if
+ * the document has no usable text. Caller decides whether to apply.
+ */
+export function titleFromDoc(doc) {
+    if (!doc || !doc.content || !Array.isArray(doc.content))
+        return '';
+    for (const block of doc.content) {
+        const raw = extractText(block);
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const cleaned = cleanMarkdownNoise(trimmed);
+        if (!cleaned)
+            continue;
+        return trimToTitleLength(cleaned, TITLE_MAX_LENGTH);
+    }
+    return '';
+}
+/**
+ * Whether the auto-titler should act on a document with this title. True
+ * when the title is empty or one of the system defaults — meaning the
+ * user (or agent) has not committed to a name yet, so we're free to
+ * derive one. Once `shouldAutoTitle` returns false, auto-naming stops
+ * permanently for that doc.
+ */
+export function shouldAutoTitle(title) {
+    if (!title)
+        return true;
+    return DEFAULT_TITLES.has(title);
+}

package/dist/server/workspaces.js

@@ -537,6 +537,29 @@ export function setContainerAutoAccept(wsFile, containerId, enabled) {
         delete found.node.autoAccept;
     writeWorkspace(wsFile, ws);
 }
+/** Set or clear the user-authored `purpose:` hint on a workspace. Trim and
+ *  treat empty string as clear, so a user can blank the field in the UI. */
+export function setWorkspacePurpose(wsFile, purpose) {
+    const ws = readWorkspace(wsFile);
+    const trimmed = purpose.trim();
+    if (trimmed)
+        ws.purpose = trimmed;
+    else
+        delete ws.purpose;
+    writeWorkspace(wsFile, ws);
+}
+export function setContainerPurpose(wsFile, containerId, purpose) {
+    const ws = readWorkspace(wsFile);
+    const found = findContainer(ws.root, containerId);
+    if (!found)
+        throw new Error(`Container ${containerId} not found in ${wsFile}`);
+    const trimmed = purpose.trim();
+    if (trimmed)
+        found.node.purpose = trimmed;
+    else
+        delete found.node.purpose;
+    writeWorkspace(wsFile, ws);
+}
 /** Collect every file inside a workspace or container subtree. Used for broadcast. */
 export function collectFilesInWorkspace(wsFile) {
     try {