@bubblebrain-ai/bubble 0.0.58 → 0.0.60

package/dist/session.js

@@ -2,22 +2,79 @@
  * Session Manager - Append-only JSONL persistence over a structured session log.
  */
 import { randomUUID } from "node:crypto";
-import { mkdirSync, appendFileSync, existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, appendFileSync, existsSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync, unlinkSync, openSync, closeSync, fsyncSync, ftruncateSync, readSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { isInternalBlockOnlyContent } from "./agent/internal-reminder-sanitizer.js";
 import { getBubbleHome } from "./bubble-home.js";
 import { CheckpointStore } from "./checkpoints.js";
-import { buildCompactedEntries, compactSessionEntries, planOldMessages, planSessionCompaction, } from "./context/compact.js";
-import { SessionLog } from "./session-log.js";
+import { withSessionWriteLock } from "./context/session-write-lock.js";
+import { compactMessages, compactCurrentTurnToolGroups, buildCompactionSummaryMessage, isCompactionSummaryMessage, } from "./context/compact.js";
+import { createContextCheckpoint, checkpointMessages } from "./context/checkpoint.js";
+import { SessionLog, affectsContextRevision } from "./session-log.js";
 import { normalizeSingleLine, truncateVisual } from "./text-display.js";
 import { deterministicTitleFromUserContent } from "./session-title.js";
-const AUTO_COMPACT_ENTRY_THRESHOLD = 180;
-const AUTO_COMPACT_KEEP_RECENT_TURNS = 3;
+/** A fenced write found the session log diverged from the writer's resident
+ * snapshot — a foreign append, clear, or rewind landed while a turn was in
+ * flight. The write is refused; the host must roll its resident history back
+ * to the file's truth (SessionContextFence.reloadHistory, then replace the
+ * agent's messages) before writing again, or every later fenced write keeps
+ * rejecting on the stale revision. */
+export class SessionHistoryDivergedError extends Error {
+    constructor(message = "Session changed during active turn; reload before committing context") {
+        super(message);
+        this.name = "SessionHistoryDivergedError";
+    }
+}
 export class SessionManager {
     sessionFile;
     log = new SessionLog();
     checkpoints;
+    diskRevision = "missing";
+    pendingCompaction;
+    /** Conversational revision excludes metadata-only writes (for example titles). */
+    getRevision() { return this.log.getRevision(); }
+    refresh() {
+        if (this.currentDiskRevision() !== this.diskRevision)
+            this.load();
+    }
+    currentDiskRevision() {
+        try {
+            const s = statSync(this.sessionFile, { bigint: true });
+            return `${s.ino}:${s.size}:${s.mtimeNs}`;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return "missing";
+            throw error;
+        }
+    }
+    withWriteLock(write, expectedRevision) {
+        mkdirSync(dirname(this.sessionFile), { recursive: true });
+        return withSessionWriteLock(`${this.sessionFile}.write-lock`, () => {
+            if (expectedRevision !== undefined) {
+                // Refresh and compare the caller's snapshot under the same lock as the
+                // append. Refreshing must never legitimize a stale caller revision.
+                this.refresh();
+                if (this.getRevision() !== expectedRevision)
+                    throw new SessionHistoryDivergedError();
+            }
+            else if (this.currentDiskRevision() !== this.diskRevision) {
+                throw new SessionHistoryDivergedError("Session changed; reload before committing context");
+            }
+            return write();
+        });
+    }
     metadataListeners = new Set();
+    contextListeners = new Set();
+    /** Local commits only: disk refreshes must never advance a host's history fence. */
+    subscribeContextCommits(listener) {
+        this.contextListeners.add(listener);
+        return () => this.contextListeners.delete(listener);
+    }
+    publishContextCommit(previous, replacement = false) {
+        for (const listener of this.contextListeners)
+            listener(previous, this.getRevision(), replacement);
+    }
     constructor(sessionFile) {
         this.sessionFile = sessionFile;
         if (existsSync(sessionFile)) {
@@ -88,11 +145,19 @@ export class SessionManager {
         return summaries.sort((a, b) => b.mtime - a.mtime);
     }
     load() {
-        const content = readFileSync(this.sessionFile, "utf-8");
-        const lines = content.split("\n").filter((line) => line.trim() !== "");
-        this.log.load(lines);
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const before = this.currentDiskRevision();
+            const content = readFileSync(this.sessionFile, "utf-8");
+            const after = this.currentDiskRevision();
+            if (before !== after)
+                continue;
+            this.log.load(content.split("\n").filter(line => line.trim() !== ""));
+            this.diskRevision = after;
+            return;
+        }
+        throw new Error("Session changed while loading; retry with a stable snapshot");
     }
-    persist(entry) {
+    persist(entry, lockHeld = false) {
         const dir = dirname(this.sessionFile);
         if (!existsSync(dir)) {
             mkdirSync(dir, { recursive: true });
@@ -101,15 +166,62 @@ export class SessionManager {
         if (entries.length === 0) {
             return;
         }
-        appendFileSync(this.sessionFile, entries.map((item) => JSON.stringify(item)).join("\n") + "\n");
-    }
-    rewrite(entries) {
-        const dir = dirname(this.sessionFile);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        writeFileSync(this.sessionFile, entries.map((entry) => JSON.stringify(entry)).join("\n") + "\n");
-        this.log.replace(entries);
+        const write = () => {
+            const fd = openSync(this.sessionFile, "a+");
+            const before = statSync(this.sessionFile).size;
+            try {
+                // Isolate an incomplete crash tail, without adding empty records normally.
+                const tail = Buffer.alloc(1);
+                if (before > 0)
+                    readSync(fd, tail, 0, 1, before - 1);
+                const separator = before > 0 && tail[0] !== 10 ? "\n" : "";
+                appendFileSync(fd, separator + entries.map((item) => JSON.stringify(item)).join("\n") + "\n");
+                fsyncSync(fd);
+            }
+            catch (error) {
+                ftruncateSync(fd, before);
+                fsyncSync(fd);
+                throw error;
+            }
+            finally {
+                closeSync(fd);
+                this.diskRevision = this.currentDiskRevision();
+            }
+        };
+        if (lockHeld)
+            write();
+        else
+            this.withWriteLock(write);
+    }
+    /** Refresh, derive the replacement from the refreshed log, and swap the file
+     * as one locked transaction; `derive` returning undefined leaves it untouched. */
+    rewrite(derive) {
+        mkdirSync(dirname(this.sessionFile), { recursive: true });
+        return withSessionWriteLock(`${this.sessionFile}.write-lock`, () => {
+            this.refresh();
+            const derived = derive(this.log.list());
+            if (!derived)
+                return undefined;
+            const temp = `${this.sessionFile}.${randomUUID()}.tmp`;
+            try {
+                writeFileSync(temp, derived.entries.map((entry) => JSON.stringify(entry)).join("\n") + "\n", { mode: 0o600 });
+                const fd = openSync(temp, "r");
+                try {
+                    fsyncSync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                renameSync(temp, this.sessionFile);
+                this.diskRevision = this.currentDiskRevision();
+                this.log.replace(derived.entries);
+            }
+            finally {
+                if (existsSync(temp))
+                    unlinkSync(temp);
+            }
+            return derived.result;
+        });
     }
     getMetadata() {
         return this.log.getMetadata();
@@ -132,8 +244,26 @@ export class SessionManager {
         return promptCacheKey;
     }
     setMetadata(metadata) {
-        const nextEntries = this.log.setMetadata(metadata);
-        this.rewrite(nextEntries);
+        this.mutateMetadata(() => metadata);
+    }
+    /** Refresh, derive, and append as one locked transaction. Metadata records
+     * are full snapshots, so a snapshot built outside the lock would silently
+     * overwrite a concurrent writer's fields. */
+    mutateMetadata(build) {
+        mkdirSync(dirname(this.sessionFile), { recursive: true });
+        try {
+            withSessionWriteLock(`${this.sessionFile}.write-lock`, () => {
+                this.refresh();
+                const entry = { id: `metadata-${randomUUID()}`, type: "metadata",
+                    metadata: build(this.log.getMetadata()), timestamp: Date.now() };
+                this.persist(entry, true);
+                this.log.appendEntries([entry]);
+            });
+        }
+        catch (error) {
+            this.reloadAfterWriteFailure();
+            throw error;
+        }
         const committed = this.log.getMetadata();
         for (const listener of this.metadataListeners) {
             try {
@@ -146,40 +276,75 @@ export class SessionManager {
         }
     }
     updateMetadata(patch) {
-        this.setMetadata({
-            ...this.log.getMetadata(),
-            ...dropUndefined(patch),
-        });
+        this.mutateMetadata((current) => ({ ...current, ...dropUndefined(patch) }));
     }
     clearTitleMetadata() {
-        const { title: _title, titleSource: _titleSource, titleUpdatedAt: _titleUpdatedAt, titleUserMessageId: _titleUserMessageId, ...metadata } = this.log.getMetadata();
-        this.setMetadata(metadata);
+        this.mutateMetadata(({ title: _title, titleSource: _titleSource, titleUpdatedAt: _titleUpdatedAt, titleUserMessageId: _titleUserMessageId, ...metadata }) => metadata);
     }
     clearExternalRuntimeMetadata() {
-        const { externalRuntime: _externalRuntime, ...metadata } = this.log.getMetadata();
-        this.setMetadata(metadata);
-    }
-    appendMessage(message) {
-        const entries = this.log.appendMessage(message);
-        this.persist(entries);
-        this.maybeAutoCompact();
-    }
-    appendCompaction(summary) {
-        const entry = this.log.appendSummary(summary);
-        this.persist(entry);
+        this.mutateMetadata(({ externalRuntime: _externalRuntime, ...metadata }) => metadata);
+    }
+    appendMessage(message, expectedRevision) {
+        this.refresh();
+        const revision = expectedRevision ?? this.getRevision();
+        try {
+            this.withWriteLock(() => {
+                const entries = this.log.appendMessage(message);
+                this.persist(entries, true);
+            }, revision);
+        }
+        catch (error) {
+            this.reloadAfterWriteFailure();
+            throw error;
+        }
+        this.publishContextCommit(revision);
+        // Persistence never decides model context policy by record count.
     }
-    appendMarker(kind, value) {
-        const entry = this.log.appendMarker(kind, value);
-        this.persist(entry);
+    reloadAfterWriteFailure() {
+        if (existsSync(this.sessionFile))
+            this.load();
+        else {
+            this.log = new SessionLog();
+            this.diskRevision = "missing";
+        }
     }
-    appendProviderError(error) {
-        const entry = this.log.appendProviderError(error);
-        this.persist(entry);
+    appendMarker(kind, value, expectedRevision) {
+        this.refresh();
+        const revision = expectedRevision ?? this.getRevision();
+        try {
+            this.withWriteLock(() => {
+                const entry = this.log.appendMarker(kind, value);
+                this.persist(entry, true);
+            }, revision);
+        }
+        catch (error) {
+            this.reloadAfterWriteFailure();
+            throw error;
+        }
+        this.publishContextCommit(revision, kind === "conversation_clear");
+    }
+    appendProviderError(error, expectedRevision) {
+        this.refresh();
+        try {
+            this.withWriteLock(() => {
+                const entry = this.log.appendProviderError(error);
+                this.persist(entry, true);
+            }, expectedRevision ?? this.getRevision());
+        }
+        catch (failure) {
+            this.reloadAfterWriteFailure();
+            throw failure;
+        }
     }
     compact(options) {
-        const result = compactSessionEntries(this.log.list(), options);
-        if (result.compacted && result.entries) {
-            this.rewrite(result.entries);
+        const messages = this.getMessages();
+        let result = compactMessages(messages, options);
+        if (!result.compacted)
+            result = compactCurrentTurnToolGroups(messages);
+        if (result.compacted && result.messages) {
+            const revision = this.getRevision();
+            this.commitContextCheckpoint(createContextCheckpoint(result.messages, "manual", result.summary, revision));
+            this.publishContextCommit(revision, true);
         }
         return result;
     }
@@ -190,32 +355,53 @@ export class SessionManager {
      * caller should then report "already compact enough" without calling a model.
      */
     getCompactionPlan(options) {
-        const plan = planSessionCompaction(this.log.list(), options);
-        if (!plan.compactable)
+        const messages = this.getMessages();
+        let candidate = compactMessages(messages, options);
+        if (!candidate.compacted)
+            candidate = compactCurrentTurnToolGroups(messages);
+        if (!candidate.compacted) {
+            this.pendingCompaction = undefined;
             return null;
-        return { oldMessages: planOldMessages(plan) };
+        }
+        this.pendingCompaction = { revision: this.getRevision(), candidate };
+        // Only the portion the candidate's summary replaces: kept recent turns
+        // survive verbatim, so feeding them to the summarizer would duplicate them
+        // in the summary and risk overflowing the compaction request into the
+        // heuristic fallback. Prior summary carriers are included so their facts
+        // roll forward.
+        return { oldMessages: candidate.evictedMessages ?? messages };
     }
     /**
      * Apply a precomputed (typically LLM-generated) summary as the compaction
-     * checkpoint, rewriting the log to [metadata, summary, kept turns]. Mirrors
+     * checkpoint, appending an exact projection without deleting originals. Mirrors
      * `compact()` but skips the built-in heuristic summarizer. Returns
      * `{ compacted: false }` if the session is no longer compactable.
      */
     applyLLMCompaction(summary, options) {
-        const entries = this.log.list();
-        const plan = planSessionCompaction(entries, options);
-        if (!plan.compactable)
+        const pending = this.pendingCompaction;
+        this.pendingCompaction = undefined;
+        const messages = this.getMessages();
+        if (pending && pending.revision !== this.getRevision())
+            throw new Error("Stale compaction plan; session changed during summarization");
+        let result = pending?.candidate ?? compactMessages(messages, options);
+        if (!result.compacted)
+            result = compactCurrentTurnToolGroups(messages);
+        if (!result.compacted || !result.messages)
             return { compacted: false };
-        const nextEntries = buildCompactedEntries(entries, plan, summary);
-        this.rewrite(nextEntries);
-        return {
-            compacted: true,
-            summary,
-            entries: nextEntries,
-            droppedEntries: plan.oldEntries.length,
-        };
+        // Replace only the summary that stands for the evicted input. A sub-turn
+        // candidate also carries earlier multi-turn summaries in its pre-turn; the
+        // summarizer never saw those, so they must survive verbatim.
+        const summaryIndex = result.summaryIndex ?? result.messages.findIndex(isCompactionSummaryMessage);
+        if (summaryIndex < 0)
+            return { compacted: false };
+        const next = result.messages.map((message, index) => index === summaryIndex ? buildCompactionSummaryMessage(summary) : message);
+        const revision = this.getRevision();
+        this.commitContextCheckpoint(createContextCheckpoint(next, "manual", summary, revision));
+        this.publishContextCommit(revision, true);
+        return { ...result, summary, messages: next };
     }
     getMessages() {
+        this.refresh();
         return this.log.toMessages();
     }
     /**
@@ -228,18 +414,26 @@ export class SessionManager {
         }
         return this.checkpoints;
     }
-    /** Entry id of the most recent user message, or "0" before the first one. */
+    /**
+     * Entry id of the most recent user turn (as listUserTurns counts them), or
+     * "0" before the first one. Checkpoints are keyed by it, so edits made after
+     * a tool screenshot or a harness-injected block stay with the user's turn.
+     */
     lastUserEntryId() {
         const entries = this.log.list();
         for (let i = entries.length - 1; i >= 0; i--) {
             const entry = entries[i];
-            if (entry.type === "user_message")
-                return entry.id;
+            if (entry.type !== "user_message")
+                continue;
+            if (entry.message.toolObservation || isInternalBlockOnlyContent(entry.message.content))
+                continue;
+            return entry.id;
         }
         return "0";
     }
     /** User messages after the latest /clear, oldest first — the valid rewind anchors. */
     listUserTurns() {
+        this.refresh();
         const entries = this.log.list();
         let start = 0;
         for (let i = entries.length - 1; i >= 0; i--) {
@@ -256,7 +450,8 @@ export class SessionManager {
                 continue;
             // Harness-injected turns (goal kicks, task wakes) are internal blocks —
             // not rewind anchors, and their markup must never render in the picker.
-            if (isInternalBlockOnlyContent(entry.message.content))
+            // Tool screenshots are user-role only for the provider; not turns either.
+            if (isInternalBlockOnlyContent(entry.message.content) || entry.message.toolObservation)
                 continue;
             const text = messageText(entry.message);
             turns.push({
@@ -273,21 +468,46 @@ export class SessionManager {
      * entry id. Returns undefined when the id does not name a user message.
      */
     rewindToEntry(entryId) {
-        const entries = this.log.list();
-        const index = entries.findIndex((entry) => entry.id === entryId && entry.type === "user_message");
-        if (index < 0)
-            return undefined;
-        const target = entries[index];
-        const removed = entries.slice(index);
-        this.rewrite(entries.slice(0, index));
-        const metadata = this.log.getMetadata();
-        if (metadata.titleUserMessageId && removed.some((entry) => entry.id === metadata.titleUserMessageId)) {
-            this.clearTitleMetadata();
+        // A rewind replaces history by explicit user action, so it selects from the
+        // refreshed log under the lock rather than fencing on a resident revision:
+        // a stale in-memory snapshot must not reject (or misplace) the rewrite.
+        let revision = this.getRevision();
+        let rewound;
+        try {
+            rewound = this.rewrite((entries) => {
+                const index = entries.findIndex((entry) => entry.id === entryId && entry.type === "user_message");
+                if (index < 0)
+                    return undefined;
+                revision = this.getRevision();
+                const target = entries[index];
+                const removed = entries.slice(index);
+                // Metadata records are full snapshots, not history deltas. Preserve the
+                // latest snapshot (including absent/cleared fields) in the atomic rewrite.
+                const metadata = { ...this.log.getMetadata() };
+                if (metadata.titleUserMessageId && removed.some((entry) => entry.id === metadata.titleUserMessageId)) {
+                    delete metadata.title;
+                    delete metadata.titleSource;
+                    delete metadata.titleUpdatedAt;
+                    delete metadata.titleUserMessageId;
+                }
+                return {
+                    entries: [...entries.slice(0, index), {
+                            id: `metadata-${randomUUID()}`, type: "metadata", metadata, timestamp: Date.now(),
+                        }],
+                    result: {
+                        removedEntries: removed.length,
+                        targetText: target.type === "user_message" ? messageText(target.message) : "",
+                    },
+                };
+            });
         }
-        return {
-            removedEntries: removed.length,
-            targetText: target.type === "user_message" ? messageText(target.message) : "",
-        };
+        catch (error) {
+            this.reloadAfterWriteFailure();
+            throw error;
+        }
+        if (rewound)
+            this.publishContextCommit(revision, true);
+        return rewound;
     }
     getEntries() {
         return this.log.list();
@@ -295,17 +515,35 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
-    maybeAutoCompact() {
-        const entries = this.log.list();
-        if (entries.length < AUTO_COMPACT_ENTRY_THRESHOLD) {
-            return;
-        }
-        const result = compactSessionEntries(entries, {
-            keepRecentTurns: AUTO_COMPACT_KEEP_RECENT_TURNS,
-        });
-        if (result.compacted && result.entries) {
-            this.rewrite(result.entries);
-        }
+    /** Commit the exact conversational projection, never delete its source history. */
+    commitContextCheckpoint(checkpoint, expectedRevision) {
+        const revision = expectedRevision ?? this.getRevision();
+        this.withWriteLock(() => {
+            const entries = this.log.list();
+            // Replay tolerates a structurally invalid (hand-edited) checkpoint record;
+            // it must not then make every later commit throw here.
+            const existing = entries.find(entry => entry.type === "context_checkpoint"
+                && entry.checkpoint?.compactionId === checkpoint.compactionId);
+            if (existing) {
+                if (existing.type !== "context_checkpoint" || JSON.stringify(existing.checkpoint) !== JSON.stringify(checkpoint)) {
+                    throw new Error("Conflicting context checkpoint id");
+                }
+                // An old receipt is not permission to restore context after clear/rewind
+                // or after new conversation data has superseded this exact projection.
+                if (entries.filter(affectsContextRevision).at(-1) !== existing)
+                    throw new Error("Stale context checkpoint receipt");
+                return;
+            }
+            if (checkpoint.baseRevision !== undefined && checkpoint.baseRevision !== this.getRevision()) {
+                throw new Error("Stale context checkpoint; session advanced during summarization");
+            }
+            checkpointMessages(checkpoint); // Validate before writing or publishing.
+            const entry = { id: `checkpoint-${checkpoint.compactionId}`, type: "context_checkpoint",
+                checkpoint: structuredClone(checkpoint), timestamp: Date.now() };
+            this.persist(entry, true);
+            this.log.appendEntries([entry]);
+        }, revision);
+        this.publishContextCommit(revision);
     }
 }
 export function getSessionsDir(cwd) {
@@ -336,11 +574,21 @@ function summarizeSessionFile(file, cwdDir) {
     const lines = content.split("\n").filter((line) => line.trim() !== "");
     if (lines.length === 0)
         return undefined;
+    // One unreadable session — an unsupported record, a hand-edited message the
+    // title/preview code cannot handle — must not take the whole listing down.
+    try {
+        return summarizeSessionLines(lines, file, cwdDir, stat.mtimeMs);
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarizeSessionLines(lines, file, cwdDir, mtime) {
     const log = new SessionLog();
     log.load(lines);
+    const messages = log.toMessages();
     const metadata = log.getMetadata();
     const entries = log.list();
-    const messages = log.toMessages();
     const firstUserEntry = firstUserEntryAfterLatestClear(entries);
     const firstUserText = firstUserEntry ? messageText(firstUserEntry.message) : "";
     const preview = firstUserText
@@ -357,7 +605,7 @@ function summarizeSessionFile(file, cwdDir) {
         preview,
         firstUserMessage: preview,
         messageCount: messages.length,
-        mtime: stat.mtimeMs,
+        mtime,
     };
 }
 function decodeCwdDir(safe) {
@@ -377,7 +625,7 @@ function firstUserEntryAfterLatestClear(entries) {
         const entry = entries[i];
         // Skip harness-injected internal blocks (goal kicks, task wakes): they
         // must not become the /resume preview or the deterministic title.
-        if (entry.type === "user_message" && !isInternalBlockOnlyContent(entry.message.content)) {
+        if (entry.type === "user_message" && !isInternalBlockOnlyContent(entry.message.content) && !entry.message.toolObservation) {
             return entry;
         }
     }

package/dist/skills/format.d.ts

@@ -1,2 +1,32 @@
 import type { SkillSummary } from "./types.js";
-export declare function formatSkillsPrompt(skills: SkillSummary[]): string;
+/** Default size of the always-present skill catalog (the listed lines, not the header). */
+export declare const SKILL_CATALOG_CHARS = 12000;
+/** Each description is cut to this length; it only has to tell the model when to load. */
+export declare const SKILL_CATALOG_DESC_CHARS = 120;
+export declare const SKILL_CATALOG_HEADING = "## Skills";
+/** First line under the heading; together they mark the catalog unambiguously. */
+export declare const SKILL_CATALOG_INTRO = "Skills are task-specific instructions loaded on demand. When a task matches a skill below, call `skill` with its exact name before starting, then follow it. Load only what clearly applies.";
+export interface SkillCatalogOptions {
+    /** Budget for the listed lines; 0 turns the catalog off. */
+    budgetChars?: number;
+    /** skill_search is available, so the overflow line can point to it. */
+    searchable?: boolean;
+}
+export interface SkillCatalog {
+    /** The system-prompt section, or "" when there is nothing to list. */
+    text: string;
+    listed: number;
+    unlisted: number;
+    /** Characters used by the listed lines, against budgetChars. */
+    chars: number;
+    budgetChars: number;
+}
+/**
+ * The always-present skill catalog: name and a one-line description per skill,
+ * so the model knows what exists and loads a body with `skill` only when it
+ * applies. Ordering is deterministic (source, then name) so the system prompt
+ * stays byte-identical, and cacheable, while the skill set is unchanged.
+ */
+export declare function buildSkillCatalog(skills: SkillSummary[], options?: SkillCatalogOptions): SkillCatalog;
+/** The catalog section text (see buildSkillCatalog). */
+export declare function formatSkillsPrompt(skills: SkillSummary[], options?: SkillCatalogOptions): string;